Sites & Catalog API Reference

Map websites into typed tools, manage site models, execute generated tools, and browse the public catalog.

Endpoints

Method	Path	Description
POST	`/v1/sites/map`	Map a website into tools
POST	`/v1/sites/{site_id}/refresh`	Re-model an existing site
GET	`/v1/sites`	List your mapped sites
GET	`/v1/sites/{site_id}`	Get full site details
GET	`/v1/sites/orders`	List mapping orders
DEL	`/v1/sites/{site_id}`	Delete a mapped site
GET	`/v1/sites/{site_id}/tools`	List tools for a site
POST	`/v1/sites/{site_id}/tools/{tool_name}`	Execute a tool
GET	`/v1/catalog`	Browse the public catalog
GET	`/v1/catalog/search`	Search catalog by domain
GET	`/v1/catalog/{site_id}`	Get a catalog entry

Site Mapping

Map a website URL to a set of typed tools that can be executed programmatically. If the site already exists in the catalog, the tools are returned immediately. Otherwise a modeling order is created and requires payment.

Map Site

POST /v1/sites/map

Map a website into typed, executable tools. If the site already exists in the catalog, the ready model is returned immediately at no cost. If the site is new, a modeling order is created and a Stripe checkout URL is returned for payment.

Request Body

Field	Type	Required	Description
`start_url`	`string`	Yes	The URL to begin mapping from (e.g., `"https://linkedin.com/jobs"`)
`auth_cookies`	`array`	No	Optional array of cookie objects to inject for authenticated mapping

Response `200 OK` — Site exists in catalog

{
  "site_id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "domain": "linkedin.com",
  "status": "ready",
  "message": "Site already exists in catalog",
  "entities": ["job", "company"],
  "recipes": ["search_jobs", "view_job"],
  "tools": ["linkedin_search_jobs", "linkedin_view_job"]
}

Response `202 Accepted` — New site, payment required

{
  "order_id": "ord_abc123",
  "domain": "linkedin.com",
  "status": "pending_payment",
  "checkout_url": "https://checkout.stripe.com/c/pay_abc123",
  "amount_cents": 1000
}

Tip: Redirect the user (or open a browser) to the checkout_url to complete payment. Once paid, modeling begins automatically.

Errors

Status	Code	Description
`402`	`upgrade_required`	Upgrade to a paid plan to model new sites.
`409`	`modeling_in_progress`	This site is already being modeled. Wait for the current order to complete.

Refresh Site

POST /v1/sites/{site_id}/refresh

Re-model an existing site to update its tools and recipes. This creates a new modeling order and returns a checkout URL for payment, similar to mapping a new site.

Path Parameters

Parameter	Type	Description
`site_id`	`string (uuid)`	The ID of the site to refresh

Response `202 Accepted`

{
  "order_id": "ord_def456",
  "domain": "linkedin.com",
  "status": "pending_payment",
  "checkout_url": "https://checkout.stripe.com/c/pay_def456",
  "amount_cents": 1000
}

Errors

Status	Code	Description
`402`	`upgrade_required`	Upgrade to a paid plan to model new sites.
`404`	`not_found`	Site not found.

Site Management

Manage your mapped sites, view detailed site models, track orders, and remove sites you no longer need.

List Sites

GET /v1/sites

List all sites mapped to your account.

Response `200 OK`

[
  {
    "site_id": "a1b2c3d4-5678-9abc-def0-123456789abc",
    "domain": "linkedin.com",
    "status": "ready",
    "entities": ["job", "company"],
    "tools_count": 5
  }
]

Get Site Details

GET /v1/sites/{site_id}

Get the full model for a mapped site, including entities, discovered pages, recipes, and tool definitions.

Path Parameters

Parameter	Type	Description
`site_id`	`string (uuid)`	The ID of the site

Response `200 OK`

