> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parse.bot/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Create and call your first API in minutes
This guide walks the full flow end to end **over the API**: find or create an API from a URL, wait for it to build, then call it. Every request goes to `https://api.parse.bot` with your API key in the `X-API-Key` header.
Prefer to do this in the browser? The [Dashboard guide](/dashboard) walks the same flow through the UI — paste a URL, test endpoints, revise, and grab a snippet. Use this page if you want to drive it programmatically.
## Prerequisites
* A Parse account at [parse.bot](https://parse.bot)
* An API key from the dashboard (**Settings → API Keys**). See [Authentication](/authentication).
Set your key as an environment variable so you can copy-paste the examples:
```bash theme={null}
export PARSE_API_KEY="pmx_your_key_here"
```
## Step 0 (optional): Check the marketplace first
Thousands of sites already have a pre-built API. Searching first is free, instant, and needs no auth:
```bash theme={null}
curl "https://api.parse.bot/marketplace/apis?q=books.toscrape.com"
```
If you find a match, you can use it right away — there are four ways, depending on whether you want your own copy:
| | Route |
| -------------------------------------------- | ------------------------------------------------------ |
| Call the canonical directly (any API key) | `POST /scraper/{canonical_scraper_id}/{endpoint_name}` |
| Subscribe — your own pinned copy, in My APIs | `POST /marketplace/apis/{id}/subscribe` |
| Fork privately — isolated, desynced copy | `POST /marketplace/apis/{id}/fork` |
| Dispatch by URL — clone it instantly | `POST /dispatch` (Step 1 below) |
Get the `canonical_scraper_id` and endpoint list from `GET /marketplace/apis/{id}`. See the [Marketplace guide](/marketplace) for the details and trade-offs. If there's no match, dispatch your URL (below) and Parse builds it from scratch.
## Step 1: Create an API
Submit a URL and, optionally, describe the data you want:
```bash theme={null}
curl -X POST https://api.parse.bot/dispatch \
-H "X-API-Key: $PARSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://books.toscrape.com",
"task": "get book titles, prices, and ratings"
}'
```
Response:
```json theme={null}
{
"task_id": "abc123-...",
"matched": false,
"may_require_auth": false
}
```
* `matched: true` — an existing API already covered this site; it's ready to call now.
* `matched: false` — a build job was queued. Poll `task_id` until it completes (Step 2).
* `may_require_auth: true` — the site likely needs a login. Authenticated APIs are built from the [dashboard](https://parse.bot), not the API — see [Authenticated APIs](/authenticated-apis).
**`contributes_to_marketplace`** (optional, default `true`). When `true`, your API stays linked to the shared canonical for its domain: you can [pull upstream improvements](/updates), and the build is free. Set it to `false` to build a fully private, desynced API (this is a charged build and the choice is permanent). Most users should leave it `true`.
## Step 2: Poll for completion
```bash theme={null}
curl https://api.parse.bot/dispatch/tasks/abc123-... \
-H "X-API-Key: $PARSE_API_KEY"
```
Poll every 3–5 seconds until `status` is `completed`. A typical build takes anywhere from a few seconds (marketplace match) to a couple of minutes (a fresh build on a complex site).
The `status` field moves through this lifecycle:
| Status | Meaning |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| `queued` | Accepted, waiting for a worker. |
| `running` | The agent is actively building. `progress` shows live detail. |
| `needs_input` | The agent needs something from you (e.g. a sample search term). Respond via `POST /dispatch/{task_id}` — see below. |
| `completed` | ✅ Done. `generated_api` is populated and the endpoints are callable. |
| `failed` | ❌ Build failed. `error` explains why. |
| `cancelled` | You cancelled it via `POST /dispatch/tasks/{task_id}/cancel`. |
A completed task includes a `generated_api` object with everything needed to call it:
```json theme={null}
{
"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": { "...": "..." }
}
]
}
}
```
The agent occasionally needs a hint — most often a realistic input to test an endpoint (e.g. a search term). The `user_input_prompt` field describes what it's asking for. Answer it and the build resumes:
```bash theme={null}
curl -X POST https://api.parse.bot/dispatch/abc123-... \
-H "X-API-Key: $PARSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_response": {"search_term": "python"}}'
```
## Step 3: Call an endpoint
Use the `scraper_id` and an `endpoint_name` from the spec. Send parameters in the JSON body for `POST` endpoints, or as query-string params for `GET` endpoints:
```bash theme={null}
curl -X POST https://api.parse.bot/scraper/scraper-456/get_books \
-H "X-API-Key: $PARSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"page": 1}'
```
A successful call returns the endpoint's own JSON — the shape defined by its `return_schema`, with no wrapper:
```json theme={null}
[
{ "title": "A Light in the Attic", "price": 51.77, "rating": 3 },
{ "title": "Tipping the Velvet", "price": 53.74, "rating": 1 }
]
```
Each execution also returns rate-limit and credit headers (`X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-Credits-Remaining`, …) so you can pace your calls. When a call fails, the HTTP status tells you whose fault it is — a `502` means the *target site* failed, a `500` means the scraper bugged out. See [Errors & Troubleshooting](/errors).
## Step 4: Revise your API
Need a change? Describe it in plain English:
```bash theme={null}
curl -X POST https://api.parse.bot/dispatch/tasks/abc123-.../revise \
-H "X-API-Key: $PARSE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"revision": "add an endpoint to search books by genre"}'
```
```json theme={null}
{ "task_id": "revision-task-id", "revision_type": "revision" }
```
Poll the new `task_id` exactly like Step 2. Your `scraper_id` stays the same — new and updated endpoints become callable when the revision completes.
## Step 5: Export or connect an agent
```bash theme={null}
# OpenAPI 3.1
curl https://api.parse.bot/dispatch/tasks/abc123-.../export/openapi \
-H "X-API-Key: $PARSE_API_KEY"
# MCP tool definitions
curl https://api.parse.bot/dispatch/tasks/abc123-.../export/mcp \
-H "X-API-Key: $PARSE_API_KEY"
```
Or skip exporting entirely and connect an AI agent straight to the hosted MCP server — it gets this API (and all your others) as callable tools. See [MCP Server](/mcp). To call your APIs from Python with fully typed clients, use the [Python SDK](/sdk).
## What's next
Typed Python clients generated by the parse CLI
Full Python & JavaScript clients with a polling helper
Search pre-built APIs before you build
Pull upstream improvements into your APIs
Read the execution envelope — whose fault a 422 / 502 / 503 is