Generated HTTP reference for the 12 operations the published OpenAPI document describes under sessions.

Sessions

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.

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

All endpoints require authentication via Bearer token. See Authentication for details on API key types and scopes.

Authorization: Bearer csk_live_your_api_key

Project scoping

Every /v1 endpoint accepts an optional x-codespar-project header that pins the request to a specific project within your account.

Header	Required	Description
`x-codespar-project`	No	Project ID in the form `prj_<16chars>`. If omitted, requests resolve to the account's default project (auto-created at signup). Project-scoped API keys ignore this header and always use the key's pinned project.

# Explicit project
curl -X POST https://api.codespar.dev/v1/sessions \
  -H "Authorization: Bearer csk_live_abc123..." \
  -H "x-codespar-project: prj_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{"servers": ["stripe"]}'

# Omitted -- falls back to the account's default project
curl -X POST https://api.codespar.dev/v1/sessions \
  -H "Authorization: Bearer csk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"servers": ["stripe"]}'

Sessions, triggers, API keys, connections, and events are all scoped to the resolved project. See Projects concept and the Projects API for details.

POST /v1/sessions

Creates a new session connected to the specified MCP servers. Returns the session object with connection status for each server.

Auth required: Yes (scope: sessions:create)

Request body

Field	Type	Required	Description
`user_id`	`string`	Yes	End-user identifier on behalf of whom the agent acts
`servers`	`string[]`	Yes*	List of server identifiers (e.g., `["stripe", "mercadopago"]`)
`preset`	`string`	No	Named preset: `brazilian`, `mexican`, `argentinian`, `colombian`, `all`
`manageConnections`	`object`	No	Connection-management options (see Sessions)
`metadata`	`object`	No	Key-value metadata attached to every tool call

*Required unless preset is specified. Can be combined with preset to add additional servers.

curl example

curl -X POST https://api.codespar.dev/v1/sessions \
  -H "Authorization: Bearer csk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "servers": ["stripe", "mercadopago"]
  }'

Response -- `201 Created`

{
  "id": "ses_abc123def456",
  "user_id": "user_123",
  "status": "active",
  "servers": [
    { "id": "stripe", "name": "Stripe", "status": "connected" },
    { "id": "mercadopago", "name": "Mercado Pago", "status": "connected" }
  ],
  "tool_calls": 0,
  "created_at": "2026-04-15T10:30:00Z",
  "expires_at": "2026-04-15T11:00:00Z"
}

SDK equivalent

const session = await codespar.create("user_123", {
  servers: ["stripe", "mercadopago"],
});

Sessions expire after 30 minutes of inactivity. The expires_at timestamp is updated with each tool call. If a server fails to connect, the session is still created with the remaining servers -- check the status field on each server entry.

GET /v1/sessions

Lists all sessions for your account. Supports pagination and filtering by status.

Auth required: Yes (scope: sessions:read)

Query parameters

Parameter	Type	Default	Description
`status`	`string`	--	Filter by status: `active`, `closed`, `error`
`limit`	`number`	`20`	Results per page (max 100)
`offset`	`number`	`0`	Pagination offset

curl example

curl "https://api.codespar.dev/v1/sessions?status=active&limit=10" \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- `200 OK`

{
  "data": [
    {
      "id": "ses_abc123def456",
      "status": "active",
      "servers": ["stripe", "mercadopago"],
      "tool_calls": 12,
      "created_at": "2026-04-15T10:30:00Z",
      "expires_at": "2026-04-15T11:00:00Z"
    },
    {
      "id": "ses_def789ghi012",
      "status": "active",
      "servers": ["correios", "nfe"],
      "tool_calls": 3,
      "created_at": "2026-04-15T10:15:00Z",
      "expires_at": "2026-04-15T10:45:00Z"
    }
  ],
  "total": 47,
  "limit": 10,
  "offset": 0
}

GET /v1/sessions/:id

Retrieves details about an existing session, including connected servers, tool call count, and expiry.

Auth required: Yes (scope: sessions:read)

curl example

curl https://api.codespar.dev/v1/sessions/ses_abc123def456 \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- `200 OK`

{
  "id": "ses_abc123def456",
  "status": "active",
  "servers": [
    { "id": "stripe", "name": "Stripe", "status": "connected" },
    { "id": "mercadopago", "name": "Mercado Pago", "status": "connected" }
  ],
  "tool_calls": 12,
  "created_at": "2026-04-15T10:30:00Z",
  "expires_at": "2026-04-15T11:00:00Z"
}

DELETE /v1/sessions/:id

Closes an active session and releases all server connections. Closed sessions cannot be reopened; create a new session instead.

Auth required: Yes

curl example

curl -X DELETE https://api.codespar.dev/v1/sessions/ses_abc123def456 \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- `200 OK`

{
  "id": "ses_abc123def456",
  "status": "closed",
  "tool_calls": 12,
  "closed_at": "2026-04-15T10:45:00Z"
}

SDK equivalent

await session.close();

