Counterparties
Generated HTTP reference for the 3 operations the published OpenAPI document describes under counterparties.
3 min read
Counterparties
This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See what is generated here for what that means.
Base URL: https://api.codespar.dev
Every operation below requires a Bearer token. See Authentication.
GET /v1/counterparties
GET
https://api.codespar.dev/v1/counterpartiesList this project's counterparties
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
identifier | string | no | — |
identifier_kind | "cnpj" | "cpf" | "email" | "phone" | "wallet_address" | "other" | no | — |
kind | "supplier" | "customer" | "agent_peer" | no | — |
limit | integer | no | — |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
400 | object | invalid_query, with the validator's issue list under details.issues. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
counterparties | array of object | yes | — |
Example request
curl -X GET https://api.codespar.dev/v1/counterparties \
-H "Authorization: Bearer $CODESPAR_API_KEY"const res = await fetch("https://api.codespar.dev/v1/counterparties", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
},
});
const data = await res.json();Example response 200
{
"counterparties": [
{
"id": "obj_0000000000000000",
"kind": "supplier",
"name": "Example",
"identifier_kind": "cnpj",
"metadata": {},
"created_at": "2026-01-15T12:00:00.000Z",
"last_seen_at": "2026-01-15T12:00:00.000Z"
}
]
}POST /v1/counterparties
POST
https://api.codespar.dev/v1/counterpartiesRegister a counterparty, or merge into the one already there
Request body
| Field | Type | Required | Description |
|---|---|---|---|
identifier | string | no | Set it together with identifier_kind or omit both. One without the other is refused. |
identifier_kind | "cnpj" | "cpf" | "email" | "phone" | "wallet_address" | "other" | no | — |
kind | "supplier" | "customer" | "agent_peer" | yes | — |
metadata | object | no | — |
name | string | yes | — |
Responses
| Status | Body | Description |
|---|---|---|
201 | object | Created, or merged into the existing row. |
400 | object | invalid_body. details.issues carries the validator's own issue list, including the case where only one of identifier / identifier_kind was sent. |
Response 201
| Field | Type | Required | Description |
|---|---|---|---|
created_at | string (date-time) | yes | — |
id | string | yes | cp_ prefixed. |
identifier | string,null | yes | Null when the counterparty was registered without one. |
identifier_kind | "cnpj" | "cpf" | "email" | "phone" | "wallet_address" | "other" | yes | — |
kind | "supplier" | "customer" | "agent_peer" | yes | — |
last_seen_at | string (date-time) | yes | Bumped by a re-registration of the same identifier and by every interaction written against this counterparty. |
metadata | object | yes | — |
name | string | yes | — |
Example request
curl -X POST https://api.codespar.dev/v1/counterparties \
-H "Authorization: Bearer $CODESPAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "supplier",
"name": "Example",
"identifier": "string",
"identifier_kind": "cnpj",
"metadata": {}
}'const res = await fetch("https://api.codespar.dev/v1/counterparties", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"kind": "supplier",
"name": "Example",
"identifier": "string",
"identifier_kind": "cnpj",
"metadata": {}
}),
});
const data = await res.json();Example response 201
{
"id": "obj_0000000000000000",
"kind": "supplier",
"name": "Example",
"identifier_kind": "cnpj",
"metadata": {},
"created_at": "2026-01-15T12:00:00.000Z",
"last_seen_at": "2026-01-15T12:00:00.000Z"
}GET /v1/counterparties/{id}
GET
https://api.codespar.dev/v1/counterparties/{id}Read one counterparty
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | cp_ prefixed. |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
404 | object | not_found, including for a counterparty outside the caller's project. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
created_at | string (date-time) | yes | — |
id | string | yes | cp_ prefixed. |
identifier | string,null | yes | Null when the counterparty was registered without one. |
identifier_kind | "cnpj" | "cpf" | "email" | "phone" | "wallet_address" | "other" | yes | CHECK (identifier_kind IN ('cnpj', 'cpf', 'email', 'phone', 'wallet_address', 'other')), migration 0050. Null exactly when identifier is null: the pair is held together by commerce_counterparties_identifier_pair, a table constraint, so one without the other cannot be stored. |
kind | "supplier" | "customer" | "agent_peer" | yes | CHECK (kind IN ('supplier', 'customer', 'agent_peer')), migration 0050. |
last_seen_at | string (date-time) | yes | Bumped by a re-registration of the same identifier and by every interaction recorded against this row. |
metadata | object | yes | — |
name | string | yes | — |
Example request
curl -X GET https://api.codespar.dev/v1/counterparties/{id} \
-H "Authorization: Bearer $CODESPAR_API_KEY"const res = await fetch("https://api.codespar.dev/v1/counterparties/{id}", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
},
});
const data = await res.json();Example response 200
{
"id": "obj_0000000000000000",
"kind": "supplier",
"name": "Example",
"identifier_kind": "cnpj",
"metadata": {},
"created_at": "2026-01-15T12:00:00.000Z",
"last_seen_at": "2026-01-15T12:00:00.000Z"
}