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.

GET /v1/sessions/:id/tools

Returns all tools available in the session, including both meta-tools and server-specific tools.

Auth required: Yes (scope: sessions:read)

Path parameters

Parameter	Type	Description
`id`	`string`	Session ID (e.g., `ses_HZb4d5yxIAxLawb4`)

Query parameters

Parameter	Type	Default	Description
`server`	`string`	--	Filter tools by server ID
`q`	`string`	--	Full-text search across tool names and descriptions

curl example

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

Response -- `200 OK`

{
  "data": [
    {
      "name": "codespar_pay",
      "description": "Process a payment via Pix, boleto, credit card, or other methods",
      "input_schema": {
        "type": "object",
        "properties": {
          "method": {
            "type": "string",
            "enum": ["pix", "boleto", "credit_card", "debit_card"],
            "description": "Payment method"
          },
          "amount": {
            "type": "integer",
            "description": "Amount in cents (e.g., 4990 for R$49.90)"
          },
          "currency": {
            "type": "string",
            "enum": ["BRL", "MXN", "ARS", "COP", "USD"],
            "description": "ISO 4217 currency code"
          },
          "provider": {
            "type": "string",
            "description": "Force a specific provider (optional — auto-routed by default)"
          },
          "description": {
            "type": "string",
            "description": "Payment description"
          }
        },
        "required": ["method", "amount", "currency"]
      },
      "server": "codespar"
    },
    {
      "name": "codespar_discover",
      "description": "Find available tools and capabilities for a commerce domain",
      "input_schema": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "enum": ["payments", "fiscal", "logistics", "messaging", "banking", "erp"],
            "description": "Commerce domain to discover"
          }
        },
        "required": ["domain"]
      },
      "server": "codespar"
    }
  ],
  "total": 24,
  "session_id": "ses_abc123"
}

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: sessions: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/sessions/:id/find-tools

Searches for tools by natural language intent. Returns tools ranked by relevance.

Auth required: Yes (scope: sessions:read)

Request body

Field	Type	Required	Description
`intent`	`string`	Yes	Natural language description of what you want to do

curl example

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

Response -- `200 OK`

{
  "data": [
    {
      "name": "codespar_pay",
      "description": "Process a payment via Pix, boleto, credit card, or other methods",
      "relevance": 0.95,
      "server": "codespar"
    },
    {
      "name": "codespar_checkout",
      "description": "Create a checkout session for a product or service",
      "relevance": 0.72,
      "server": "codespar"
    }
  ]
}

Next steps

Sessions API — Create and manage sessions
Servers API — Browse the server catalog
Tools & Meta-Tools — Understand meta-tool routing

Tools API

On this page