Closing a session is idempotent. Calling DELETE on an already-closed session returns 200 OK with the existing closed state.

POST /v1/sessions/:id/execute

Executes a tool call synchronously. The request blocks until the tool completes and the result is available. Use this for operations where the agent needs the response before continuing.

Auth required: Yes

Request body

Field	Type	Required	Description
`name`	`string`	Yes	Tool name (e.g., `codespar_pay`, `stripe_create_refund`)
`arguments`	`object`	Yes	Tool arguments matching the tool's `input_schema`

curl example

curl -X POST https://api.codespar.dev/v1/sessions/ses_abc123/execute \
  -H "Authorization: Bearer csk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "codespar_pay",
    "arguments": {
      "method": "pix",
      "amount": 9990,
      "currency": "BRL",
      "description": "Order #1234",
      "customer_email": "maria@example.com"
    }
  }'

Response -- `200 OK`

{
  "tool_call_id": "tc_xyz789abc",
  "name": "codespar_pay",
  "result": {
    "payment_id": "pay_xyz789",
    "status": "pending",
    "method": "pix",
    "provider": "asaas",
    "pix_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "qr_code_url": "https://api.codespar.dev/qr/pay_xyz789.png",
    "amount": 9990,
    "currency": "BRL",
    "expires_at": "2026-04-15T11:00:00Z"
  },
  "execution_time_ms": 342
}

SDK equivalent

const result = await session.execute("codespar_pay", {
  method: "pix",
  amount: 9990,
  currency: "BRL",
});

Each call to this endpoint counts as one tool call for billing purposes. If the tool fails (e.g., provider error), it still counts as a tool call.

POST /v1/sessions/:id/send

Sends a natural-language message. The CodeSpar backend runs a Claude tool-use loop using the session's connected servers, calling whichever tools the agent decides it needs, and returns the final response along with every tool call made. Use this for the simplest possible agent integration, with no client-side orchestration.

Auth required: Yes

Request body

Field	Type	Required	Description
`message`	`string`	Yes	Natural-language instruction for the agent

curl example

curl -X POST https://api.codespar.dev/v1/sessions/ses_abc123/send \
  -H "Authorization: Bearer csk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Charge R$150 via Pix for order #5678 and send a WhatsApp confirmation"
  }'

Response -- `200 OK`

{
  "message": "Done. Pix QR code generated and WhatsApp message sent.",
  "tool_calls": [
    { "id": "tc_1", "tool_name": "codespar_pay", "status": "success", "duration_ms": 412 },
    { "id": "tc_2", "tool_name": "codespar_notify", "status": "success", "duration_ms": 287 }
  ],
  "iterations": 2
}

Streaming variant

Streaming is content-negotiated on the same endpoint: send Accept: text/event-stream on POST /v1/sessions/:id/send to receive an SSE stream of StreamEvents (assistant text, tool use, tool result, done) -- see the SDK reference for event shapes.

SDK equivalent

const result = await session.send(
  "Charge R$150 via Pix for order #5678 and send a WhatsApp confirmation",
);

GET /v1/sessions/:id/connections

Lists OAuth connections for a session created with manageConnections: true. Returns the connection status and authorization URL for each server.

Auth required: Yes

curl example

curl https://api.codespar.dev/v1/sessions/ses_abc123/connections \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- `200 OK`

{
  "connections": [
    {
      "server": "stripe",
      "status": "connected",
      "connected_at": "2026-04-15T10:31:00Z"
    },
    {
      "server": "mercadopago",
      "status": "pending",
      "authUrl": "https://codespar.dev/connect/mercadopago?session=ses_abc123"
    }
  ]
}

Connection status	Description
`pending`	User has not yet authenticated. The `authUrl` field contains the OAuth URL.
`connected`	User has authenticated. Tool calls to this server use the user's credentials.
`expired`	OAuth token has expired. A new `authUrl` is provided for re-authentication.
`revoked`	User revoked access. A new `authUrl` is provided.

SDK equivalent

const connections = await session.connections();

POST /v1/sessions/:id/tool-calls

Records a tool call result from an external execution. This is used in advanced workflows where the tool is executed outside of CodeSpar (e.g., by the LLM framework) and the result needs to be recorded for auditing and billing.

Auth required: Yes (scope: tools:execute)

Request body

Field	Type	Required	Description
`name`	`string`	Yes	Tool name that was called
`arguments`	`object`	Yes	Arguments that were passed to the tool
`result`	`object`	Yes	Result returned by the tool

curl example

curl -X POST https://api.codespar.dev/v1/sessions/ses_abc123/tool-calls \
  -H "Authorization: Bearer csk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "codespar_pay",
    "arguments": {"method": "pix", "amount": 5000, "currency": "BRL"},
    "result": {"payment_id": "pay_ext_001", "status": "completed"}
  }'

Response -- `201 Created`

{
  "id": "tc_rec_abc123",
  "session_id": "ses_abc123",
  "name": "codespar_pay",
  "status": "recorded",
  "recorded_at": "2026-04-15T10:50:00Z"
}

