4.2 — CRUD endpoints

CRUD is the primary data access API — reading and writing every entity type (projects, features, user stories, acceptance criteria, personas, pages, sections). All endpoints follow the same shape, so once you've learned one entity, you've learned them all.

Responses are automatically scoped to projects owned by the authenticated user. Trying to read or write another user's resources returns 403 Forbidden.

Route pattern

Every entity type shares the same URL structure:

Available entities

Examples

List features for a project

GET /api/crud/features?projectId=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response 200 OK:

{
  "data": [
    {
      "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "User Authentication",
      "description": "OAuth2 login with Google and GitHub providers",
      "priority": "high",
      "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2026-03-15T10:30:00Z"
    },
    {
      "id": "f2b3c4d5-e6f7-8901-bcde-f12345678901",
      "name": "Dashboard Analytics",
      "description": "Real-time usage metrics and charts",
      "priority": "medium",
      "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2026-03-15T10:32:00Z"
    }
  ]
}

Get a single feature

GET /api/crud/features?id=f1a2b3c4-d5e6-7890-abcd-ef1234567890

Response 200 OK:

{
  "data": {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "User Authentication",
    "description": "OAuth2 login with Google and GitHub providers",
    "priority": "high",
    "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-03-15T10:30:00Z"
  }
}

Create a feature

POST /api/crud/features
Content-Type: application/json

{
  "name": "User Authentication",
  "description": "OAuth2 login with Google and GitHub providers",
  "priority": "high",
  "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response 201 Created:

{
  "data": {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "User Authentication",
    "description": "OAuth2 login with Google and GitHub providers",
    "priority": "high",
    "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-03-15T10:30:00Z"
  }
}

Update a feature

PATCH /api/crud/features
Content-Type: application/json

{
  "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "priority": "critical",
  "description": "OAuth2 login with Google, GitHub, and Microsoft providers"
}

Response 200 OK:

{
  "data": {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "User Authentication",
    "description": "OAuth2 login with Google, GitHub, and Microsoft providers",
    "priority": "critical",
    "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-03-15T10:30:00Z"
  }
}

Delete a feature

DELETE /api/crud/features
Content-Type: application/json

{
  "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890"
}

Response 204 No Content (empty body).

Filtering

List endpoints accept query parameters for filtering:

Error responses

{
  "error": "Feature not found"
}

Common errors: 400 for missing required fields, 401 for unauthenticated requests, 403 for accessing another user's data, 404 for non-existent resources.

Where to go next

→ 4.3 — Generation endpoints