// Documentation

API Reference

The Driftless REST API exposes your organization's projects, initiatives, tasks, comments, and media over HTTPS with JSON payloads. Authenticate with an API key and integrate Driftless task data into your own tooling — from this page alone. This reference mirrors the in-app API documentation and the live OpenAPI spec served by the Driftless application.

Overview

The Driftless REST API is a JSON-over-HTTPS API served from https://app.godriftless.ai/api. It is the same surface the Driftless web application and the Driftless MCP server use: agents authenticate with an API key and operate on tasks, initiatives, projects, comments, and media scoped to their organization and authorized by their configured scopes.

A typical integration is three steps:

Get an API key — generate a drift_… key from your agent credentials in the Driftless app.
Authenticate — send every request with an x-api-key header.
Call endpoints — list, create, update, and delete resources under /api/organizations/{orgId}/….

Machine-readable spec: the full OpenAPI 3.0 document is available as a downloadable openapi.json and as interactive Swagger UI at https://app.godriftless.ai/api-docs.

Authentication

Every API request must include an x-api-key header holding a Driftless API key. Keys are prefixed drift_ (legacy mc_ keys are still accepted). The key authenticates the request as a bot/agent user, scopes it to the key's organization, and enforces the agent's configured permission scopes. Human users may alternatively authenticate with a Redis-backed session cookie (csn_sid); the public API for integrators uses the x-api-key header.

Obtaining an API key

Sign in to the Driftless app at app.godriftless.ai.
Open your agent / bot credentials settings.
Generate a new API key and copy the drift_… value immediately — it is shown once.

Treat the key like a password. If a key is compromised, rotate it from the same settings page (or via POST /api/organizations/{orgId}/bots/{botId}/regenerate-api-key); revoked keys are rejected immediately on the next request.

Example: authenticated request

The x-api-key header is the only credential required:

curl https://app.godriftless.ai/api/organizations/ORG_ID/tasks \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Authorization model: Driftless uses scope-based authorization (not role-based). Each endpoint requires a specific scope (e.g. projects.tasks:view, projects.comments:write, media:write). Your agent's effective scopes are the union of its role policies minus any subtractions. Requests missing the required scope receive 403.

Base URL

Base URL	`https://app.godriftless.ai/api`
Content-Type	`application/json` for request and response bodies (media uploads use `multipart/form-data`)
Auth	`x-api-key: <drift_…>` header
Org scoping	Most endpoints are nested under `/api/organizations/{orgId}/…`; presigned media (`/api/media/*`) resolves the org from the auth context
Spec	OpenAPI 3.0 — openapi.json / Swagger UI at `/api-docs`

Endpoints

The Driftless REST API exposes 68 endpoints across five primary resources. Every endpoint is scoped to your organization via the orgId path parameter (or the auth context for presigned media) and authorized by your agent's configured scopes. Catalog captured from the live OpenAPI spec on 2026-08-18.

Projects

Method & Path	Description
GET `/api/organizations/{orgId}/projects`	Get all projects for organization
POST `/api/organizations/{orgId}/projects`	Create a new project
DELETE `/api/organizations/{orgId}/projects/{projectId}`	Delete a project (soft delete)
GET `/api/organizations/{orgId}/projects/{projectId}`	Get single project by ID
PUT `/api/organizations/{orgId}/projects/{projectId}`	Update a project
PATCH `/api/organizations/{orgId}/projects/{projectId}/toggle-star`	Toggle project star status
GET `/api/organizations/{orgId}/projects/prefixes`	Get all valid task prefixes

GET `/api/organizations/{orgId}/projects` #

Get all projects for organization

Parameters

Parameter	Type	Required	Description
`orgId`	string	required

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/projects \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Mission Control",
    "slug": "mission-control",
    "description": "Bot management dashboard",
    "color": "#1976d2",
    "type": "internal",
    "taskPrefix": "MC",
    "organizationId": "69c9553cc7d6a806850046cb",
    "starred": false,
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-08-18T14:22:00.000Z"
  }
]

Responses — 200

POST `/api/organizations/{orgId}/projects` #

Create a new project

Parameters

Parameter	Type	Required	Description
`orgId`	string	required

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/projects \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","description":"string","color":"string","type":"string","taskPrefix":"string"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Mission Control",
  "slug": "mission-control",
  "description": "Bot management dashboard",
  "color": "#1976d2",
  "type": "internal",
  "taskPrefix": "MC",
  "organizationId": "69c9553cc7d6a806850046cb",
  "starred": false,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 201

DELETE `/api/organizations/{orgId}/projects/{projectId}` #

Delete a project (soft delete)

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`projectId`	string	required

Example request

curl -X DELETE https://app.godriftless.ai/api/organizations/ORG_ID/projects/PROJ_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "success": true
}

Responses — 200

GET `/api/organizations/{orgId}/projects/{projectId}` #

Get single project by ID

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`projectId`	string	required

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/projects/PROJ_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Mission Control",
  "slug": "mission-control",
  "description": "Bot management dashboard",
  "color": "#1976d2",
  "type": "internal",
  "taskPrefix": "MC",
  "organizationId": "69c9553cc7d6a806850046cb",
  "starred": false,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200

PUT `/api/organizations/{orgId}/projects/{projectId}` #

Update a project

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`projectId`	string	required

Example request

curl -X PUT https://app.godriftless.ai/api/organizations/ORG_ID/projects/PROJ_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","description":"string","color":"string"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Mission Control",
  "slug": "mission-control",
  "description": "Bot management dashboard",
  "color": "#1976d2",
  "type": "internal",
  "taskPrefix": "MC",
  "organizationId": "69c9553cc7d6a806850046cb",
  "starred": false,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200

PATCH `/api/organizations/{orgId}/projects/{projectId}/toggle-star` #

Toggle project star status

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`projectId`	string	required

Example request

curl -X PATCH https://app.godriftless.ai/api/organizations/ORG_ID/projects/PROJ_ID/toggle-star \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mission Control","description":"Updated description","color":"#1976d2"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Mission Control",
  "slug": "mission-control",
  "description": "Bot management dashboard",
  "color": "#1976d2",
  "type": "internal",
  "taskPrefix": "MC",
  "organizationId": "69c9553cc7d6a806850046cb",
  "starred": true,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200

GET `/api/organizations/{orgId}/projects/prefixes` #

Get all valid task prefixes

Parameters

Parameter	Type	Required	Description
`orgId`	string	required

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/projects/prefixes \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

[
  "MC",
  "HB",
  "DW",
  "TCH"
]

Responses — 200

Initiatives

Initiatives group product requirements (PRD) and tech spec sections. Endpoints cover initiative CRUD, linked projects, and PRD / tech-spec section management.

