# HTTP API

> The addresses your agent calls when it has no MCP client — publish, artifacts, uploads and the account check — with hosts and the error shape.

Kind: reference · ~3 min · Verified v0.66.1 · Next: [Limits](https://pr-756-stg.superartifacts.app/docs/reference/limits.md)

You normally never call these yourself: your agent does, over [MCP](https://pr-756-stg.superartifacts.app/docs/reference/mcp.md)
when it can, and over these addresses when it has no MCP client. This page is what it is
reading. Every call carries the agent's key in an `Authorization: Bearer <key>` header, except
the upload `PUT`, whose address is the permission. Bodies are JSON.

## Hosts

A plane is one running copy of Super Artifacts. Yours is production.

| Plane | Dashboard and MCP | Artifacts | API |
| --- | --- | --- | --- |
| production | `https://superartifacts.app` | `https://superart.page/{id}/` | `https://api.superart.page` |
| staging | `https://stg.superartifacts.app` | `https://stg.superart.page/{id}/` | `https://api-stg.superart.page` |

## Routes

| Method and path | Does |
| --- | --- |
| `POST /deploy` | Publishes files as a new version. `201` with `id`, `version`, `url`. |
| `POST /deploy/from-template` | The same, from a template's slots instead of files. |
| `GET /artifacts` | Your artifacts. `?slug=` narrows it. |
| `POST /artifacts` | Names a draft before it has bytes; its `url` is final. |
| `GET /artifacts/{id}` | One artifact, its versions and visibility. |
| `PATCH /artifacts/{id}` | Title, description, visibility, `sharedWith`, and the analytics and header switches. |
| `DELETE /artifacts/{id}` | Deletes it, every version and every response. |
| `POST /artifacts/{id}/publish` | `{"version": 3}` serves that version. |
| `DELETE /artifacts/{id}/versions/{n}` | Deletes an unpublished version. |
| `POST /artifacts/{id}/open` | A ten-minute viewer URL for your own private artifact. |
| `PUT /uploads/{owner}/{id}/{path}` | Stores one staged file. The URL comes from `super_upload`. |
| `GET /whoami` | Which account and plane the key belongs to. Call it first. |

## A publish, request and answer

```http
POST /deploy
Authorization: Bearer <key>

{
  "slug": "workout-tracker",
  "metadata": {
    "title": "Workout tracker",
    "prompt": "a tracker for my lifting sessions"
  },
  "files": [
    { "path": "index.html", "content": "PGh0bWw+…", "sha256": "e3b0c442…" }
  ]
}
```

```json
{
  "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "slug": "workout-tracker",
  "version": 2,
  "visibility": "private",
  "url": "https://superart.page/3f2504e0-4f89-41d3-9a0c-0305e82c3301/"
}
```

- `prompt` is required: one sentence on why the page was built (`missing_prompt`).
- `index.html` at the top level is required (`missing_index`).
- `content` is the file's bytes in base64. `sha256` is optional; sent, it must match.
- A `policy` beside `metadata` switches on [collecting data](https://pr-756-stg.superartifacts.app/docs/collecting-data.md).

## Reserved paths

A bundle path whose first segment starts with `_` is refused with `invalid_path`. Served
paths under `/{id}/__sa/` belong to the platform and never reach your bundle.

## Responses

Errors are `{ "error": { "code", "message" } }` with an accurate status
([Error codes](https://pr-756-stg.superartifacts.app/docs/reference/errors.md)). Every artifact response carries
`x-robots-tag: noindex, nofollow, noarchive, nosnippet, noimageindex`. Anything but a public
artifact's published version carries `cache-control: private, no-store`.
Sizes are on [Limits](https://pr-756-stg.superartifacts.app/docs/reference/limits.md).