API Reference

Full request and response schemas for every tool.

Getting Started

The Clawoop API speaks JSON. Every call needs an API key — no bearer token, no session. Mint a key from your dashboard and send it on every request.

Base URL

https://api.clawoop.com

Authentication

Send your key in the X-API-Key header. Keys are prefixed cl_live_.

X-API-Key: cl_live_abc123...

Quickstart — list available tools

curl https://api.clawoop.com/v1/tools \
  -H "X-API-Key: $CLAWOOP_API_KEY"

Run your first tool

curl -X POST https://api.clawoop.com/v1/run/web-search \
  -H "X-API-Key: $CLAWOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"query": "latest AI news"}}'

Use Cases

Every tool belongs to one or more use cases. Pass a slug as ?use_case= on /v1/tools or as a path param on /v1/use-cases/:slug/tools.

Slug	Name	Description
`trading`	Trading	Real-time market data, price signals, and trend detection for trading decisions.
`research`	Research	Deep research, information gathering, and knowledge synthesis.
`writing`	Writing	Content creation, editing, translation, and long-form writing.
`coding`	Coding	Software development, code generation, and documentation extraction.
`marketing`	Marketing	Campaign content, asset generation, and audience trend analysis.
`sales`	Sales	Prospect research, competitive intelligence, and outreach enrichment.
`support`	Customer support	Ticket triage, knowledge lookup, and response drafting.
`analytics`	Analytics	Data analysis, reporting, and insight generation.
`design`	Design	Visual asset creation, image generation, and creative exploration.
`operations`	Operations	Workflow automation, monitoring, and internal tooling.

Discovery endpoints

List tools

List all enabled tools with their providers and per-call cost. Optionally filter by use case slug.

GET/v1/tools

Query params

Name	Type	Required	Description
`use_case`	`string`	No	Filter tools by use case slug (see Use Cases reference).(e.g. `"trading"`)

Request

curl "https://api.clawoop.com/v1/tools?use_case=trading" \
  -H "X-API-Key: $CLAWOOP_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "name": "financial-data",
      "description": "Get real-time financial market data for stocks and cryptocurrencies.",
      "providers": [
        {
          "name": "finnhub",
          "enabled": true,
          "costPerCall": 0.002
        },
        {
          "name": "coinmarketcap",
          "enabled": true,
          "costPerCall": 0.005
        }
      ]
    },
    {
      "name": "trend-tracking",
      "description": "Track trends for a keyword across search interest and news.",
      "providers": [
        {
          "name": "serpapi",
          "enabled": true,
          "costPerCall": 0.016
        },
        {
          "name": "newsapi",
          "enabled": true,
          "costPerCall": 0.002
        }
      ]
    }
  ],
  "meta": {
    "request_id": "req_lt_abc123"
  }
}

Tool detail

Full detail for a single tool — providers, pricing, use cases, execution mode, and tags.

GET/v1/tools/:name

Path params

Name	Type	Required	Description
`name`	`string`	Yes	Tool name (e.g. translate, web-search, generate-image).(e.g. `"financial-data"`)

Request

curl https://api.clawoop.com/v1/tools/financial-data \
  -H "X-API-Key: $CLAWOOP_API_KEY"

Response

{
  "success": true,
  "data": {
    "name": "financial-data",
    "display_name": "Financial Data",
    "description": "Get real-time financial market data for stocks and cryptocurrencies.",
    "use_cases": [
      {
        "slug": "trading",
        "name": "Trading"
      },
      {
        "slug": "analytics",
        "name": "Analytics"
      },
      {
        "slug": "research",
        "name": "Research"
      }
    ],
    "tags": [
      "finance",
      "market-data"
    ],
    "execution_mode": "sync",
    "estimated_seconds": null,
    "providers": [
      {
        "name": "finnhub",
        "description": "US equities quote and company profile",
        "cost_per_call": 0.002,
        "enabled": true,
        "is_default": true,
        "features": [
          "stocks",
          "profiles"
        ]
      },
      {
        "name": "coinmarketcap",
        "description": "Cryptocurrency market data",
        "cost_per_call": 0.005,
        "enabled": true,
        "is_default": false,
        "features": [
          "crypto",
          "rank",
          "dominance"
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_td_def456"
  }
}

Tool JSON Schema

Draft-07 JSON Schema for a tool, optimized for LLM function calling. Use as the function/tool definition in your agent.

GET/v1/tools/:name/schema

Path params

Name	Type	Required	Description
`name`	`string`	Yes	Tool name.(e.g. `"translate"`)

Request

curl https://api.clawoop.com/v1/tools/translate/schema \
  -H "X-API-Key: $CLAWOOP_API_KEY"

Response

{
  "success": true,
  "data": {
    "name": "translate",
    "description": "Translate text between languages with auto-detection.",
    "input_schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "required": [
        "text",
        "target"
      ],
      "properties": {
        "text": {
          "type": "string",
          "description": "Text to translate"
        },
        "target": {
          "type": "string",
          "description": "Target language code (ISO 639-1)"
        },
        "source": {
          "type": "string",
          "description": "Source language code (auto-detected if omitted)"
        }
      }
    },
    "output_schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "required": [
        "translated_text",
        "source_language",
        "target_language"
      ],
      "properties": {
        "translated_text": {
          "type": "string"
        },
        "source_language": {
          "type": "string"
        },
        "target_language": {
          "type": "string"
        }
      }
    }
  },
  "meta": {
    "request_id": "req_ts_ghi789"
  }
}

