API Documentation

Everything you need to integrate ClawToolkit into your AI agents.

Quick Start

Call any tool with a single HTTP request:

curl -X POST https://toolkit.clawlabz.xyz/api/v1/gateway/web-search \
  -H "Authorization: Bearer tk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "latest AI news"}'

Authentication

All API requests require a Bearer token in the Authorization header.

**Option 1: API Key** (recommended for agents)

Authorization: Bearer tk_your_api_key_here

**Option 2: Supabase JWT** (for browser sessions)

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Create API keys in your [Dashboard](/dashboard).

Authorization: Bearer tk_your_api_key_here

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Gateway — Call a Tool

POST /api/v1/gateway/{tool-slug}

Content-Type: application/json

Authorization: Bearer tk_your_api_key

{

"query": "example input"

}

Response:

{

"data": { ... },

"meta": {

"latency_ms": 234,

"cp_cost": 5,

"is_free_tier": false,

"status": "success"

}

**Headers returned:** `X-Toolkit-Latency`, `X-Toolkit-CP-Cost`, `X-Toolkit-Free-Tier`

**Free tier:** 100 calls/tool/month at no cost. After that, CP is deducted per call.

POST /api/v1/gateway/{tool-slug}
Content-Type: application/json
Authorization: Bearer tk_your_api_key

{
  "query": "example input"
}

{
  "data": { ... },
  "meta": {
    "latency_ms": 234,
    "cp_cost": 5,
    "is_free_tier": false,
    "status": "success"
  }
}

Tools API

List tools (public)

GET /api/v1/tools?q=search&sort=popular&category={id}&protocol=mcp&page=1&limit=20

Get tool detail

GET /api/v1/tools/{id-or-slug}

**Create tool** (authenticated)

POST /api/v1/tools

{

"name": "My Tool",

"summary": "Does something useful",

"category_id": "uuid",

"protocol": "rest",

"endpoint_url": "https://api.example.com/v1/action",

"pricing_per_call": 5,

"tags": ["search", "web"]

}

**Update tool** (owner only)

PATCH /api/v1/tools/{id}

{ "summary": "Updated description" }

**Publish tool** (draft → active)

POST /api/v1/tools/{id}/publish

**Delete tool** (soft-delete to archived)

DELETE /api/v1/tools/{id}

GET /api/v1/tools?q=search&sort=popular&category={id}&protocol=mcp&page=1&limit=20

GET /api/v1/tools/{id-or-slug}

POST /api/v1/tools
{
  "name": "My Tool",
  "summary": "Does something useful",
  "category_id": "uuid",
  "protocol": "rest",
  "endpoint_url": "https://api.example.com/v1/action",
  "pricing_per_call": 5,
  "tags": ["search", "web"]
}

PATCH /api/v1/tools/{id}
{ "summary": "Updated description" }

POST /api/v1/tools/{id}/publish

DELETE /api/v1/tools/{id}

MCP Schema Parser

Parse MCP (Model Context Protocol) tool definitions to auto-fill publishing form.

POST /api/v1/tools/parse-mcp

{

"type": "raw",

"json": "{\"name\": \"search\", \"description\": \"Web search\", \"inputSchema\": {...}}"

}

Supported input types:

- `"type": "tool"` — single tool definition

- `"type": "manifest"` — full manifest with `tools[]`

- `"type": "raw"` — raw JSON string (auto-detected)

POST /api/v1/tools/parse-mcp
{
  "type": "raw",
  "json": "{\"name\": \"search\", \"description\": \"Web search\", \"inputSchema\": {...}}"
}

Billing API

Get balance

GET /api/v1/billing/balance

→ { "balance_cp": 5000, "spent_this_month_cp": 120, "calls_this_month": 45 }

**Top up** (creates Stripe Checkout)

POST /api/v1/billing/topup

{ "amount_usd": 10 }

→ { "checkout_url": "https://checkout.stripe.com/..." }

Withdraw

POST /api/v1/billing/withdraw

{ "amount_cp": 10000 }

**Rate:** $1 = 1,000 CP. Min topup: $5. Min withdraw: 10,000 CP.

Platform fee: 20% on publisher earnings.

GET /api/v1/billing/balance
→ { "balance_cp": 5000, "spent_this_month_cp": 120, "calls_this_month": 45 }

POST /api/v1/billing/topup
{ "amount_usd": 10 }
→ { "checkout_url": "https://checkout.stripe.com/..." }

POST /api/v1/billing/withdraw
{ "amount_cp": 10000 }

API Keys

List keys

GET /api/v1/keys

Create key

POST /api/v1/keys

{ "name": "My Agent Key" }

→ { "key": "tk_abc123...", "key_prefix": "tk_abc123..." }

⚠️ The full key is only shown once at creation. Store it securely.

Revoke key

DELETE /api/v1/keys/{id}

Max 20 active keys per user.

GET /api/v1/keys

POST /api/v1/keys
{ "name": "My Agent Key" }
→ { "key": "tk_abc123...", "key_prefix": "tk_abc123..." }

DELETE /api/v1/keys/{id}

Base URL: https://toolkit.clawlabz.xyz
Rate limits: Auth: 10/min · Gateway: 1000/min · Publish: 5/min · Public: 100/min