Skip to main content

Onboarding

3 operations under /v1/onboarding (GET POST): parameters, status codes, refusal bodies, and the same request in curl, HTTP, Python and TypeScript.

5 min read
View MarkdownEdit on GitHub

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

GET /v1/onboarding

GEThttps://api.codespar.dev/v1/onboarding

The 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

NameTypeRequiredDescription
project_idstringno—

Responses

StatusBodyDescription
200objectOK
400objectThe query did not match the schema.
404objectproject_id names a project other than the one the request resolved to.

Response 200

FieldTypeRequiredDescription
agentobjectyes—
approvalobjectyes—
connectobjectyes—
environment"live" | "test"yes—
project_idstringyes—
receiveobjectyes—
resultobjectyes—
scenarioobjectyes—
shop_paymentobjectyes—
Nested fieldValues
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"
Example request
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_KEY
import 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");
Example response 200
application/json
{
  "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

GEThttps://api.codespar.dev/v1/onboarding/first-receive

The 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

StatusBodyDescription
200objectOK

Response 200

FieldTypeRequiredDescription
amount_minorintegeryesAlways 1000 (R$ 10,00): the server's, never the request's.
attempt_idstring,nullyes—
charge_idstring,nullyes—
link_idstring,nullyes—
object"first_receive"yes—
paymentobject,nullyesOnly in received: confirmed by the provider (D-A), with its ledger entry and signed receipt.
project_has_confirmed_receiptbooleanyesAny confirmed Collect receipt of the project, from this link or another: the guide's first step is done.
refusalobject,nullyesIn blocked and failed.
state"not_started" | "creating_charge" | "paying" | "awaiting_confirmation" | "received" | "failed" | "blocked"yes—
Nested fieldValues
payment.status"paid_confirmed"
Example request
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_KEY
import 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");
Example response 200
application/json
{
  "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

POSThttps://api.codespar.dev/v1/onboarding/first-receive
Moves money

has 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

StatusBodyDescription
200objectOK
400objectA body was sent: amount, receiver and payer are the server's.

Response 200

FieldTypeRequiredDescription
amount_minorintegeryesAlways 1000 (R$ 10,00): the server's, never the request's.
attempt_idstring,nullyes—
charge_idstring,nullyes—
link_idstring,nullyes—
object"first_receive"yes—
paymentobject,nullyesOnly in received: confirmed by the provider (D-A), with its ledger entry and signed receipt.
project_has_confirmed_receiptbooleanyesAny confirmed Collect receipt of the project, from this link or another: the guide's first step is done.
refusalobject,nullyesIn blocked and failed.
state"not_started" | "creating_charge" | "paying" | "awaiting_confirmation" | "received" | "failed" | "blocked"yes—
Nested fieldValues
payment.status"paid_confirmed"
Example request
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_KEY
import 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");
Example response 200
application/json
{
  "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
}
Onboarding | CodeSpar