Onboarding
3 operations under /v1/onboarding (GET POST): parameters, status codes, refusal bodies, and the same request in curl, HTTP, Python and TypeScript.
Base URL: https://api.codespar.dev
Every operation below requires a Bearer token. See Authentication.
GET /v1/onboarding
https://api.codespar.dev/v1/onboardingThe first-access guide's progress for the project
Three steps, read in one call. agent: the organization has a registered agent other than a Playground scene's own; in_project says whether one of them works in this project (an active mandate funds it). scenario: a session of this project recorded a tool call; the first one names the session and, for a Playground session, its scene. result: money moved under a mandate in this project (the first debit); test funding is not a result. Added for the new guide, each derived from the server's own records, with a state (done, pending, or unverified when the read failed: done is then null, never a false nobody read): receive (the first Collect payment confirmed by the provider, in the ledger, with its signed receipt; test funding, the initial credit included, never counts; the same source as the first receipt's project_has_confirmed_receipt), shop_payment (the Shop assistant's first settled, debited and receipted payment), approval (a person's first decision on a proposal parked above the mandate's limit) and connect (a valid connection from its own state: an unexpired, unrevoked OAuth grant under a live key, else an API key used at least once and not revoked). Read-only. project_id, when sent, must be the project the request resolved to, or the answer is 404.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
project_id | string | no | — |
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
400 | object | The query did not match the schema. |
404 | object | project_id names a project other than the one the request resolved to. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
agent | object | yes | — |
approval | object | yes | — |
connect | object | yes | — |
environment | "live" | "test" | yes | — |
project_id | string | yes | — |
receive | object | yes | — |
result | object | yes | — |
scenario | object | yes | — |
shop_payment | object | yes | — |
| Nested field | Values |
|---|---|
approval.decision | "approved" | "denied" |
approval.state | "done" | "pending" | "unverified" |
connect.state | "done" | "pending" | "unverified" |
connect.via | "oauth" | "bearer" |
receive.state | "done" | "pending" | "unverified" |
shop_payment.origin | "wallet_pix" | "wallet_boleto" | "external_card" | "store_on_file" |
shop_payment.state | "done" | "pending" | "unverified" |
curl -X GET https://api.codespar.dev/v1/onboarding \
-H "Authorization: Bearer $CODESPAR_API_KEY"GET /v1/onboarding HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEYimport os
import requests
res = requests.get(
"https://api.codespar.dev/v1/onboarding",
headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()const res = await fetch("https://api.codespar.dev/v1/onboarding", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
},
});
const data = await res.json();const result = await cs.api.get("/v1/onboarding");{
"project_id": "prj_0000000000000000",
"environment": "live",
"agent": {
"done": true,
"agent_id": "agt_0000000000000000",
"in_project": true,
"at": "2026-01-15T12:00:00.000Z"
},
"scenario": {
"done": true,
"session_id": "ses_0000000000000000",
"scene": "string",
"at": "2026-01-15T12:00:00.000Z"
},
"result": {
"done": true,
"ledger_entry_id": "ledgerentry_0000000000000000",
"at": "2026-01-15T12:00:00.000Z"
},
"receive": {
"state": "done",
"done": true,
"at": "2026-01-15T12:00:00.000Z",
"charge_id": "charge_0000000000000000",
"receipt_id": "receipt_0000000000000000",
"ledger_entry_id": "ledgerentry_0000000000000000"
},
"shop_payment": {
"state": "done",
"done": true,
"origin": "wallet_pix",
"at": "2026-01-15T12:00:00.000Z",
"proposal_id": "proposal_0000000000000000",
"mandate_id": "mandate_0000000000000000",
"receipt_id": "receipt_0000000000000000",
"ledger_entry_id": "ledgerentry_0000000000000000",
"order_id": "order_0000000000000000"
},
"approval": {
"state": "done",
"done": true,
"at": "2026-01-15T12:00:00.000Z",
"proposal_id": "proposal_0000000000000000",
"decision": "approved",
"receipt_id": "receipt_0000000000000000"
},
"connect": {
"state": "done",
"done": true,
"at": "2026-01-15T12:00:00.000Z",
"via": "oauth",
"client_name_declared": "Example",
"key_id_masked": "string"
}
}GET /v1/onboarding/first-receive
https://api.codespar.dev/v1/onboarding/first-receiveThe project's first test receipt (the guide's Receber R$ 10)
Read-only. The project's first-receive obligation is a Collect link under the reference codespar_first_receive (version 1), R$ 10,00, paid by the platform's Test payer. States, from Collect's records, never a clock: not_started (no link, or no attempt), creating_charge (the charge waits for its copia-e-cola), paying (open, the Test payer has not taken it: a POST pays it), awaiting_confirmation (the payer took it, or a payment is not yet confirmed with its receipt), received (paid_confirmed, in the ledger, with its signed receipt; the only state that says received), failed (refusal.retriable says whether a POST starts again, on the same link), blocked (a precondition is missing; nothing is created).
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
amount_minor | integer | yes | Always 1000 (R$ 10,00): the server's, never the request's. |
attempt_id | string,null | yes | — |
charge_id | string,null | yes | — |
link_id | string,null | yes | — |
object | "first_receive" | yes | — |
payment | object,null | yes | Only in received: confirmed by the provider (D-A), with its ledger entry and signed receipt. |
project_has_confirmed_receipt | boolean | yes | Any confirmed Collect receipt of the project, from this link or another: the guide's first step is done. |
refusal | object,null | yes | In blocked and failed. |
state | "not_started" | "creating_charge" | "paying" | "awaiting_confirmation" | "received" | "failed" | "blocked" | yes | — |
| Nested field | Values |
|---|---|
payment.status | "paid_confirmed" |
curl -X GET https://api.codespar.dev/v1/onboarding/first-receive \
-H "Authorization: Bearer $CODESPAR_API_KEY"GET /v1/onboarding/first-receive HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEYimport os
import requests
res = requests.get(
"https://api.codespar.dev/v1/onboarding/first-receive",
headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()const res = await fetch("https://api.codespar.dev/v1/onboarding/first-receive", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
},
});
const data = await res.json();const result = await cs.api.get("/v1/onboarding/first-receive");{
"object": "first_receive",
"state": "not_started",
"amount_minor": 1000,
"link_id": "link_0000000000000000",
"attempt_id": "attempt_0000000000000000",
"charge_id": "charge_0000000000000000",
"payment": {
"payment_id": "payment_0000000000000000",
"status": "paid_confirmed",
"receipt_id": "receipt_0000000000000000",
"ledger_entry_id": "ledgerentry_0000000000000000",
"paid_at": "2026-01-15T12:00:00.000Z"
},
"refusal": {
"code": "string",
"message": "string",
"retriable": true,
"next_action": "string"
},
"project_has_confirmed_receipt": true
}POST /v1/onboarding/first-receive
https://api.codespar.dev/v1/onboarding/first-receivehas the Test payer pay the open attempt (one payment per charge)
Take the project's first test receipt one step further
No body. Idempotent: a repeated click, a refresh or a timeout resumes the same obligation, never a second link, attempt or payment. From where the records are: creates or answers the referenced link, publishes it, asks it for an attempt, or has the Test payer pay the open attempt (one payment per charge). The copia-e-cola arrives after the POST, so the answer is often creating_charge; once the GET reads paying, one more POST pays it. Test projects only; an admin's or the owner's act from the dashboard, or the project's own key. Answers the GET's view. States, from Collect's records, never a clock: not_started (no link, or no attempt), creating_charge (the charge waits for its copia-e-cola), paying (open, the Test payer has not taken it: a POST pays it), awaiting_confirmation (the payer took it, or a payment is not yet confirmed with its receipt), received (paid_confirmed, in the ledger, with its signed receipt; the only state that says received), failed (refusal.retriable says whether a POST starts again, on the same link), blocked (a precondition is missing; nothing is created).
Responses
| Status | Body | Description |
|---|---|---|
200 | object | OK |
400 | object | A body was sent: amount, receiver and payer are the server's. |
Response 200
| Field | Type | Required | Description |
|---|---|---|---|
amount_minor | integer | yes | Always 1000 (R$ 10,00): the server's, never the request's. |
attempt_id | string,null | yes | — |
charge_id | string,null | yes | — |
link_id | string,null | yes | — |
object | "first_receive" | yes | — |
payment | object,null | yes | Only in received: confirmed by the provider (D-A), with its ledger entry and signed receipt. |
project_has_confirmed_receipt | boolean | yes | Any confirmed Collect receipt of the project, from this link or another: the guide's first step is done. |
refusal | object,null | yes | In blocked and failed. |
state | "not_started" | "creating_charge" | "paying" | "awaiting_confirmation" | "received" | "failed" | "blocked" | yes | — |
| Nested field | Values |
|---|---|
payment.status | "paid_confirmed" |
curl -X POST https://api.codespar.dev/v1/onboarding/first-receive \
-H "Authorization: Bearer $CODESPAR_API_KEY"POST /v1/onboarding/first-receive HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEYimport os
import requests
res = requests.post(
"https://api.codespar.dev/v1/onboarding/first-receive",
headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()const res = await fetch("https://api.codespar.dev/v1/onboarding/first-receive", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
},
});
const data = await res.json();const result = await cs.api.post("/v1/onboarding/first-receive");{
"object": "first_receive",
"state": "not_started",
"amount_minor": 1000,
"link_id": "link_0000000000000000",
"attempt_id": "attempt_0000000000000000",
"charge_id": "charge_0000000000000000",
"payment": {
"payment_id": "payment_0000000000000000",
"status": "paid_confirmed",
"receipt_id": "receipt_0000000000000000",
"ledger_entry_id": "ledgerentry_0000000000000000",
"paid_at": "2026-01-15T12:00:00.000Z"
},
"refusal": {
"code": "string",
"message": "string",
"retriable": true,
"next_action": "string"
},
"project_has_confirmed_receipt": true
}