API reference

Trawl API.

AI web extraction as an async job API. Every endpoint, request, and response — generated from the live OpenAPI spec.

Base URL

https://api.trawl.productcraft.co

Auth

Authorization: Bearer …

Spec version

OpenAPI 3.0.0 · v0.1.0

OpenAPI spec

https://api.trawl.productcraft.co/docs-json

Webhooks

get/v1/workspaces/{workspace_id}/webhooksAuth

List webhooks for the workspace (paginated, newest first, secrets masked)

Path parameters

workspace_id*string

Query parameters

cursorstring

Opaque cursor from the previous response's `pagination.next_cursor`.

limitinteger

Page size. Defaults to 20, capped at 100.

Response · 200 Page of webhooks with a pagination cursor.

data*array

pagination*object

next_cursor*string

has_more*boolean

Example

Request

GET /v1/workspaces/{workspace_id}/webhooks
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "id": "string",
      "workspace_id": "string",
      "url": "string",
      "active": false,
      "failure_count": 0,
      "last_status_code": 0,
      "last_attempt_at": "string",
      "auto_disabled_at": "string",
      "first_failure_at": "string",
      "created_at": "string"
    }
  ],
  "pagination": {
    "next_cursor": "string",
    "has_more": false
  }
}

post/v1/workspaces/{workspace_id}/webhooksAuth

Create a workspace webhook. The response includes the signing secret in clear EXACTLY ONCE — copy it now.

Path parameters

workspace_id*string

Headers

Idempotency-Keystring

Stripe-style idempotency key. The signing secret is returned exactly once; a retry without this header creates a second webhook + secret. 24h TTL.

Request body

url*string

Destination URL (https required in prod).

activeboolean

Disabled webhooks are never delivered to.

Response · 201 Webhook created. Includes plaintext `signing_secret` exactly once.

id*string

workspace_id*string

url*string

active*boolean

failure_count*number

last_status_code*number

last_attempt_at*string

auto_disabled_at*string

first_failure_at*string

created_at*string

signing_secret*string

Plaintext signing secret returned EXACTLY ONCE on create + rotate. Persist immediately — it never appears on subsequent GETs.

Example

Request

POST /v1/workspaces/{workspace_id}/webhooks
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "url": "string",
  "active": false
}

Response

{
  "id": "string",
  "workspace_id": "string",
  "url": "string",
  "active": false,
  "failure_count": 0,
  "last_status_code": 0,
  "last_attempt_at": "string",
  "auto_disabled_at": "string",
  "first_failure_at": "string",
  "created_at": "string",
  "signing_secret": "string"
}

get/v1/workspaces/{workspace_id}/webhooks/{id}Auth

Get a webhook (secret masked)

Path parameters

workspace_id*string

id*string

Response · 200

id*string

workspace_id*string

url*string

active*boolean

failure_count*number

last_status_code*number

last_attempt_at*string

auto_disabled_at*string

first_failure_at*string

created_at*string

Example

Request

GET /v1/workspaces/{workspace_id}/webhooks/{id}
Authorization: Bearer YOUR_TOKEN

Response

{
  "id": "string",
  "workspace_id": "string",
  "url": "string",
  "active": false,
  "failure_count": 0,
  "last_status_code": 0,
  "last_attempt_at": "string",
  "auto_disabled_at": "string",
  "first_failure_at": "string",
  "created_at": "string"
}

patch/v1/workspaces/{workspace_id}/webhooks/{id}Auth

Update url / active flag (active=true clears auto-disable)

Path parameters

workspace_id*string

id*string

Request body

urlstring

New destination URL.

activeboolean

Pause/resume the webhook. Setting active=true clears auto-disable.

Response · 200

id*string

workspace_id*string

url*string

active*boolean

failure_count*number

last_status_code*number

last_attempt_at*string

auto_disabled_at*string

first_failure_at*string

created_at*string

Example

Request