Compare providers

Side-by-side provider comparison for a tool — pricing, features, and supported options.

GET/v1/tools/:name/compare

Path params

Name	Type	Required	Description
`name`	`string`	Yes	Tool name.(e.g. `"web-scrape"`)

Request

curl https://api.clawoop.com/v1/tools/web-scrape/compare \
  -H "X-API-Key: $CLAWOOP_API_KEY"

Response

{
  "success": true,
  "data": {
    "tool": "web-scrape",
    "display_name": "Web Scrape",
    "providers": [
      {
        "name": "firecrawl",
        "description": "Full-featured scraper with rendering",
        "cost_per_call": 0.006,
        "is_default": true,
        "features": [
          "render-js",
          "markdown",
          "screenshots"
        ],
        "supported_options": {
          "type": "object",
          "properties": {
            "render_js": {
              "type": "boolean",
              "default": true
            },
            "wait_for": {
              "type": "string"
            }
          }
        }
      },
      {
        "name": "jina",
        "description": "Fast reader-mode scraper",
        "cost_per_call": 0.003,
        "is_default": false,
        "features": [
          "markdown",
          "fast"
        ],
        "supported_options": null
      }
    ]
  },
  "meta": {
    "request_id": "req_tc_jkl012"
  }
}

Use cases for a tool

Reverse lookup — list all use cases a given tool is mapped to.

GET/v1/tools/:name/use-cases

Path params

Name	Type	Required	Description
`name`	`string`	Yes	Tool name.(e.g. `"trend-tracking"`)

Request

curl https://api.clawoop.com/v1/tools/trend-tracking/use-cases \
  -H "X-API-Key: $CLAWOOP_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "slug": "trading",
      "name": "Trading"
    },
    {
      "slug": "marketing",
      "name": "Marketing"
    },
    {
      "slug": "research",
      "name": "Research"
    },
    {
      "slug": "sales",
      "name": "Sales"
    }
  ],
  "meta": {
    "request_id": "req_tuc_mno345"
  }
}

List use cases

List every use case with its tool count. Use to surface workflow groupings to an agent.

GET/v1/use-cases

Request

curl https://api.clawoop.com/v1/use-cases \
  -H "X-API-Key: $CLAWOOP_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "slug": "trading",
      "name": "Trading",
      "description": "Real-time market data, price signals, and trend detection for trading decisions.",
      "tool_count": 2
    },
    {
      "slug": "research",
      "name": "Research",
      "description": "Deep research, information gathering, and knowledge synthesis.",
      "tool_count": 5
    }
  ],
  "meta": {
    "request_id": "req_luc_pqr678"
  }
}

Tools for a use case

List enabled tools mapped to a given use case.

GET/v1/use-cases/:slug/tools

Path params

Name	Type	Required	Description
`slug`	`string`	Yes	Use case slug (see Use Cases reference for valid values).(e.g. `"trading"`)

Request

curl https://api.clawoop.com/v1/use-cases/trading/tools \
  -H "X-API-Key: $CLAWOOP_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "name": "financial-data",
      "description": "Get real-time financial market data for stocks and cryptocurrencies.",
      "providers": [
        {
          "name": "finnhub",
          "enabled": true,
          "costPerCall": 0.002
        },
        {
          "name": "coinmarketcap",
          "enabled": true,
          "costPerCall": 0.005
        }
      ]
    },
    {
      "name": "trend-tracking",
      "description": "Track trends for a keyword across search interest and news.",
      "providers": [
        {
          "name": "serpapi",
          "enabled": true,
          "costPerCall": 0.016
        },
        {
          "name": "newsapi",
          "enabled": true,
          "costPerCall": 0.002
        }
      ]
    }
  ],
  "meta": {
    "request_id": "req_uct_stu901"
  }
}