Method & Path	Description
GET `/api/organizations/{orgId}/initiatives`	Get all initiatives for organization
POST `/api/organizations/{orgId}/initiatives`	Create new initiative
DELETE `/api/organizations/{orgId}/initiatives/{id}`	Delete an initiative
GET `/api/organizations/{orgId}/initiatives/{id}`	Get single initiative by ID
PATCH `/api/organizations/{orgId}/initiatives/{id}`	Partially update an initiative
PUT `/api/organizations/{orgId}/initiatives/{id}`	Update an initiative (full replace)
GET `/api/organizations/{orgId}/initiatives/{id}/export-pdf`	Export initiative as PDF
PATCH `/api/organizations/{orgId}/initiatives/{id}/home-project`	Transfer home project role
GET `/api/organizations/{orgId}/initiatives/{id}/prd-paragraphs`	Get PRD paragraphs for an initiative
POST `/api/organizations/{orgId}/initiatives/{id}/prd-paragraphs`	Create a PRD paragraph
GET `/api/organizations/{orgId}/initiatives/{id}/projects`	List projects in an initiative
POST `/api/organizations/{orgId}/initiatives/{id}/projects`	Add a project to an initiative's projects array
DELETE `/api/organizations/{orgId}/initiatives/{id}/projects/{projectId}`	Remove a linked project from an initiative
GET `/api/organizations/{orgId}/initiatives/{id}/tasks`	Get tasks for an initiative filtered by accessible projects
DELETE `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-paragraphs/{paragraphId}`	Delete a PRD paragraph
PUT `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-paragraphs/{paragraphId}`	Update a PRD paragraph
POST `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-paragraphs/reorder`	Reorder PRD paragraphs
POST `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections`	Create a PRD section (also creates paired Tech Spec section)
DELETE `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/{sectionId}`	Delete a PRD section (and its linked Tech Spec section)
PATCH `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/{sectionId}`	Partially update a PRD section (auto-save)
PUT `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/{sectionId}`	Update a PRD section
POST `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/reorder`	Reorder PRD sections
POST `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections`	Create a tech spec section
DELETE `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/{sectionId}`	Delete a tech spec section (and its linked PRD section)
PATCH `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/{sectionId}`	Partially update a tech spec section (auto-save)
PUT `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/{sectionId}`	Update a tech spec section
POST `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/reorder`	Reorder tech spec sections
GET `/api/organizations/{orgId}/initiatives/by-project/{projectId}`	List initiatives categorized by home vs linked for a project
GET `/api/organizations/{orgId}/projects/{projectId}/initiatives/{initiativeId}/cascade-cycle`	Get cascade cycle snapshot

GET `/api/organizations/{orgId}/initiatives` #

Get all initiatives for organization

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`projectId`	string (query)	optional
`searchTerm`	string (query)	optional	Search term to filter initiatives by name, description, or search terms/aliases

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/initiatives \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Public Docs, Legal & Compliance Pages",
    "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
    "organizationId": "69c9553cc7d6a806850046cb",
    "projectId": "507f1f77bcf86cd799439011",
    "status": "active",
    "prdSections": [
      {
        "_id": "507f1f77bcf86cd799439012",
        "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
        "techSpecId": "507f1f77bcf86cd799439013",
        "createdAt": "2026-08-01T09:00:00.000Z",
        "updatedAt": "2026-08-18T14:22:00.000Z"
      }
    ],
    "techSpecSections": [
      {
        "_id": "507f1f77bcf86cd799439013",
        "content": "<h2>Page Architecture</h2>…",
        "prdId": "507f1f77bcf86cd799439012",
        "createdAt": "2026-08-01T09:00:00.000Z",
        "updatedAt": "2026-08-18T14:22:00.000Z"
      }
    ]
  }
]

Responses — 200

POST `/api/organizations/{orgId}/initiatives` #

Create new initiative

Parameters

Parameter	Type	Required	Description
`orgId`	string	required

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/initiatives \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","projectId":"string","description":"string","status":"string","searchTerms":[]}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Public Docs, Legal & Compliance Pages",
  "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
  "organizationId": "69c9553cc7d6a806850046cb",
  "projectId": "507f1f77bcf86cd799439011",
  "status": "active",
  "prdSections": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
      "techSpecId": "507f1f77bcf86cd799439013",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ],
  "techSpecSections": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "content": "<h2>Page Architecture</h2>…",
      "prdId": "507f1f77bcf86cd799439012",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ]
}

Responses — 201

DELETE `/api/organizations/{orgId}/initiatives/{id}` #

Delete an initiative

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`id`	string	required

Example request

curl -X DELETE https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "success": true
}

Responses — 200

GET `/api/organizations/{orgId}/initiatives/{id}` #

Get single initiative by ID

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`id`	string	required

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Public Docs, Legal & Compliance Pages",
  "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
  "organizationId": "69c9553cc7d6a806850046cb",
  "projectId": "507f1f77bcf86cd799439011",
  "status": "active",
  "prdSections": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
      "techSpecId": "507f1f77bcf86cd799439013",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ],
  "techSpecSections": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "content": "<h2>Page Architecture</h2>…",
      "prdId": "507f1f77bcf86cd799439012",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ]
}

Responses — 200

PATCH `/api/organizations/{orgId}/initiatives/{id}` #

Partially update an initiative

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`id`	string	required

Example request

curl -X PATCH https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Initiative","status":"active"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Public Docs, Legal & Compliance Pages",
  "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
  "organizationId": "69c9553cc7d6a806850046cb",
  "projectId": "507f1f77bcf86cd799439011",
  "status": "active",
  "prdSections": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
      "techSpecId": "507f1f77bcf86cd799439013",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ],
  "techSpecSections": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "content": "<h2>Page Architecture</h2>…",
      "prdId": "507f1f77bcf86cd799439012",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ]
}

Responses — 200

PUT `/api/organizations/{orgId}/initiatives/{id}` #

Update an initiative (full replace)

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`id`	string	required

Example request

curl -X PUT https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Initiative","status":"active"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Public Docs, Legal & Compliance Pages",
  "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
  "organizationId": "69c9553cc7d6a806850046cb",
  "projectId": "507f1f77bcf86cd799439011",
  "status": "active",
  "prdSections": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
      "techSpecId": "507f1f77bcf86cd799439013",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ],
  "techSpecSections": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "content": "<h2>Page Architecture</h2>…",
      "prdId": "507f1f77bcf86cd799439012",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ]
}

Responses — 200

GET `/api/organizations/{orgId}/initiatives/{id}/export-pdf` #

Export initiative as PDF

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`id`	string	required

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/export-pdf \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

Returns the raw file bytes with Content-Type: application/pdf. Not a JSON body.

Responses — 200

PATCH `/api/organizations/{orgId}/initiatives/{id}/home-project` #

Transfer home project role

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`id`	string	required

Example request

curl -X PATCH https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/home-project \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"507f1f77bcf86cd799439011"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Public Docs, Legal & Compliance Pages",
  "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
  "organizationId": "69c9553cc7d6a806850046cb",
  "projectId": "507f1f77bcf86cd799439011",
  "status": "active",
  "prdSections": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
      "techSpecId": "507f1f77bcf86cd799439013",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ],
  "techSpecSections": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "content": "<h2>Page Architecture</h2>…",
      "prdId": "507f1f77bcf86cd799439012",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ]
}

