Account

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

Every operation below requires a Bearer token. See Authentication.

GET /v1/account/agent-activity

BRL spent and received per agent, over a window

One row per agent of the organization plus any agent id this project's entries are attributed to, most spent first. spent_minor and received_minor (money received only, as in the summary) are BRL over the window, with the summary's geometry: the last 24 hours for 24h, the last 7 or 30 São Paulo calendar days for 7d and 30d. window defaults to 30d. last_activity_at is the newest entry attributed to the agent in this project, in any currency and at any time, and null when there is none. tool_calls counts the tool calls made in this project over the window by the sessions the agent opened (agent_id at session creation); a session opened without an agent counts for nobody. spent_within_mandate_minor is the part of spent_minor the mandate itself allowed: every debit except those a person approved above the mandate's signed per-transaction cap.

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/account/agent-activity \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/account/agent-activity HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/account/agent-activity",
    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/account/agent-activity", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/account/agent-activity");

{
  "window": "24h",
  "currency": "BRL",
  "agents": [
    {
      "agent_id": "agt_0000000000000000",
      "spent_minor": "1000",
      "spent_within_mandate_minor": "1000",
      "received_minor": "1000",
      "last_activity_at": "2026-01-15T12:00:00.000Z",
      "tool_calls": 0
    }
  ]
}

GET /v1/account/balances

Account balances, per currency

The sum of the balance caches of every non-closed wallet in the caller's project, one row per currency. held_minor is balance_minor − available_minor, the money open holds reserve. open_holds counts HOLD entries that no release or debit settles yet, paired by metadata.hold_ref, by withdrawal_id for owner withdrawals, or by attempt_id — the same pairing the hold sweeper uses.

Scoped to the organization AND the project: another project's wallets are in no sum.

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/account/balances \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/account/balances HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/account/balances",
    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/account/balances", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/account/balances");

{
  "project_id": "prj_0000000000000000",
  "currencies": [
    {
      "currency": "BRL",
      "balance_minor": "1000",
      "available_minor": "1000",
      "held_minor": "1000",
      "open_holds": 0
    }
  ],
  "as_of": "2026-01-15T12:00:00.000Z"
}

POST /v1/account/fund/sandbox

Add test balance (test projects only)

Credits test balance, in BRL, in a TEST project. Nothing is sent to any bank or provider; rail is the label the person picked. The entry is a FUND marked test_funding: true on GET /v1/account/ledger, and it is never counted as money received.

target picks the wallet. account (the default) is the project's account wallet, created on first use: the account Wallet shows it, but no agent spends from it. consumer is the consumer wallet a mandate spend reserves and debits: mandate_id's consumer, else consumer_id, else the one consumer the organization's active BRL mandates name; none or several answer test_funding_target_required with the candidates. Naming mandate_id or consumer_id implies consumer. A consumer wallet created here starts with exactly the amount funded.

At most 1000000 centavos per call. idempotency_key is required: the same key with the same amount and wallet answers the first entry with 200 and idempotent_replay: true; with another amount or wallet, idempotency_key_conflict. Requires an admin or owner (x-codespar-user on the dashboard path).

Request body

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/account/fund/sandbox \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "amount_minor": 1000,
       "idempotency_key": "string",
       "rail": "pix",
       "target": "account",
       "mandate_id": "mandate_0000000000000000",
       "consumer_id": "csm_0000000000000000"
     }'