GET /v1/sessions/:id/tool-calls

Lists all tool calls made within a session. Useful for auditing and debugging agent behavior.

Auth required: Yes (scope: sessions:read)

Query parameters

Parameter	Type	Default	Description
`limit`	`number`	`100`	Rows to return, newest first (min 1, max 500)

limit is the only query parameter. There is no offset and no server-side filter by status, server, tool, or date range: the endpoint returns the newest limit rows for the session and you filter client-side.

curl example

curl "https://api.codespar.dev/v1/sessions/ses_abc123/tool-calls?limit=5" \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- `200 OK`

{
  "tool_calls": [
    {
      "id": "tc_001",
      "session_id": "ses_abc123",
      "server_id": "codespar",
      "tool_name": "codespar_discover",
      "status": "success",
      "duration_ms": 67,
      "error_code": null,
      "input": { "domain": "payments" },
      "output": { "servers": ["asaas", "stripe"] },
      "called_at": "2026-04-15T10:30:05Z"
    },
    {
      "id": "tc_002",
      "session_id": "ses_abc123",
      "server_id": "asaas",
      "tool_name": "codespar_pay",
      "status": "success",
      "duration_ms": 342,
      "error_code": null,
      "input": { "method": "pix", "amount": 9990, "currency": "BRL" },
      "output": { "id": "pay_z8rwa1qnr0twili5", "status": "PENDING" },
      "called_at": "2026-04-15T10:30:12Z"
    }
  ]
}

The envelope carries tool_calls and nothing else: no total, no limit, no offset echo. status is running on a call recorded but not yet finalized, then success or error. Two further keys, routing and failover_trail, appear on a row only when a routing decision was recorded for it.

PATCH /v1/sessions/:id/tool-calls/:tc_id

Updates the status or metadata of a recorded tool call. Used to mark externally-executed tool calls as completed or failed.

Auth required: Yes

Request body

Field	Type	Required	Description
`status`	`string`	No	New status: `completed`, `failed`
`result`	`object`	No	Updated result object
`error`	`object`	No	Error details if the tool call failed

curl example

curl -X PATCH https://api.codespar.dev/v1/sessions/ses_abc123/tool-calls/tc_rec_abc123 \
  -H "Authorization: Bearer csk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "result": {
      "payment_id": "pay_ext_001",
      "status": "paid",
      "paid_at": "2026-04-15T10:51:00Z"
    }
  }'

Response -- `200 OK`

{
  "id": "tc_rec_abc123",
  "session_id": "ses_abc123",
  "name": "codespar_pay",
  "status": "completed",
  "result": {
    "payment_id": "pay_ext_001",
    "status": "paid",
    "paid_at": "2026-04-15T10:51:00Z"
  },
  "updated_at": "2026-04-15T10:51:05Z"
}

GET /v1/health

Consolidated health check across the six router subsystems: db, vault, embeddings, fx_rates, telemetry, connections. Always returns 200 OK regardless of individual check status: monitors should parse the status field, not the HTTP code.

Auth required: Yes (dual-auth: API key or service key).

curl example

curl https://api.codespar.dev/v1/health \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- `200 OK`

{
  "status": "healthy",
  "checks": {
    "db": { "status": "healthy", "latency_ms": 12 },
    "vault": { "status": "healthy", "latency_ms": 8 },
    "embeddings": { "status": "healthy", "latency_ms": 41 },
    "fx_rates": { "status": "healthy", "stale_seconds": 312 },
    "telemetry": { "status": "healthy" },
    "connections": { "status": "healthy", "count": 47 }
  },
  "schema_version": { "current": 64, "expected": 64 },
  "observed_at": "2026-05-04T18:30:00Z"
}

The top-level status rolls up to healthy, degraded, or down. State transitions emit system.health.degraded and system.health.recovered events to operator webhooks.

GET /health

Unauthenticated liveness probe. No subsystem detail; use /v1/health for that.

curl example

curl https://api.codespar.dev/health

Response -- `200 OK`

{
  "status": "ok",
  "uptime_ms": 8421305
}

Async settlement

codespar_charge, codespar_pay, and codespar_kyc return immediately with a tool_call_id. Settlement happens on the provider's clock: Pix in seconds, cards in minutes, Boleto and ACH in days. Blocking the agent's request for that window is not workable, so the tool call and the settlement are decoupled. You poll or stream the status endpoints below until a terminal state.

Correlation chain

Three identifiers connect a tool call to the provider webhook that settles it:

tool_call_id: returned by the SDK or POST /v1/sessions/:id/execute. Opaque. Use it as the path parameter on every status endpoint.
idempotency_key: a UUID the backend generates, stores on the tool-call record, and forwards upstream in the provider's idempotency or external-reference field.
external_reference: what the provider echoes back in its webhook payload.

When the webhook arrives, the backend normalizes it into an event keyed by external_reference and matches that against the tool call's idempotency_key. Until a matching event lands, the status endpoints return { "status": "pending" }.