Poll async job status

Poll the status of an async job (returned as HTTP 202 from run endpoints like generate-image). Returns current state, and the tool output once completed.

GET/v1/status/:requestId

Path params

Name	Type	Required	Description
`requestId`	`string`	Yes	The request_id returned when the async job was submitted.(e.g. `"req_img_456"`)

Request

curl https://api.clawoop.com/v1/status/req_img_456 \
  -H "X-API-Key: $CLAWOOP_API_KEY"

Response

{
  "success": true,
  "data": {
    "status": "completed",
    "job_id": "job_img_789",
    "request_id": "req_img_456",
    "poll_url": "/v1/status/req_img_456",
    "estimated_seconds": null,
    "output": {
      "images": [
        {
          "url": "https://cdn.clawoop.dev/img/abc123.png"
        }
      ],
      "seed": 42
    },
    "error": null,
    "execution_ms": 8420,
    "created_at": "2026-03-23T14:22:00Z",
    "completed_at": "2026-03-23T14:22:08Z"
  },
  "meta": {
    "request_id": "req_js_vwx234"
  }
}

Run tools

Web Scrape

Scrape any public URL and get clean markdown content optimized for LLM consumption.

sync$0.006

POSThttps://api.clawoop.com/v1/run/web-scrape

Providers

firecrawljina

Request Body

input

Field	Type	Required	Description
`url`	`string`	Yes	The URL to scrape

Response Data

Scraped page content as clean markdown with metadata

data

Field	Type	Required	Description
`markdown`	`string`	Yes	Clean markdown content of the page
`title`	`string`	Yes	Page title
`description`	`string`	Yes	Page meta description
`language`	`string`	Yes	Detected page language (ISO 639-1)
`status_code`	`number`	Yes	HTTP status code of the scraped page
`source_url`	`string`	Yes	Final URL after redirects
`warnings`	`string[]`	No	Warnings (e.g., empty or minimal content)

Example

Request

curl -X POST https://api.clawoop.com/v1/run/web-scrape \
  -H "X-API-Key: $CLAWOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "url": "https://example.com"
  },
  "provider": "firecrawl"
}'

Response

{
  "success": true,
  "tool": "web-scrape",
  "data": {
    "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples in documents.",
    "title": "Example Domain",
    "description": "",
    "language": "en",
    "status_code": 200,
    "source_url": "https://example.com",
    "warnings": []
  },
  "meta": {
    "duration_ms": 1240,
    "provider": "firecrawl",
    "request_id": "req_ws_abc123"
  }
}

Translate

Translate text between languages with auto-detection.

sync$0.002

POSThttps://api.clawoop.com/v1/run/translate

Providers

google-translate

Request Body

input

Field	Type	Required	Description
`text`	`string`	Yes	Text to translate
`target`	`string`	Yes	Target language code (ISO 639-1)
`source`	`string`	No	Source language code (auto-detected if omitted)

Response Data

Translation result

data

Field	Type	Required	Description
`translated_text`	`string`	Yes	The translated text
`source_language`	`string`	Yes	Detected or specified source language code
`target_language`	`string`	Yes	The target language code

Example

Request

curl -X POST https://api.clawoop.com/v1/run/translate \
  -H "X-API-Key: $CLAWOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "text": "Hello world",
    "target": "tr"
  },
  "provider": "google-translate"
}'

Response

{
  "success": true,
  "tool": "translate",
  "data": {
    "translated_text": "Merhaba dunya",
    "source_language": "en",
    "target_language": "tr"
  },
  "meta": {
    "duration_ms": 182,
    "provider": "google-translate",
    "request_id": "req_x7k9m2n4"
  }
}

Web Search

Search the web and return title, URL, and snippet per result.

sync$0.004

POSThttps://api.clawoop.com/v1/run/web-search

Providers

serper

Request Body

input

Field	Type	Required	Description
`query`	`string`	Yes	Search query

Response Data

Search results array

data

Field	Type	Required	Description
`results`	`SearchResult[]`	Yes	Array of search results

SearchResult

Field	Type	Required	Description
`title`	`string`	Yes	Page title
`url`	`string`	Yes	Page URL
`snippet`	`string`	Yes	Text snippet from the search result