{
  "site_id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "domain": "linkedin.com",
  "status": "ready",
  "start_url": "https://linkedin.com/jobs",
  "entities": [
    {
      "name": "job",
      "fields": ["title", "company", "location", "salary"]
    },
    {
      "name": "company",
      "fields": ["name", "industry", "size"]
    }
  ],
  "pages": [
    "https://linkedin.com/jobs",
    "https://linkedin.com/jobs/search",
    "https://linkedin.com/jobs/view/123"
  ],
  "recipes": [
    {
      "name": "search_jobs",
      "description": "Search for job listings by keyword and location",
      "action_type": "search"
    },
    {
      "name": "view_job",
      "description": "View details for a specific job listing",
      "action_type": "view"
    }
  ],
  "tools": [
    {
      "name": "linkedin_search_jobs",
      "description": "Search for job listings",
      "params": [
        {"name": "query", "type": "string", "required": true},
        {"name": "location", "type": "string", "required": false}
      ],
      "returns": {"type": "array", "items": "job"}
    }
  ],
  "pages_visited": 12
}

Errors

Status	Code	Description
`404`	`not_found`	Site not found.

List Orders

GET /v1/sites/orders

List all site modeling orders for your account, including their status and payment details.

Response `200 OK`

{
  "orders": [
    {
      "order_id": "ord_abc123",
      "domain": "linkedin.com",
      "order_type": "new",
      "status": "completed",
      "amount_cents": 1000,
      "created_at": "2026-04-01T09:00:00Z",
      "completed_at": "2026-04-01T09:15:00Z",
      "error": null
    }
  ]
}

Delete Site

DEL /v1/sites/{site_id}

Delete a mapped site from your account. This removes the site and all associated tools. This action cannot be undone.

Path Parameters

Parameter	Type	Description
`site_id`	`string (uuid)`	The ID of the site to delete

Response `200 OK`

{
  "success": true,
  "site_id": "a1b2c3d4-5678-9abc-def0-123456789abc"
}

Errors

Status	Code	Description
`404`	`not_found`	Site not found.

Tools

Tools are generated automatically when a site is mapped. Each tool represents a specific action that can be performed on the site, with typed parameters and return values.

List Tools

GET /v1/sites/{site_id}/tools

List all tools generated for a mapped site, including their parameters and return types.

Path Parameters

Parameter	Type	Description
`site_id`	`string (uuid)`	The ID of the site

Response `200 OK`

{
  "site_id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "domain": "linkedin.com",
  "tools": [
    {
      "name": "linkedin_search_jobs",
      "description": "Search for job listings",
      "params": [
        {"name": "query", "type": "string", "required": true},
        {"name": "location", "type": "string", "required": false}
      ],
      "returns": {"type": "array", "items": "job"}
    },
    {
      "name": "linkedin_view_job",
      "description": "View details for a specific job listing",
      "params": [
        {"name": "job_id", "type": "string", "required": true}
      ],
      "returns": {"type": "object", "items": "job"}
    }
  ]
}

Errors

Status	Code	Description
`404`	`not_found`	Site not found.

Execute Tool

POST /v1/sites/{site_id}/tools/{tool_name}

Execute a generated tool on a mapped site. BabelWrap opens a browser session, runs the tool's recipe steps, and returns the extracted data.

Path Parameters

Parameter	Type	Description
`site_id`	`string (uuid)`	The ID of the site
`tool_name`	`string`	The name of the tool to execute (e.g., `linkedin_search_jobs`)

Request Body

Field	Type	Required	Description
`params`	`object`	Yes	Key-value map of parameters for the tool (see tool definition for expected params)

{
  "params": {
    "query": "python developer",
    "location": "NYC"
  }
}

Response `200 OK`

{
  "success": true,
  "data": [
    {
      "title": "Senior Python Developer",
      "company": "Acme Corp",
      "location": "New York, NY"
    }
  ],
  "duration_ms": 4500,
  "steps_executed": 5
}