Where the idempotency key lands, per provider

The backend writes the same UUID into whichever field the provider supports. You only need this table when debugging a webhook that did not correlate.

Provider	Field
Asaas	`externalReference` body field, echoed on every webhook
Mercado Pago	`X-Idempotency-Key` header plus `external_reference` body field
Stripe	`Idempotency-Key` header, surfaced on the resulting object's metadata
iugu	`idempotency_key` body field, echoed on webhooks
Stone	`idempotency_key` body field, echoed on webhooks

One caveat: Mercado Pago's webhook payload omits external_reference and carries only the payment ID. On receipt, the backend fetches the payment from the Mercado Pago API (5 second timeout) to recover the reference before normalizing. If that fetch fails, the event lands without a reference and the status endpoint keeps returning pending until reconciled. Nothing to configure; noted here so the missing field in MP's own webhook docs does not surprise you.

Polling or streaming

Both read the same events, so they always agree. Poll (payment-status, verification-status) for one-off checks and batch reconciliation jobs that walk many tool calls on a schedule. Stream for live UX and long settlement windows where latency to terminal matters; see Streaming status.

Streaming status

Two SDK methods push settlement state over Server-Sent Events instead of polling:

session.paymentStatusStream(toolCallId, opts) for codespar_charge / codespar_pay
session.verificationStatusStream(toolCallId, opts) for codespar_kyc

Both wrap a single GET to /v1/tool-calls/:id/<status>/stream that opens a long-lived text/event-stream response. The wrapper parses frames, fires callbacks, and resolves on terminal.

Event shape

Event	When	Payload
`snapshot`	Once, immediately on connect	Current state of the tool call, often `pending`
`update`	On each state change after connect; zero or more	The new status envelope
`done`	Once, 5 seconds after the state goes terminal, then the connection closes	The final envelope

snapshot is guaranteed first, done guaranteed last. A frame on the wire:

event: update
data: {"status":"completed","tool_call_id":"tc_xyz789","final_amount_minor":9990,"settled_at":"2026-04-15T10:35:12Z"}

Heartbeats

Every 15 seconds the server emits a comment frame:

: heartbeat 1713178215000

Heartbeats keep proxies from idle-closing quiet streams. Comment frames are not events: clients scanning for event: lines skip them naturally, and the TypeScript and Python wrappers filter them so your update callback never fires on a heartbeat.

Callbacks and cancellation

Awaiting the method resolves with the final envelope. Pass onUpdate to observe every transition, and an AbortSignal to drop the stream before terminal:

const ac = new AbortController();
setTimeout(() => ac.abort(), 60_000); // give up after 60s

const final = await session.paymentStatusStream(charge.tool_call_id, {
  onUpdate: (env) => console.log(env.observed_at, env.status),
  signal: ac.signal, // rejects with AbortError if aborted before terminal
});

In Python, payment_status_stream takes on_update and cancels like any awaitable:

task = asyncio.create_task(
    session.payment_status_stream(charge["tool_call_id"], on_update=print),
)
try:
    final = await asyncio.wait_for(task, timeout=60)
except asyncio.TimeoutError:
    task.cancel()  # status not yet terminal

A synchronous wrapper on Session blocks the calling thread until terminal, for non-async callers.

Aborting the stream does not cancel the payment or the verification; it only stops watching. State lives server-side, so you can reconnect or fall back to polling at any time.

GET /v1/tool-calls/:id/payment-status

Polling endpoint for async payment settlement against codespar_charge and codespar_pay tool calls. Returns { status: "pending" } until the provider webhook correlates the call (see Async settlement); on settlement, returns the final amount and settlement timestamp.

Auth required: Yes

curl example

curl https://api.codespar.dev/v1/tool-calls/tc_xyz789/payment-status \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- `200 OK` (settled)

{
  "status": "completed",
  "idempotency_key": "idem_5f3a...",
  "external_reference": "asaas_pay_abc123",
  "final_amount_minor": 9990,
  "settled_at": "2026-04-15T10:35:12Z"
}

Response -- `200 OK` (pending)

{
  "status": "pending"
}

SDK equivalent

const status = await session.paymentStatus("tc_xyz789");

GET /v1/tool-calls/:id/payment-status/stream

Server-Sent Events variant of payment-status. Emits snapshot, update, and done events with a 15s comment heartbeat; see Streaming status for the full event contract, callbacks, and cancellation. The polling sibling stays available, clients pick whichever fits their runtime.

Auth required: Yes

curl example

curl -N https://api.codespar.dev/v1/tool-calls/tc_xyz789/payment-status/stream \
  -H "Authorization: Bearer csk_live_abc123..."

Stream output

event: snapshot
data: {"status":"pending"}

event: update
data: {"status":"completed","final_amount_minor":9990,"settled_at":"2026-04-15T10:35:12Z"}

event: done
data: {"status":"completed"}

SDK equivalent