Example

Request

curl -X POST https://api.clawoop.com/v1/run/web-search \
  -H "X-API-Key: $CLAWOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "query": "best restaurants in Istanbul"
  },
  "provider": "serper"
}'

Response

{
  "success": true,
  "tool": "web-search",
  "data": {
    "results": [
      {
        "title": "Top 10 Restaurants in Istanbul - TripAdvisor",
        "url": "https://tripadvisor.com/istanbul-restaurants",
        "snippet": "Discover the best restaurants in Istanbul with reviews from real travelers..."
      },
      {
        "title": "Istanbul Food Guide 2026",
        "url": "https://example.com/istanbul-food",
        "snippet": "A comprehensive guide to dining in Istanbul covering traditional and modern cuisine..."
      }
    ]
  },
  "meta": {
    "duration_ms": 340,
    "provider": "serper",
    "request_id": "req_a1b2c3d4"
  }
}

Generate Image

Generate an image from a text prompt. Returns async (202) for long-running generation.

async$0.01

POSThttps://api.clawoop.com/v1/run/generate-image

Providers

fal-aigoogle-imagen

Request Body

input

Field	Type	Required	Description
`prompt`	`string`	Yes	Image generation prompt
`image_size`	`string`	No	Image size preset `square_hdsquarelandscape_4_3landscape_16_9portrait_4_3portrait_16_9` (default: square_hd)
`seed`	`number`	No	Seed for reproducibility

Response Data

Generated image(s) with seed

data

Field	Type	Required	Description
`images`	`ImageResult[]`	Yes	Array of generated images
`seed`	`number`	Yes	The seed used for generation

ImageResult

Field	Type	Required	Description
`url`	`string`	Yes	CDN URL of the generated image

Example

Request

curl -X POST https://api.clawoop.com/v1/run/generate-image \
  -H "X-API-Key: $CLAWOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "prompt": "A cat sitting on a mountain at sunset, digital art",
    "image_size": "landscape_16_9"
  },
  "provider": "fal-ai"
}'

Response

{
  "success": true,
  "tool": "generate-image",
  "data": {
    "images": [
      {
        "url": "https://cdn.clawoop.dev/img/abc123.png"
      }
    ],
    "seed": 42
  },
  "meta": {
    "duration_ms": 8420,
    "provider": "fal-ai",
    "request_id": "req_img_456"
  }
}

Async tool — may return HTTP 202 with a job reference. Poll GET /v1/status/{ request_id } for the result.

Financial Data

Get real-time financial market data. Supports US stocks via Finnhub (1 credit) and cryptocurrency via Nansen or CoinMarketCap (3-5 credits). Response schema varies by asset_type.

sync$0.002

POSThttps://api.clawoop.com/v1/run/financial-data

Providers

finnhubnansencoinmarketcap

Request Body

input

Field	Type	Required	Description
`asset_type`	`string`	Yes	The type of financial asset. Use "stock" for US equities (via Finnhub) or "crypto" for cryptocurrency (via Nansen/CoinMarketCap). `stockcrypto`
`symbol`	`string`	Yes	Ticker symbol. For stocks: AAPL, MSFT, GOOGL. For crypto: BTC, ETH, or slug like bitcoin.

Response Data

Response depends on asset_type. Stock returns quote + company profile. Crypto returns market data with price changes.

data

Field	Type	Required	Description
`asset_type`	`string`	Yes	Discriminator: "stock" or "crypto"
`symbol`	`string`	Yes	Ticker symbol
`quote`	`StockQuote`	Yes	Stock quote data (stock only)
`profile`	`StockProfile`	Yes	Company profile (stock only)

StockQuote (stock)

Field	Type	Required	Description
`price`	`number`	Yes	Current price
`change`	`number`	No	Price change
`percent_change`	`number`	No	Percent change
`day_high`	`number`	Yes	Day high price
`day_low`	`number`	Yes	Day low price
`open`	`number`	Yes	Open price
`previous_close`	`number`	Yes	Previous close price
`timestamp`	`number`	Yes	Unix timestamp

StockProfile (stock)

Field	Type	Required	Description
`name`	`string`	Yes	Company name
`ticker`	`string`	Yes	Ticker symbol
`country`	`string`	Yes	Country of registration
`currency`	`string`	Yes	Currency
`exchange`	`string`	Yes	Exchange name
`ipo`	`string`	Yes	IPO date (YYYY-MM-DD)
`market_capitalization`	`number`	Yes	Market cap in millions
`shares_outstanding`	`number`	Yes	Shares outstanding in millions
`logo`	`string`	Yes	Company logo URL
`phone`	`string`	Yes	Phone number
`weburl`	`string`	Yes	Website URL
`industry`	`string`	Yes	Industry classification

