> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supersonic.cv/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Call any Supersonic tool via a single HTTP POST endpoint.

All 62 tools are available through one endpoint. Send the tool name and parameters as JSON, get the result back.

## Endpoint

```
POST https://mcp.supersonic.cv/api/developers/mcp/call/
Authorization: Bearer supersonic_live_YOUR_KEY
Content-Type: application/json
```

## Request

```json theme={null}
{
  "tool": "records.list",
  "params": {
    "object_type_slug": "contacts",
    "page_size": 10
  }
}
```

## Response

On success, the tool result is returned directly:

```json theme={null}
{
  "items": [...],
  "total": 42,
  "page": 1
}
```

On error:

```json theme={null}
{
  "error": "Record not found",
  "code": "validation_error"
}
```

## Examples

<CodeGroup>
  ```python Python theme={null}
  import httpx

  API_KEY = "supersonic_live_YOUR_KEY"
  URL = "https://mcp.supersonic.cv/api/developers/mcp/call/"

  def call(tool, params={}):
      r = httpx.post(URL, headers={"Authorization": f"Bearer {API_KEY}"}, json={"tool": tool, "params": params})
      r.raise_for_status()
      return r.json()

  contacts = call("records.list", {"object_type_slug": "contacts"})
  deal = call("records.create", {"object_type_slug": "deals", "data": {"name": "Acme Deal", "value": 50000}})
  results = call("records.search", {"query": "Acme"})
  ```

  ```typescript TypeScript theme={null}
  const API_KEY = "supersonic_live_YOUR_KEY";
  const URL = "https://mcp.supersonic.cv/api/developers/mcp/call/";

  async function call(tool: string, params: Record<string, any> = {}) {
    const res = await fetch(URL, {
      method: "POST",
      headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({ tool, params }),
    });
    return res.json();
  }

  const contacts = await call("records.list", { object_type_slug: "contacts" });
  ```

  ```bash curl theme={null}
  curl -X POST https://mcp.supersonic.cv/api/developers/mcp/call/ \
    -H "Authorization: Bearer supersonic_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{"tool": "records.list", "params": {"object_type_slug": "contacts"}}'
  ```
</CodeGroup>

## Error codes

| Code                    | HTTP Status | Meaning            |
| ----------------------- | ----------- | ------------------ |
| `validation_error`      | 400         | Invalid parameters |
| `permission_denied`     | 403         | Insufficient role  |
| `tool_not_found`        | 404         | Tool doesn't exist |
| `subscription_required` | 403         | Trial expired      |

## Rate limits

1,000 calls per minute per API key. See [Rate Limits](/reference/rate-limits).