POST /v1/account/fund/sandbox HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "amount_minor": 1000,
  "idempotency_key": "string",
  "rail": "pix",
  "target": "account",
  "mandate_id": "mandate_0000000000000000",
  "consumer_id": "csm_0000000000000000"
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/account/fund/sandbox",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "amount_minor": 1000,
      "idempotency_key": "string",
      "rail": "pix",
      "target": "account",
      "mandate_id": "mandate_0000000000000000",
      "consumer_id": "csm_0000000000000000"
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/account/fund/sandbox", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "amount_minor": 1000,
    "idempotency_key": "string",
    "rail": "pix",
    "target": "account",
    "mandate_id": "mandate_0000000000000000",
    "consumer_id": "csm_0000000000000000"
  }),
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/account/fund/sandbox", {
  body: {
    amount_minor: 1000,
    idempotency_key: "string",
    rail: "pix",
    target: "account",
    mandate_id: "mandate_0000000000000000",
    consumer_id: "csm_0000000000000000"
  }
});
// r.status is one of the documented statuses (200, 403, 422),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "entry_id": "entry_0000000000000000",
  "wallet_id": "wlt_0000000000000000",
  "target": "account",
  "consumer_id": "csm_0000000000000000",
  "mandate_id": "mandate_0000000000000000",
  "amount_minor": "1000",
  "currency": "BRL",
  "test_funding": true,
  "idempotent_replay": true,
  "balance": {
    "balance_minor": "1000",
    "available_minor": "1000"
  }
}

POST /v1/account/fund/sandbox/initial

Grant the initial test balance (test projects only, once)

Credits 10000 centavos of test money to the project's account wallet, once per project: the first call answers 201 with granted: true, every later call, and the loser of two concurrent calls, answers 200 with granted: false and the same entry. The amount, the wallet and the idempotency reference are the server's, so the route takes no body (send none, or {}). The entry is a FUND with test_funding_kind: initial_balance on GET /v1/account/ledger and is never counted as money received. No agent spends from the account wallet. To add more, POST /v1/account/fund/sandbox.

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/account/fund/sandbox/initial \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

POST /v1/account/fund/sandbox/initial HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/account/fund/sandbox/initial",
    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/account/fund/sandbox/initial", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/account/fund/sandbox/initial");
// r.status is one of the documented statuses (200, 403),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "entry_id": "entry_0000000000000000",
  "wallet_id": "wlt_0000000000000000",
  "target": "account",
  "amount_minor": "1000",
  "currency": "BRL",
  "test_funding": true,
  "granted": true,
  "balance": {
    "balance_minor": "1000",
    "available_minor": "1000"
  }
}

POST /v1/account/fund/sandbox/refill

Refill the test balance (test projects only, confirmed)

Brings the project's test balance (available + held, every wallet) back up to 10000 centavos, crediting only the difference to the account wallet; a balance already there answers 200 with refilled: false and credits nothing. At most 3 refills per São Paulo calendar day per project; the credit and the quota use are one row in one transaction, and a refill that credits nothing uses no quota. Adicionar fundos is a separate action and never counts. An explicit, confirmed act of a person: the body must be { "confirm": true }. The entry is test funding (test_funding_kind: refill) and never money received. Admin or owner.

Request body

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/account/fund/sandbox/refill \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "confirm": true
     }'

POST /v1/account/fund/sandbox/refill HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "confirm": true
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/account/fund/sandbox/refill",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "confirm": True
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/account/fund/sandbox/refill", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "confirm": true
  }),
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/account/fund/sandbox/refill", {
  body: {
    confirm: true
  }
});
// r.status is one of the documented statuses (200, 403),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "environment": "live",
  "mode": "sandbox_float",
  "balance": {
    "total_minor": "1000",
    "available_minor": "1000",
    "held_minor": "1000"
  },
  "refill": {
    "target_minor": "1000",
    "daily_limit": 1000,
    "used_today": 0,
    "left_today": 0,
    "resets_at": "2026-01-15T12:00:00.000Z",
    "room_minor": "1000"
  },
  "add_funds": {
    "max_per_call_minor": "1000",
    "counts_toward_refills": false
  },
  "refilled": true,
  "entry_id": "entry_0000000000000000",
  "wallet_id": "wlt_0000000000000000",
  "amount_minor": "1000",
  "currency": "BRL",
  "test_funding": true
}

GET /v1/account/ledger

The project's ledger, every wallet merged

Every ledger entry of every wallet in the caller's project (closed wallets included: the ledger is history), newest first by entry id. Page with before set to the previous page's next_before; next_before is null on the last page.