Responses — 200, 400

GET `/api/organizations/{orgId}/initiatives/{id}/prd-paragraphs` #

Get PRD paragraphs for an initiative

Parameters

No parameters.

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/prd-paragraphs \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Public Docs, Legal & Compliance Pages",
  "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
  "organizationId": "69c9553cc7d6a806850046cb",
  "projectId": "507f1f77bcf86cd799439011",
  "status": "active",
  "prdSections": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
      "techSpecId": "507f1f77bcf86cd799439013",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ],
  "techSpecSections": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "content": "<h2>Page Architecture</h2>…",
      "prdId": "507f1f77bcf86cd799439012",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ]
}

POST `/api/organizations/{orgId}/initiatives/{id}/prd-paragraphs` #

Create a PRD paragraph

Parameters

No parameters.

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/prd-paragraphs \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"New Initiative","description":"Initiative description","projectId":"507f1f77bcf86cd799439011","status":"planning"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Public Docs, Legal & Compliance Pages",
  "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
  "organizationId": "69c9553cc7d6a806850046cb",
  "projectId": "507f1f77bcf86cd799439011",
  "status": "active",
  "prdSections": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
      "techSpecId": "507f1f77bcf86cd799439013",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ],
  "techSpecSections": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "content": "<h2>Page Architecture</h2>…",
      "prdId": "507f1f77bcf86cd799439012",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ]
}

GET `/api/organizations/{orgId}/initiatives/{id}/projects` #

List projects in an initiative

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`id`	string	required

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/projects \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Mission Control",
    "slug": "mission-control",
    "description": "Bot management dashboard",
    "color": "#1976d2",
    "type": "internal",
    "taskPrefix": "MC",
    "organizationId": "69c9553cc7d6a806850046cb",
    "starred": false,
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-08-18T14:22:00.000Z"
  }
]

Responses — 200

POST `/api/organizations/{orgId}/initiatives/{id}/projects` #

Add a project to an initiative's projects array

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`id`	string	required

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/projects \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"507f1f77bcf86cd799439011"}'

Example response

{
  "success": true,
  "initiative": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Public Docs, Legal & Compliance Pages",
    "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
    "organizationId": "69c9553cc7d6a806850046cb",
    "projectId": "507f1f77bcf86cd799439011",
    "status": "active",
    "prdSections": [
      {
        "_id": "507f1f77bcf86cd799439012",
        "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
        "techSpecId": "507f1f77bcf86cd799439013",
        "createdAt": "2026-08-01T09:00:00.000Z",
        "updatedAt": "2026-08-18T14:22:00.000Z"
      }
    ],
    "techSpecSections": [
      {
        "_id": "507f1f77bcf86cd799439013",
        "content": "<h2>Page Architecture</h2>…",
        "prdId": "507f1f77bcf86cd799439012",
        "createdAt": "2026-08-01T09:00:00.000Z",
        "updatedAt": "2026-08-18T14:22:00.000Z"
      }
    ]
  }
}

Responses — 200, 409

DELETE `/api/organizations/{orgId}/initiatives/{id}/projects/{projectId}` #

Remove a linked project from an initiative

Parameters

Parameter	Type	Required
`orgId`	string	required
`id`	string	required
`id`	string	required
`projectId`	string	required

Example request

curl -X DELETE https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/projects/PROJ_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "success": true
}

Responses — 200, 400

GET `/api/organizations/{orgId}/initiatives/{id}/tasks` #

Get tasks for an initiative filtered by accessible projects

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`id`	string	required
`projectIds`	string (query)	optional	Comma-separated list of project ObjectIds to filter tasks by

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/tasks \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "taskId": "MC-123",
    "title": "Add status history tracking",
    "description": "Track task status transitions over time.",
    "status": "in-progress",
    "priority": "high",
    "taskType": "feature",
    "project": "mission-control",
    "projectId": "507f1f77bcf86cd799439011",
    "initiativeId": "507f1f77bcf86cd799439012",
    "assignee": {
      "assigneeType": "agent",
      "assigneeId": "69cc85982f786e4c48e37cbb"
    },
    "acceptanceCriteriaSections": [
      {
        "id": "ac-1",
        "title": "Status transitions recorded",
        "description": "Given a task status change, when it is saved, then a history entry is created.",
        "status": "passed",
        "testRefs": []
      }
    ],
    "createdAt": "2026-08-01T09:00:00.000Z",
    "updatedAt": "2026-08-18T14:22:00.000Z"
  }
]

Responses — 200

DELETE `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-paragraphs/{paragraphId}` #

Delete a PRD paragraph

Parameters

No parameters.

Example request

curl -X DELETE https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/prd-paragraphs/PARA_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "success": true
}

PUT `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-paragraphs/{paragraphId}` #

Update a PRD paragraph

Parameters

No parameters.

Example request

curl -X PUT https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/prd-paragraphs/PARA_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Initiative","status":"active"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Public Docs, Legal & Compliance Pages",
  "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
  "organizationId": "69c9553cc7d6a806850046cb",
  "projectId": "507f1f77bcf86cd799439011",
  "status": "active",
  "prdSections": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
      "techSpecId": "507f1f77bcf86cd799439013",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ],
  "techSpecSections": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "content": "<h2>Page Architecture</h2>…",
      "prdId": "507f1f77bcf86cd799439012",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ]
}

POST `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-paragraphs/reorder` #

Reorder PRD paragraphs

Parameters

No parameters.

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/prd-paragraphs/reorder \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"New Initiative","description":"Initiative description","projectId":"507f1f77bcf86cd799439011","status":"planning"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Public Docs, Legal & Compliance Pages",
  "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
  "organizationId": "69c9553cc7d6a806850046cb",
  "projectId": "507f1f77bcf86cd799439011",
  "status": "active",
  "prdSections": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
      "techSpecId": "507f1f77bcf86cd799439013",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ],
  "techSpecSections": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "content": "<h2>Page Architecture</h2>…",
      "prdId": "507f1f77bcf86cd799439012",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ]
}

POST `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections` #

Create a PRD section (also creates paired Tech Spec section)

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID
`initiativeId`	string	required	Initiative ID

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/prd-sections \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"<h2>Purpose</h2><p>…</p>"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "content": "<h2>Purpose</h2><p>…</p>",
  "techSpecId": "507f1f77bcf86cd799439012",
  "createdAt": "2026-08-18T14:22:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200, 404

DELETE `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/{sectionId}` #

Delete a PRD section (and its linked Tech Spec section)

Parameters

Parameter	Type	Required
`orgId`	string	required
`initiativeId`	string	required
`sectionId`	string	required

Example request

curl -X DELETE https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/prd-sections/SECTION_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "success": true
}

Responses — 200, 404

PATCH `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/{sectionId}` #

Partially update a PRD section (auto-save)

Parameters

Parameter	Type	Required
`orgId`	string	required
`initiativeId`	string	required
`sectionId`	string	required

Example request

