HTTP API reference for managing server connections and OAuth flows within CodeSpar sessions.

Connections API

The Connections API lets you inspect and manage the server connections within a session. Each connection represents an active link between the session and an MCP server, with its authentication status and available tools.

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

All endpoints require authentication via Bearer token. See Authentication.

GET /v1/sessions/:id/connections

Returns all server connections in the session with their status and tool counts.

Auth required: Yes (scope: sessions:read)

Path parameters

Parameter	Type	Description
`id`	`string`	Session ID

curl example

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

Response -- `200 OK`

{
  "data": [
    {
      "id": "stripe",
      "name": "Stripe",
      "category": "payments",
      "country": "GLOBAL",
      "auth_type": "api_key",
      "connected": true,
      "tools_count": 8,
      "status": "ready"
    },
    {
      "id": "mercadopago",
      "name": "Mercado Pago",
      "category": "payments",
      "country": "BR",
      "auth_type": "oauth",
      "connected": true,
      "tools_count": 6,
      "status": "ready"
    },
    {
      "id": "correios",
      "name": "Correios",
      "category": "logistics",
      "country": "BR",
      "auth_type": "api_key",
      "connected": true,
      "tools_count": 4,
      "status": "ready"
    }
  ],
  "total": 3,
  "session_id": "ses_abc123"
}

GET /v1/sessions/:id/connections/:serverId

Returns detailed information about a specific server connection, including all available tools.

Auth required: Yes (scope: sessions:read)

Path parameters

Parameter	Type	Description
`id`	`string`	Session ID
`serverId`	`string`	Server identifier (e.g., `stripe`)

Response -- `200 OK`

{
  "id": "stripe",
  "name": "Stripe",
  "category": "payments",
  "country": "GLOBAL",
  "auth_type": "api_key",
  "connected": true,
  "status": "ready",
  "capabilities": ["credit_card", "debit_card", "checkout_link", "subscription", "refund"],
  "tools": [
    {
      "name": "stripe_create_payment_intent",
      "description": "Create a Stripe PaymentIntent for card payments"
    },
    {
      "name": "stripe_create_checkout",
      "description": "Create a Stripe Checkout session"
    }
  ],
  "connected_at": "2026-04-17T15:30:00Z",
  "latency_ms": 120
}

POST /v1/sessions/:id/connections/:serverId/authorize

Initiates an OAuth flow for servers that require user-level authentication (e.g., Mercado Pago, Google, Shopify).

Auth required: Yes (scope: sessions:write)

Path parameters

Parameter	Type	Description
`id`	`string`	Session ID
`serverId`	`string`	Server identifier

Request body

Field	Type	Required	Description
`redirect_url`	`string`	No	URL to redirect after OAuth completes
`scopes`	`string[]`	No	Override default OAuth scopes

Response -- `200 OK`

{
  "connected": false,
  "redirect_url": "https://auth.mercadopago.com/authorization?client_id=...&redirect_uri=...",
  "state": "oauth_abc123",
  "expires_at": "2026-04-17T16:00:00Z"
}

After the user completes OAuth, the connection status changes to connected: true and the server's tools become available in the session.

DELETE /v1/sessions/:id/connections/:serverId

Disconnects a server from the session. Its tools will no longer be available.

Auth required: Yes (scope: sessions:write)

Response -- `204 No Content`

No response body.

Error codes

Code	Description
`404`	Session or server not found
`409`	Server already connected / already disconnected
`422`	Server requires OAuth but no redirect URL provided

Next steps

Sessions API — Create and manage sessions
Tools API — List and execute tools
Servers API — Browse the server catalog
Authentication — API keys and OAuth

Connections API

On this page