hold_ref returns that hold and every release, debit and fee that settles it — an id that is not a hold of this project returns no entries.

category returns the entries stamped with that spend category at write time: recebivel on money received, fornecedor on a payable's payment, compra on a codespar_shop purchase, and otherwise what the agent declared on codespar_pay. It is never inferred from the description, so an entry no writer categorised is in no category and is listed only without the filter.

source and phase are the writer's own stamps, as written: they name an entry no writer described, e.g. consumer-payments + settle-fund is a payment's settlement FUND. A phase is only unique within its source; both are open vocabularies and null where unstamped.

proposal_id is the payment proposal the entry was booked for: a pay proposal's, read from its attempt id (<proposal>_t<n>_hold|_debit); a receive proposal's, on the FUND of the Pix charge it sent. Only when that proposal is in this org and project; the proposal_id filter returns those entries.

reverses, on a REVERSE entry, is the id of the entry it reverses when that entry is in this project; null on every other kind.

agent_id is resolved through the entry's consumer mandate, else, on the FUND of a Pix charge a receive proposal sent, that proposal's agent, else the wallet's agent. balance_after_minor is the running BOOKED balance of the project in the entry's currency, over every entry and not only the filtered ones: holds and releases leave it unchanged, as they leave balance_minor unchanged. At the newest entry it equals the sum of balance_minor over the project's wallets in that currency.

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/account/ledger \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/account/ledger HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/account/ledger",
    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/account/ledger", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/account/ledger");

{
  "entries": [
    {
      "id": "obj_0000000000000000",
      "wallet_id": "wlt_0000000000000000",
      "currency": "BRL",
      "kind": "fund",
      "amount_minor": "1000",
      "posted_at": "2026-01-15T12:00:00.000Z",
      "mandate_id": "mandate_0000000000000000",
      "agent_id": "agt_0000000000000000",
      "agent_display_name": "Example",
      "origin_kind": "agent",
      "description": "string",
      "rail": "string",
      "external_ref": "string",
      "hold_ref": "string",
      "receipt_id": "receipt_0000000000000000",
      "authorization": "string",
      "category": "compra",
      "test_funding": true,
      "test_funding_kind": "initial_balance",
      "proposal_id": "proposal_0000000000000000",
      "reverses": "string",
      "source": "string",
      "phase": "string",
      "executor": "codespar_simulator",
      "balance_after_minor": "1000"
    }
  ],
  "next_before": "string"
}

GET /v1/account/payments

The project's payments, newest first

One row per spend attempt the payment lifecycle claimed in the caller's project, on every door (by mandate id, signed envelope, MCP, payment link, an approved execution), with its status: settled is paid and on the ledger (debit_entry_id), failed provably moved nothing, uncertain is held for reconciliation, the rest are in flight. A spend refused at a gate before any money step leaves no attempt and is not listed. agent_id is the agent of the mandate the payment was spent under. Page with before set to the previous page's next_before, an opaque cursor; next_before is null on the last page.

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/account/payments \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/account/payments HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/account/payments",
    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/account/payments", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/account/payments");