PATCH /v1/workspaces/{workspace_id}/webhooks/{id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "url": "string",
  "active": false
}

Response

{
  "id": "string",
  "workspace_id": "string",
  "url": "string",
  "active": false,
  "failure_count": 0,
  "last_status_code": 0,
  "last_attempt_at": "string",
  "auto_disabled_at": "string",
  "first_failure_at": "string",
  "created_at": "string"
}

delete/v1/workspaces/{workspace_id}/webhooks/{id}Auth

Delete a webhook

Path parameters

workspace_id*string

id*string

Response · 204

No content.

get/v1/workspaces/{workspace_id}/webhooks/{id}/deliveriesAuth

Delivery attempts for a webhook (paginated, default 50, max 200, newest first)

Path parameters

workspace_id*string

id*string

Query parameters

statusenum (2)

Filter by derived outcome. `succeeded` = 2xx response; `failed` = any non-2xx, including attempts where the destination never responded.

cursorstring

Opaque cursor from the previous response's `pagination.next_cursor`.

limitinteger

Page size. Defaults to 50, capped at 200.

Response · 200 Page of delivery attempts with a pagination cursor.

data*array

pagination*object

next_cursor*string

has_more*boolean

Example

Request

GET /v1/workspaces/{workspace_id}/webhooks/{id}/deliveries
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "id": "string",
      "webhook_id": "string",
      "job_id": "string",
      "event_id": "string",
      "event_type": "string",
      "attempt_number": 0,
      "status_code": 0,
      "response_body_truncated": "string",
      "error_message": "string",
      "latency_ms": 0,
      "attempted_at": "string"
    }
  ],
  "pagination": {
    "next_cursor": "string",
    "has_more": false
  }
}

post/v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secretAuth

Rotate the signing secret. Returns the new secret in clear EXACTLY ONCE.

Path parameters

workspace_id*string

id*string

Response · 201

No content.

post/v1/workspaces/{workspace_id}/webhooks/{id}/testAuth

Fire a synthetic event to this webhook (asynchronous; check the destination logs)

Path parameters

workspace_id*string

id*string

Response · 202

No content.

Jobs

get/v1/workspaces/{workspace_id}/jobsAuth

List trawl jobs (paginated, newest first)

Path parameters

workspace_id*string

Query parameters

statusenum (5)

Filter by job status.

cursorstring

Opaque cursor for pagination.

limitnumber

Response · 200 Page of jobs with pagination cursor.

data*array

pagination*object

next_cursor*string

has_more*boolean

Example

Request

GET /v1/workspaces/{workspace_id}/jobs
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": [
    {
      "id": "string",
      "workspace_id": "string",
      "status": "queued",
      "json_schema": {},
      "description": "string",
      "suggested_urls": [
        "string"
      ],
      "max_steps": 0,
      "timeout_s": 0,
      "model_tier": "string",
      "webhook_id": "string",
      "result": {},
      "error": "string",
      "attempts": 0,
      "enqueued_at": "string",
      "started_at": "string",
      "completed_at": "string",
      "created_at": "string"
    }
  ],
  "pagination": {
    "next_cursor": "string",
    "has_more": false
  }
}

post/v1/workspaces/{workspace_id}/jobsAuth

Create (enqueue) a trawl job

Path parameters

workspace_id*string

Headers

Idempotency-Keystring

Pass a key (1..256 chars, [A-Za-z0-9_\-:]) to make retries safe — replays return the original response for 24h.

Request body

json_schema*object

JSON Schema describing the shape of the extraction result. Must be a non-empty object with `type: "object"`.

Example: {"type":"object","properties":{"title":{"type":"string"}},"required":["title"]}

description*string

Natural-language description of what to extract.

Example: "Extract the product title and price from each page."

suggested_urlsarray

Seed URLs the worker should start from.

webhook_idstring

Webhook id to notify when the job finishes.

max_stepsnumber