CryptoData (crypto)

Field	Type	Required	Description
`symbol`	`string`	Yes	Ticker symbol
`name`	`string`	Yes	Full name
`slug`	`string`	Yes	URL-friendly slug
`rank`	`number`	Yes	Rank by market cap
`price_usd`	`number`	Yes	Current price in USD
`percent_change_1h`	`number`	Yes	1h price change (%)
`percent_change_24h`	`number`	Yes	24h price change (%)
`percent_change_7d`	`number`	Yes	7d price change (%)
`percent_change_30d`	`number`	No	30d price change (%)
`market_cap_usd`	`number`	Yes	Market cap in USD
`volume_24h_usd`	`number`	Yes	24h volume in USD
`circulating_supply`	`number`	Yes	Circulating supply
`max_supply`	`number`	No	Max supply (null if unlimited)
`dominance_pct`	`number`	Yes	Market dominance %
`last_updated`	`string`	Yes	Last updated (ISO 8601)

Example

Request

curl -X POST https://api.clawoop.com/v1/run/financial-data \
  -H "X-API-Key: $CLAWOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "asset_type": "stock",
    "symbol": "AAPL"
  },
  "provider": "finnhub"
}'

Response

{
  "success": true,
  "tool": "financial-data",
  "data": {
    "asset_type": "stock",
    "symbol": "AAPL",
    "quote": {
      "price": 255.92,
      "change": 0.29,
      "percent_change": 0.1134,
      "day_high": 256.13,
      "day_low": 250.65,
      "open": 254.2,
      "previous_close": 255.63,
      "timestamp": 1775160000
    },
    "profile": {
      "name": "Apple Inc",
      "ticker": "AAPL",
      "country": "US",
      "currency": "USD",
      "exchange": "NASDAQ NMS - GLOBAL MARKET",
      "ipo": "1980-12-12",
      "market_capitalization": 3757187.112,
      "shares_outstanding": 14702.7,
      "logo": "https://static2.finnhub.io/file/publicdatany/finnhubimage/stock_logo/AAPL.png",
      "phone": "14089961010",
      "weburl": "https://www.apple.com/",
      "industry": "Technology"
    }
  },
  "meta": {
    "duration_ms": 182,
    "provider": "finnhub",
    "request_id": "req_f1n2d3a4"
  }
}

YouTube Transcript

Extract transcript text from YouTube videos with language selection and auto-fallback. Accepts video URLs or IDs.

sync$0.004

POSThttps://api.clawoop.com/v1/run/transcript

Providers

youtube-transcript

Request Body

input

Field	Type	Required	Description
`url`	`string`	Yes	YouTube video URL or video ID (11 characters). Supports youtube.com/watch, youtu.be, shorts, and embed formats.
`language`	`string`	No	Preferred transcript language (ISO 639-1). Falls back to English, then any available track.

Response Data

Transcript text with video metadata

data

Field	Type	Required	Description
`full_text`	`string`	Yes	Complete transcript as concatenated text
`requested_language`	`string`	Yes	The language that was requested
`actual_language`	`string`	Yes	The language actually returned
`title`	`string`	Yes	Video title
`channel_name`	`string`	Yes	Channel name
`duration_seconds`	`number`	Yes	Video duration in seconds
`published_at`	`string`	Yes	Video publish date (ISO 8601)
`video_id`	`string`	Yes	Resolved YouTube video ID

Example

Request

curl -X POST https://api.clawoop.com/v1/run/transcript \
  -H "X-API-Key: $CLAWOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "language": "en"
  },
  "provider": "youtube-transcript"
}'

Response

{
  "success": true,
  "tool": "transcript",
  "data": {
    "full_text": "We're no strangers to love. You know the rules and so do I...",
    "requested_language": "en",
    "actual_language": "en",
    "title": "Rick Astley - Never Gonna Give You Up",
    "channel_name": "Rick Astley",
    "duration_seconds": 213,
    "published_at": "2009-10-25T00:00:00Z",
    "video_id": "dQw4w9WgXcQ"
  },
  "meta": {
    "duration_ms": 1845,
    "provider": "youtube-transcript",
    "request_id": "req_tr_abc123"
  }
}

