REST API

Execute

Run any registered capability through one endpoint.

`POST /execute` is the stable REST entry point for every registered capability. The web layer never special-cases a platform ID; the capability's registered manifest supplies its input schema, timeout, example, canary, and fixed credit cost.

## Request

```http
POST https://data.upscrape.com/execute
Authorization: Bearer UPSCRAPE_API_KEY
Content-Type: application/json
Prefer: wait=30
Idempotency-Key: UNIQUE_LOGICAL_OPERATION
```

```json
{
  "capability": "platform.capability.action",
  "input": {}
}
```

`capability` must be an available capability ID. `input` must satisfy that capability's JSON Schema. Find both on its [public platform page](/scrapers).

## Waiting for completion

Without `Prefer: wait`, execution is asynchronous and normally returns HTTP `202`. Send `Prefer: wait=N` to wait for up to `N` seconds, with a server-side maximum of 300 seconds.

A wait is a response preference, not a different job type. If the job is still running when the window ends, Upscrape returns the same job as pending.

## Completed response

Completed work returns HTTP `200` with `state: "completed"` and `success: true`. Capability output is intentionally open-ended because each upstream source has a different data shape.

```json
{
  "job_id": "job_id",
  "state": "completed",
  "success": true,
  "results": [
    {"data": {"...": "capability-specific JSON"}}
  ],
  "billing": {"credits_charged": 1},
  "stats": {}
}
```

Use the capability's sample response as a realistic preview, but treat its input schema, not the sample output, as the validation contract.

## Pending response

Pending work returns HTTP `202` with a job ID and non-terminal `state`. Poll the job instead of resubmitting the execution.

## Validation

Invalid capability IDs, malformed JSON, and schema-invalid inputs fail before worker execution. Fix the request rather than retrying it unchanged.

When a waited job fails, the response keeps `state: "failed"` and uses a non-2xx status. Known validation, authorization, upstream, and availability failures map to their documented HTTP class; an unrecognized terminal failure is HTTP `500`, never a successful `200`.

## Charging

The fixed capability cost is charged once when the logical job completes successfully. Polls, internal retries, failed executions, and idempotent replays do not add another capability charge.

POST /execute is the stable REST entry point for every registered capability. The web layer never special-cases a platform ID; the capability's registered manifest supplies its input schema, timeout, example, canary, and fixed credit cost.

Request

POST https://data.upscrape.com/execute
Authorization: Bearer UPSCRAPE_API_KEY
Content-Type: application/json
Prefer: wait=30
Idempotency-Key: UNIQUE_LOGICAL_OPERATION

{
  "capability": "platform.capability.action",
  "input": {}
}

capability must be an available capability ID. input must satisfy that capability's JSON Schema. Find both on its public platform page.

Waiting for completion

Without Prefer: wait, execution is asynchronous and normally returns HTTP 202. Send Prefer: wait=N to wait for up to N seconds, with a server-side maximum of 300 seconds.

A wait is a response preference, not a different job type. If the job is still running when the window ends, Upscrape returns the same job as pending.

Completed response

Completed work returns HTTP 200 with state: "completed" and success: true. Capability output is intentionally open-ended because each upstream source has a different data shape.

{
  "job_id": "job_id",
  "state": "completed",
  "success": true,
  "results": [
    {"data": {"...": "capability-specific JSON"}}
  ],
  "billing": {"credits_charged": 1},
  "stats": {}
}

Use the capability's sample response as a realistic preview, but treat its input schema, not the sample output, as the validation contract.

Pending response

Pending work returns HTTP 202 with a job ID and non-terminal state. Poll the job instead of resubmitting the execution.

Validation

Invalid capability IDs, malformed JSON, and schema-invalid inputs fail before worker execution. Fix the request rather than retrying it unchanged.

When a waited job fails, the response keeps state: "failed" and uses a non-2xx status. Known validation, authorization, upstream, and availability failures map to their documented HTTP class; an unrecognized terminal failure is HTTP 500, never a successful 200.

Charging

The fixed capability cost is charged once when the logical job completes successfully. Polls, internal retries, failed executions, and idempotent replays do not add another capability charge.