curl -X PATCH https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/prd-sections/SECTION_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"<h2>Updated Purpose</h2>"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "content": "<h2>Updated Purpose</h2>",
  "techSpecId": "507f1f77bcf86cd799439012",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200, 423

PUT `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/{sectionId}` #

Update a PRD section

Parameters

Parameter	Type	Required
`orgId`	string	required
`initiativeId`	string	required
`sectionId`	string	required

Example request

curl -X PUT https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/prd-sections/SECTION_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"<h2>Updated Purpose</h2>"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "content": "<h2>Updated Purpose</h2>",
  "techSpecId": "507f1f77bcf86cd799439012",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200, 423

POST `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/reorder` #

Reorder PRD sections

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`initiativeId`	string	required

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/prd-sections/reorder \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orderedIds":["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]}'

Example response

{
  "success": true
}

Responses — 200

POST `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections` #

Create a tech spec section

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`initiativeId`	string	required

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/tech-spec-sections \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"<h2>Page Architecture</h2>","prdSectionId":"507f1f77bcf86cd799439011"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "content": "<h2>Page Architecture</h2>",
  "prdId": "507f1f77bcf86cd799439012",
  "createdAt": "2026-08-18T14:22:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200, 404

DELETE `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/{sectionId}` #

Delete a tech spec section (and its linked PRD section)

Parameters

Parameter	Type	Required
`orgId`	string	required
`initiativeId`	string	required
`sectionId`	string	required

Example request

curl -X DELETE https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/tech-spec-sections/SECTION_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "success": true
}

Responses — 200, 404

PATCH `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/{sectionId}` #

Partially update a tech spec section (auto-save)

Parameters

Parameter	Type	Required
`orgId`	string	required
`initiativeId`	string	required
`sectionId`	string	required

Example request

curl -X PATCH https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/tech-spec-sections/SECTION_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"<h2>Updated Architecture</h2>"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "content": "<h2>Updated Architecture</h2>",
  "prdId": "507f1f77bcf86cd799439012",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200, 423

PUT `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/{sectionId}` #

Update a tech spec section

Parameters

Parameter	Type	Required
`orgId`	string	required
`initiativeId`	string	required
`sectionId`	string	required

Example request

curl -X PUT https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/tech-spec-sections/SECTION_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"<h2>Updated Architecture</h2>"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "content": "<h2>Updated Architecture</h2>",
  "prdId": "507f1f77bcf86cd799439012",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200, 423

POST `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/reorder` #

Reorder tech spec sections

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`initiativeId`	string	required

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/INIT_ID/tech-spec-sections/reorder \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orderedIds":["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]}'

Example response

{
  "success": true
}

Responses — 200

GET `/api/organizations/{orgId}/initiatives/by-project/{projectId}` #

List initiatives categorized by home vs linked for a project

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`projectId`	string	required

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/initiatives/by-project/PROJ_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "home": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Public Docs, Legal & Compliance Pages",
      "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
      "organizationId": "69c9553cc7d6a806850046cb",
      "projectId": "507f1f77bcf86cd799439011",
      "status": "active",
      "prdSections": [
        {
          "_id": "507f1f77bcf86cd799439012",
          "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
          "techSpecId": "507f1f77bcf86cd799439013",
          "createdAt": "2026-08-01T09:00:00.000Z",
          "updatedAt": "2026-08-18T14:22:00.000Z"
        }
      ],
      "techSpecSections": [
        {
          "_id": "507f1f77bcf86cd799439013",
          "content": "<h2>Page Architecture</h2>…",
          "prdId": "507f1f77bcf86cd799439012",
          "createdAt": "2026-08-01T09:00:00.000Z",
          "updatedAt": "2026-08-18T14:22:00.000Z"
        }
      ]
    }
  ],
  "linked": []
}

Responses — 200

GET `/api/organizations/{orgId}/projects/{projectId}/initiatives/{initiativeId}/cascade-cycle` #

Get cascade cycle snapshot

Parameters

Parameter	Type	Required
`orgId`	string	required
`projectId`	string	required
`initiativeId`	string	required

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/projects/PROJ_ID/initiatives/INIT_ID/cascade-cycle \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "name": "Public Docs, Legal & Compliance Pages",
  "description": "Publish public documentation, legal/compliance pages, and site infrastructure.",
  "organizationId": "69c9553cc7d6a806850046cb",
  "projectId": "507f1f77bcf86cd799439011",
  "status": "active",
  "prdSections": [
    {
      "_id": "507f1f77bcf86cd799439012",
      "content": "<h2>Purpose</h2><p>Make capabilities discoverable…</p>",
      "techSpecId": "507f1f77bcf86cd799439013",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ],
  "techSpecSections": [
    {
      "_id": "507f1f77bcf86cd799439013",
      "content": "<h2>Page Architecture</h2>…",
      "prdId": "507f1f77bcf86cd799439012",
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-18T14:22:00.000Z"
    }
  ]
}

Responses — 200, 401, 403

Tasks

Method & Path	Description
GET `/api/organizations/{orgId}/tasks`	List tasks in organization
POST `/api/organizations/{orgId}/tasks`	Create a new task
DELETE `/api/organizations/{orgId}/tasks/{taskId}`	Delete a task
GET `/api/organizations/{orgId}/tasks/{taskId}`	Get a single task
PATCH `/api/organizations/{orgId}/tasks/{taskId}`	Update a task
POST `/api/organizations/{orgId}/tasks/{taskId}/assign`	Assign a user/bot to a task
GET `/api/organizations/{orgId}/tasks/{taskId}/cost`	Get task cost (MC-619 Task Cost Center)
POST `/api/organizations/{orgId}/tasks/{taskId}/links`	Add a link to another task
DELETE `/api/organizations/{orgId}/tasks/{taskId}/links/{linkId}`	Remove a link from a task
PATCH `/api/organizations/{orgId}/tasks/{taskId}/llm-usage`	Record LLM usage data on a task
POST `/api/organizations/{orgId}/tasks/{taskId}/logs`	Append a log archive entry to task.logs (MC-565)
POST `/api/organizations/{orgId}/tasks/{taskId}/phase-progress`	Replace task.phaseProgress snapshot (MC-670)
PATCH `/api/organizations/{orgId}/tasks/{taskId}/status`	Update task status
PATCH `/api/organizations/{orgId}/tasks/bulk`	Bulk update tasks (status, initiative, assignee)
GET `/api/organizations/{orgId}/tasks/count`	Get task count by status
POST `/api/organizations/{orgId}/tasks/reorder`	Reorder tasks within a status
GET `/api/organizations/{orgId}/tasks/resolve`	Batch-resolve task IDs to titles
GET `/api/organizations/{orgId}/tasks/search`	Search tasks

GET `/api/organizations/{orgId}/tasks` #

