Skip to content

Developers

API Reference

REST v1 and MCP. Machine-readable spec: openapi.json

Authentication

Two auth modes accept all v1 endpoints:

  1. Browser session via NextAuth — used by the dashboard. teamId must be supplied as a query parameter.
  2. Personal Access Token via Authorization: Bearer qf_live_…. The token is bound to one team and a set of scopes at creation. Get one at Settings → API Keys.

Token plaintext follows the shape qf_<mode>_<prefix>_<secret>. Test-mode tokens use the qf_test_ prefix and bind to Stripe test products.

Scopes

ScopePurpose
jobs:readRead jobs and history.
jobs:writeCreate, update, move jobs.
stages:readRead pipeline stages.
stages:writeCreate or update stages.
tags:readRead tags.
tags:writeCreate or update tags.
members:readRead team membership list (email masked for tokens).
mcp:claimClaim / release / report progress on jobs.
mcp:assignAssign jobs to members. Available on every plan.
mcp:decideRequest a human decision on a job.
mcp:resolve_decisionResolve an open decision (with the human's chat reply as excerpt).
mcp:evidenceAttach evidence to a job.
team:readRead team metadata.
team:adminReserved — destructive verbs intentionally NOT bound to this scope today.

Endpoints

MethodPathScope
POST/api/auth/tokens
Issue a Personal Access Token. Needs the current password (and the 2FA code when on). Returns plaintext ONCE.
session, owner+admin
GET/api/auth/tokens
List tokens for a team.
session, owner+admin
DELETE/api/auth/tokens/[id]
Soft-revoke a token (sets revokedAt).
session
GET/api/v1/jobs
List jobs (cursor-paginated, max 100/req). Filters: stageId, assignedToId, status, flagged, tag, dueBefore, dueAfter, q, daysInStageMin.
jobs:read
POST/api/v1/jobs
Create a job in the first stage unless stageId is supplied.
jobs:write
GET/api/v1/jobs/[id]
Read a single job with tags + assignee.
jobs:read
PATCH/api/v1/jobs/[id]
Update title, description, priority, dueDate, poNumber, value. An exact dueDate needs Premium or Diamond (402 on Free); null resets it to the default.
jobs:write
POST/api/v1/jobs/[id]/tags
Attach a tag to a job ({ tagId }). Premium+.
jobs:write
DELETE/api/v1/jobs/[id]/tags
Detach a tag from a job. Premium+.
jobs:write
POST/api/v1/jobs/[id]/move
Move a job to another stage with workflow validation. A move to the last stage completes the job, and its QR codes expire 90 days later (as on the board). A move to the job's current stage is a no-op: 200 with the job unchanged.
jobs:write
POST/api/v1/jobs/[id]/assign
Assign a job to a team member (or null to unassign). Every plan.
mcp:assign
GET/api/v1/templates
List the team's job templates. POST /api/v1/jobs accepts { templateId }.
jobs:read
GET/api/v1/agent/briefing
What this agent token should know now: decisions waiting, unacknowledged approvals, expired decisions, held jobs, new human notes.
jobs:read
POST/api/v1/decisions/[id]/ack
Mark a resolved or expired decision as read by this token.
mcp:decide
GET/api/v1/stages
List stages, ordered.
stages:read
POST/api/v1/stages
Create a stage (inserted before the final stage).
stages:write
PATCH/api/v1/stages/[id]
Rename, change SLA, change color.
stages:write
GET/api/v1/tags
List tags.
tags:read
POST/api/v1/tags
Create a tag.
tags:write
PATCH/api/v1/tags/[id]
Rename / recolor.
tags:write
GET/api/v1/members
List members with role + joinedAt.
members:read
GET/api/v1/audit-log
Read token-authed request log. Tokens cannot read this.
session, owner+admin
GET/api/health
Shallow liveness (no DB). Add ?deep=1 for DB + Stripe readiness. No auth.
public

Rate limits

  • Token-authed requests: 20 / 60 / 120 per minute per token on Free / Premium / Diamond, plus a monthly volume quota of 2,000 / 20,000 / 100,000 requests per team.
  • Writes (POST/PATCH/DELETE) count against the same per-minute limit as reads.
  • Anonymous (newsletter, public boards): 20 / minute per IP.
  • Rate-limited responses return 429 with Retry-After and X-RateLimit-* headers.

Destructive operations

DELETE /api/teams/[id] requires session auth AND a body of { "confirm": "DELETE" } (case-insensitive; the older "DELETE <team-slug>" is still accepted). It deletes the team only; the user account stays active. Tokens cannot delete teams. Bulk-delete and Stripe mutation are not exposed via the API at all.

Plans & limits

The API and MCP enforce the same plan matrix as the app. Reads and the agent-collaboration loop (claim, progress, decisions) are open on every plan; attaching and listing evidence needs Premium; scale and premium capabilities are gated:

CapabilityMinimum plan
Create / move jobs (within active-job cap)FREE
Flag priorityFREE
TagsPREMIUM
Attach / list evidencePREMIUM
Assign jobs to membersFREE

Exceeding a gate returns a structured upgrade hint (see Errors). Active-job caps: FREE 10 (up to 20 with referrals), PREMIUM 40, DIAMOND 150.

MCP server

Stdio MCP server published as qodflow-mcp. Point your AI client at it and pass QODFLOW_API_TOKEN as an env var (and QODFLOW_API_BASE=https://www.qodflow.com if overriding). Tools exposed:

  • Read: list_jobs, get_job, list_stages, list_tags, list_members, list_templates, get_briefing, get_timeline, list_decisions, list_evidence
  • Write: create_job, update_job, move_job, assign_job, create_tag (PREMIUM+), update_tag, create_stage, update_stage
  • Agent loop: claim_job, release_job, report_progress, request_human_decision, resolve_decision, ack_decision, attach_evidence

Destructive verbs are intentionally NOT exposed via MCP. See /security.

Errors

All errors follow the shape { success: false, error: { code, message, details? } }. Codes include UNAUTHORIZED, FORBIDDEN, INVALID_INPUT, NOT_FOUND, RATE_LIMIT_EXCEEDED, PLAN_LIMIT_REACHED, PLAN_UPGRADE_REQUIRED.

Plan and quota errors carry a machine-readable upgrade hint so an agent can relay it in-context:

{
  "success": false,
  "error": {
    "code": "PLAN_UPGRADE_REQUIRED",
    "message": "Feature \"tags\" requires the PREMIUM plan. You're on FREE.",
    "details": {
      "feature": "tags",
      "currentPlan": "FREE",
      "requiredPlan": "PREMIUM",
      "upgradeUrl": "https://www.qodflow.com/settings/billing",
      "docsUrl": "https://www.qodflow.com/api-docs#plans"
    }
  }
}