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

# API Reference

> Control Plane API documentation.

This section documents the **Control Plane API**—the API that powers the Backdrift dashboard. This is separate from the APIs generated for your projects.

## Base URL

```
https://api.backdrift.ai
```

## Authentication

All endpoints (except `/auth/*`) require a Bearer token:

```bash theme={null}
Authorization: Bearer <access_token>
```

Get a token by logging in:

```bash theme={null}
curl -X POST https://api.backdrift.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
```

## Common Responses

### Success

```json theme={null}
{
  "data": { ... }
}
```

### Error

```json theme={null}
{
  "error": "Error message",
  "code": "ERROR_CODE"
}
```

## Rate Limiting

| Endpoint Category    | Limit   |
| -------------------- | ------- |
| Authentication       | 10/min  |
| Project Operations   | 100/min |
| Blueprint Generation | 10/min  |
| Deployments          | 5/min   |

## API Categories

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="#authentication-endpoints">
    Signup, login, token refresh
  </Card>

  <Card title="Projects" icon="folder" href="#project-endpoints">
    Create, list, update, delete projects
  </Card>

  <Card title="Specs" icon="file-text" href="#spec-endpoints">
    Chat, apply, generate blueprints from specs
  </Card>

  <Card title="Blueprints" icon="blueprint" href="#blueprint-endpoints">
    Generate, validate, get blueprints
  </Card>

  <Card title="Revisions" icon="git-branch" href="#revision-endpoints">
    Version history, compare, classify changes
  </Card>

  <Card title="Validations" icon="shield-check" href="#validation-endpoints">
    Well-Architected validation, auto-fixes
  </Card>

  <Card title="Deployments" icon="rocket" href="#deployment-endpoints">
    Deploy, preview, destroy, rollback
  </Card>

  <Card title="Templates" icon="copy" href="#template-endpoints">
    Pre-built starter templates
  </Card>
</CardGroup>

## Authentication Endpoints

### POST /auth/signup

Create a new account.

```bash theme={null}
curl -X POST https://api.backdrift.ai/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "SecurePass123!"
  }'
```

### POST /auth/login

Authenticate and get tokens.

```bash theme={null}
curl -X POST https://api.backdrift.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "SecurePass123!"
  }'
```

Response:

```json theme={null}
{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "expiresIn": 3600
}
```

### POST /auth/refresh

Refresh an expired access token.

```bash theme={null}
curl -X POST https://api.backdrift.ai/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJ..."
  }'
```

### GET /auth/me

Get current user info.

```bash theme={null}
curl https://api.backdrift.ai/auth/me \
  -H "Authorization: Bearer $TOKEN"
```

## Project Endpoints

### GET /projects

List your projects.

```bash theme={null}
curl https://api.backdrift.ai/projects \
  -H "Authorization: Bearer $TOKEN"
```

### POST /projects

Create a new project.

```bash theme={null}
curl -X POST https://api.backdrift.ai/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "description": "A task management application"
  }'
```

### GET /projects/:id

Get project details.

### PATCH /projects/:id

Update a project.

### DELETE /projects/:id

Archive a project.

## Spec Endpoints

The Spec API enables conversational backend editing. Users chat with AI to refine their backend specification, then apply changes and generate blueprints.

### GET /projects/:projectId/spec

Get the current project specification.

```bash theme={null}
curl https://api.backdrift.ai/projects/$PROJECT_ID/spec \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "spec": {
    "id": "spec-uuid",
    "projectId": "project-uuid",
    "content": "# My App\n\n## Entities\n...",
    "version": 3,
    "lastUserMessage": "Add comments to tasks",
    "createdAt": "2024-01-15T10:00:00Z"
  },
  "project": {
    "id": "project-uuid",
    "name": "My App"
  }
}
```

### POST /projects/:projectId/spec/chat

Send a chat message to refine the spec. Returns updated spec content (draft, not saved).

```bash theme={null}
curl -X POST https://api.backdrift.ai/projects/$PROJECT_ID/spec/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Add a comments feature to tasks"
  }'
```

Response:

```json theme={null}
{
  "spec": "# My App\n\n## Entities\n\n### Task\n...\n\n### Comment\n...",
  "previousSpec": "# My App\n\n## Entities\n\n### Task\n...",
  "assistantMessage": "I've added a Comment entity with task_id, author_id, content, and created_at fields.",
  "currentVersion": 3,
  "conversationId": "conv-uuid"
}
```

### POST /projects/:projectId/spec/apply

