# DevBlanket API for AI Agents

This document is for AI agents that have been granted access to DevBlanket by a user.

## Authentication

You likely have an **Extra Key** - a memorable token like `ArcticCondorGoldenCobra` that a user created and shared with you.

Use it as a Bearer token on all API requests:

```
Authorization: Bearer <your-extra-key>
```

The key acts on behalf of that specific user within their organization. All actions you take are attributed to them.

## Quick Start

Verify your key and get user/org context:

```bash
curl https://door.devblanket.com/api/me \
  -H "Authorization: Bearer <your-extra-key>"
```

Response:

```json
{
  "user": {
    "id": "abc123",
    "email": "user@example.com",
    "displayName": "User Name"
  },
  "organization": {
    "id": "org456",
    "name": "My Organization",
    "slug": "my-org"
  }
}
```

Use the `organization.id` for all org-scoped API calls.

## Services

Each service provides detailed documentation at its root (via `Accept: text/markdown`) and an OpenAPI schema at `/openapi.json`.

| Service | Base URL | Purpose |
|---------|----------|---------|
| door | https://door.devblanket.com | Authentication, users, organizations |
| uploads | https://uploads.devblanket.com | File storage and management |
| base | https://base.devblanket.com | Message queues, lambdas |
| craft | https://craft.devblanket.com | AI-assisted content creation, projects, chat |
| engine | https://engine.devblanket.com | Serverless edge runtime for custom domains |

To get full API documentation for a service:

```bash
# Human-readable docs
curl https://door.devblanket.com/ -H "Accept: text/markdown"

# Machine-readable OpenAPI schema
curl https://door.devblanket.com/openapi.json
```

## Error Responses

All APIs return consistent error formats:

```json
{
  "error": "Error message here"
}
```

Common HTTP status codes:
- `401` - Invalid or missing Extra Key
- `403` - Key valid but lacks permission for this action
- `404` - Resource not found
- `500` - Server error

## Rate Limits

Be respectful of API usage. Excessive requests may be throttled.