Docs · REST API

REST API reference.

Complete reference for the Stori REST API. All endpoints accept and return JSON unless noted otherwise. Base URL: https://app.stori.zone/api

Overview

Endpoints

Resources

REST

Protocol

Authentication: Include Authorization: Bearer <token> for authenticated endpoints. Some read endpoints work without auth.

Create, list, update, and delete projects. Each project has a unique key (2–5 uppercase chars).

GET/api/projects

List all projects.

Response

[{ "id": 1, "name": "Pictura", "key": "PIC", "description": "...", "ownerId": "...", "createdAt": "...", "updatedAt": "..." }]

Example

curl http://localhost:3100/api/projects

POST/api/projects

Create a new project.

Request Body

{
  "name": "My Project",       // required, min 1 char
  "key": "MYP",               // required, 2-5 chars, auto-uppercased
  "description": "Optional"   // optional
}

Response

{ "id": 2, "name": "My Project", "key": "MYP", "description": "Optional", "ownerId": "...", "createdAt": "...", "updatedAt": "..." }

Example

curl -X POST http://localhost:3100/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project", "key": "MYP"}'

GET/api/projects/:id

Get a single project by ID.

Parameters

id — Project ID (number)

Response

{ "id": 1, "name": "Pictura", "key": "PIC", "description": "...", "ownerId": "...", "createdAt": "...", "updatedAt": "..." }

Example

curl http://localhost:3100/api/projects/1

PATCH/api/projects/:id

Update a project. All fields optional.

Parameters

id — Project ID (number)

Request Body

{
  "name": "New Name",         // optional
  "key": "NEW",               // optional, 2-5 chars
  "description": "Updated"    // optional
}

Response

{ "id": 1, "name": "New Name", "key": "NEW", ... }

Example

curl -X PATCH http://localhost:3100/api/projects/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "New Name"}'

DELETE/api/projects/:id

Delete a project and all its work items, comments, and attachments.

Parameters

id — Project ID (number)

Response

{ "deleted": true }

Example

curl -X DELETE http://localhost:3100/api/projects/1

Error Responses

All error responses follow a consistent shape:

{
  "error": "Description of the error"   // string or object with field-level errors
}

// HTTP status codes:
// 400 — Bad request (validation error)
// 401 — Unauthorized
// 403 — Forbidden (not the owner)
// 404 — Not found
// 409 — Conflict (duplicate slug, etc.)
// 429 — Rate limited (TraQL: 30 req/min), or monthly call quota exceeded

Monthly call quota

API and MCP calls share one monthly quota, counted per organization (the org your API key is scoped to). When the cap is reached, further calls return 429until you upgrade or the month rolls over. The body carries the limit and an upgrade link; settings/account calls are not counted. Caps scale with your plan — see your usage on the org's billing settings.

// 429 — quota exceeded
{
  "error": "Monthly API & MCP call quota exceeded for this org. Upgrade to raise the limit.",
  "code": "quota_exceeded",
  "used": 1000,
  "limit": 1000,
  "upgrade_url": "https://app.stori.zone/settings/org/<orgId>"
}
// Headers: X-RateLimit-Limit, X-RateLimit-Remaining