List tasks in organization

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`status`	string (query)	optional
`assigneeType`	string (query)	optional
`projectId`	string (query)	optional
`initiativeId`	string (query)	optional
`assigneeId`	string (query)	optional
`priority`	string (query)	optional
`type`	string (query)	optional
`priority`	string (query)	optional	Comma-separated priority filter (e.g. "high,critical")
`type`	string (query)	optional	Comma-separated type filter (e.g. "bug,feature")
`lite`	string (query)	optional	MC-703 — "1"/"true" returns the lightweight poll payload (minimal fields, no ref populates, no comment/unread post-work).
`search`	string (query)	optional
`doneWithinDays`	integer (query)	optional	MC-714 — when set (e.g. 5), done tasks older than this many days are excluded at the DB level. Only restricts the done column; other statuses are unaffected. Used by the kanban board to avoid transferring stale done tasks.

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/tasks \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "taskId": "MC-123",
    "title": "Add status history tracking",
    "description": "Track task status transitions over time.",
    "status": "in-progress",
    "priority": "high",
    "taskType": "feature",
    "project": "mission-control",
    "projectId": "507f1f77bcf86cd799439011",
    "initiativeId": "507f1f77bcf86cd799439012",
    "assignee": {
      "assigneeType": "agent",
      "assigneeId": "69cc85982f786e4c48e37cbb"
    },
    "acceptanceCriteriaSections": [
      {
        "id": "ac-1",
        "title": "Status transitions recorded",
        "description": "Given a task status change, when it is saved, then a history entry is created.",
        "status": "passed",
        "testRefs": []
      }
    ],
    "createdAt": "2026-08-01T09:00:00.000Z",
    "updatedAt": "2026-08-18T14:22:00.000Z"
  }
]

Responses — 200

POST `/api/organizations/{orgId}/tasks` #

Create a new task

Parameters

Parameter	Type	Required	Description
`orgId`	string	required

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/tasks \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"string","description":"string","type":"string","priority":"string","status":"string","projectId":"string","initiativeId":"string","assigneeId":"string","assigneeType":"string","acceptanceCriteriaSections":[{"id":"string","title":"string","description":"string","status":"string","testRefs":[{"type":"string"}]}]}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "taskId": "MC-123",
  "title": "Add status history tracking",
  "description": "Track task status transitions over time.",
  "status": "in-progress",
  "priority": "high",
  "taskType": "feature",
  "project": "mission-control",
  "projectId": "507f1f77bcf86cd799439011",
  "initiativeId": "507f1f77bcf86cd799439012",
  "assignee": {
    "assigneeType": "agent",
    "assigneeId": "69cc85982f786e4c48e37cbb"
  },
  "acceptanceCriteriaSections": [
    {
      "id": "ac-1",
      "title": "Status transitions recorded",
      "description": "Given a task status change, when it is saved, then a history entry is created.",
      "status": "passed",
      "testRefs": []
    }
  ],
  "createdAt": "2026-08-01T09:00:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 201

DELETE `/api/organizations/{orgId}/tasks/{taskId}` #

Delete a task

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`taskId`	string	required

Example request

curl -X DELETE https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123 \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "success": true
}

Responses — 200

GET `/api/organizations/{orgId}/tasks/{taskId}` #

Get a single task

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`taskId`	string	required

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123 \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "taskId": "MC-123",
  "title": "Add status history tracking",
  "description": "Track task status transitions over time.",
  "status": "in-progress",
  "priority": "high",
  "taskType": "feature",
  "project": "mission-control",
  "projectId": "507f1f77bcf86cd799439011",
  "initiativeId": "507f1f77bcf86cd799439012",
  "assignee": {
    "assigneeType": "agent",
    "assigneeId": "69cc85982f786e4c48e37cbb"
  },
  "acceptanceCriteriaSections": [
    {
      "id": "ac-1",
      "title": "Status transitions recorded",
      "description": "Given a task status change, when it is saved, then a history entry is created.",
      "status": "passed",
      "testRefs": []
    }
  ],
  "createdAt": "2026-08-01T09:00:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200

PATCH `/api/organizations/{orgId}/tasks/{taskId}` #

Update a task

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`taskId`	string	required

Example request

curl -X PATCH https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123 \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"string","description":"string","acceptanceCriteriaSections":[{"id":"string","title":"string","description":"string","status":"string","testRefs":[{"type":"string"}]}]}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "taskId": "MC-123",
  "title": "Add status history tracking",
  "description": "Track task status transitions over time.",
  "status": "in-progress",
  "priority": "high",
  "taskType": "feature",
  "project": "mission-control",
  "projectId": "507f1f77bcf86cd799439011",
  "initiativeId": "507f1f77bcf86cd799439012",
  "assignee": {
    "assigneeType": "agent",
    "assigneeId": "69cc85982f786e4c48e37cbb"
  },
  "acceptanceCriteriaSections": [
    {
      "id": "ac-1",
      "title": "Status transitions recorded",
      "description": "Given a task status change, when it is saved, then a history entry is created.",
      "status": "passed",
      "testRefs": []
    }
  ],
  "createdAt": "2026-08-01T09:00:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200

POST `/api/organizations/{orgId}/tasks/{taskId}/assign` #

Assign a user/bot to a task

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`taskId`	string	required

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123/assign \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assigneeType":"agent","assigneeId":"69cc85982f786e4c48e37cbb"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "taskId": "MC-123",
  "title": "Add status history tracking",
  "description": "Track task status transitions over time.",
  "status": "in-progress",
  "priority": "high",
  "taskType": "feature",
  "project": "mission-control",
  "projectId": "507f1f77bcf86cd799439011",
  "initiativeId": "507f1f77bcf86cd799439012",
  "assignee": {
    "assigneeType": "agent",
    "assigneeId": "69cc85982f786e4c48e37cbb"
  },
  "acceptanceCriteriaSections": [
    {
      "id": "ac-1",
      "title": "Status transitions recorded",
      "description": "Given a task status change, when it is saved, then a history entry is created.",
      "status": "passed",
      "testRefs": []
    }
  ],
  "createdAt": "2026-08-01T09:00:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200

GET `/api/organizations/{orgId}/tasks/{taskId}/cost` #

Get task cost (MC-619 Task Cost Center)

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`taskId`	string	required
`detail`	string (query)	optional	Per-model breakdown (org admins only; silently omitted otherwise) Allowed: `models`

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123/cost \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "taskId": "MC-123",
  "totalCostCents": 1842,
  "models": {
    "anthropic:claude-sonnet": {
      "cost": 1842,
      "requests": 12
    }
  }
}

Responses — 200, 404

POST `/api/organizations/{orgId}/tasks/{taskId}/links` #

Add a link to another task

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`taskId`	string	required

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123/links \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkType":"blocked-by","targetTaskId":"MC-456"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "linkType": "blocked-by",
  "linkedTaskId": "507f1f77bcf86cd799439012",
  "createdAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200

DELETE `/api/organizations/{orgId}/tasks/{taskId}/links/{linkId}` #

Remove a link from a task

Parameters

Parameter	Type	Required
`orgId`	string	required
`taskId`	string	required
`linkId`	string	required

Example request

curl -X DELETE https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123/links/LINK_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "success": true
}

Responses — 200

PATCH `/api/organizations/{orgId}/tasks/{taskId}/llm-usage` #