await session.paymentStatusStream("tc_xyz789", {
  onUpdate: (s) => console.log(s.status),
});

GET /v1/tool-calls/:id/verification-status

Polling endpoint for async KYC settlement against codespar_kyc inquiries. Status priority is approved > rejected > review > expired > pending when multiple events have been recorded.

Auth required: Yes

curl example

curl https://api.codespar.dev/v1/tool-calls/tc_kyc456/verification-status \
  -H "Authorization: Bearer csk_live_abc123..."

Response -- `200 OK`

{
  "status": "approved",
  "idempotency_key": "idem_kyc_a1b2...",
  "external_reference": "persona_inq_xyz",
  "settled_at": "2026-04-15T10:36:00Z"
}

SDK equivalent

const status = await session.verificationStatus("tc_kyc456");

GET /v1/tool-calls/:id/verification-status/stream

SSE variant of verification-status. Same event contract as the payment-status stream (see Streaming status), with the verification terminal vocabulary (approved, rejected, review, expired). Polling sibling stays available.

Auth required: Yes

curl example

curl -N https://api.codespar.dev/v1/tool-calls/tc_kyc456/verification-status/stream \
  -H "Authorization: Bearer csk_live_abc123..."

SDK equivalent

await session.verificationStatusStream("tc_kyc456", {
  onUpdate: (s) => console.log(s.status),
});

GET /v1/meta-tools/stats

Per-(provider × canonical_tool) router observability rollup. Reports attempt counts, success counts, and p50 latency for each rail in META_TOOL_CATALOG. Powers the /dashboard/router observability page.

Auth required: Operator/service auth only. This is a dashboard-internal observability rollup, not part of the agent (Bearer-key) surface: a csk_ API key answers 401, and the credential that does open it is CodeSpar's platform secret, which never leaves our infrastructure. Read this rollup at /dashboard/router; the shape below is what that page renders.

Request

GET /v1/meta-tools/stats

Response -- `200 OK`

{
  "rows": [
    {
      "canonical_tool": "codespar_pay",
      "provider_id": "asaas",
      "attempts": 1284,
      "successes": 1271,
      "p50_ms": 412
    },
    {
      "canonical_tool": "codespar_charge",
      "provider_id": "mercadopago",
      "attempts": 902,
      "successes": 897,
      "p50_ms": 318
    }
  ]
}

GET /v1/meta-tools/stats/hourly

Same shape as /v1/meta-tools/stats but bucketed into the last 24 hourly windows for a single provider+tool pair. Used to render router latency/error sparklines.

Auth required: Operator/service auth only (dashboard-internal; not callable with a csk_ API key).

Query parameters

Parameter	Type	Required	Description
`provider_id`	`string`	Yes	Provider identifier (e.g., `asaas`)
`canonical_tool`	`string`	Yes	Canonical meta-tool (e.g., `codespar_pay`)

Request

GET /v1/meta-tools/stats/hourly?provider_id=asaas&canonical_tool=codespar_pay

Response -- `200 OK`

{
  "provider_id": "asaas",
  "canonical_tool": "codespar_pay",
  "buckets": [
    { "hour": "2026-05-04T18:00:00Z", "attempts": 54, "successes": 53, "p50_ms": 408 },
    { "hour": "2026-05-04T17:00:00Z", "attempts": 61, "successes": 60, "p50_ms": 412 }
  ]
}

POST /v1/connections/hmac-validate

Round-trip validation for the hmac_signed auth_type. The dashboard calls this when an operator pastes a key + secret pair into the connect modal: the backend signs a probe request against the provider and reports whether the credentials produced a valid signature on the wire.

Auth required: Yes

Request body

Field	Type	Required	Description
`server_id`	`string`	Yes	Provider identifier (e.g., `foxbit`)
`key`	`string`	Yes	Signing key
`secret`	`string`	Yes	Signing secret

curl example

curl -X POST https://api.codespar.dev/v1/connections/hmac-validate \
  -H "Authorization: Bearer csk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "foxbit",
    "key": "fx_key_abc",
    "secret": "fx_secret_xyz"
  }'

Response -- `200 OK`

{
  "valid": true,
  "probed_endpoint": "GET /rest/v3/me"
}

Response -- `200 OK` (invalid)

{
  "valid": false,
  "probed_endpoint": "GET /rest/v3/me",
  "provider_status": 401,
  "provider_message": "Invalid signature"
}

Error responses

All endpoints follow a consistent error format:

{
  "error": "error_code",
  "message": "Human-readable error description.",
  "status": 400
}

Status	Error code	Description	Resolution
`400`	`invalid_request`	Missing required fields or invalid values	Check the request body against the schema
`401`	`unauthorized`	Invalid or missing API key	Verify the `Authorization` header
`403`	`forbidden`	API key lacks the required scope	Check key scopes in the dashboard
`404`	`not_found`	Session or resource not found	Verify the session ID; the session may have been closed
`429`	`rate_limited`	Too many requests	Wait and retry; check `Retry-After` header
`429`	`quota_exceeded`	Monthly tool call quota exceeded	Upgrade your plan or wait for the next billing cycle
`500`	`internal_error`	Server error	Retry with exponential backoff; contact support if persistent
`503`	`server_unavailable`	MCP server is temporarily unavailable	The specific provider may be down; retry or use an alternative server

