Skip to content

Public API

Read and deploy your projects over HTTP with an API token.

View as Markdown

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.json describes 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:

terminal
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

terminal
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:

terminal
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

AreaOperations
ProjectsList and read projects.
DeploymentsList and read deployments and build logs; upload a build bundle and blobs, then finalize it.
ServicesList, add, update and remove services; choose the default public service and a Durable Object implementation owner. See Services and releases.
Service environmentsRead service environment overrides with secrets masked, and replace those overrides.
ReleasesList and read releases, build and publish all services together, and restore an earlier release.
RunsRecheck the served deployment and read a run; see Activity.
Git sourceRead, set, disconnect and deploy a branch, tag or commit.
Environment variablesRead and replace variables; see Environment variables.
Custom domainsList, remove and recheck domains.
DeliveryConfigure Cache Inspector, local cache copies, CSP nonce and CSP reporting settings.
Storage and computeManage environment bindings and default storage; check native Images availability. See Bindings.
ObservabilityManage and test drains; configure PostHog capture paths.
Access protectionRead and change protection, revoke sessions, manage links and codes, and rotate the automation key. See Access protection.
OIDCRead and change federation settings and issue a development token. See OIDC federation.
EmailManage domains, project settings, sending keys and message history. Sending keys separately authorize sending and reading their own messages. See Email.
GitHubList 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" } }
StatuscodeMeaning
401unauthorizedNo token, or one that is unknown, revoked or expired.
403forbiddenThe token lacks the operation's permission, or may not be used for it or from here.
404not_foundNothing by that ID in your team, or in the projects the token is limited to.
409run_in_progress, project_suspended, …The request conflicts with the project's state; message says how.
429rate_limitedToo many requests; wait and try again.
503deploys_pausedArkor 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.