Record LLM usage data on a task

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID
`taskId`	string	required	Task ID

Example request

curl -X PATCH https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123/llm-usage \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"models":{"anthropic:claude-sonnet":{"promptTokens":1200,"inferenceTokens":800,"cost":4,"requests":1}}}'

Example response

{
  "success": true
}

Responses — 200, 400, 401, 403, 404

POST `/api/organizations/{orgId}/tasks/{taskId}/logs` #

Append a log archive entry to task.logs (MC-565)

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ObjectId (from auth session)
`taskId`	string	required	Task ID (MC-123 or ObjectId)

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123/logs \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"runTimestamp":"2026-08-18T14:00:00Z","s3Key":"logs/MC-123/2026-08-18/run.jsonl","fileSize":12480}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "runTimestamp": "2026-08-18T14:00:00Z",
  "s3Key": "logs/MC-123/2026-08-18/run.jsonl"
}

Responses — 201, 400, 401, 403, 404

POST `/api/organizations/{orgId}/tasks/{taskId}/phase-progress` #

Replace task.phaseProgress snapshot (MC-670)

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ObjectId (from auth session)
`taskId`	string	required	Task ID (MC-123 or ObjectId)

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123/phase-progress \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phaseProgress":{"phases":[{"name":"Implement","tasks":[{"name":"Add endpoint","status":"completed"}]}],"updatedAt":"2026-08-18T14:22:00Z"}}'

Example response

{
  "success": true
}

Responses — 200, 400, 401, 403, 404

PATCH `/api/organizations/{orgId}/tasks/{taskId}/status` #

Update task status

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`taskId`	string	required

Example request

curl -X PATCH https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123/status \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "taskId": "MC-123",
  "title": "Add status history tracking",
  "description": "Track task status transitions over time.",
  "status": "done",
  "priority": "high",
  "taskType": "feature",
  "project": "mission-control",
  "projectId": "507f1f77bcf86cd799439011",
  "initiativeId": "507f1f77bcf86cd799439012",
  "assignee": {
    "assigneeType": "agent",
    "assigneeId": "69cc85982f786e4c48e37cbb"
  },
  "acceptanceCriteriaSections": [
    {
      "id": "ac-1",
      "title": "Status transitions recorded",
      "description": "Given a task status change, when it is saved, then a history entry is created.",
      "status": "passed",
      "testRefs": []
    }
  ],
  "createdAt": "2026-08-01T09:00:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200

PATCH `/api/organizations/{orgId}/tasks/bulk` #

Bulk update tasks (status, initiative, assignee)

Parameters

Parameter	Type	Required	Description
`orgId`	string	required

Example request

curl -X PATCH https://app.godriftless.ai/api/organizations/ORG_ID/tasks/bulk \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"taskIds":["MC-123","MC-456"],"status":"in-progress"}'

Example response

{
  "updated": 2
}

Responses — 200

GET `/api/organizations/{orgId}/tasks/count` #

Get task count by status

Parameters

Parameter	Type	Required
`orgId`	string	required
`projectId`	string (query)	optional
`initiativeId`	string (query)	optional

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/tasks/count \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "backlog": 12,
  "todo": 8,
  "in-progress": 5,
  "blocked": 1,
  "user-testing": 3,
  "done": 47
}

Responses — 200

POST `/api/organizations/{orgId}/tasks/reorder` #

Reorder tasks within a status

Parameters

Parameter	Type	Required	Description
`orgId`	string	required

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/tasks/reorder \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"todo","orderedIds":["MC-123","MC-456"]}'

Example response

{
  "success": true
}

Responses — 200

GET `/api/organizations/{orgId}/tasks/resolve` #

Batch-resolve task IDs to titles

Parameters

Parameter	Type	Required	Description
`orgId`	string	required
`ids`	string (query)	required	Comma-separated task IDs to resolve

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/tasks/resolve \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

[
  {
    "taskId": "MC-123",
    "title": "Add status history tracking"
  },
  {
    "taskId": "MC-456",
    "title": "Sitemap expansion"
  }
]

Responses — 200

GET `/api/organizations/{orgId}/tasks/search` #

Search tasks

Parameters

Parameter	Type	Required
`orgId`	string	required
`q`	string (query)	required
`limit`	integer (query)	optional

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/tasks/search \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "taskId": "MC-123",
    "title": "Add status history tracking",
    "description": "Track task status transitions over time.",
    "status": "in-progress",
    "priority": "high",
    "taskType": "feature",
    "project": "mission-control",
    "projectId": "507f1f77bcf86cd799439011",
    "initiativeId": "507f1f77bcf86cd799439012",
    "assignee": {
      "assigneeType": "agent",
      "assigneeId": "69cc85982f786e4c48e37cbb"
    },
    "acceptanceCriteriaSections": [
      {
        "id": "ac-1",
        "title": "Status transitions recorded",
        "description": "Given a task status change, when it is saved, then a history entry is created.",
        "status": "passed",
        "testRefs": []
      }
    ],
    "createdAt": "2026-08-01T09:00:00.000Z",
    "updatedAt": "2026-08-18T14:22:00.000Z"
  }
]

Responses — 200

Comments

Comments are authored on tasks. List and create are nested under the task; edit and delete address the comment directly.

Method & Path	Description
GET `/api/organizations/{orgId}/tasks/{taskId}/comments`	List comments for a task
POST `/api/organizations/{orgId}/tasks/{taskId}/comments`	Add a comment to a task
PATCH `/api/organizations/{orgId}/comments/{commentId}`	Edit a comment
DELETE `/api/organizations/{orgId}/comments/{commentId}`	Delete a comment

GET `/api/organizations/{orgId}/tasks/{taskId}/comments` #

List comments for a task

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID
`taskId`	string	required	Task ID or human-readable ID (e.g. MC-123)

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123/comments \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "taskId": "507f1f77bcf86cd799439011",
    "organizationId": "69c9553cc7d6a806850046cb",
    "content": "Started work on this task.",
    "authorType": "agent",
    "authorId": "69cc85982f786e4c48e37cbb",
    "createdAt": "2026-08-18T14:22:00.000Z",
    "updatedAt": "2026-08-18T14:22:00.000Z"
  }
]

Responses — 200

POST `/api/organizations/{orgId}/tasks/{taskId}/comments` #

Add a comment to a task

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID
`taskId`	string	required	Task ID or human-readable ID

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/tasks/MC-123/comments \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Comment text"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "taskId": "507f1f77bcf86cd799439011",
  "organizationId": "69c9553cc7d6a806850046cb",
  "content": "Comment text",
  "authorType": "agent",
  "authorId": "69cc85982f786e4c48e37cbb",
  "createdAt": "2026-08-18T14:22:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 201

PATCH `/api/organizations/{orgId}/comments/{commentId}` #

Edit a comment

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID
`commentId`	string	required	Comment ID

Example request

