Complete HTTP API reference for creating, managing, and interacting with CodeSpar sessions, including tool execution and connection management.

Sessions API

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

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
`servers`	`string[]`	Yes*	List of server identifiers (e.g., `["stripe", "mercadopago"]`)
`preset`	`string`	No	Named preset: `payments`, `ecommerce`, `fiscal`, `logistics`, `messaging`, `brazilian`, `mexican`, `argentine`
`manageConnections`	`boolean`	No	Enable OAuth connection management for servers requiring user-level auth. Default: `false`

*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 '{
    "servers": ["stripe", "mercadopago"],
    "manageConnections": false
  }'

Response -- `201 Created`

{
  "id": "ses_abc123def456",
  "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.sessions.create({
  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 organization. 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 (scope: sessions:create)

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 (scope: tools:execute)

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({
  name: "codespar_pay",
  arguments: { 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 tool call for asynchronous execution. Returns immediately with a queued status. Use this for fire-and-forget operations like notifications.

Auth required: Yes (scope: tools:execute)

Request body

Field	Type	Required	Description
`name`	`string`	Yes	Tool name
`arguments`	`object`	Yes	Tool arguments matching the tool's `input_schema`

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 '{
    "name": "codespar_notify",
    "arguments": {
      "channel": "whatsapp",
      "to": "+5511999999999",
      "template": "order_shipped",
      "variables": {
        "customerName": "Maria",
        "trackingCode": "BR123456789"
      }
    }
  }'

Response -- `202 Accepted`

{
  "tool_call_id": "tc_msg_abc123",
  "name": "codespar_notify",
  "status": "queued",
  "queued_at": "2026-04-15T10:46:00Z"
}

SDK equivalent

await session.send({
  name: "codespar_notify",
  arguments: {
    channel: "whatsapp",
    to: "+5511999999999",
    template: "order_shipped",
    variables: { customerName: "Maria", trackingCode: "BR123456789" },
  },
});

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 (scope: sessions:read)

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`	`50`	Results per page (max 100)
`offset`	`number`	`0`	Pagination offset

curl example

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

Response -- `200 OK`

{
  "data": [
    {
      "id": "tc_001",
      "name": "codespar_discover",
      "arguments": { "domain": "payments" },
      "status": "completed",
      "execution_time_ms": 67,
      "created_at": "2026-04-15T10:30:05Z"
    },
    {
      "id": "tc_002",
      "name": "codespar_pay",
      "arguments": { "method": "pix", "amount": 9990, "currency": "BRL" },
      "status": "completed",
      "execution_time_ms": 342,
      "created_at": "2026-04-15T10:30:12Z"
    },
    {
      "id": "tc_003",
      "name": "codespar_notify",
      "arguments": { "channel": "whatsapp", "to": "+5511999999999" },
      "status": "completed",
      "execution_time_ms": 189,
      "created_at": "2026-04-15T10:30:15Z"
    }
  ],
  "total": 3,
  "limit": 5,
  "offset": 0
}

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 (scope: tools:execute)

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

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

Servers API -- Browse the server catalog
Sessions concept -- Understanding session lifecycle
Tools and Meta-Tools -- What tools are available
Authentication -- API key management

Sessions API

On this page