# OpenMetal API (/api-reference)



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

## Production base URL [#production-base-url]

```text
https://api.openmetal.sh
```

## Start with a project key [#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](https://www.openmetal.sh/dashboard), create an organization and project, then
create a project key. Send both project credentials:

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

Check connectivity without authentication:

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

Then follow [Create a sandbox](/guides/create-sandbox) for a complete API request.

## Account management [#account-management]

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

```http
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 [#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 [#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 [#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]

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.

<Cards>
  <Card title="Create a sandbox" href="/guides/create-sandbox" />

  <Card title="Authenticate requests" href="/get-started/authentication" />

  <Card title="Receive webhooks" href="/guides/webhooks" />

  <Card title="Common errors" href="/errors/common-errors" />
</Cards>