Save the current spec (creates a new version).

```bash theme={null}
curl -X POST https://api.backdrift.ai/projects/$PROJECT_ID/spec/apply \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# My App\n\n## Entities\n...",
    "lastUserMessage": "Add comments to tasks"
  }'
```

Response:

```json theme={null}
{
  "spec": {
    "id": "spec-uuid",
    "version": 4,
    "content": "...",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "message": "Spec saved as version 4"
}
```

### POST /projects/:projectId/spec/generate-blueprint

Generate a BlueprintIR from the saved spec. Returns immediately with a status URL.

```bash theme={null}
curl -X POST https://api.backdrift.ai/projects/$PROJECT_ID/spec/generate-blueprint \
  -H "Authorization: Bearer $TOKEN"
```

Response (202 Accepted):

```json theme={null}
{
  "blueprint": {
    "id": "blueprint-uuid",
    "projectId": "project-uuid",
    "status": "processing",
    "createdAt": "2024-01-15T10:35:00Z"
  },
  "specVersion": 4,
  "message": "Blueprint generation started",
  "statusUrl": "/blueprints/blueprint-uuid/status"
}
```

### GET /projects/:projectId/spec/generation-status/:blueprintId

Poll for blueprint generation progress.

```bash theme={null}
curl https://api.backdrift.ai/projects/$PROJECT_ID/spec/generation-status/$BLUEPRINT_ID \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "status": "processing",
  "currentStep": "Generating data model...",
  "progress": 45,
  "startedAt": "2024-01-15T10:35:00Z"
}
```

### GET /projects/:projectId/spec/chat/history

Get chat message history for a project.

```bash theme={null}
curl "https://api.backdrift.ai/projects/$PROJECT_ID/spec/chat/history?limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "conversationId": "conv-uuid",
  "messages": [
    {
      "id": "msg-1",
      "role": "user",
      "content": "Add a comments feature to tasks",
      "createdAt": "2024-01-15T10:00:00Z"
    },
    {
      "id": "msg-2",
      "role": "assistant",
      "content": "I've added a Comment entity...",
      "createdAt": "2024-01-15T10:00:05Z"
    }
  ]
}
```

### POST /projects/:projectId/spec/chat/message

Add an assistant message to the chat history (used for system notifications like generation status).

```bash theme={null}
curl -X POST https://api.backdrift.ai/projects/$PROJECT_ID/spec/chat/message \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "assistant",
    "content": "Blueprint generated successfully!"
  }'
```

Response:

```json theme={null}
{
  "message": {
    "id": "msg-uuid",
    "role": "assistant",
    "content": "Blueprint generated successfully!",
    "createdAt": "2024-01-15T10:36:00Z"
  },
  "conversationId": "conv-uuid"
}
```

## Blueprint Endpoints

### POST /projects/:id/blueprints

Generate a blueprint from a prompt.

```bash theme={null}
curl -X POST https://api.backdrift.ai/projects/$PROJECT_ID/blueprints \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A task management app with projects, tasks, and team members"
  }'
```

### POST /blueprints/:id/validate

Run validation checks on a blueprint.

### GET /blueprints/:id/validation-report

Get detailed validation results.

## Deployment Endpoints

### POST /projects/:id/validate

Preview deployment (dry run).

### POST /projects/:id/deploy

Deploy the project.

### GET /deployments/:id

Get deployment status and logs.

### DELETE /projects/:id/stack

Destroy all stacks.

### POST /projects/:id/rollback

Rollback to a previous deployment.

## Artifact Endpoints

### GET /projects/:id/artifacts/openapi

Get OpenAPI specification (JSON).

### GET /projects/:id/artifacts/design-doc

Get design documentation.

### GET /projects/:id/artifacts/sdk/python

Download Python SDK.

### GET /projects/:id/artifacts/cdk

Download CDK project.

## Usage Endpoints

### GET /usage/me

Get your LLM usage summary.

```bash theme={null}
curl https://api.backdrift.ai/usage/me \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "user": {
    "id": "user-123",
    "email": "you@example.com"
  },
  "usage": {
    "totalCalls": 42,
    "inputTokens": 150000,
    "outputTokens": 50000,
    "totalCostCents": 325,
    "totalCostFormatted": "$3.25"
  }
}
```

### GET /usage/recent

Get recent LLM calls for debugging.

```bash theme={null}
curl "https://api.backdrift.ai/usage/recent?limit=10" \
  -H "Authorization: Bearer $TOKEN"
```