API Calls

Learn how to launch Workers, run Task templates, and inspect runs programmatically using CoreClaw API v2.

Getting Started

Authentication

The API v2 base URL is:

https://openapi.coreclaw.com

Authenticated endpoints support Bearer token, the legacy api-key header, and query token. New integrations should prefer Bearer token:

curl -X GET "https://openapi.coreclaw.com/api/v2/users/account" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get your API key from the CoreClaw Console.

For the full endpoint reference, see Base URL & Authentication.

Identifier Types

Identifier	What it identifies	How to get it	Used by
workerId	A Worker	Use the Worker slug, or encode a path such as coreclaw/google-maps-scraper as coreclaw~google-maps-scraper. You can get it from Store search or your Worker list.	/api/v2/workers/{workerId}, /api/v2/workers/{workerId}/runs
workerTaskId	A saved Task template	Generated when a user creates and saves a Task template.	/api/v2/worker-tasks/{workerTaskId}/runs
runId	A specific run record	Returned as data.run_slug after starting or rerunning a Worker or Task.	/api/v2/worker-runs/{runId}, /api/v2/worker-runs/{runId}/result, /api/v2/worker-runs/{runId}/result/export

Do not mix these identifiers. Passing a runId where a workerId or workerTaskId is expected results in request validation errors.

Start a Worker run

POST /api/v2/workers/{workerId}/runs

Request body:

{
  "input": {
    "keyword": "coffee",
    "limit": 10
  },
  "is_async": true,
  "version": "latest",
  "callback_url": "https://your-callback.example.com/webhook"
}

is_async controls whether the run executes asynchronously: true for async, false to wait for completion. Provide callback_url when you need webhook delivery of results.

input varies per Worker. It is not the old custom_params JSON string field. Read the Worker schema before constructing the payload:

• API: Call GET /api/v2/workers/{workerId}/input-schema and build input from the returned schema.
• Console: Open the Worker in the CoreClaw Console, go to the Input tab, click the API button in the top-right corner, and select API clients to view ready-to-use code snippets.

When building input:

• Follow the Worker input schema exactly.
• Provide every required field.
• Keep limit at 100 or lower when using synchronous result pagination.
• If input is missing or does not match the Worker schema, the API returns a validation error.

How to get version

version is optional. If omitted, the platform uses the latest version automatically. To pin a specific version, use the Worker version shown in the Console or the version field returned by Run Detail.

Run a saved Task template

POST /api/v2/worker-tasks/{workerTaskId}/runs

Request body:

{
  "is_async": true,
  "callback_url": "https://your-callback.example.com/webhook"
}

Task templates already contain their saved input settings. Use callback_url when you need webhook delivery, and use the returned data.run_slug as the runId for follow-up calls.

Inspect a run

Use the returned runId with the run APIs:

• Run Detail for status, Worker, and version.
• Run Log for execution logs.
• Run Result List for paginated results.
• Export Run Result for file export.

Common mistakes

• Using old v1 paths instead of the v2 resource paths.
• Sending system_params or custom_params as stringified JSON.
• Passing a runId where a workerId or workerTaskId is required.
• Omitting required Worker-specific input fields.
• Treating last run endpoints as stable references when a concrete runId is available.