Skip to main content
This guide walks through the full flow: create an API from a URL, wait for it to build, then call it.

​
Prerequisites

​
Step 1: Create an API

Submit a URL and optionally describe the data you need: 
curl -X POST https://api.parse.bot/dispatch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://books.toscrape.com",
    "task": "get book titles, prices, and ratings"
  }'
Response: 
{
  "task_id": "abc123-...",
  "matched": false,
  "may_require_auth": false
}
  • matched: true — an existing API was found and is ready immediately
  • matched: false — a build job was queued, poll until complete

​
Step 2: Poll for completion

curl https://api.parse.bot/dispatch/tasks/abc123-... \
  -H "X-API-Key: YOUR_API_KEY"
Keep polling until status is "completed". The response includes a generated_api object with everything you need to call it: 
{
  "id": "abc123-...",
  "url": "https://books.toscrape.com",
  "status": "completed",
  "generated_api": {
    "marketplace_id": "mp-789",
    "scraper_id": "scraper-456",
    "name": "Books to Scrape",
    "source_url": "https://books.toscrape.com",
    "execution_base_url": "https://api.parse.bot/scraper/scraper-456",
    "endpoints": [
      {
        "method": "POST",
        "endpoint_name": "get_books",
        "description": "Get book listings with titles, prices, and ratings",
        "input_params": {
          "page": { "type": "integer", "description": "Page number" }
        },
        "return_schema": { "..." : "..." }
      }
    ]
  }
}
Other status values you may see while polling: queued, running, needs_input, failed.

​
Step 3: Call an endpoint

Use the execution_base_url and endpoint_name from the spec: 
curl -X POST https://api.parse.bot/scraper/scraper-456/get_books \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": 1}'
Response: 
{
  "status": "success",
  "data": [
    {
      "title": "A Light in the Attic",
      "price": 51.77,
      "rating": 3
    }
  ],
  "scraper_id": "scraper-456",
  "execution_time": 2.3
}

​
Step 4: Revise your API

Need changes? Describe what you want in plain English: 
curl -X POST https://api.parse.bot/dispatch/tasks/abc123-.../revise \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": "add an endpoint to search books by genre"}'

{
  "task_id": "revision-task-id",
  "revision_type": "revision"
}
Poll the new task_id the same way as step 2.

​
Step 5: Export or connect an agent

Export as OpenAPI 3.1: 
curl https://api.parse.bot/dispatch/tasks/abc123-.../export/openapi \
  -H "X-API-Key: YOUR_API_KEY"
Export as MCP tools: 
curl https://api.parse.bot/dispatch/tasks/abc123-.../export/mcp \
  -H "X-API-Key: YOUR_API_KEY"
Connect an AI agent directly — see the MCP Server guide for full setup.

​
What’s next