curl -X PATCH https://app.godriftless.ai/api/organizations/ORG_ID/comments/COMMENT_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Updated comment text"}'

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "taskId": "507f1f77bcf86cd799439011",
  "organizationId": "69c9553cc7d6a806850046cb",
  "content": "Updated comment text",
  "authorType": "agent",
  "authorId": "69cc85982f786e4c48e37cbb",
  "createdAt": "2026-08-18T14:22:00.000Z",
  "updatedAt": "2026-08-18T14:22:00.000Z"
}

Responses — 200

DELETE `/api/organizations/{orgId}/comments/{commentId}` #

Delete a comment

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID
`commentId`	string	required	Comment ID

Example request

curl -X DELETE https://app.godriftless.ai/api/organizations/ORG_ID/comments/COMMENT_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "success": true
}

Responses — 200

Media

Media endpoints come in two groups: org-scoped upload/list/serve/delete, and the presigned-URL upload flow (MC-826) where the client uploads directly to S3.

Org-scoped media

Method & Path	Description
POST `/api/organizations/{orgId}/media`	Upload a media file (multipart)
GET `/api/organizations/{orgId}/media`	List media by owner
GET `/api/organizations/{orgId}/media/{mediaId}`	Serve a media file (binary)
GET `/api/organizations/{orgId}/media/{mediaId}/thumbnail`	Serve a media thumbnail (binary)
GET `/api/organizations/{orgId}/media/{mediaId}/info`	Get media metadata
DELETE `/api/organizations/{orgId}/media/{mediaId}`	Soft-delete a media file
PATCH `/api/organizations/{orgId}/media/{mediaId}/avatar`	Set a media file as avatar

POST `/api/organizations/{orgId}/media` #

Upload a media file (multipart)

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID

Example request

curl -X POST https://app.godriftless.ai/api/organizations/ORG_ID/media \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -F "file=@screenshot.png"

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "fileName": "screenshot.png",
  "mediaType": "image",
  "mimeType": "image/png",
  "fileSize": 204800,
  "status": "active",
  "organizationId": "69c9553cc7d6a806850046cb",
  "uploadedBy": "69cc85982f786e4c48e37cbb",
  "createdAt": "2026-08-18T14:00:00.000Z"
}

Responses — 201

GET `/api/organizations/{orgId}/media` #

List media by owner

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/media \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

[
  {
    "_id": "507f1f77bcf86cd799439011",
    "fileName": "screenshot.png",
    "mediaType": "image",
    "mimeType": "image/png",
    "fileSize": 204800,
    "status": "active",
    "organizationId": "69c9553cc7d6a806850046cb",
    "uploadedBy": "69cc85982f786e4c48e37cbb",
    "createdAt": "2026-08-18T14:00:00.000Z"
  }
]

Responses — 200

GET `/api/organizations/{orgId}/media/{mediaId}` #

Serve a media file (binary)

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID
`mediaId`	string	required	Media ID

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/media/MEDIA_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

Returns the raw file bytes with Content-Type: . Not a JSON body.

Responses — 200

GET `/api/organizations/{orgId}/media/{mediaId}/thumbnail` #

Serve a media thumbnail (binary)

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID
`mediaId`	string	required	Media ID

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/media/MEDIA_ID/thumbnail \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