Rate limit headers

Every response includes rate limit information:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1713178260

Next steps

CONCEPT

Sessions

Lifecycle, presets, connection management: the mental model.

REFERENCE

Tools API

Execute tools, list them, search by intent within a session.

REFERENCE

Servers API

Browse the full MCP server catalog.

CONCEPT

Authentication

API key types, scopes, rotation, and service auth.

Every operation, from the spec

Generated from the published OpenAPI document, so it never drifts from what the API actually serves. The section above is written by hand and carries what a schema cannot: the object model, field rules, and the order to call things in.

GET `/v1/sessions`

List sessions

Query parameters

Name	Type	Required	Description
`before`	`string`	no	—
`limit`	`integer`	no	—
`status`	`"active"` \| `"closed"` \| `"error"`	no	—
`user_id`	`string`	no	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	Bad Request — the body or query did not match the schema.

Response 200

Field	Type	Required	Description
`next_before`	`string,null`	yes	—
`sessions`	array of Session	yes	—

Example response

{
  "sessions": [
    {
      "id": "ses_0000000000000000",
      "org_id": "org_0000000000000000",
      "project_id": "prj_0000000000000000",
      "user_id": "user_0000000000000000",
      "servers": [
        "string"
      ],
      "status": "active",
      "created_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Example request

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

POST `/v1/sessions`

Open a session

Request body

Field	Type	Required	Description
`chaos`	object	no	—
`mocks`	object	no	—
`servers`	array of `string`	yes	—
`user_id`	`string`	no	—

Responses

Status	Body	Description
`201`	Session	OK
`400`	object \| object	Bad Request — schema failure, or an unknown server id.
`403`	object	OK
`413`	object	OK

Response 201

Field	Type	Required	Description
`closed_at`	`string,null (date-time)`	no	—
`created_at`	`string (date-time)`	yes	—
`id`	`string`	yes	`ses_`-prefixed
`org_id`	`string`	yes	—
`project_id`	`string`	yes	—
`servers`	array of `string`	yes	—
`status`	`"active"` \| `"closed"` \| `"error"`	yes	—
`user_id`	`string`	yes	—

Example response

{
  "id": "ses_0000000000000000",
  "org_id": "org_0000000000000000",
  "project_id": "prj_0000000000000000",
  "user_id": "user_0000000000000000",
  "servers": [
    "string"
  ],
  "status": "active",
  "created_at": "2026-01-15T12:00:00.000Z"
}

Example request

curl -X POST https://api.codespar.dev/v1/sessions \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "servers": [
         "string"
       ],
       "user_id": "user_0000000000000000",
       "mocks": {},
       "chaos": {}
     }'

GET `/v1/sessions/{id}`

Read one session

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Responses

Status	Body	Description
`200`	object	OK
`404`	object	Not Found

Response 200

Field	Type	Required	Description
`closed_at`	`string,null (date-time)`	no	—
`created_at`	`string (date-time)`	yes	—
`id`	`string`	yes	`ses_`-prefixed
`org_id`	`string`	yes	—
`project_id`	`string`	yes	—
`servers`	array of `string`	yes	—
`status`	`"active"` \| `"closed"` \| `"error"`	yes	—
`tool_calls_count`	`integer`	yes	—
`user_id`	`string`	yes	—

Example response

{
  "id": "obj_0000000000000000",
  "org_id": "org_0000000000000000",
  "project_id": "prj_0000000000000000",
  "user_id": "user_0000000000000000",
  "servers": [
    "string"
  ],
  "status": "active",
  "created_at": "2026-01-15T12:00:00.000Z",
  "tool_calls_count": 1
}

Example request

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

DELETE `/v1/sessions/{id}`

Close a session

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Responses

Status	Body	Description
`200`	object	OK
`404`	object	Not Found

Response 200

Field	Type	Required	Description
`closed_at`	`string,null (date-time)`	yes	—
`id`	`string`	yes	—
`status`	`"closed"`	yes	—

Example response

{
  "id": "obj_0000000000000000",
  "status": "closed"
}

Example request

curl -X DELETE https://api.codespar.dev/v1/sessions/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET `/v1/sessions/{id}/connections`

List a session's servers and the tools it can call

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Responses

Status	Body	Description
`200`	object	OK
`404`	object	Not Found

Response 200

Field	Type	Required	Description
`servers`	array of object	yes	—
`tools`	array of object	yes	—

Example response

{
  "servers": [
    {
      "id": "obj_0000000000000000",
      "name": "Example",
      "category": "string",
      "country": "string",
      "auth_type": "string",
      "connected": true
    }
  ],
  "tools": [
    {
      "name": "Example",
      "description": "string",
      "input_schema": {
        "type": "object",
        "properties": {},
        "required": [
          "string"
        ]
      },
      "server": "codespar"
    }
  ]
}

Example request

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

POST `/v1/sessions/{id}/execute`

Run one tool in the session

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Request body

Field	Type	Required	Description
`estimatedCost`	`number`	no	—
`input`	object	no	—
`params`	object	no	—
`tool`	`string`	yes	—

Responses

Status	Body	Description
`200`	object \| object	OK. The full envelope, or the short unregistered-tool envelope that carries no `tool_call_id` and no `called_at`.
`400`	object	Bad Request — the body or query did not match the schema.
`403`	object \| object	Forbidden — either a policy rule refused the call, or the org's monthly tool-call allowance is spent. The two bodies are disjoint: the policy one is `\{ reason, ruleType, ruleId \}` and carries NO `error` key (plus `approval_id` and `expires_at` when the refusal opened a pending approval); the quota one is `\{ error: "quota_exceeded", ... \}`.
`404`	object	Not Found
`409`	object	Conflict — the session is not `active`, so it dispatches nothing.
`422`	object	Unprocessable — the session declares mocks and this tool has none left, or none at all. `tool_name` is present only on `tool_not_mocked`. Reached from the catalog branch; a meta-tool never answers 422.
`503`	object \| object	Service Unavailable — the route's policy guard could not answer (`\{ error: "policy_engine_error" \}`), or the mock engine failed (`\{ code: "mocks_engine_error", message \}`). Two different bodies at the same status.

Example response

{
  "success": true,
  "duration": 0,
  "server": "string",
  "tool": "string",
  "tool_call_id": "tc_0000000000000000",
  "called_at": "string"
}

Example request

curl -X POST https://api.codespar.dev/v1/sessions/{id}/execute \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "tool": "string",
       "params": {},
       "input": {},
       "estimatedCost": 0
     }'

