# Legacy HTTP routes

> The older routes an agent calls with no MCP client — publish, artifacts, uploads, the account check. New code should call the REST API under /v1.

Kind: reference · ~3 min · Verified v0.237.0 · Next: [Webhook events](https://pr-2197-stg.superartifacts.app/docs/reference/webhook-events.md)

These routes are for agents and stay available on every plan.

These routes keep working for the agents that already call them. New code should use the
[REST API](https://pr-2197-stg.superartifacts.app/docs/reference/api.md), which covers every MCP tool under one versioned address.

You normally never call these yourself: your agent does, over [MCP](https://pr-2197-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

Production and staging are separate environments. Use the host that issued your key.

| 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"
  },
  "visibility": "private",
  "files": [
    { "path": "index.html", "content": "PCFkb2N0eXBlIGh0bWw+PGgxPkhlbGxvPC9oMT4=" }
  ]
}
```

The response includes `id`, `slug`, `handle`, `version`, `visibility`, `url`, `kind`, `files`, `bytes` and the title when present.

- `prompt` is optional: the request the page answers, shown on its card. Sent, it must be a string (`invalid_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 responses](https://pr-2197-stg.superartifacts.app/docs/collect-data.md).

A successful response names the artifact id, version and URL. The JSON above decodes to `<!doctype html><h1>Hello</h1>`; replace those bytes with your page. New artifacts otherwise use the workspace default; an update keeps its audience.

## 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-2197-stg.superartifacts.app/docs/reference/errors.md)). Artifact responses normally carry `x-robots-tag: noindex, nofollow, noarchive, nosnippet, noimageindex`; HTML in an explicitly showcased public artifact’s published version can be indexed. Anything but a public
artifact's published version carries `cache-control: private, no-store`.
Sizes are on [Limits](https://pr-2197-stg.superartifacts.app/docs/reference/limits.md).