Maximum number of agent steps (one LLM call each) before the job stops. Defaults to 20. Multi-source extractions typically need 40+. The server additionally clamps this to an operator ceiling, so a very large value does not guarantee a very long run — `timeout_s` still applies.

timeout_snumber

Wall-clock timeout for the job, in seconds.

model_tierstring

Model tier the worker should use (e.g. `standard`, `pro`).

Response · 201 Job created and queued.

id*string

workspace_id*string

status*enum (5)

json_schema*object

description*string

suggested_urls*array

max_steps*number

timeout_s*number

model_tier*string

webhook_id*string

result*object

error*string

attempts*number

enqueued_at*string

started_at*string

completed_at*string

created_at*string

Example

Request

POST /v1/workspaces/{workspace_id}/jobs
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "json_schema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string"
      }
    },
    "required": [
      "title"
    ]
  },
  "description": "Extract the product title and price from each page.",
  "suggested_urls": [
    "string"
  ],
  "webhook_id": "string",
  "max_steps": 0,
  "timeout_s": 0,
  "model_tier": "string"
}

Response

{
  "id": "string",
  "workspace_id": "string",
  "status": "queued",
  "json_schema": {},
  "description": "string",
  "suggested_urls": [
    "string"
  ],
  "max_steps": 0,
  "timeout_s": 0,
  "model_tier": "string",
  "webhook_id": "string",
  "result": {},
  "error": "string",
  "attempts": 0,
  "enqueued_at": "string",
  "started_at": "string",
  "completed_at": "string",
  "created_at": "string"
}

get/v1/workspaces/{workspace_id}/jobs/{id}Auth

Get a single trawl job

Path parameters

workspace_id*string

id*string

Response · 200 Job row.

id*string

workspace_id*string

status*enum (5)

json_schema*object

description*string

suggested_urls*array

max_steps*number

timeout_s*number

model_tier*string

webhook_id*string

result*object

error*string

attempts*number

enqueued_at*string

started_at*string

completed_at*string

created_at*string

Example

Request

GET /v1/workspaces/{workspace_id}/jobs/{id}
Authorization: Bearer YOUR_TOKEN

Response

{
  "id": "string",
  "workspace_id": "string",
  "status": "queued",
  "json_schema": {},
  "description": "string",
  "suggested_urls": [
    "string"
  ],
  "max_steps": 0,
  "timeout_s": 0,
  "model_tier": "string",
  "webhook_id": "string",
  "result": {},
  "error": "string",
  "attempts": 0,
  "enqueued_at": "string",
  "started_at": "string",
  "completed_at": "string",
  "created_at": "string"
}

post/v1/workspaces/{workspace_id}/jobs/{id}/cancelAuth

Cancel a queued or running trawl job

Path parameters

workspace_id*string

id*string

Response · 200 Job cancelled.

id*string

workspace_id*string

status*enum (5)

json_schema*object

description*string

suggested_urls*array

max_steps*number

timeout_s*number

model_tier*string

webhook_id*string

result*object

error*string

attempts*number

enqueued_at*string

started_at*string

completed_at*string

created_at*string

Example

Request

POST /v1/workspaces/{workspace_id}/jobs/{id}/cancel
Authorization: Bearer YOUR_TOKEN

Response

{
  "id": "string",
  "workspace_id": "string",
  "status": "queued",
  "json_schema": {},
  "description": "string",
  "suggested_urls": [
    "string"
  ],
  "max_steps": 0,
  "timeout_s": 0,
  "model_tier": "string",
  "webhook_id": "string",
  "result": {},
  "error": "string",
  "attempts": 0,
  "enqueued_at": "string",
  "started_at": "string",
  "completed_at": "string",
  "created_at": "string"
}

Credits

get/v1/workspaces/{workspace_id}/creditsAuth

Remaining Trawl steps for this workspace, with recent ledger entries

Path parameters

workspace_id*string

Query parameters

limit*string

Response · 200

Balance and recent entries.