Response `400 Bad Request` — Execution failure

{
  "success": false,
  "error": "Step 2 (fill: location field) failed: Element not found",
  "duration_ms": 2100
}

Errors

Status	Code	Description
`404`	`not_found`	Site or tool not found.

Catalog

Catalog endpoints are public and do not require authentication. Anyone can browse and search the catalog of pre-mapped sites.

The catalog is a public directory of sites that have already been mapped by BabelWrap users. When you map a site that exists in the catalog, the tools are available immediately at no cost.

List Catalog

GET /v1/catalog

Browse the public catalog of pre-mapped sites with pagination.

Query Parameters

Parameter	Type	Required	Description
`page`	`integer`	No	Page number (default: `1`)
`per_page`	`integer`	No	Results per page (default: `20`, max: `100`)

Response `200 OK`

{
  "total": 42,
  "page": 1,
  "per_page": 20,
  "sites": [
    {
      "site_id": "a1b2c3d4-5678-9abc-def0-123456789abc",
      "domain": "linkedin.com",
      "start_url": "https://linkedin.com/jobs",
      "recipe_count": 5,
      "version": 1,
      "last_validated_at": "2026-03-28T12:00:00Z",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Search Catalog

GET /v1/catalog/search

Search the catalog by domain name.

Query Parameters

Parameter	Type	Required	Description
`domain`	`string`	Yes	Domain to search for (e.g., `"linkedin"`)

Response `200 OK`

{
  "results": [
    {
      "site_id": "a1b2c3d4-5678-9abc-def0-123456789abc",
      "domain": "linkedin.com",
      "start_url": "https://linkedin.com/jobs",
      "recipe_count": 5,
      "version": 1
    }
  ]
}

Get Catalog Entry

GET /v1/catalog/{site_id}

Get the full details of a catalog entry, including available tools and recipes.

Path Parameters

Parameter	Type	Description
`site_id`	`string (uuid)`	The ID of the catalog entry

Response `200 OK`

{
  "site_id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "domain": "linkedin.com",
  "start_url": "https://linkedin.com/jobs",
  "recipe_count": 5,
  "version": 1,
  "tools": [
    {
      "name": "linkedin_search_jobs",
      "description": "Search for job listings"
    },
    {
      "name": "linkedin_view_job",
      "description": "View details for a specific job listing"
    }
  ],
  "recipes": [
    {
      "name": "search_jobs",
      "description": "Search for job listings by keyword and location",
      "action_type": "search"
    },
    {
      "name": "view_job",
      "description": "View details for a specific job listing",
      "action_type": "view"
    }
  ],
  "created_at": "2026-03-01T10:00:00Z",
  "last_validated_at": "2026-03-28T12:00:00Z"
}

Errors

Status	Code	Description
`404`	`not_found`	Catalog entry not found.

Sites & Catalog API Reference

Endpoints

Site Mapping

Map Site

Request Body

Response 200 OK — Site exists in catalog

Response 202 Accepted — New site, payment required

Errors

Refresh Site

Path Parameters

Response 202 Accepted

Errors

Site Management

List Sites

Response 200 OK

Get Site Details

Path Parameters

Response 200 OK

Errors

List Orders

Response 200 OK

Delete Site

Path Parameters

Response 200 OK

Errors

Tools

List Tools

Path Parameters

Response 200 OK

Errors

Execute Tool

Path Parameters

Request Body

Response 200 OK

Response 400 Bad Request — Execution failure

Errors

Catalog

List Catalog

Query Parameters

Response 200 OK

Search Catalog

Query Parameters

Response 200 OK

Get Catalog Entry

Path Parameters

Response 200 OK

Errors

Response `200 OK` — Site exists in catalog

Response `202 Accepted` — New site, payment required

Response `202 Accepted`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `400 Bad Request` — Execution failure

Response `200 OK`

Response `200 OK`

Response `200 OK`