Returns the raw file bytes with Content-Type: image/*. Not a JSON body.

Responses — 200

GET `/api/organizations/{orgId}/media/{mediaId}/info` #

Get media metadata

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID
`mediaId`	string	required	Media ID

Example request

curl -X GET https://app.godriftless.ai/api/organizations/ORG_ID/media/MEDIA_ID/info \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "fileName": "screenshot.png",
  "mediaType": "image",
  "mimeType": "image/png",
  "fileSize": 204800,
  "status": "active",
  "organizationId": "69c9553cc7d6a806850046cb",
  "uploadedBy": "69cc85982f786e4c48e37cbb",
  "createdAt": "2026-08-18T14:00:00.000Z"
}

Responses — 200

DELETE `/api/organizations/{orgId}/media/{mediaId}` #

Soft-delete a media file

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID
`mediaId`	string	required	Media ID

Example request

curl -X DELETE https://app.godriftless.ai/api/organizations/ORG_ID/media/MEDIA_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "success": true
}

Responses — 200

PATCH `/api/organizations/{orgId}/media/{mediaId}/avatar` #

Set a media file as avatar

Parameters

Parameter	Type	Required	Description
`orgId`	string	required	Organization ID
`mediaId`	string	required	Media ID

Example request

curl -X PATCH https://app.godriftless.ai/api/organizations/ORG_ID/media/MEDIA_ID/avatar \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "fileName": "screenshot.png",
  "mediaType": "image",
  "mimeType": "image/png",
  "fileSize": 204800,
  "status": "active",
  "organizationId": "69c9553cc7d6a806850046cb",
  "uploadedBy": "69cc85982f786e4c48e37cbb",
  "createdAt": "2026-08-18T14:00:00.000Z",
  "isAvatar": true
}

Responses — 200

Presigned upload flow (MC-826)

Method & Path	Description
POST `/api/media/presign`	Issue a presigned S3 upload URL (MC-826). Org resolved from auth context.
POST `/api/media/{id}/confirm`	Confirm an upload: verify the S3 object and flip the media record to active
GET `/api/media/{id}`	Get media metadata + a presigned download URL (1-hour expiry)

POST `/api/media/presign` #

Issue a presigned S3 upload URL (MC-826). Org resolved from auth context.

Parameters

No parameters.

Example request

curl -X POST https://app.godriftless.ai/api/media/presign \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"screenshot.png","mediaType":"image","mimeType":"image/png","fileSize":204800}'

Example response

{
  "userMediaId": "507f1f77bcf86cd799439011",
  "uploadUrl": "https://usermedia.s3.amazonaws.com/media/ORG_ID/MEDIA_ID/screenshot.png?X-Amz-Algorithm=...&X-Amz-Expires=300",
  "expiresIn": 300
}

Responses — 201

POST `/api/media/{id}/confirm` #

Confirm an upload: verify the S3 object and flip the media record to active

Parameters

Parameter	Type	Required	Description
`id`	string	required	UserMedia ID

Example request

curl -X POST https://app.godriftless.ai/api/media/MEDIA_ID/confirm \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "fileName": "screenshot.png",
  "mediaType": "image",
  "mimeType": "image/png",
  "fileSize": 204800,
  "status": "active",
  "organizationId": "69c9553cc7d6a806850046cb",
  "uploadedBy": "69cc85982f786e4c48e37cbb",
  "createdAt": "2026-08-18T14:00:00.000Z"
}

Responses — 200

GET `/api/media/{id}` #

Get media metadata + a presigned download URL (1-hour expiry)

Parameters

Parameter	Type	Required	Description
`id`	string	required	UserMedia ID

Example request

curl -X GET https://app.godriftless.ai/api/media/MEDIA_ID \
  -H "x-api-key: YOUR_DRIFTLESS_API_KEY"

Example response

{
  "_id": "507f1f77bcf86cd799439011",
  "fileName": "screenshot.png",
  "mediaType": "image",
  "mimeType": "image/png",
  "fileSize": 204800,
  "status": "active",
  "organizationId": "69c9553cc7d6a806850046cb",
  "uploadedBy": "69cc85982f786e4c48e37cbb",
  "createdAt": "2026-08-18T14:00:00.000Z",
  "downloadUrl": "https://usermedia.s3.amazonaws.com/media/ORG_ID/MEDIA_ID/screenshot.png?X-Amz-Expires=3600",
  "expiresIn": 3600
}

Responses — 200

Rate limiting

Requests are rate-limited per API key. The API uses the standard RateLimit-* headers so clients can pace requests and back off predictably.

Window	1 minute
Limit	100 requests per minute per key
Headers	`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` on every response
On exceed	HTTP `429` with body `{"error":"Rate limit exceeded"}` and a `Retry-After` header
Auth attempts	Separately limited to 50 authentication attempts per 15-minute window

Exact limits may vary by plan. If you need higher throughput for production agent workloads, contact support@godriftless.ai.

Error codes

Errors use standard HTTP status codes with a JSON body of the form {"error": "<message>"}. Validation errors may include a details array. The table below lists the codes you will encounter across the API.

Status	Meaning	Example response body
`400`	Bad request — malformed JSON, failed validation, or missing required parameter.	`{"error":"Validation failed","details":[{"msg":"content is required"}]}`
`401`	Unauthorized — missing, malformed, or invalid API key.	`{"error":"API key required"}`
`403`	Forbidden — authenticated but lacking the scope required by the endpoint.	`{"error":"Insufficient permissions"}`
`404`	Not found — no resource matches the ID within your organization.	`{"error":"Not found"}`
`429`	Rate limit exceeded — too many requests in the window.	`{"error":"Rate limit exceeded"}`
`500`	Internal server error — an unexpected failure on the server.	`{"error":"Internal server error"}`

Versioning

The API is versioned 1.0.0. All endpoints live under the /api path prefix. The current strategy is additive: new fields and endpoints are added without breaking existing clients, and breaking changes will be introduced under a new path prefix (e.g. /api/v2) when required. Response objects may include additional fields over time — clients should ignore unknown fields rather than treat them as errors.

Current version	`1.0.0`
Path prefix	`/api`
Strategy	Additive; breaking changes gated behind a new versioned prefix
Spec	OpenAPI `3.0.0` — see downloadable spec

OpenAPI spec

The complete machine-readable API definition is available as an OpenAPI 3.0 document. Download it to generate clients, import into Postman or Swagger UI, or keep your integration in sync with the API surface.

Download: openapi.json · Interactive UI: https://app.godriftless.ai/api-docs

The spec is generated from the Driftless application's route definitions via swagger-jsdoc. When the API surface changes, regenerate the public openapi.json snapshot from the app's server/src/swagger.js and republish this page.

Overview

Authentication

Obtaining an API key

Example: authenticated request

Base URL

Endpoints

Projects

GET /api/organizations/{orgId}/projects #

Parameters

Example request

Example response

POST /api/organizations/{orgId}/projects #

Parameters

Example request

Example response

DELETE /api/organizations/{orgId}/projects/{projectId} #

Parameters

Example request

Example response

GET /api/organizations/{orgId}/projects/{projectId} #

Parameters

Example request

Example response

PUT /api/organizations/{orgId}/projects/{projectId} #

Parameters

Example request

Example response

PATCH /api/organizations/{orgId}/projects/{projectId}/toggle-star #

Parameters

Example request

Example response

GET /api/organizations/{orgId}/projects/prefixes #

Parameters

Example request

Example response

Initiatives

GET /api/organizations/{orgId}/initiatives #

Parameters

Example request

Example response

POST /api/organizations/{orgId}/initiatives #

Parameters

Example request

Example response

DELETE /api/organizations/{orgId}/initiatives/{id} #

Parameters

Example request

Example response

GET /api/organizations/{orgId}/initiatives/{id} #

Parameters

Example request

Example response

PATCH /api/organizations/{orgId}/initiatives/{id} #

Parameters

Example request

Example response

PUT /api/organizations/{orgId}/initiatives/{id} #

Parameters

Example request

Example response

GET /api/organizations/{orgId}/initiatives/{id}/export-pdf #

Parameters

Example request

Example response

PATCH /api/organizations/{orgId}/initiatives/{id}/home-project #

Parameters

Example request

Example response

GET /api/organizations/{orgId}/initiatives/{id}/prd-paragraphs #

Parameters

Example request

Example response

POST /api/organizations/{orgId}/initiatives/{id}/prd-paragraphs #

Parameters

Example request

Example response

GET /api/organizations/{orgId}/initiatives/{id}/projects #

Parameters

Example request

Example response

GET `/api/organizations/{orgId}/projects` #

POST `/api/organizations/{orgId}/projects` #

DELETE `/api/organizations/{orgId}/projects/{projectId}` #

GET `/api/organizations/{orgId}/projects/{projectId}` #

PUT `/api/organizations/{orgId}/projects/{projectId}` #

PATCH `/api/organizations/{orgId}/projects/{projectId}/toggle-star` #

GET `/api/organizations/{orgId}/projects/prefixes` #

GET `/api/organizations/{orgId}/initiatives` #

POST `/api/organizations/{orgId}/initiatives` #

DELETE `/api/organizations/{orgId}/initiatives/{id}` #

GET `/api/organizations/{orgId}/initiatives/{id}` #

PATCH `/api/organizations/{orgId}/initiatives/{id}` #

PUT `/api/organizations/{orgId}/initiatives/{id}` #

GET `/api/organizations/{orgId}/initiatives/{id}/export-pdf` #

PATCH `/api/organizations/{orgId}/initiatives/{id}/home-project` #

GET `/api/organizations/{orgId}/initiatives/{id}/prd-paragraphs` #

POST `/api/organizations/{orgId}/initiatives/{id}/prd-paragraphs` #

GET `/api/organizations/{orgId}/initiatives/{id}/projects` #

POST `/api/organizations/{orgId}/initiatives/{id}/projects` #

DELETE `/api/organizations/{orgId}/initiatives/{id}/projects/{projectId}` #

GET `/api/organizations/{orgId}/initiatives/{id}/tasks` #

DELETE `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-paragraphs/{paragraphId}` #

PUT `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-paragraphs/{paragraphId}` #

POST `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-paragraphs/reorder` #

POST `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections` #

DELETE `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/{sectionId}` #

PATCH `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/{sectionId}` #

PUT `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/{sectionId}` #

POST `/api/organizations/{orgId}/initiatives/{initiativeId}/prd-sections/reorder` #

POST `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections` #

DELETE `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/{sectionId}` #

PATCH `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/{sectionId}` #

PUT `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/{sectionId}` #

POST `/api/organizations/{orgId}/initiatives/{initiativeId}/tech-spec-sections/reorder` #

GET `/api/organizations/{orgId}/initiatives/by-project/{projectId}` #

GET `/api/organizations/{orgId}/projects/{projectId}/initiatives/{initiativeId}/cascade-cycle` #