GET `/v1/sessions/{id}/mocks`

Read a session's declared mocks and their consume counters

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Responses

Status	Body	Description
`200`	object	OK
`404`	object	Not Found

Response 200

Field	Type	Required	Description
`counters`	object	yes	—
`mocks`	`object,null`	yes	—

Example response

{
  "counters": {}
}

Example request

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

POST `/v1/sessions/{id}/proxy_execute`

Make one raw HTTP call to a connected server

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Request body

Field	Type	Required	Description
`body`	—	no	—
`endpoint`	`string`	yes	—
`estimatedCost`	`number`	no	—
`headers`	object	no	—
`method`	`"GET"` \| `"POST"` \| `"PUT"` \| `"PATCH"` \| `"DELETE"`	yes	—
`params`	object	no	—
`server`	`string`	yes	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object \| object	Bad Request — the body did not match the schema, or `server` is not one of the ids this session was opened on. The second body names the connected servers and points at the pre-connected sandbox meta-tool instead.
`403`	object \| object	Forbidden — either a policy rule refused the call, or the org's monthly tool-call allowance is spent. The two bodies are disjoint: the policy one is `\{ reason, ruleType, ruleId \}` and carries NO `error` key (plus `approval_id` and `expires_at` when the refusal opened a pending approval); the quota one is `\{ error: "quota_exceeded", ... \}`.
`404`	object	Not Found
`409`	object	Conflict — the session is not `active`, so it dispatches nothing.
`413`	object	Payload Too Large — the serialized tool input exceeded the policy engine's cap under an `approval-required` rule. Not a policy denial: 403 and 413 are kept apart so a client can tell "refused" from "too big".
`424`	object	Failed Dependency — no usable credential for this server. `reason` is the resolver's own outcome.
`429`	object	Too Many Requests — the per-(org, server) bucket is empty. See the `Retry-After` header.
`502`	object	Bad Gateway — the upstream call itself failed (transport, not status). The attempt is still logged and chained, and `proxy_call_id` names the row.
`503`	object	Service Unavailable — the policy engine could not answer. Fail-closed: the call did not run. Distinct from a 403, which is a decision that was taken.

Response 200

Field	Type	Required	Description
`data`	—	no	—
`duration`	`number`	yes	—
`headers`	object	yes	—
`proxy_call_id`	`string`	yes	`px_`-prefixed id of the logged call.
`status`	`integer`	yes	The UPSTREAM status code, not this call's.

Example response

{
  "status": 0,
  "headers": {},
  "duration": 0,
  "proxy_call_id": "proxycall_0000000000000000"
}

Example request

curl -X POST https://api.codespar.dev/v1/sessions/{id}/proxy_execute \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "server": "string",
       "endpoint": "https://example.com/hook",
       "method": "GET",
       "params": {},
       "headers": {},
       "estimatedCost": 0
     }'

POST `/v1/sessions/{id}/send`

Drive a model loop that may call tools

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Request body

