Base URL & Authentication

Overview

CoreClaw’s API is a RESTful surface over three objects:

• Worker — a runnable script in the Store or your private workspace.
• Worker Task — a saved, optionally scheduled run configuration (input + settings).
• Run — a single execution of a Worker or Task, producing logs and results.

The typical flow: find a Worker → read its input schema → start a run (async) → poll or receive a callback → read results or export a file. This page covers base URL, auth, conventions, and the full endpoint catalog; individual endpoints have their own pages.

API Base URL

Use https://openapi.coreclaw.com as the HTTP API base URL. Every v2 endpoint path starts with /api/v2, for example https://openapi.coreclaw.com/api/v2/users/account.

https://openapi.coreclaw.com

Authentication

Authenticated endpoints support three token transport modes. Prefer Bearer tokens, while keeping compatibility with the legacy api-key header and query token:

-H "Authorization: Bearer YOUR_API_KEY"

Mode	Example	Notes
Bearer token	Authorization: Bearer YOUR_API_KEY	Recommended for new server-side integrations; also works in the browser playground
Legacy header	api-key: YOUR_API_KEY	Compatible with v1 integrations; server-side only — the browser playground cannot use it due to a CORS preflight restriction; use Bearer or query token instead
Query token	?token=YOUR_API_KEY	Use only when headers are unavailable; avoid logging tokenized URLs

Public endpoints do not require a token, including proxy region lookup and Store Worker search.

Calling Conventions

• Read the Worker input schema before sending input; fields differ by Worker.
• Use POST /api/v2/workers/{workerId}/runs for a direct Worker run, or POST /api/v2/worker-tasks/{workerTaskId}/runs for a saved task run.
• is_async: true returns immediately; use runId to read details, logs, and results. is_async: false waits for completion and returns a synchronous result window.
• offset is 1-based on list and result endpoints — offset=1 returns the first page (think of it as page_index = offset, with limit as the page size). limit is capped at 100.
• Use export endpoints when the caller needs a downloadable result file instead of fetching every page in a browser.

Response Envelope

Most JSON responses include code, message, request_id, and data. HTTP status describes the request layer; application code: 0 means the business operation succeeded. Keep HTTP status, code, message, and request_id when troubleshooting failed requests.

Errors

When code is non-zero, the business operation failed even though the request reached the service. Common ones: 12001/12002 (auth), 13000 (rate-limited), 30001 (insufficient balance), 50001/60001/70001 (Worker/task/run not found). See the full Error Codes page for the table and handling guidance.

Callbacks

For async runs, pass callback_url in the request body and CoreClaw will POST to it when the run finishes — no need to poll. Callers should still store data.run_slug and request_id for follow-up reads. See Callback Notifications.

Identifier Types

Identifier	Meaning	Usage
workerId	Worker identifier	Accepts a Worker slug or a path encoded as owner~name from owner/name
workerTaskId	Saved task template identifier	Passed as a path parameter when running a task template
runId	Run record identifier	The data.run_slug returned after starting or rerunning a Worker

Endpoint Reference

#	Method	Endpoint	Docs
1	GET	/api/v2/proxy/region	List Proxy Regions
2	GET	/api/v2/store	List Store Workers
3	GET	/api/v2/users/account	Get User Account
4	GET	/api/v2/workers	List Workers
5	GET	/api/v2/workers/{workerId}	Get Worker Detail
6	GET	/api/v2/workers/{workerId}/input-schema	Get Worker Input Schema
7	POST	/api/v2/workers/{workerId}/runs	Run Worker
8	GET	/api/v2/worker-tasks	List Worker Tasks
9	POST	/api/v2/worker-tasks/{workerTaskId}/runs	Run Worker Task
10	POST	/api/v2/worker-tasks	Create Worker Task
11	GET	/api/v2/worker-tasks/{workerTaskId}	Get Worker Task
12	PUT	/api/v2/worker-tasks/{workerTaskId}	Update Worker Task
13	DELETE	/api/v2/worker-tasks/{workerTaskId}	Delete Worker Task
14	GET	/api/v2/worker-tasks/{workerTaskId}/input	Get Worker Task Input
15	PUT	/api/v2/worker-tasks/{workerTaskId}/input	Update Worker Task Input
16	GET	/api/v2/worker-runs	List Worker Runs
17	GET	/api/v2/worker-runs/last	Get Last Worker Run
18	POST	/api/v2/worker-runs/last/abort	Abort Last Worker Run
19	GET	/api/v2/worker-runs/last/export	Export Last Worker Run Results
20	GET	/api/v2/worker-runs/last/log	Get Last Worker Run Log
21	POST	/api/v2/worker-runs/last/rerun	Rerun Last Worker Run
22	GET	/api/v2/worker-runs/last/result	List Last Worker Run Results
23	GET	/api/v2/worker-runs/{runId}	Get Worker Run Detail
24	POST	/api/v2/worker-runs/{runId}/abort	Abort Worker Run
25	GET	/api/v2/worker-runs/{runId}/log	Get Worker Run Log
26	POST	/api/v2/worker-runs/{runId}/rerun	Rerun Worker Run
27	GET	/api/v2/worker-runs/{runId}/result	List Worker Run Results
28	GET	/api/v2/worker-runs/{runId}/result/export	Export Worker Run Results
29	GET	/api/v2/workers/{workerId}/runs/last	Get Worker Last Run
30	POST	/api/v2/workers/{workerId}/runs/last/abort	Abort Worker Last Run
31	GET	/api/v2/workers/{workerId}/runs/last/export	Export Worker Last Run Results
32	GET	/api/v2/workers/{workerId}/runs/last/log	Get Worker Last Run Log
33	POST	/api/v2/workers/{workerId}/runs/last/rerun	Rerun Worker Last Run
34	GET	/api/v2/workers/{workerId}/runs/last/result	List Worker Last Run Results

Next steps

• Run a Worker — start your first run
• Error Codes — interpret non-zero code values
• Callback Notifications — receive run-status webhooks
• Examples — runnable snippets in Python, Node.js, Go, PHP, and Java