Trend Tracking

Track trends for a keyword. serpapi (default) returns interest-over-time data; newsapi returns recent news articles. Both share the same response schema.

sync$0.016

POSThttps://api.clawoop.com/v1/run/trend-tracking

Providers

serpapinewsapi

Request Body

input

Field	Type	Required	Description
`keyword`	`string`	Yes	Search keyword or phrase to track
`dateRange`	`string`	No	How far back to look. Applied by serpapi; ignored by newsapi. `7-d1-m3-m1-y5-y` (default: "7-d")

Response Data

Trend data — timeline and/or articles depending on provider

data

Field	Type	Required	Description
`timeline`	`TrendTimelinePoint[]`	Yes	Interest-over-time data points (populated by serpapi)
`articles`	`TrendArticle[]`	Yes	Recent news articles (populated by newsapi)

TrendTimelinePoint

Field	Type	Required	Description
`date`	`string`	Yes	ISO 8601 date string
`value`	`number`	Yes	Normalized interest score 0-100

TrendArticle

Field	Type	Required	Description
`title`	`string`	Yes	Article headline
`url`	`string`	Yes	URL to full article
`publishedAt`	`string`	Yes	ISO 8601 publication date

Example

Request

curl -X POST https://api.clawoop.com/v1/run/trend-tracking \
  -H "X-API-Key: $CLAWOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": {
    "keyword": "AI agents",
    "dateRange": "1-y"
  },
  "provider": "serpapi"
}'

Response

{
  "success": true,
  "tool": "trend-tracking",
  "data": {
    "timeline": [
      {
        "date": "2025-05-01T00:00:00.000Z",
        "value": 32
      },
      {
        "date": "2025-08-01T00:00:00.000Z",
        "value": 58
      },
      {
        "date": "2025-11-01T00:00:00.000Z",
        "value": 74
      },
      {
        "date": "2026-02-01T00:00:00.000Z",
        "value": 91
      },
      {
        "date": "2026-04-01T00:00:00.000Z",
        "value": 100
      }
    ],
    "articles": []
  },
  "meta": {
    "duration_ms": 1340,
    "provider": "serpapi",
    "request_id": "req_tt_s7e9r1"
  }
}

Response Envelope

Every successful tool response is wrapped in this envelope.

Field	Type	Description
`success`	`boolean`	Whether the request succeeded
`tool`	`string`	The tool that was executed
`data`	`object`	Tool-specific output (see per-tool schema)
`meta`	`object`	Request metadata

Field	Type	Required	Description
`duration_ms`	`number`	No	Execution time in milliseconds
`provider`	`string`	No	Provider that served the request
`request_id`	`string`	No	Unique request identifier

Async Polling

Returned as HTTP 202 for async tools (e.g. generate-image). Poll the poll_url for status.

GET/v1/status/{request_id}

Possible statuses

pendingprocessingcompletedfailed

HTTP 202 Job Reference

{
  "status": "pending",
  "job_id": "job_img_789",
  "request_id": "req_img_456",
  "poll_url": "/v1/status/req_img_456",
  "estimated_seconds": 12,
  "meta": {
    "tool": "generate-image",
    "provider": "fal-ai"
  }
}

Error Codes

All errors follow a consistent format. The code field is machine-readable; message is human-readable.

Error response shape

{
  "success": false,
  "error": {
    "code": "CL_RATE_LIMITED",
    "message": "Rate limit exceeded. 5 requests/minute on Free plan.",
    "http_status": 429,
    "retryable": true,
    "retry_after_ms": 12000
  },
  "meta": {
    "request_id": "req_x7k9m2n4"
  }
}

Code	HTTP	Description
`CL_SCHEMA_VALIDATION`	400	Input does not match tool schema
`CL_AUCL_INVALID`	401	API key missing, malformed, or revoked
`CL_CREDITS_EXHAUSTED`	402	No credits remaining
`CL_FORBIDDEN`	403	API key does not have permission
`CL_TOOL_NOT_FOUND`	404	Tool does not exist
`CL_PROVIDER_NOT_FOUND`	404	Provider does not exist for this tool
`CL_RATE_LIMITED`	429	Rate limit exceeded
`CL_PROVIDER_QUOTA_FULL`	429	Provider global quota exhausted
`CL_PROVIDER_DOWN`	502	Provider health check failing
`CL_TIMEOUT`	504	Tool execution exceeded timeout
`CL_INTERNAL_ERROR`	500	Unexpected Clawoop error