Field	Type	Required	Description
`message`	`string`	yes	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	Bad Request — the body or query did not match the schema.
`403`	object	Forbidden — the org's monthly tool-call allowance is spent.
`404`	object	Not Found
`409`	object	Conflict — the session is not `active`, so it dispatches nothing.
`500`	object	Internal Server Error — the loop failed mid-flight. Carries the work that already completed, in the same fields as the 200.
`503`	object	Service Unavailable — this deployment has no model credential configured.

Response 200

Field	Type	Required	Description
`aborted`	`true`	no	—
`iterations`	`integer`	yes	—
`message`	`string`	yes	The model's last text turn. Empty when it ended on a tool call.
`tool_calls`	array of object	yes	—

Example response

{
  "message": "string",
  "tool_calls": [
    {
      "id": "obj_0000000000000000",
      "tool_name": "Example",
      "server_id": "srv_0000000000000000",
      "status": "success",
      "duration_ms": 0
    }
  ],
  "iterations": 0,
  "aborted": true
}

Example request

curl -X POST https://api.codespar.dev/v1/sessions/{id}/send \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "message": "string"
     }'

GET `/v1/sessions/{id}/tool-calls`

List one session's tool calls

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Query parameters

Name	Type	Required	Description
`limit`	`integer`	no	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	Bad Request — the body or query did not match the schema.
`404`	object	Not Found

Response 200

Field	Type	Required	Description
`tool_calls`	array of ToolCall	yes	—

Example response

{
  "tool_calls": [
    {
      "id": "tc_0000000000000000",
      "session_id": "ses_0000000000000000",
      "server_id": "srv_0000000000000000",
      "tool_name": "Example",
      "status": "running",
      "called_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Example request

curl -X GET https://api.codespar.dev/v1/sessions/{id}/tool-calls \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

POST `/v1/sessions/{id}/tool-calls`

Record a tool call the client executed

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Request body

Field	Type	Required	Description
`duration_ms`	`integer`	no	—
`error_code`	`string`	no	—
`input`	—	no	—
`output`	—	no	—
`server_id`	`string`	yes	—
`status`	`"running"` \| `"success"` \| `"error"`	no	—
`tool_name`	`string`	yes	—

Responses

Status	Body	Description
`201`	ToolCall	OK
`400`	object	Bad Request — the body or query did not match the schema.
`404`	object	Not Found
`409`	object	OK

Response 201

Field	Type	Required	Description
`called_at`	`string (date-time)`	yes	—
`duration_ms`	`integer,null`	yes	—
`error_code`	`string,null`	yes	—
`failover_trail`	—	no	—
`id`	`string`	yes	`tc_`-prefixed: the bigserial with a `tc_` prefix prepended
`input`	—	no	—
`output`	—	no	—
`routing`	—	no	—
`server_id`	`string`	yes	—
`session_id`	`string`	yes	—
`status`	`"running"` \| `"success"` \| `"error"`	yes	—
`tool_name`	`string`	yes	—

Example response

{
  "id": "tc_0000000000000000",
  "session_id": "ses_0000000000000000",
  "server_id": "srv_0000000000000000",
  "tool_name": "Example",
  "status": "running",
  "called_at": "2026-01-15T12:00:00.000Z"
}

Example request

curl -X POST https://api.codespar.dev/v1/sessions/{id}/tool-calls \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "server_id": "srv_0000000000000000",
       "tool_name": "Example",
       "status": "running",
       "duration_ms": 0,
       "error_code": "string"
     }'

PATCH `/v1/sessions/{id}/tool-calls/{tc_id}`

Finalize a recorded tool call

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—
`tc_id`	`string`	yes	`tc_`-prefixed

Request body

Field	Type	Required	Description
`duration_ms`	`integer`	no	—
`error_code`	`string,null`	no	—
`output`	—	no	—
`status`	`"success"` \| `"error"`	no	—

Responses

Status	Body	Description
`200`	ToolCall	OK
`400`	object	Bad Request — the body or query did not match the schema.
`404`	object	Not Found

Response 200

Field	Type	Required	Description
`called_at`	`string (date-time)`	yes	—
`duration_ms`	`integer,null`	yes	—
`error_code`	`string,null`	yes	—
`failover_trail`	—	no	—
`id`	`string`	yes	`tc_`-prefixed: the bigserial with a `tc_` prefix prepended
`input`	—	no	—
`output`	—	no	—
`routing`	—	no	—
`server_id`	`string`	yes	—
`session_id`	`string`	yes	—
`status`	`"running"` \| `"success"` \| `"error"`	yes	—
`tool_name`	`string`	yes	—

Example response

{
  "id": "tc_0000000000000000",
  "session_id": "ses_0000000000000000",
  "server_id": "srv_0000000000000000",
  "tool_name": "Example",
  "status": "running",
  "called_at": "2026-01-15T12:00:00.000Z"
}

Example request

curl -X PATCH https://api.codespar.dev/v1/sessions/{id}/tool-calls/{tc_id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "status": "success",
       "duration_ms": 0
     }'

Sessions

On this page