HTTP API reference for listing, searching, and inspecting tool definitions available in a CodeSpar session.

Tools API

The Tools API lets you list and inspect the tools available in a session. Tools are JSON Schema-defined functions that your agent can call to perform commerce operations.

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

All endpoints require authentication via Bearer token. See Authentication.

List a session's tools (MCP `tools/list`)

The session tool list is served over the session's MCP transport, not a bare REST route: send a JSON-RPC tools/list to POST /v1/sessions/:id/mcp (or call session.tools() in the SDK, which does this for you). The list contains the meta-tools plus any server-specific tools the session's connections expose.

Auth required: Yes (scope: tools:execute on the MCP POST surface)

curl example

curl -X POST https://api.codespar.dev/v1/sessions/ses_abc123/mcp \
  -H "Authorization: Bearer csk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Response -- `200 OK` (JSON-RPC result)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "codespar_pay",
        "description": "Send money on LATAM rails (Pix and more) under mandate governance",
        "inputSchema": {
          "type": "object",
          "properties": {
            "method": { "type": "string", "description": "Payment method (rail), e.g. pix" },
            "amount": { "type": "integer", "description": "Amount in minor units" },
            "currency": { "type": "string", "description": "ISO 4217 currency code" },
            "recipient": { "type": "string", "description": "Pix key or account identifier" }
          },
          "required": ["amount", "currency", "recipient"]
        }
      },
      {
        "name": "codespar_discover",
        "description": "Search the catalog for tools and capabilities by intent"
      }
    ]
  }
}

POST /v1/sessions/:id/execute

Executes a tool call within the session. Routes the call to the appropriate MCP server and returns the result.

Auth required: Yes (scope: tools:execute)

Path parameters

Parameter	Type	Description
`id`	`string`	Session ID

Request body

Field	Type	Required	Description
`tool`	`string`	Yes	Tool name (e.g., `codespar_pay`)
`params`	`object`	Yes	Tool input parameters 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 '{
    "tool": "codespar_pay",
    "params": {
      "method": "pix",
      "amount": 15000,
      "currency": "BRL",
      "description": "Order #1234"
    }
  }'

Response -- `200 OK`

{
  "success": true,
  "data": {
    "payment_id": "pay_xyz789",
    "pix_qr_code": "00020126580014br.gov.bcb...",
    "pix_copy_paste": "00020126580014br.gov.bcb.pix...",
    "amount": 15000,
    "currency": "BRL",
    "status": "pending",
    "expires_at": "2026-04-18T23:59:59Z"
  },
  "error": null,
  "duration": 430,
  "server": "asaas",
  "tool": "codespar_pay",
  "tool_call_id": "tc_9f8e7d6c",
  "called_at": "2026-04-17T15:30:00Z"
}

Error response -- `400 Bad Request`

{
  "success": false,
  "data": null,
  "error": "Invalid parameter: amount must be a positive integer",
  "duration": 12,
  "server": "codespar",
  "tool": "codespar_pay"
}

POST /v1/tools/search

Searches the meta-tool surface by natural-language intent. Not session-scoped: the classifier ranks which meta-tool fits the intent, with a keyword fallback when the classifier is unavailable (the endpoint degrades, it doesn't error).

Auth required: Yes

Request body

Field	Type	Required	Description
`intent`	`string`	Yes	Natural language description of what you want to do
`limit`	`int`	No	Max hits to return

curl example

curl -X POST https://api.codespar.dev/v1/tools/search \
  -H "Authorization: Bearer csk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "intent": "process a Pix payment" }'

Response -- `200 OK`

{
  "intent": "process a Pix payment",
  "hits": [
    {
      "tool_name": "codespar_pay",
      "confidence": "high",
      "rationale": "outbound Pix payment matches the pay meta-tool"
    },
    {
      "tool_name": "codespar_charge",
      "confidence": "medium",
      "rationale": "if the goal is to COLLECT a Pix payment from a buyer"
    }
  ],
  "elapsed_ms": 420,
  "source": "llm"
}

source is "llm" when the classifier ran and "fallback" when the keyword heuristic answered. In-catalog tool search (raw provider tools, not meta-tools) is exposed to agents via the codespar_discover meta-tool.

Next steps

REFERENCE

Sessions API

Create, list, close sessions — the container for tool execution.

REFERENCE

Servers API

Browse the MCP server catalog and filter by category or country.

CONCEPT

Tools & Meta-Tools

How the meta-tools route to the right MCP server.

REFERENCE

SDK Reference

Every TypeScript method for session.execute and tool search.

Tools API

On this page