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

# Antideploy REST API: Overview

> Base URL, authentication, the four endpoints, rate limits, and error format for the Antideploy API.

The Antideploy API deploys a project and reports on it. It is deliberately
small (four endpoints) because that is all deploying takes.

## Base URL

```
https://antideploy.com/api/v1
```

<Tip>
  That URL is also a live, unauthenticated description of the API. `curl` it and
  you get the full contract as JSON: request shapes, error codes, and current
  limits. If you are pointing an AI agent at Antideploy, give it this URL along
  with the project key.
</Tip>

## Authentication

Every request carries a project API key as a bearer token:

```bash theme={null}
curl https://antideploy.com/api/v1/deployments/$TASK_ID \
  -H "Authorization: Bearer $ANTIDEPLOY_KEY"
```

Keys are **scoped to a single application**. The key identifies which app you
are acting on, so no application id is ever sent.

<Card title="Authentication" icon="key" href="/docs/api/authentication">
  Creating, rotating, and revoking keys.
</Card>

## Endpoints

| Method | Path                           | Purpose                                 |
| ------ | ------------------------------ | --------------------------------------- |
| `GET`  | `/api/v1`                      | The API contract. No key required.      |
| `POST` | `/api/v1/deploy`               | Push a project and deploy it.           |
| `GET`  | `/api/v1/deployments/{taskId}` | Status, steps, spec, warnings, hazards. |
| `PUT`  | `/api/v1/secrets`              | Write environment variables.            |
| `GET`  | `/api/v1/secrets`              | List variable names. Never values.      |

That is the complete surface. There are no endpoints for creating,
listing or deleting applications: projects are created in the dashboard,
which is also where keys are issued.

<Card title="Deploy over the API" icon="rocket" href="/docs/api/deploy">
  The full deploy reference, with the one command that ships a directory.
</Card>

## Request format

`POST /api/v1/deploy` is **`multipart/form-data`**: it carries your source
tree. Everything else is JSON.

## Rate limits

| Limit                              | Value |
| ---------------------------------- | ----- |
| Deploys per hour, per application  | 20    |
| Concurrent deploys per application | 1     |

A second deploy while one is running returns `409` with the in-flight
`taskId`, not an error you need to retry blindly. Exceeding the hourly limit
returns `429` with `retryAfterSeconds`.

<Note>
  Both limits exist because agents retry. A human clicks Deploy a few times a
  day; a loop that treats failure as retryable will hit the API as fast as it is
  accepted.
</Note>

## Errors

Errors return a JSON body with a stable `code`, a human-readable `error`, and
a `documentation` URL pointing back at the contract.

```json theme={null}
{
  "error": "Received 1 file but 2 paths. Send one `paths` field per `files` field, in the same order, or send an `archive` instead.",
  "code": "paths_mismatch",
  "documentation": "https://antideploy.com/api/v1"
}
```

| Status | Codes                                                                |
| ------ | -------------------------------------------------------------------- |
| 400    | `empty`, `bad_request`, `bad_archive`, `paths_mismatch`, `too_large` |
| 401    | `unauthorized`                                                       |
| 409    | `deploy_in_progress`                                                 |
| 429    | `rate_limited`                                                       |

Match on `code`, not on the message text.

## Asynchronous by design

`POST /api/v1/deploy` returns `202` immediately with a `taskId`. Building and
releasing take a minute or two. Poll `/api/v1/deployments/{taskId}` until
`status` is `succeeded` or `failed`.

The poll response carries `warnings` and `hazards` as structured data. A
deploy can succeed and still not behave as its author expects; those fields
are how you find out.