{
  "payments": [
    {
      "attempt_id": "attempt_0000000000000000",
      "mandate_id": "mandate_0000000000000000",
      "agent_id": "agt_0000000000000000",
      "agent_display_name": "Example",
      "amount_minor": "1000",
      "currency": "BRL",
      "rail": "string",
      "payee": "string",
      "status": "claimed",
      "failure_code": "string",
      "receipt_id": "receipt_0000000000000000",
      "debit_entry_id": "debitentry_0000000000000000",
      "executor": "codespar_simulator",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "next_before": "string"
}

GET /v1/account/sessions

The project's sessions, as the activity list draws them

Each session with its agent, origin, tool calls, reviews and money, newest first, one read per page. agent_id is the agent the session was created as, else the Playground scene's agent. origin_kind is playground for a Playground session, else person when a dashboard person opened it, else agent when an agent is named, else api. opened_by_user_id is that person's Clerk user id on any origin, null when an API key or token opened the session. tool_calls.denied counts approvals of the session a person denied; review counts its approvals pending and decided. amount_minor sums the BRL debited by payments made in the session (a spend that sent session_id, or a payment made through a tool of the session), and is null when there is none: it is never estimated. total counts the sessions matching the filters, cursor aside. Page with before set to the previous page's next_before, an opaque cursor.

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/account/sessions \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/account/sessions HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/account/sessions",
    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/account/sessions", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/account/sessions");

{
  "sessions": [
    {
      "id": "obj_0000000000000000",
      "status": "string",
      "created_at": "2026-01-15T12:00:00.000Z",
      "closed_at": "2026-01-15T12:00:00.000Z",
      "agent_id": "agt_0000000000000000",
      "agent_display_name": "Example",
      "origin_kind": "agent",
      "opened_by_user_id": "openedbyuser_0000000000000000",
      "tool_calls": {
        "count": 1,
        "errors": 0,
        "denied": 0
      },
      "mandate_id": "mandate_0000000000000000",
      "amount_minor": "1000",
      "review": {
        "pending": 0,
        "decided": 0
      },
      "title": "Example",
      "scene": "string",
      "executor": "codespar_simulator"
    }
  ],
  "next_before": "string",
  "total": 0
}

GET /v1/account/summary

BRL money in, agent spend, tool calls and sessions over a window

BRL only. received_minor sums the funding entries stamped as money received (category recebivel): test funding and the fund legs that mirror a payment on its way out are not received. spent_by_agents_minor sums debits attributed to an agent. The window is N whole buckets ending with the current, partial one: 24 hours for 24h, 7 or 30 São Paulo calendar days for 7d and 30d. series has exactly those N buckets, oldest first, and sums to the two totals; previous covers the N buckets immediately before. received_by_rail groups that received funding by metadata.rail, null where the writer recorded none. tool_calls and sessions are counts over the same window and scope (tool calls by called_at, sessions by creation); sessions.active_now counts the sessions open at the time of the read that were created or made a tool call in the last 15 minutes, whatever the window: nothing closes an idle session, so an open session idle for longer is not counted. sessions.active_idle_ms states that threshold (900000). window defaults to 7d.

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/account/summary \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/account/summary HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/account/summary",
    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/account/summary", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/account/summary");

{
  "window": "24h",
  "currency": "BRL",
  "received_minor": "1000",
  "spent_by_agents_minor": "1000",
  "previous": {
    "received_minor": "1000",
    "spent_by_agents_minor": "1000"
  },
  "series": [
    {
      "bucket_start": "2026-01-15T12:00:00.000Z",
      "received_minor": "1000",
      "spent_by_agents_minor": "1000"
    }
  ],
  "received_by_rail": [
    {
      "rail": "string",
      "received_minor": "1000"
    }
  ],
  "tool_calls": {
    "total": 0,
    "errors": 0
  },
  "sessions": {
    "total": 0,
    "active_now": 0,
    "active_idle_ms": 900000
  }
}

GET /v1/account/test-balance

The test balance, the refill quota and the Adicionar fundos cap

One read for both test-credit actions. balance.total_minor is available + held over every wallet of the project, the number a refill compares to its target; refill is the day's quota (São Paulo calendar day) and the room a refill would credit now; add_funds is the separate per-call cap, which has no cumulative cap and never counts toward the refills.

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/account/test-balance \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/account/test-balance HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/account/test-balance",
    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/account/test-balance", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/account/test-balance");

{
  "environment": "live",
  "mode": "sandbox_float",
  "balance": {
    "total_minor": "1000",
    "available_minor": "1000",
    "held_minor": "1000"
  },
  "refill": {
    "target_minor": "1000",
    "daily_limit": 1000,
    "used_today": 0,
    "left_today": 0,
    "resets_at": "2026-01-15T12:00:00.000Z",
    "room_minor": "1000"
  },
  "add_funds": {
    "max_per_call_minor": "1000",
    "counts_toward_refills": false
  }
}