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, last 30 days

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 are BRL over the last 30 São Paulo calendar days; 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.

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": "30d",
  "currency": "BRL",
  "agents": [
    {
      "agent_id": "agt_0000000000000000",
      "spent_minor": "1000",
      "received_minor": "1000",
      "last_activity_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}

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"
}

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.

agent_id is resolved through the entry's consumer mandate, 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",
      "balance_after_minor": "1000"
    }
  ],
  "next_before": "string"
}

GET /v1/account/summary

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

BRL only. received_minor sums funding entries; 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 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, whenever they were created. 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
  }
}