Public API
Read and deploy your projects over HTTP with an API token.
The Public API lets a tool of your own read your team's projects, deploy them and change their settings.
- Base URL:
https://api.arkor.dev - Reference: the OpenAPI 3.1 document at
https://api.arkor.dev/openapi.jsondescribes every operation, its parameters and its answers. - Authentication: an API token, sent as
authorization: Bearer ark_…. A token holds permissions, each at Read or Read and write, and may be limited to some projects and addresses. Sending email uses a separate project- and environment-scoped sending key.
Use the API from servers and scripts. Keep tokens out of browser code; cross-origin browser requests are not supported.
To connect an AI assistant, use the Remote MCP server.
Find a project's ID
The API names a project by its ID, which is not the ID in the dashboard's address. List the team's projects to find it:
curl https://api.arkor.dev/v1/projects -H "authorization: Bearer $ARKOR_TOKEN"Each project in projects has an id and a displayName, such as my-app.
Deploy the production branch
curl -X POST https://api.arkor.dev/v1/projects/$PROJECT_ID/source/deploy \
-H "authorization: Bearer $ARKOR_TOKEN" \
-H "content-type: application/json" \
-d '{}'The answer has the new deployment. Pass { "ref": "<commit SHA>" } to build a given commit
instead; it is published to production like any other build. Then follow the deployment:
curl https://api.arkor.dev/v1/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID \
-H "authorization: Bearer $ARKOR_TOKEN"Its status is active once it is published, and failed if it failed. Its build log is at
/v1/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID/log.
What the API covers
| Area | Operations |
|---|---|
| Projects | List and read projects. |
| Deployments | List and read deployments and build logs; upload a build bundle and blobs, then finalize it. |
| Services | List, add, update and remove services; choose the default public service and a Durable Object implementation owner. See Services and releases. |
| Service environments | Read service environment overrides with secrets masked, and replace those overrides. |
| Releases | List and read releases, build and publish all services together, and restore an earlier release. |
| Runs | Recheck the served deployment and read a run; see Activity. |
| Git source | Read, set, disconnect and deploy a branch, tag or commit. |
| Environment variables | Read and replace variables; see Environment variables. |
| Custom domains | List, remove and recheck domains. |
| Delivery | Configure Cache Inspector, local cache copies, CSP nonce and CSP reporting settings. |
| Storage and compute | Manage environment bindings and default storage; check native Images availability. See Bindings. |
| Observability | Manage and test drains; configure PostHog capture paths. |
| Access protection | Read and change protection, revoke sessions, manage links and codes, and rotate the automation key. See Access protection. |
| OIDC | Read and change federation settings and issue a development token. See OIDC federation. |
| Manage domains, project settings, sending keys and message history. Sending keys separately authorize sending and reading their own messages. See Email. | |
| GitHub | List the team's connected GitHub accounts and available repositories. |
Creating projects, adding custom domains, connecting GitHub accounts and managing API tokens are done in the dashboard. Reading runtime log events, analytics reports, Speed Insights and usage is not part of this API; drains export new observability events to your endpoint.
For an uploaded build, send bundle.json to POST /v1/projects/{projectId}/deployments, upload the
blob hashes returned in missing, then call POST /v1/projects/{projectId}/deployments/{deploymentId}/finalize.
Follow the returned run to confirm publication. The OpenAPI reference
and MCP upload example describe the request shapes.
Direct uploads require a single service with default routes and connections, no production service environment overrides, and all production resources assigned under their original names. For other configurations, deploy from Git; see Services and releases.
Register Workers AI
With a token that holds Bindings at Read and write, call POST /v1/projects/{projectId}/environments/production/bindings with { "name": "INFERENCE", "type": "ai" }. No location or provider options are accepted. The binding starts as pending_deployment and becomes ready after successful publication. List environments and bindings to inspect its state. Branch previews receive isolated identities from production definitions. See Bindings for the inference-only SDK and billing behavior.
Errors
A refused request answers with an HTTP status and a body such as:
{ "ok": false, "error": { "code": "not_found", "message": "unknown project" } }| Status | code | Meaning |
|---|---|---|
| 401 | unauthorized | No token, or one that is unknown, revoked or expired. |
| 403 | forbidden | The token lacks the operation's permission, or may not be used for it or from here. |
| 404 | not_found | Nothing by that ID in your team, or in the projects the token is limited to. |
| 409 | run_in_progress, project_suspended, … | The request conflicts with the project's state; message says how. |
| 429 | rate_limited | Too many requests; wait and try again. |
| 503 | deploys_paused | Arkor is not taking deployments for a moment. Retry after the retry-after header. |
A deployment or a run asked for while the team's projects are paused is refused with
409 spend_limit_reached: the team has reached its
spend limit, or, on the
free plan, its month has used what the plan includes.
Every answer carries an x-arkor-request-id header. Quote it when you ask for help with a request.
Rate limits
Each IP address, and each token, may make 120 requests a minute. Past that, requests are answered
429 rate_limited; wait before trying again.
Blob uploads (PUT /v1/projects/{projectId}/deployments/{deploymentId}/blobs/{sha256}) are counted
separately, at 3,000 a minute, since a deployment uploads one request per blob.
Native Images bindings
Register { "name": "IMAGES", "type": "images" } through the same binding endpoint. No resource
ID or location is accepted. The host must have enabled its verified private Images service.
GET /v1/projects/{projectId}/images-capability returns its build availability, automatic-binding
policy and registered names. A deployment seals these values when it starts. See
Images transforms for the transform-only API and metering.