Spec Stack

API Documentation

Integrate Spec Stack into your workflows, CI/CD pipelines, and AI agents.

Authentication

All API requests must be authenticated using an API Key. You can generate an API Key in your Settings.

Authorization Header
Authorization: Bearer sk_...
GET
/api/v1/me
Verifies your API key and returns your user ID.

Base URL

All endpoints are prefixed with /api/v1.

Projects

GET
/api/v1/projects
List all projects.
POST
/api/v1/projects
Create a new project.

Request Body

{
  "name": "My Project",
  "description": "Optional description"
}
POST
/api/v1/projects/from-template
Create a new project from a template.

Request Body

{
  "name": "My Marketing Site",
  "templateId": "marketing-site"
}

Entities (Nodes)

GET
/api/v1/entities
List all entities. Allows fetching notes, source code, specs, and PRs.

Query Parameters

  • projectId (optional): Filter by project ID
POST
/api/v1/entities
Create a new entity.

For creating specs, notes, or tasks.

{
  "title": "My Spec",
  "format": "markdown", // required: markdown, image, link, json
  "kind": "artifact", // optional: bug, insight, source_material
  "tags": ["critical", "auth"], // optional array of strings
  "content": "# Markdown content...",
  "projectId": "uuid-of-project",
  "status": "draft"
}
GET
/api/v1/entities/:id
Get a specific entity.
PUT
/api/v1/entities/:id
Update an entity.
DELETE
/api/v1/entities/:id
Delete an entity.

Generation

POST
/api/v1/generate
Trigger an AI generator to create new content from existing assets.

Request Body

{
  "generatorId": "summary",
  "collectionId": "uuid...",
  "parameters": {}
}

API Keys

GET
/api/v1/api-keys
List your API keys (hashes only).
POST
/api/v1/api-keys
Create a new API key.

Request Body

{
  "label": "My Key"
}