> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.deepmask.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API quickstart

> Enable API billing, create your first API key, and send a chat completion request to DeepMask models from your own code.

This guide takes you from no API access to your first successful request. You enable API billing for your organization, create a key, and call a model with cURL, Python, or Node.js. The DeepMask API is OpenAI-compatible, so you can use the official OpenAI SDKs by setting the base URL and your DeepMask API key. The API supports chat completions (`POST /v1/chat/completions`) and model listing (`GET /v1/models`). Other OpenAI endpoints aren't supported. For example, the Responses API (`/v1/responses`) returns `404`.

> [!NOTE]
>
> New to the DeepMask API? Read the [API overview](https://documentation.deepmask.io/api/overview.md) for what the API offers and how it fits alongside your Chat plan.

## Before you start

You need:

* **Admin access to your organization.** Only organization admins see **API** in **User Settings**. If you're a member, ask an admin to set up access. See [Team management](https://documentation.deepmask.io/enterprise/team-management.md) for roles.
* **An active paid plan.** Your organization needs an active Pro, Power, or Enterprise plan. The Free plan, trials, and plans with an overdue payment don't include API access.
* **A payment method for API billing.** The API is billed separately from your Chat plan, so checkout asks for a payment method and a billing address.
* **A way to send requests.** Use a macOS or Linux terminal with `curl`, or Python or Node.js with the OpenAI SDK. On Windows, run the cURL commands in WSL or Git Bash.

> [!NOTE]
>
> If your organization isn't on an eligible plan, the API page shows "API access needs an active paid Chat plan." Use the **Chat billing** link in that notice to review your plan.

## Set up access and send a test request

**1. Open the API settings**

At the bottom of the chat sidebar, click your name and choose **User Settings**. In the settings sidebar, click **API**.

The page shows the **Base URL** for all requests, `https://api.deepmask.io/v1`, with a copy button. Below it are the **Keys**, **Models**, **Usage**, and **Billing** tabs.

**2. Enable API billing**

Until API billing is active, the page shows "Enable API billing to start using your keys." and **Create key** is unavailable.

Click **Enable API billing** in that notice. You can also open the **Billing** tab, where the **API billing** card shows **Not enabled**, and click **Enable API billing** there.

DeepMask opens Stripe Checkout. Add a payment method, check your billing address, and complete checkout. If your organization already has a name and billing address on file, checkout fills them in. You can also add a VAT ID, which is optional. API billing is a pay-as-you-go subscription: your monthly invoice includes model costs plus a 3% fee, plus VAT where applicable. See [Billing](https://documentation.deepmask.io/api/billing.md) for details.

![API settings page with the notice Enable API billing to start using your keys, an Enable API billing button, the Base URL, and an empty Keys tab.](https://mintcdn.com/deepmaskgmbh/Tc7tJrGOE8MSnXNJ/images/api/enable-billing.jpg?fit=max\&auto=format\&n=Tc7tJrGOE8MSnXNJ\&q=85\&s=7afe57ef042a7091b168cc228f8e7810)

Until API billing is enabled, the API page asks you to enable it before you can create keys.

**3. Confirm that billing is active**

After checkout, you return to the API page, which refreshes automatically. Open the **Billing** tab and check that the **API billing** status shows **Active**.

Activation can take a moment. If the status hasn't changed yet, wait briefly and click **Refresh** at the top of the page.

If you leave checkout before finishing, API billing stays **Not enabled**. Click **Enable API billing** to try again.

**4. Review the spending cap (optional)**

On the **Billing** tab, the **Gateway spending cap** is the organization-wide cap shared by all your keys. It starts at €100 of model costs per month, before the 3% fee and tax. It resets at 00:00 UTC on the 1st of each month.

To change it, enter an amount up to the maximum shown below the field and click **Save cap**. You can also give each key its own cap. See [Spending caps](https://documentation.deepmask.io/api/spending-caps.md).

**5. Create a key**

Open the **Keys** tab and click **Create key**. In the **Create API key** dialog:

1. Enter a **Key name** that identifies the app or environment, such as "Production service".
2. Optionally, enter a monthly amount in **Key spending cap (optional)**. It can't be higher than the **Gateway spending cap**. Leave it empty to rely on the **Gateway spending cap** only.
3. Under **Model access**, keep **Choose models** and select the models this key can use. Models are grouped by provider, and each group starts collapsed. To follow the examples on this page, search for `gpt-4o` or expand **OpenAI**, and select GPT-4o. Or choose **All current models** to grant every model available today. Models added later aren't included.
4. Click **Create key**.

You can't change a key's models after you create it. To grant different models, create a new key. See [API keys](https://documentation.deepmask.io/api/keys.md).

**6. Save your key**

The **Save your API key** dialog shows your new key. Click **Copy key** and store the key somewhere safe, such as your secrets manager or an environment variable.

> [!WARNING]
>
> DeepMask shows the full key only once. If you close the dialog, reload the page, or switch organizations before you copy it, you can't get it back. If you lose it, revoke the key and create a new one.

**7. Test your key**

Before you close the dialog, expand **Test your key**. Set the `DEEPMASK_API_KEY` environment variable to your key:

```bash theme={null}
export DEEPMASK_API_KEY="sk-..."
```

To keep the key out of your shell history, run `read -rs DEEPMASK_API_KEY && export DEEPMASK_API_KEY` instead, then paste the key and press Enter.

Click **Copy command**, then paste the command into the same terminal and run it. The command sends "Hello" to one of the key's models. A JSON response with a reply means your key works. Test requests are billed like any other request.

When you're done, click **I’ve saved it** to close the dialog.

![Save your API key dialog with the key in a read-only field, the Copy key button, the Shown once warning, an expanded Test your key section with a cURL command and Copy command, and the I’ve saved it button.](https://mintcdn.com/deepmaskgmbh/Tc7tJrGOE8MSnXNJ/images/api/save-key.jpg?fit=max\&auto=format\&n=Tc7tJrGOE8MSnXNJ\&q=85\&s=237c8f7d85001eec8a8c07de974d1b6d)

Copy your key before you close the dialog, then test it with the ready-made command.

> [!TIP]
>
> Keep your key on your server. Read it from an environment variable or a secrets manager, and never put it in browser code, mobile apps, or version control.

## Make your first request

Send a chat completion to `POST /v1/chat/completions`. Each example reads your key from `DEEPMASK_API_KEY` and uses `gpt-4o`. To use another model, copy its **API model ID** from the **Models** tab and make sure your key can use it.

To run the SDK examples, install the official `openai` package:

* **Python:** Run `pip install openai`. Save the example as `quickstart.py` and run `python quickstart.py`.
* **Node.js:** Run `npm install openai`. Save the example as `quickstart.mjs` in the same folder and run `node quickstart.mjs`. The `.mjs` extension lets the file use `import` and top-level `await`.

Run the examples in the same terminal where you set `DEEPMASK_API_KEY`. In Windows PowerShell, set the variable with `$env:DEEPMASK_API_KEY = "sk-..."` instead.

```bash cURL theme={null}
curl https://api.deepmask.io/v1/chat/completions \
  -H "Authorization: Bearer $DEEPMASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what an API key is in one sentence."}
    ],
    "max_tokens": 200
  }'
```

```python Python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepmask.io/v1",
    api_key=os.environ["DEEPMASK_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what an API key is in one sentence."},
    ],
    max_tokens=200,
)

print(response.choices[0].message.content)
```

```javascript Node.js theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepmask.io/v1",
  apiKey: process.env.DEEPMASK_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Explain what an API key is in one sentence." },
  ],
  max_tokens: 200,
});

console.log(response.choices[0].message.content);
```

> [!WARNING]
>
> The API accepts a fixed set of request fields. `max_tokens`, used in the examples above, is one of them. Sampling options such as `temperature`, `top_p`, `stop`, and `seed` are accepted within their ranges. Some models ignore some of these options without an error. Some models refuse certain values, such as a `temperature` above 1. Other parameters, such as `response_format` and `logprobs`, are refused with a `400` error and the code `API_REQUEST_UNBOUNDED`. So is an `n` value other than 1. Check [Sampling options](https://documentation.deepmask.io/api/chat-completions.md#sampling-options) and [Unsupported parameters](https://documentation.deepmask.io/api/chat-completions.md#unsupported-parameters) before you add options.

## Read the response

A successful request returns HTTP `200` with a standard chat completion object. This example is abbreviated, and your values will differ:

```json theme={null}
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "An API key is a secret token that identifies your app when it calls an API."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 18,
    "total_tokens": 45
  }
}
```

* `choices[0].message.content` contains the model's reply.
* `usage` shows the input and output tokens of the request. Requests are billed by token. See [Models](https://documentation.deepmask.io/api/models.md) for how pricing works.

Your request also appears in the **Request log** on the **Usage** tab. If you don't see it yet, click **Refresh** at the top of the page. See [Usage and logs](https://documentation.deepmask.io/api/usage-and-logs.md).

To receive the reply in pieces as the model writes it, set `stream` to `true`. See [Chat completions](https://documentation.deepmask.io/api/chat-completions.md) for streaming, tools, and all supported fields.

## If your first request fails

Every error returns a JSON body whose `error.code` names the problem, such as `API_MODEL_NOT_ALLOWED`. The `error.message` is always the same, so check the HTTP status and `error.code`. See [Error response format](https://documentation.deepmask.io/api/errors.md#error-response-format) for the full body.

| Status | Code | What to check |
| - | - | - |
| `401` | `API_CREDENTIAL_INVALID` | The key is missing, mistyped, or revoked. Send exactly one `Authorization: Bearer <key>` header. |
| `403` | `API_SUBSCRIPTION_INACTIVE` | API billing isn't active, or your organization isn't on an active paid plan. Check the **API billing** status on the **Billing** tab and any notice at the top of the API page. |
| `403` | `API_MODEL_NOT_ALLOWED` | The key can't use this model. Use the exact **API model ID**, and make sure the key includes the model. |
| `400` | `API_REQUEST_INVALID` | The body isn't valid JSON, the `Content-Type: application/json` header is missing, or `model` is missing. Check your quoting and headers. |
| `400` | `API_REQUEST_UNBOUNDED` | The request contains a field or value the API doesn't accept, such as `response_format` or a `temperature` above 2. |
| `404` | `API_ENDPOINT_NOT_FOUND` | The path isn't supported. Check that your base URL is exactly `https://api.deepmask.io/v1`, and call `/v1/chat/completions` without a trailing slash. A path outside `/v1/` returns `404` with an empty body. |
| `429` | `API_CONCURRENCY_LIMIT`, `API_RPM_LIMIT`, `API_TPM_LIMIT`, `API_RATE_LIMIT`, `API_MODEL_CAPACITY` | You've reached a limit. Most limits are shared by all keys in your organization. Each key also has a few limits of its own. See **API limits** on the **Usage** tab and [Limits at a glance](https://documentation.deepmask.io/api/limits.md#limits-at-a-glance). `API_MODEL_CAPACITY` means the model has reached its capacity limit, which all organizations share. Wait briefly and retry, or try another model. |
| `503` | `API_ADMISSION_UNAVAILABLE` | DeepMask can't take requests for your organization right now. Wait a minute and retry. If it keeps happening, check the notice at the top of the API page. If it says requests are paused, don't retry in a loop. See [When requests are paused](https://documentation.deepmask.io/api/errors.md#when-requests-are-paused). |
| `503`, `504` | `API_INFERENCE_UNAVAILABLE` | DeepMask couldn't get a response from the model. You aren't billed unless usage for the request still arrives later. Retry with backoff, but don't resend the request in a loop. More than 20 failures like this in 24 hours pause your organization's requests. See [Unclear outcomes](https://documentation.deepmask.io/api/limits.md#unclear-outcomes). |

To see which models your key can use, call `GET /v1/models`. It returns only the models granted to that key:

```bash theme={null}
curl https://api.deepmask.io/v1/models \
  -H "Authorization: Bearer $DEEPMASK_API_KEY"
```

For any other code, including spending cap refusals, see [Errors and retries](https://documentation.deepmask.io/api/errors.md). For every limit, see [Limits and fair use](https://documentation.deepmask.io/api/limits.md).

## Next steps

> [card] [Manage API keys](https://documentation.deepmask.io/api/keys.md)
>
> Create keys per app or environment, review their status, and revoke keys you no longer need.

> [card] [Set spending caps](https://documentation.deepmask.io/api/spending-caps.md)
>
> Control monthly model costs with the organization-wide cap and optional per-key caps.

> [card] [Chat completions reference](https://documentation.deepmask.io/api/chat-completions.md)
>
> Learn the supported request fields, streaming, tool calling, and response format.

> [card] [Models and pricing](https://documentation.deepmask.io/api/models.md)
>
> Browse API models, find their model IDs, and learn how per-token pricing works.

> [card] [Limits and fair use](https://documentation.deepmask.io/api/limits.md)
>
> Check the rate, token, and budget limits that apply to your requests.

> [card] [Errors and retries](https://documentation.deepmask.io/api/errors.md)
>
> Understand error codes, which errors to retry, and how to handle refused requests.

> [card] [Usage and logs](https://documentation.deepmask.io/api/usage-and-logs.md)
>
> Track monthly charges, check your API limits, and review your requests.

> [card] [Billing](https://documentation.deepmask.io/api/billing.md)
>
> Understand your monthly API invoice and manage invoices and cancellation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.