# Spec-Stack API V1 Reference

Spec-Stack provides a REST API to manage your knowledge base, specifications, and nodes programmatically.

## 1. Authentication & Base URL
- **Base URL:** `https://specstack.xyz/api/v1`
- **Authentication:** ALL requests require a standard User API Key passed in the header.
  ```http
  Authorization: Bearer <SPEC_STACK_API_KEY>
  ```

---

## 2. Core Data Model
Spec-Stack relies on a 2-tier hierarchy using typed taxonomies:
1. **Projects:** The top-level workspace (e.g., "Mobile App Refactor").
2. **Entities:** The universal data unit. An Entity is a flexible data type representing any piece of knowledge belonging to a Project.

*(Note: "Collections" are deprecated. Entities are now organized using strict `domain` and `kind` enums.)*

### Entity Schema
When creating or updating an Entity, you must provide its taxonomy via JSON:
```json
{
  "title": "Module 1 Specification",
  "format": "markdown",
  "kind": "artifact",
  "tags": ["critical", "auth"],
  "content": "Markdown text or data content here...",
  "projectId": "uuid-of-project",
  "status": "draft"
}
```

Notes on fields:
- `title` (required)
- `format` (required): `'markdown' | 'image' | 'link' | 'json'`
- `kind` (optional, defaults to `'artifact'`): `'spec' | 'bug' | 'recommendation' | 'observation' | 'praise' | 'artifact' | 'insight' | 'source_material' | 'draft_pr'`
- `tags` (optional): Array of strings. Highly recommended for organizing and filtering knowledge.
- `status` (optional, defaults to `'active'`): `'draft' | 'active' | 'developing' | 'archived'`

---

## 3. Core REST Endpoints

### Authentication Check
**GET** `/me`
Verifies your API key and returns your user ID.

### Projects
**GET** `/projects`
List all projects owned by the authenticated user.

**GET** `/projects/:id`
Get project details.

### Entities (Knowledge Units)
**GET** `/entities?projectId=:id`
List all entities in a project.

**GET** `/entities/:id`
Get a specific entity.

**POST** `/entities`
Create a new entity. Requires `format` and `title`. `projectId` and `content` are highly recommended.

**PUT** `/entities/:id`
Update an existing entity.

**DELETE** `/entities/:id`
Delete an entity.

### AI Context Aggregation & Chat
**GET** `/projects/:id/context`
Returns a highly optimized, stringified dump of all relevant text-nodes belonging to a specific project. Use this endpoint to ingest project context into your system prompt before writing code or generating new specs.

**POST** `/projects/:id/chat`
Submit a prompt to converse with the Omni-Agent using the new project-wide domain context.

---

## 4. Special Integrations (Partner Apps / Webhooks)
Partner apps (like automated QA testers or code agents) use static endpoints and standard API Keys to push data into Spec-Stack.

**POST** `/webhooks/userzero/:projectId`
- Partner apps make authenticated `POST` requests directly to their designated webhook route, specifying the `projectId` in the URL.
- The webhook verifies the API Key's user actually owns the `projectId` before ingesting the payload.

## 5. MCP (Model Context Protocol) Server

SpecStack provides a fully compliant Model Context Protocol (MCP) server that allows external AI agents (like Claude Desktop, Cursor, or your own custom agents) to securely connect to your workspace and interact with your project documentation and autonomous workflows.

### Connection Details

- **URL:** `https://specstack.xyz/api/mcp`
- **Transport:** HTTP (standard Next.js MCP handler)
- **Authentication:** Provide your API Key via the standard SpecStack Authorization header.

### Available MCP Tools

Once an agent connects, it automatically discovers and can execute the following tools:

1. **`get_active_specs`**:
   - *Description:* Retrieve all currently active architectural specifications and documents for a given project.
   - *Input:* `projectId` (string).

2. **`create_specstack_task`**:
   - *Description:* Enqueue a background research or maintenance task for the SpecStack Autonomous AI Worker.
   - *Input:* `projectId` (string), `title` (string), `description` (string), `priority` (enum: low|medium|high), `kind` (enum: chore|feature|bug|research).

3. **`trigger_heartbeat_synthesis`**:
   - *Description:* Force trigger the daily Strategist Synthesis workflow to analyze recent events and strategically groom the project data.
   - *Input:* `projectId` (string).