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:

Authorization: Bearer <access_token>

Get a token by logging in:

curl -X POST https://api.backdrift.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]", "password": "your-password"}'

Common Responses

Success

{
  "data": { ... }
}

Error

{
  "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

Authentication

Signup, login, token refresh

Projects

Create, list, update, delete projects

Specs

Chat, apply, generate blueprints from specs

Blueprints

Generate, validate, get blueprints

Revisions

Version history, compare, classify changes

Validations

Well-Architected validation, auto-fixes

Deployments

Deploy, preview, destroy, rollback

Templates

Pre-built starter templates

Authentication Endpoints

POST /auth/signup

Create a new account.

curl -X POST https://api.backdrift.ai/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "SecurePass123!"
  }'

POST /auth/login

Authenticate and get tokens.

curl -X POST https://api.backdrift.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "SecurePass123!"
  }'

Response:

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "expiresIn": 3600
}

POST /auth/refresh

Refresh an expired access token.

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

GET /auth/me

Get current user info.

curl https://api.backdrift.ai/auth/me \
  -H "Authorization: Bearer $TOKEN"

Project Endpoints

GET /projects

List your projects.

curl https://api.backdrift.ai/projects \
  -H "Authorization: Bearer $TOKEN"

POST /projects

Create a new project.

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.

curl https://api.backdrift.ai/projects/$PROJECT_ID/spec \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "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).

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:

{
  "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).

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:

{
  "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.

curl -X POST https://api.backdrift.ai/projects/$PROJECT_ID/spec/generate-blueprint \
  -H "Authorization: Bearer $TOKEN"

Response (202 Accepted):

{
  "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.

curl https://api.backdrift.ai/projects/$PROJECT_ID/spec/generation-status/$BLUEPRINT_ID \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "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.

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

Response:

{
  "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).

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:

{
  "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.

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.

curl https://api.backdrift.ai/usage/me \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "user": {
    "id": "user-123",
    "email": "[e-mail]"
  },
  "usage": {
    "totalCalls": 42,
    "inputTokens": 150000,
    "outputTokens": 50000,
    "totalCostCents": 325,
    "totalCostFormatted": "$3.25"
  }
}

GET /usage/recent

Get recent LLM calls for debugging.

curl "https://api.backdrift.ai/usage/recent?limit=10" \
  -H "Authorization: Bearer $TOKEN"