# Spec Stack API V1

Spec Stack provides a REST API to manage your specs and collections programmatically.

## Authentication

All API requests must be authenticated using an API Key. You can generate an API Key in your [Settings](/settings/api-keys).

Include the API Key in the `Authorization` header:

```http
Authorization: Bearer sk_...
```

## Base URL

All endpoints are prefixed with `/api/v1`.

## Endpoints

### Authentication Check

**GET** `/me`

Verifies your API key and returns your user ID.

**Response:**
```json
{
  "data": {
    "id": "user_...",
    "type": "api_key",
    "message": "Authenticated via api_key"
  }
}
```

### Assets

**GET** `/assets`

List all your assets.

**POST** `/assets`

Create a new asset.

**Body (JSON - for text/links):**
```json
{
  "title": "My Spec",
  "type": "markdown",
  "content": "Markdown content...",
  "collectionId": "optional-uuid",
  "isPublic": false
}
```

**Body (Multipart Form Data - for images):**
- `file`: (Binary file)
- `title`: "My Image"
- `collectionId`: "optional-uuid"
- `isPublic`: "true" or "false"

**GET** `/assets/:id`

Get a specific asset.

**PUT** `/assets/:id`

Update an asset.

**DELETE** `/assets/:id`

Delete an asset.

### Collections

**GET** `/collections`

List all your collections.

**POST** `/collections`

Create a new collection.

**Body:**
```json
{
  "name": "My Project",
  "description": "Optional description"
}
```

**GET** `/collections/:id/context`

Get a formatted text dump of the collection and all its assets, suitable for LLM context injection.

### Projects

**GET** `/projects`

List all your projects.

**POST** `/projects`

Create a new project.

**Body:**
```json
{
  "name": "My Project",
  "description": "Optional description"
}
```

### Agents

**POST** `/agent/run`

Trigger an agent to perform a task.

**Body:**
```json
{
  "agentId": "uuid-of-agent",
  "prompt": "Summarize the marketing specs.",
  "context": {
    "collectionId": "uuid-of-collection"
  }
}
```

**Response:**
```json
{
  "runId": "uuid-of-run",
  "status": "completed",
  "result": "The marketing specs focus on..."
}
```

**GET** `/agent/run/:id`

Get the status and result of a specific run.

### Admin

**POST** `/admin/agents`

Register or update an agent definition.

**Body:**
```json
{
  "name": "Marketing Assistant",
  "type": "simple",
  "systemPrompt": "You are a marketing expert...",
  "capabilities": ["web-search"]
}
```

**GET** `/api-keys`

List your API keys (hashes only).

**POST** `/api-keys`

Create a new API key.

**Body:**
```json
{
  "label": "My Key"
}
```

### AI Tools (MCP)

**GET** `/mcp`

Returns a list of available tools for AI agents.

**POST** `/mcp`

Execute a tool.

**Body:**
```json
{
  "tool": "get_assets",
  "parameters": {
    "collectionId": "..."
  }
}
```