OpenMetal API

The OpenMetal API uses JSON over HTTPS. Versioned endpoints are available under /v1.

Production base URL

https://api.openmetal.sh

Start with a project key

Most integrations use a project API key to create sandboxes, run processes, transfer files, expose HTTP endpoints, and inspect operations. Sign in to the OpenMetal dashboard, create an organization and project, then create a project key. Send both project credentials:

Authorization: Bearer metal_sk_your_key
X-Metal-Project-ID: prj_your_project

Check connectivity without authentication:

curl https://api.openmetal.sh/ready

Then follow Create a sandbox for a complete API request.

Account management

Organization, member, project, billing, usage, and webhook management routes use an OpenMetal user access token:

Authorization: Bearer <openmetal-user-access-token>

The dashboard and CLI manage this user session for you. Most sandbox integrations only need a project key.

Route families

• /v1/sandboxes, /v1/operations, and sandbox runtime routes use project credentials and are the primary integration surface used by the SDK and CLI.
• /v1/organizations and /v1/projects manage account-level resources with a user access token.
• Project-scoped sandbox aliases under /v1/projects/{project_id}/sandboxes support dashboard and user-session integrations.

Asynchronous operations

Sandbox lifecycle and runtime mutations can return 202 Accepted before provider work finishes. Persist the returned operation ID and wait until it reaches succeeded, failed, or cancelled.

Idempotency

Mutation endpoints that accept Idempotency-Key return the original result when the same key and identical request are replayed. Keep the original key after an uncertain network result. Reusing it with different input returns idempotency_mismatch.

Errors

Errors include a stable machine-readable code, a safe message, a request ID, and whether the failure is retryable. Provider capability failures can appear on the operation after the initial request is accepted.