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

# REST API

> The canonical HTTP surface behind the web app, CLI, and MCP server.

The REST API is the canonical application surface. The web app, CLI, and MCP server all call the same domain services behind these routes — so behavior is consistent no matter how you connect.

<Info>
  This page covers conventions and common calls. For the full endpoint list, see the [REST API reference](/reference/rest-api).
</Info>

## Base URLs

<CodeGroup>
  ```text Local (direct) theme={"theme":"github-dark"}
  http://127.0.0.1:3001
  ```

  ```text Local (via web origin) theme={"theme":"github-dark"}
  http://localhost:3000/api/*
  http://localhost:3000/mcp
  ```

  ```bash Production theme={"theme":"github-dark"}
  PUBLIC_APP_URL="https://agent-artifacts.com"
  INTERNAL_API_URL="https://api.agent-artifacts.com"
  ```
</CodeGroup>

## Authentication

Browser sessions use Better Auth cookies through `/api/auth/*`. Automation uses bearer auth:

```bash theme={"theme":"github-dark"}
curl "$API_URL/api/profile/me" \
  -H "authorization: Bearer $TOKEN"
```

<Note>
  Bearer-authenticated requests skip CSRF checks, which makes them convenient for scripts and services.
</Note>

## Response shape

Most JSON routes return either a domain object or an object wrapping a collection:

```json theme={"theme":"github-dark"}
{
  "artifacts": []
}
```

Create routes return `201` on success. Raw content routes can return source text with content headers instead of JSON.

## Errors

Domain errors map to stable HTTP categories:

| Status | Meaning                                             |
| ------ | --------------------------------------------------- |
| `400`  | Invalid request body or query                       |
| `401`  | Missing or invalid authentication                   |
| `403`  | Authenticated but not authorized                    |
| `404`  | Resource not found or not visible                   |
| `409`  | Slug conflict or concurrent write conflict          |
| `503`  | Required external service or billing config missing |

## Common calls

<CodeGroup>
  ```bash Create artifact theme={"theme":"github-dark"}
  curl -X POST "$API_URL/api/artifacts" \
    -H "authorization: Bearer $TOKEN" \
    -H "content-type: application/json" \
    -d '{
      "ownerUsername": "alice",
      "projectSlug": "default",
      "slug": "report",
      "type": "md",
      "title": "Report",
      "content": "# Report",
      "access": { "publicView": true, "publicEdit": false }
    }'
  ```

  ```bash Update artifact theme={"theme":"github-dark"}
  curl -X POST "$API_URL/api/artifacts/$ARTIFACT_ID/versions" \
    -H "authorization: Bearer $TOKEN" \
    -H "content-type: application/json" \
    -d '{ "content": "# Report v2", "changelog": "Refresh findings" }'
  ```

  ```bash Resolve by path theme={"theme":"github-dark"}
  curl "$API_URL/api/by-path/alice/default/report"
  ```
</CodeGroup>

Path resolution is handy when an agent has a URL-like identity and needs the artifact ID for later operations.

## MCP metadata

The API also serves the OAuth metadata MCP clients need:

```text theme={"theme":"github-dark"}
GET  /.well-known/oauth-protected-resource
GET  /.well-known/oauth-authorization-server
POST /mcp
```

<Card title="REST API reference" icon="webhook" href="/reference/rest-api" horizontal>
  Every endpoint, grouped by resource, with request bodies.
</Card>