API Endpoints

Auto-generated

This reference is auto-generated from the OpenAPI 3.0 specification. Last generated: 2026-05-02. Run npm run generate-api to regenerate.

Base URL: https://api.orkosi.com/api (production) or http://localhost:3001/api (local)

For interactive testing, use the Swagger UI.

---

Endpoint summary

Method	Path	Auth	Description
GET	/version	No	Get application version and uptime
GET	/health	No	API health check (DB connectivity, version, uptime)
GET	/ready	No	Readiness probe (200 when DB is connected)
GET	/activity-log	Yes	List recent activities with filtering
POST	/activity-log	Yes	Create a new activity record
GET	/activity-log/stats	Yes	Activity summary statistics
GET	/organizations/{orgId}/api-keys	Yes	List API keys for organization (masked)
POST	/organizations/{orgId}/api-keys	Yes	Create API key (returns raw key once)
GET	/organizations/{orgId}/api-keys/{keyId}	Yes	Get API key detail (masked)
PATCH	/organizations/{orgId}/api-keys/{keyId}	Yes	Update API key name, description, scopes, or active status
DELETE	/organizations/{orgId}/api-keys/{keyId}	Yes	Soft-delete API key
POST	/organizations/{orgId}/api-keys/{keyId}/revoke	Yes	Revoke API key instantly
POST	/organizations/{orgId}/api-keys/{keyId}/rotate	Yes	Rotate API key (old key valid for 24h grace period)
POST	/organizations/{orgId}/api-keys/{keyId}/roll	Yes	Roll (regenerate) API key (no grace period)
GET	/organizations/{orgId}/api-keys/{keyId}/usage	Yes	Per-key usage log
POST	/auth/register	No	Register a new user account
POST	/auth/login	No	Authenticate with email and password
POST	/auth/logout	Yes	Revoke current session token (or all tokens for the user)
GET	/auth/me	Yes	Get current authenticated user
POST	/auth/forgot-password	No	Request a password reset email
GET	/automations	Yes	List automations (run scripts and LaunchAgents)
POST	/automations	Yes	Create automation record
GET	/automations/{id}	Yes	Get single automation
PATCH	/automations/{id}	Yes	Update automation
DELETE	/automations/{id}	Yes	Delete automation
GET	/backups	Yes	List backup files (newest first)
GET	/backups/stats	Yes	Aggregate backup stats (count, size, last backup)
GET	/backups/logs	Yes	Tail of offsite_backup.log (last 100 lines)
GET	/backups/github-status	Yes	Latest backup in GitHub db-backups repo and sync check
GET	/backups/{filename}/download	Yes	Download a backup file
DELETE	/backups/{filename}	Yes	Delete a backup file from disk
POST	/backups/trigger	Yes	Trigger a manual pg_dump backup
GET	/billing/overview	Yes	OS billing dashboard (MRR, infra spend, AI costs)
GET	/billing/subscription	Yes	Get current user subscription
POST	/billing/checkout	Yes	Create Stripe checkout session for plan purchase
POST	/billing/portal	Yes	Create Stripe customer portal session
POST	/billing/create-payment-intent	Yes	Create payment intent for one-time token purchase
POST	/billing/webhook	No	Stripe webhook handler
GET	/billing/usage	Yes	Get current usage stats and limits
GET	/billing/tiers	No	List available subscription tiers
GET	/billing/pricing	No	Public pricing strategy (tiers, token packages, economics)
POST	/billing/change-plan	Yes	Upgrade or downgrade subscription plan
GET	/billing/plan-summary	Yes	Full plan limits and current usage summary
POST	/billing/validate-downgrade	Yes	Check if downgrade to target tier is possible
GET	/billing/auto-topup	Yes	Get auto top-up configuration
POST	/billing/auto-topup	Yes	Configure auto top-up (initial setup)
PUT	/billing/auto-topup	Yes	Update auto top-up configuration
GET	/billing/credit-auto-topup	Yes	Get credit auto top-up configuration
POST	/billing/credit-auto-topup	Yes	Configure credit auto top-up (initial setup)
PUT	/billing/credit-auto-topup	Yes	Update credit auto top-up configuration
POST	/bull-queue/submit	Yes	Submit a job to a BullMQ queue
POST	/bull-queue/submit-scheduled	Yes	Submit a scheduled or recurring job
GET	/bull-queue/stats	Yes	Get BullMQ queue statistics
GET	/bull-queue/{queue}/jobs	Yes	List jobs from a BullMQ queue
GET	/changelog	Yes	List changelog entries from completed tasks
GET	/changelog/summary	Yes	Aggregated changelog grouped by date and area
GET	/changelog/feed	Yes	RSS 2.0 feed of changelog entries
GET	/credentials	Yes	List all credential keys (values hidden)
POST	/credentials	Yes	Create or update a credential (admin only)
GET	/credentials/{key}	Yes	Get a single credential (decrypted value)
DELETE	/credentials/{key}	Yes	Delete a credential (admin only)
GET	/dashboard	No	Dashboard root — overview stats and available sub-endpoints
GET	/dashboard/agent-efficiency	Yes	Per-agent efficiency KPIs (tokens, cost, tasks per 1k tokens)
GET	/dashboard/agent-queue-health	Yes	Per-agent queued task count and wait times
GET	/dashboard/stats	Yes	Dashboard overview stats (agents, tasks, products, pending)
GET	/dashboard/overview	Yes	Aggregated overview (token balance, recent runs, protocols, 7d usage)
GET	/discovery-engines	Yes	List all discovery engines with stats
POST	/discovery-engines	Yes	Create new discovery engine with cron job
GET	/discovery-engines/efficiency	Yes	Per-engine efficiency and waste stats
GET	/discovery-engines/{slug}	Yes	Get single discovery engine with recent runs
PATCH	/discovery-engines/{slug}	Yes	Update discovery engine and sync cron job
DELETE	/discovery-engines/{slug}	Yes	Delete discovery engine and associated cron job
POST	/discovery-engines/{slug}/run	Yes	Trigger immediate discovery engine run
GET	/factory-workers	Yes	List all factory workers with state and metrics
GET	/factory-workers/stats	Yes	Factory summary stats
PATCH	/factory-workers/config	Yes	Update factory worker count and concurrency config
GET	/factory-workers/health-summary	Yes	Factory health summary with launchctl status
GET	/files	Yes	List files with pagination
POST	/files	Yes	Create or upsert a file record
GET	/files/{id}	Yes	Get a single file with content
GET	/files/search	Yes	Search files by name or content
GET	/arch-health	No	Architecture health overview (DB, memory, git, tunnel, rate limits)
GET	/integrations	Yes	List all integrations with status
GET	/integrations/{id}/status	Yes	Check if an integration is configured
POST	/integrations/{id}/configure	Yes	Save integration credentials
GET	/logs	Yes	List merged log lines (file + DB)
POST	/logs	Yes	Store an agent log entry
GET	/logs/files	Yes	List available log files
GET	/notifications	Yes	List notifications
POST	/notifications	Yes	Create a notification
GET	/notifications/unread-count	Yes	Get unread notification count
PATCH	/notifications/read-all	Yes	Mark all notifications as read
GET	/organizations	Yes	List organizations for the current user
POST	/organizations	Yes	Create organization within user's tenant
GET	/organizations/{id}	Yes	Get organization detail with member count
PATCH	/organizations/{id}	Yes	Update organization name, slug, or avatar
DELETE	/organizations/{id}	Yes	Soft-delete organization (owner only)
GET	/organizations/{id}/members	Yes	List organization members
POST	/organizations/{id}/members	Yes	Add a member to organization (admin+)
PATCH	/organizations/{id}/members/{userId}	Yes	Update member role in organization
DELETE	/organizations/{id}/members/{userId}	Yes	Remove member from organization (admin+)
GET	/organizations/{id}/invites	Yes	List pending organization invites
POST	/organizations/{id}/invites	Yes	Invite user by email to organization
POST	/organizations/invites/{token}/accept	Yes	Accept an organization invite
GET	/v1/public/health	No	Public API health check
GET	/v1/public/tasks	Yes	List tasks
POST	/v1/public/tasks	Yes	Create a task
GET	/v1/public/tasks/{id}	Yes	Get a task by ID
PATCH	/v1/public/tasks/{id}	Yes	Update a task
DELETE	/v1/public/tasks/{id}	Yes	Archive a task (sets status to cancelled)
GET	/v1/public/agents	Yes	List agents
POST	/v1/public/agents	Yes	Create an agent
GET	/v1/public/agents/{id}	Yes	Get an agent by ID
PATCH	/v1/public/agents/{id}	Yes	Update an agent
DELETE	/v1/public/agents/{id}	Yes	Deactivate an agent (sets status to offline)
GET	/v1/public/templates	Yes	List agent templates
POST	/v1/public/templates	Yes	Create an agent template
GET	/v1/public/templates/{id}	Yes	Get a template by ID
PATCH	/v1/public/templates/{id}	Yes	Update a template
DELETE	/v1/public/templates/{id}	Yes	Archive a template (soft delete)
GET	/rules	Yes	List architectural rules (filterable by scope, agent, category)
POST	/rules	Yes	Create a new rule
PATCH	/rules/{id}	Yes	Update a rule
DELETE	/rules/{id}	Yes	Delete a rule (non-permanent only)
GET	/search	Yes	Global search across tasks, products, and agents
GET	/system/health	Yes	Architecture health dashboard (compliance score, per-section breakdowns)
POST	/task-queue/submit	Yes	Submit a new job to the task queue
POST	/task-queue/claim	Yes	Claim next job(s) from queue (SKIP LOCKED)
GET	/teams	Yes	List all teams with member counts
POST	/teams	Yes	Create a new team
GET	/teams/{id}	Yes	Get team with members
PATCH	/teams/{id}	Yes	Update team name or description
DELETE	/teams/{id}	Yes	Delete team (admin+ only)
GET	/teams/{id}/members	Yes	List team members
POST	/teams/{id}/members	Yes	Add member to team
GET	/teams/{id}/invites	Yes	List team invites
POST	/teams/{id}/invites	Yes	Invite user to team by email
GET	/tokens/balance	Yes	Get current user's token balance
GET	/tokens/transactions	Yes	Get token transaction history
POST	/tokens/consume	Yes	Consume tokens for an action
GET	/users	Yes	List all users
GET	/users/{id}	Yes	Get a user by ID
PATCH	/users/{id}	Yes	Update a user
DELETE	/users/{id}	Yes	Delete a user
DELETE	/users/me	Yes	Delete own account (GDPR right to be forgotten)
POST	/agents	Yes	Create a new agent
GET	/agents	Yes	List all agents
POST	/agents/{name}/stop	Yes	Stop an agent
POST	/agents/{name}/start	Yes	Start an agent
POST	/agents/{name}/restart	Yes	Restart an agent
GET	/agent-runs/idle-check	No	Idle-skip preflight check
GET	/tasks	Yes	List tasks
POST	/tasks	Yes	Create a task
GET	/tasks/{id}	Yes	Get a single task
DELETE	/tasks/{id}	Yes	Delete a task
GET	/products	Yes	List products
POST	/products	Yes	Create a product
GET	/products/{slug}	Yes	Get a product by slug
PATCH	/products/{slug}	Yes	Update a product

---

Auth

Authentication, registration, password reset, and token refresh

GET /organizations/{orgId}/api-keys

List API keys for organization (masked)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
orgId	path	string	Yes

Responses:

• 200: API keys list (values masked)

---

POST /organizations/{orgId}/api-keys

Create API key (returns raw key once)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
orgId	path	string	Yes

Request body (application/json):

Field	Type	Required	Description
name	string	Yes
description	string	No
scopes	string[]	No
expires_at	string	No

Responses:

• 201: Key created (raw key in response, only shown once)

---

GET /organizations/{orgId}/api-keys/{keyId}

Get API key detail (masked)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
orgId	path	string	Yes
keyId	path	string	Yes

Responses:

• 200: Key detail

---

PATCH /organizations/{orgId}/api-keys/{keyId}

Update API key name, description, scopes, or active status

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
orgId	path	string	Yes
keyId	path	string	Yes

Responses:

• 200: Key updated

---

DELETE /organizations/{orgId}/api-keys/{keyId}

Soft-delete API key

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
orgId	path	string	Yes
keyId	path	string	Yes

Responses:

• 200: Key deleted

---

POST /organizations/{orgId}/api-keys/{keyId}/revoke

Revoke API key instantly

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
orgId	path	string	Yes
keyId	path	string	Yes

Responses:

• 200: Key revoked (immediately unusable)

---

POST /organizations/{orgId}/api-keys/{keyId}/rotate

Rotate API key (old key valid for 24h grace period)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
orgId	path	string	Yes
keyId	path	string	Yes

Request body (application/json):

Field	Type	Required	Description
grace_hours	integer	No

Responses:

• 200: New raw key returned (old key valid during grace period)

---

POST /organizations/{orgId}/api-keys/{keyId}/roll

Roll (regenerate) API key (no grace period)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
orgId	path	string	Yes
keyId	path	string	Yes

Responses:

• 200: New raw key returned (old key invalidated)

---

GET /organizations/{orgId}/api-keys/{keyId}/usage

Per-key usage log

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
orgId	path	string	Yes
keyId	path	string	Yes

Responses:

• 200: Usage log entries

---

POST /auth/register

Register a new user account

Authentication: None

Request body (application/json):

Field	Type	Required	Description
username	string	Yes
email	string	Yes
password	string	Yes
invite_code	string	No
terms_accepted	boolean	Yes
privacy_accepted	boolean	Yes

Responses:

• 201: User created successfully
• 400: Validation error — Error
• 409: User already exists

---

POST /auth/login

Authenticate with email and password

Authentication: None

Request body (application/json):

Field	Type	Required	Description
email	string	Yes
password	string	Yes

Responses:

• 200: Login successful
• 400: Missing or invalid credentials
• 401: Invalid email or password

---

POST /auth/logout

Revoke current session token (or all tokens for the user)

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
all_devices	boolean	No	Example: undefined

Responses:

• 200: Logged out — SuccessResponse

---

GET /auth/me

Get current authenticated user

Authentication: Bearer token / API key

Responses:

• 200: Current user info
• 401: Not authenticated

---

POST /auth/forgot-password

Request a password reset email

Authentication: None

Request body (application/json):

Field	Type	Required	Description
email	string	Yes

Responses:

• 200: Reset email sent (always returns success to prevent enumeration) — SuccessResponse

---

Users

User management and profiles

GET /users

List all users

Returns all users (id, username, email, role, timestamps). Requires authentication.

Authentication: Bearer token / API key

Responses:

• 200: User list — ListResponse
• 401: Unauthorized

---

GET /users/{id}

Get a user by ID

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: User details — ItemResponse
• 404: User not found

---

PATCH /users/{id}

Update a user

Admin-only. Updatable fields are username, email, and role.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Request body (application/json):

Field	Type	Required	Description
username	string	No
email	string	No
role	admin | editor | viewer | builder | agent | demo	No

Responses:

• 200: User updated — ItemResponse
• 404: User not found

---

DELETE /users/{id}

Delete a user

Admin-only. Cannot delete your own account.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: User deleted — DeletedResponse
• 403: Cannot delete your own account
• 404: User not found

---

DELETE /users/me

Delete own account (GDPR right to be forgotten)

Self-service account erasure. Admin accounts cannot self-delete.

Authentication: Bearer token / API key

Responses:

• 200: Account deleted — DeletedResponse
• 403: Admin accounts cannot be self-deleted

---

Health

Health checks, readiness, and liveness probes

GET /version

Get application version and uptime

Authentication: None

Responses:

• 200: Version info

---

GET /health

API health check (DB connectivity, version, uptime)

Authentication: None

Responses:

• 200: Healthy
• 503: Database unavailable

---

GET /ready

Readiness probe (200 when DB is connected)

Authentication: None

Responses:

• 200: Ready
• 503: Not ready (DB unavailable)

---

GET /arch-health

Architecture health overview (DB, memory, git, tunnel, rate limits)

Authentication: None

Responses:

• 200: Detailed system health status
• 503: System degraded

---

Agents

Agent lifecycle, state, and monitoring

POST /agents

Create a new agent

10-step bootstrap protocol: DB registration, workspace creation, SOUL.md, run script, automations, LaunchAgent plist, load agent, update heartbeat, and log.

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
name	string	Yes	Example: felix
display_name	string	No	Example: Felix
model	string	No	Example: claude-haiku-4-5
interval_sec	integer	No	Example: 3600
emoji	string	No	Example: 📦
color	string	No	Example: #3b82f6

Responses:

• 200: Agent created with bootstrap step results — SuccessResponse
• 409: Agent already exists

---

GET /agents

List all agents

Returns agents with registry info, state, automations, completion rates, and file-based state merged.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
limit	query	integer	No	Max items to return
offset	query	integer	No	Number of items to skip
status	query	string	No	Filter by agent status (comma-separated)

Responses:

• 200: Paginated agent list — ListResponse
• 503: Database unavailable

---

POST /agents/{name}/stop

Stop an agent

Sets the agent status to stopped in both file state and DB, creates a /tmp flag, and logs the event.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
name	path	string	Yes	Agent name

Request body (application/json):

Field	Type	Required	Description
note	string	No	Example: undefined

Responses:

• 200: Agent stopped — SuccessResponse
• 400: Invalid agent name

---

POST /agents/{name}/start

Start an agent

Removes the stop flag, updates DB and file state, loads the LaunchAgent, and logs the event.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
name	path	string	Yes

Request body (application/json):

Field	Type	Required	Description
note	string	No

Responses:

• 200: Agent started — SuccessResponse
• 400: Invalid agent name

---

POST /agents/{name}/restart

Restart an agent

Unloads the LaunchAgent, waits briefly, reloads it, and logs the event.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
name	path	string	Yes

Request body (application/json):

Field	Type	Required	Description
note	string	No

Responses:

• 200: Agent restarted — SuccessResponse

---

Agent Runs

Agent run tracking and analytics

GET /agent-runs/idle-check

Idle-skip preflight check

Lightweight check (~100ms) called by shell scripts before starting a full agent run. Returns whether the agent should skip this cycle.

Authentication: None

Parameters:

Name	In	Type	Required	Description
agent_name	query	string	Yes	Agent name to check
run_mode	query	string	No	Run mode (task, discovery, etc.)

Responses:

• 200: Idle check result
• 400: Missing agent_name parameter

---

Tasks

Task CRUD, verification, and workflow

GET /tasks

List tasks

Paginated task list with filters for status, search, assignee, product, priority, and more.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
limit	query	integer	No
offset	query	integer	No
status	query	string	No	Comma-separated status filter (todo, in_progress, review, done, blocked, archived)
q	query	string	No	Full-text search in title and description
assignee	query	string	No	Filter by assignee name (use "me" with auth token)
next	query	true | false	No	Return highest-priority todo task for the given assignee

Responses:

• 200: Paginated task list — ListResponse
• 503: Database unavailable

---

POST /tasks

Create a task

Creates a new task with validation, dedup, and post-create hooks (agent task derivation, cascade changes).

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
title	string	Yes	Example: Fix login bug
description	string	No
status	todo | in_progress | review | done | blocked | archived	No
priority	P0 | P1 | P2 | P3	No
assignee	string	No
product_slug	string	No

Responses:

• 201: Task created — ItemResponse
• 400: Validation error
• 429: Rate limit exceeded

---

GET /tasks/{id}

Get a single task

Returns a task by ID with embedded blocking/dependency info.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes	Task ID

Responses:

• 200: Task details — ItemResponse
• 404: Task not found

---

DELETE /tasks/{id}

Delete a task

Permanently deletes a task. Requires admin role.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Task deleted — DeletedResponse
• 400: Invalid task ID
• 404: Task not found

---

Products

Product catalog, features, and assets

GET /products

List products

Returns all products with optional status and search filters. Merges DB rows with file-based brand metadata.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
status	query	string	No	Comma-separated status filter (active, building, archived)
q	query	string	No	Search query
slug	query	string	No	Filter by exact slug

Responses:

• 200: Product list with summary stats — ListResponse
• 401: Authentication required

---

POST /products

Create a product

Creates a new product with slug generation, brand directory scaffolding, and guideline sync.

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
name	string	Yes	Example: My Product
slug	string	No	Example: my-product
tagline	string	No
description	string	No
status	active | building | archived	No

Responses:

• 201: Product created — ItemResponse
• 400: Validation error
• 409: Product slug already exists

---

GET /products/{slug}

Get a product by slug

Returns a single product merged with file-based brand metadata.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
slug	path	string	Yes	Product slug (e.g. "unosend")

Responses:

• 200: Product details — ItemResponse
• 401: Authentication required
• 404: Product not found

---

PATCH /products/{slug}

Update a product

Upserts product fields. Triggers guideline sync, cascade tasks, and status-change side effects.

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
slug	path	string	Yes

Request body (application/json):

Field	Type	Required	Description
name	string	No
tagline	string	No
description	string	No
status	active | building | archived | live | placeholder	No
brand_color	string	No
accent_color	string	No

Responses:

• 200: Product updated — ItemResponse
• 404: Product not found

---

Credentials

Encrypted credential storage (AES-256-GCM)

GET /credentials

List all credential keys (values hidden)

Authentication: Bearer token / API key

Responses:

• 200: Credential keys list — ListResponse

---

POST /credentials

Create or update a credential (admin only)

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
key	string	Yes
value	string	Yes
description	string	No

Responses:

• 201: Credential saved — ItemResponse
• 400: Validation error
• 403: Admin required

---

GET /credentials/{key}

Get a single credential (decrypted value)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
key	path	string	Yes

Responses:

• 200: Credential with decrypted value — ItemResponse
• 404: Credential not found
• 500: Decryption failed

---

DELETE /credentials/{key}

Delete a credential (admin only)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
key	path	string	Yes

Responses:

• 200: Credential deleted — DeletedResponse
• 403: Admin required
• 404: Not found

---

Tokens

Token-based usage and billing

GET /tokens/balance

Get current user's token balance

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
company_id	query	integer	No	Scope to a specific company

Responses:

• 200: Token balance

---

GET /tokens/transactions

Get token transaction history

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
company_id	query	integer	No
type	query	consume | purchase | bonus | signup_bonus | admin_grant | refund	No
limit	query	integer	No
offset	query	integer	No

Responses:

• 200: Transaction list — ListResponse

---

POST /tokens/consume

Consume tokens for an action

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
amount	integer	Yes
action	string	Yes
company_id	integer	No
reference_id	string	No
metadata	object	No

Responses:

• 200: Tokens consumed
• 400: Invalid amount or missing action
• 402: Insufficient balance

---

Discovery

Discovery engines and automated audits

GET /discovery-engines

List all discovery engines with stats

Authentication: Bearer token / API key

Responses:

• 200: All engines with run stats, linked task counts

---

POST /discovery-engines

Create new discovery engine with cron job

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
name	string	Yes
description	string	No
layer	string	Yes
schedule_interval_ms	integer	No
model	string	No
enabled	boolean	No

Responses:

• 201: Engine created

---

GET /discovery-engines/efficiency

Per-engine efficiency and waste stats

Authentication: Bearer token / API key

Responses:

• 200: Efficiency metrics per engine (cost, waste, compute minutes)

---

GET /discovery-engines/{slug}

Get single discovery engine with recent runs

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
slug	path	string	Yes

Responses:

• 200: Engine details with recent run history
• 404: Engine not found

---

PATCH /discovery-engines/{slug}

Update discovery engine and sync cron job

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
slug	path	string	Yes

Responses:

• 200: Engine updated
• 404: Engine not found

---

DELETE /discovery-engines/{slug}

Delete discovery engine and associated cron job

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
slug	path	string	Yes

Responses:

• 200: Engine deleted
• 404: Engine not found

---

POST /discovery-engines/{slug}/run

Trigger immediate discovery engine run

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
slug	path	string	Yes

Responses:

• 200: Run queued
• 404: Engine not found

---

Monitoring

System health, metrics, and dashboards

GET /activity-log

List recent activities with filtering

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
actor_type	query	agent | system | user	No
actor_id	query	string	No
action	query	string	No
limit	query	integer	No
offset	query	integer	No

Responses:

• 200: Activity list — ListResponse

---

POST /activity-log

Create a new activity record

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
actor_type	agent | system | user	Yes
actor_id	string	Yes
action	string	Yes
entity_type	string	No
entity_id	string	No
metadata	object	No

Responses:

• 201: Activity created — ItemResponse

---

GET /activity-log/stats

Activity summary statistics

Authentication: Bearer token / API key

Responses:

• 200: Activity statistics — ItemResponse

---

GET /dashboard

Dashboard root — overview stats and available sub-endpoints

Authentication: None

Responses:

• 200: Overview counts and endpoint list

---

GET /dashboard/agent-efficiency

Per-agent efficiency KPIs (tokens, cost, tasks per 1k tokens)

Authentication: Bearer token / API key

Responses:

• 200: Agents sorted by tasks per 1k tokens

---

GET /dashboard/agent-queue-health

Per-agent queued task count and wait times

Authentication: Bearer token / API key

Responses:

• 200: Queue health per agent

---

GET /dashboard/stats

Dashboard overview stats (agents, tasks, products, pending)

Authentication: Bearer token / API key

Responses:

• 200: Aggregate counts

---

GET /dashboard/overview

Aggregated overview (token balance, recent runs, protocols, 7d usage)

Authentication: Bearer token / API key

Responses:

• 200: Full dashboard overview

---

GET /logs

List merged log lines (file + DB)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
limit	query	integer	No
source	query	file | db | all	No
agent	query	string	No
level	query	error | warn | info	No
q	query	string	No

Responses:

• 200: Log entries

---

POST /logs

Store an agent log entry

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
agent	string	Yes
message	string	Yes
level	string	No
meta	object	No

Responses:

• 201: Log entry created

---

GET /logs/files

List available log files

Authentication: Bearer token / API key

Responses:

• 200: Available log files

---

GET /system/health

Architecture health dashboard (compliance score, per-section breakdowns)

Authentication: Bearer token / API key

Responses:

• 200: Overall compliance score with agent, task, product, and file health sections

---

Operations

Automations, pipelines, and deployments

GET /automations

List automations (run scripts and LaunchAgents)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
agent_name	query	string	No	Filter by agent name
type	query	string	No	Filter by type (e.g. launchagent, script)
status	query	active | inactive | disabled	No
q	query	string	No	Full-text search (max 100 chars)

Responses:

• 200: List of automations with live filesystem status — ListResponse

---

POST /automations

Create automation record

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
name	string	Yes
agent_name	string	Yes
type	string	Yes
path	string	Yes
label	string	No
status	active | inactive | disabled	No

Responses:

• 201: Automation created

---

GET /automations/{id}

Get single automation

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Automation detail with live status
• 404: Not found

---

PATCH /automations/{id}

Update automation

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Automation updated

---

DELETE /automations/{id}

Delete automation

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Automation deleted

---

GET /backups

List backup files (newest first)

Authentication: Bearer token / API key

Responses:

• 200: Backup file list with sizes and timestamps

---

GET /backups/stats

Aggregate backup stats (count, size, last backup)

Authentication: Bearer token / API key

Responses:

• 200: Backup statistics

---

GET /backups/logs

Tail of offsite_backup.log (last 100 lines)

Authentication: Bearer token / API key

Responses:

• 200: Log lines

---

GET /backups/github-status

Latest backup in GitHub db-backups repo and sync check

Authentication: Bearer token / API key

Responses:

• 200: GitHub backup status

---

GET /backups/{filename}/download

Download a backup file

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
filename	path	string	Yes

Responses:

• 200: Backup file stream
• 400: Invalid filename

---

DELETE /backups/{filename}

Delete a backup file from disk

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
filename	path	string	Yes

Responses:

• 200: File deleted

---

POST /backups/trigger

Trigger a manual pg_dump backup

Authentication: Bearer token / API key

Responses:

• 200: Backup triggered

---

GET /changelog

List changelog entries from completed tasks

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
limit	query	integer	No
offset	query	integer	No
agent	query	string	No	Filter by agent name
task_id	query	integer	No	Filter by source task ID

Responses:

• 200: Paginated changelog entries — ListResponse

---

GET /changelog/summary

Aggregated changelog grouped by date and area

Authentication: Bearer token / API key

Responses:

• 200: Human-readable summaries per date

---

GET /changelog/feed

RSS 2.0 feed of changelog entries

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
limit	query	integer	No
agent	query	string	No
product	query	string	No

Responses:

• 200: RSS 2.0 XML feed

---

GET /files

List files with pagination

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
category	query	string	No
page	query	integer	No
limit	query	integer	No

Responses:

• 200: Paginated file list

---

POST /files

Create or upsert a file record

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
name	string	Yes
path	string	Yes
file_type	string	No
category	string	No
content	string	No

Responses:

• 201: File record created

---

GET /files/{id}

Get a single file with content

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: File details — ItemResponse
• 404: File not found

---

GET /files/search

Search files by name or content

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
q	query	string	No
workspace	query	string	No
category	query	string	No
ext	query	string	No

Responses:

• 200: Matching files — ListResponse

---

GET /integrations

List all integrations with status

Authentication: Bearer token / API key

Responses:

• 200: Integration catalogue with connection status

---

GET /integrations/{id}/status

Check if an integration is configured

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes

Responses:

• 200: Integration configuration status
• 404: Unknown integration

---

POST /integrations/{id}/configure

Save integration credentials

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes

Request body (application/json):

Field	Type	Required	Description
fields	object	No

Responses:

• 200: Integration configured — SuccessResponse

---

GET /organizations

List organizations for the current user

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
limit	query	integer	No
offset	query	integer	No

Responses:

• 200: Paginated list of organizations with member counts — ListResponse

---

POST /organizations

Create organization within user's tenant

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
name	string	Yes
slug	string	No

Responses:

• 201: Organization created (creator becomes owner)
• 409: Slug already exists in tenant

---

GET /organizations/{id}

Get organization detail with member count

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes

Responses:

• 200: Organization detail
• 404: Not found

---

PATCH /organizations/{id}

Update organization name, slug, or avatar

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes

Request body (application/json):

Field	Type	Required	Description
name	string	No
slug	string	No
avatar_url	string	No

Responses:

• 200: Organization updated
• 409: Slug already in use

---

DELETE /organizations/{id}

Soft-delete organization (owner only)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes

Responses:

• 200: Organization deleted — DeletedResponse

---

GET /organizations/{id}/members

List organization members

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes

Responses:

• 200: List of members with roles

---

POST /organizations/{id}/members

Add a member to organization (admin+)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes

Request body (application/json):

Field	Type	Required	Description
user_id	string	Yes
role	owner | admin | member | viewer	No

Responses:

• 201: Member added
• 409: User already a member

---

PATCH /organizations/{id}/members/{userId}

Update member role in organization

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes
userId	path	string	Yes

Request body (application/json):

Field	Type	Required	Description
role	owner | admin | member | viewer	Yes

Responses:

• 200: Role updated

---

DELETE /organizations/{id}/members/{userId}

Remove member from organization (admin+)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes
userId	path	string	Yes

Responses:

• 200: Member removed

---

GET /organizations/{id}/invites

List pending organization invites

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes

Responses:

• 200: Pending invite list

---

POST /organizations/{id}/invites

Invite user by email to organization

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	string	Yes

Request body (application/json):

Field	Type	Required	Description
email	string	Yes
role	admin | member | viewer	No

Responses:

• 201: Invite sent
• 409: Active invite already exists

---

POST /organizations/invites/{token}/accept

Accept an organization invite

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
token	path	string	Yes

Responses:

• 200: Invite accepted, user added as member
• 404: Invalid or expired invite

---

GET /rules

List architectural rules (filterable by scope, agent, category)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
scope	query	string	No	Filter by scope (e.g. 'all' for universal rules)
agent	query	string	No	Agent name — returns agent-scoped + universal rules
category	query	string	No	Filter by category (e.g. arch-stack, workflow, security)
permanent	query	0 | 1	No

Responses:

• 200: Rules list — ListResponse

---

POST /rules

Create a new rule

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
rule	string	Yes
scope	string	No
category	string	No
permanent	boolean	No

Responses:

• 201: Rule created

---

PATCH /rules/{id}

Update a rule

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Rule updated

---

DELETE /rules/{id}

Delete a rule (non-permanent only)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Rule deleted
• 403: Cannot delete permanent rules

---

GET /search

Global search across tasks, products, and agents

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
q	query	string	Yes	Search query (searches titles, names, slugs, IDs)

Responses:

• 200: Search results grouped by entity type
• 400: Query too long

---

POST /task-queue/submit

Submit a new job to the task queue

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
task_type	string	Yes
payload	object	No
queue_name	string	No
priority	integer	No
tenant_id	integer	No
max_attempts	integer	No
timeout_seconds	integer	No
idempotency_key	string	No

Responses:

• 201: Job submitted — ItemResponse
• 400: Missing task_type
• 503: Queue table not available

---

POST /task-queue/claim

Claim next job(s) from queue (SKIP LOCKED)

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
worker_id	string	Yes
queue_name	string	No
task_type	string	No
tenant_id	integer	No
batch_size	integer	No

Responses:

• 200: Claimed job(s) or null if queue empty
• 400: Missing worker_id

---

GET /teams

List all teams with member counts

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
name	query	string	No	Filter by team name (ILIKE)
limit	query	integer	No
offset	query	integer	No

Responses:

• 200: Paginated team list — ListResponse

---

POST /teams

Create a new team

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
name	string	Yes
description	string	No

Responses:

• 201: Team created (creator becomes owner)

---

GET /teams/{id}

Get team with members

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Team details with member list
• 404: Team not found

---

PATCH /teams/{id}

Update team name or description

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Team updated

---

DELETE /teams/{id}

Delete team (admin+ only)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Team deleted

---

GET /teams/{id}/members

List team members

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Member list with roles

---

POST /teams/{id}/members

Add member to team

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Request body (application/json):

Field	Type	Required	Description
user_id	integer	Yes
role	owner | admin | member	No

Responses:

• 201: Member added

---

GET /teams/{id}/invites

List team invites

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Pending invites

---

POST /teams/{id}/invites

Invite user to team by email

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Request body (application/json):

Field	Type	Required	Description
email	string	Yes
role	owner | admin | member	No

Responses:

• 201: Invite sent

---

Factory

Factory workers and task pipeline

GET /factory-workers

List all factory workers with state and metrics

Authentication: Bearer token / API key

Responses:

• 200: Worker states, task counts, CC slots, and throughput

---

GET /factory-workers/stats

Factory summary stats

Authentication: Bearer token / API key

Responses:

• 200: Factory summary statistics

---

PATCH /factory-workers/config

Update factory worker count and concurrency config

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
worker_count	integer	No
max_concurrent	integer	No

Responses:

• 200: Config updated

---

GET /factory-workers/health-summary

Factory health summary with launchctl status

Authentication: Bearer token / API key

Responses:

• 200: Health status with worker PIDs and alerts

---

Billing

Billing, costs, invoices, and Stripe integration

GET /billing/overview

OS billing dashboard (MRR, infra spend, AI costs)

Authentication: Bearer token / API key

Responses:

• 200: Billing overview with MRR by product, infrastructure and AI spend

---

GET /billing/subscription

Get current user subscription

Authentication: Bearer token / API key

Responses:

• 200: Current subscription details
• 404: No subscription found

---

POST /billing/checkout

Create Stripe checkout session for plan purchase

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
tier	string	Yes	Example: undefined

Responses:

• 200: Checkout session created

---

POST /billing/portal

Create Stripe customer portal session

Authentication: Bearer token / API key

Responses:

• 200: Portal session URL

---

POST /billing/create-payment-intent

Create payment intent for one-time token purchase

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
package_slug	string	Yes
idempotency_key	string	No

Responses:

• 200: Payment intent created

---

POST /billing/webhook

Stripe webhook handler

Authentication: None

Responses:

• 200: Webhook processed

---

GET /billing/usage

Get current usage stats and limits

Authentication: Bearer token / API key

Responses:

• 200: Current period usage, subscription tier, and limits
• 404: No subscription or usage data found

---

GET /billing/tiers

List available subscription tiers

Authentication: None

Responses:

• 200: Available tiers — ListResponse

---

GET /billing/pricing

Public pricing strategy (tiers, token packages, economics)

Authentication: None

Responses:

• 200: Full pricing strategy

---

POST /billing/change-plan

Upgrade or downgrade subscription plan

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
tier	string	Yes	Example: undefined

Responses:

• 200: Plan changed or checkout session created
• 422: Usage exceeds target tier limits

---

GET /billing/plan-summary

Full plan limits and current usage summary

Authentication: Bearer token / API key

Responses:

• 200: Plan limits with current usage

---

POST /billing/validate-downgrade

Check if downgrade to target tier is possible

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
tier	string	Yes

Responses:

• 200: Validation result with violations if any

---

GET /billing/auto-topup

Get auto top-up configuration

Authentication: Bearer token / API key

Responses:

• 200: Auto top-up config with available packages

---

POST /billing/auto-topup

Configure auto top-up (initial setup)

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
threshold_tokens	integer	Yes	Example: undefined
package_id	string	Yes	Example: undefined
enabled	boolean	No
max_monthly_topups	integer	No
stripe_payment_method_id	string	No	Example: undefined

Responses:

• 201: Auto top-up configured
• 400: Missing or invalid parameters
• 409: Auto top-up already configured for this tenant

---

PUT /billing/auto-topup

Update auto top-up configuration

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
enabled	boolean	No
package_slug	string	No
threshold_tokens	integer	No
max_monthly_topups	integer	No
stripe_payment_method_id	string	No

Responses:

• 200: Updated configuration

---

GET /billing/credit-auto-topup

Get credit auto top-up configuration

Authentication: Bearer token / API key

Responses:

• 200: Credit auto top-up config with available packages

---

POST /billing/credit-auto-topup

Configure credit auto top-up (initial setup)

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
threshold_cents	integer	Yes	Example: undefined
package_slug	string	Yes	Example: undefined
enabled	boolean	No
max_monthly_topups	integer	No
stripe_payment_method_id	string	No	Example: undefined

Responses:

• 201: Credit auto top-up configured
• 400: Missing or invalid parameters
• 409: Credit auto top-up already configured for this user

---

PUT /billing/credit-auto-topup

Update credit auto top-up configuration

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
enabled	boolean	No
package_slug	string	No
threshold_cents	integer	No
max_monthly_topups	integer	No
stripe_payment_method_id	string	No

Responses:

• 200: Updated configuration

---

Notifications

Notification delivery and templates

GET /notifications

List notifications

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
read	query	true | false	No
type	query	info | warning | error | success	No
limit	query	integer	No
offset	query	integer	No

Responses:

• 200: Notification list — ListResponse

---

POST /notifications

Create a notification

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
title	string	Yes
message	string	Yes
type	info | warning | error | success	No
source	string	No
link	string	No

Responses:

• 201: Created notification — ItemResponse

---

GET /notifications/unread-count

Get unread notification count

Authentication: Bearer token / API key

Responses:

• 200: Unread count

---

PATCH /notifications/read-all

Mark all notifications as read

Authentication: Bearer token / API key

Responses:

• 200: All marked as read — SuccessResponse

---

Queue

POST /bull-queue/submit

Submit a job to a BullMQ queue

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
queue	string	Yes	Example: undefined
name	string	Yes	Example: undefined
data	object	Yes	Example: undefined
priority	integer	No	Example: undefined
attempts	integer	No	Example: undefined
backoff	object	No
delay	integer	No	Example: undefined
job_id	string	No	Example: undefined

Responses:

• 201: Job submitted
• 400: Missing required fields
• 503: BullMQ not available

---

POST /bull-queue/submit-scheduled

Submit a scheduled or recurring job

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
queue	string	Yes
name	string	Yes
data	object	Yes
delay	integer	No	Example: undefined
repeat	string	No	Example: undefined
every	integer	No	Example: undefined

Responses:

• 201: Scheduled job submitted

---

GET /bull-queue/stats

Get BullMQ queue statistics

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
queue	query	string	No	Filter by queue name (optional)

Responses:

• 200: Queue statistics

---

GET /bull-queue/{queue}/jobs

List jobs from a BullMQ queue

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
queue	path	string	Yes
status	query	waiting | active | completed | failed | delayed | paused | prioritized	No
start	query	integer	No
end	query	integer	No

Responses:

• 200: List of jobs

---

Public API

GET /v1/public/health

Public API health check

Authentication: None

Responses:

• 200: API is healthy

---

GET /v1/public/tasks

List tasks

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
limit	query	integer	No
offset	query	integer	No
status	query	string	No	Filter by status
priority	query	string	No	Filter by priority
assigned_to	query	string	No	Filter by assignee
product_id	query	integer	No	Filter by product

Responses:

• 200: Paginated task list
• 401: Authentication required
• 403: Insufficient scope

---

POST /v1/public/tasks

Create a task

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
title	string	Yes
description	string	No
type	feature | bug | research | ops | infra | content | other	No
priority	low | medium | high | critical	No
status	todo | in_progress | review | done | blocked | cancelled	No
assigned_to	string	No
product_id	integer	No
max_duration_seconds	integer	No

Responses:

• 201: Task created
• 400: Validation error
• 401: Authentication required
• 403: Insufficient scope

---

GET /v1/public/tasks/{id}

Get a task by ID

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Task detail
• 404: Task not found

---

PATCH /v1/public/tasks/{id}

Update a task

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Request body (application/json):

Field	Type	Required	Description
title	string	No
description	string	No
type	string	No
priority	string	No
status	string	No
assigned_to	string	No
product_id	integer	No
resolution	string	No
max_duration_seconds	integer	No

Responses:

• 200: Task updated
• 404: Task not found

---

DELETE /v1/public/tasks/{id}

Archive a task (sets status to cancelled)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Task archived
• 404: Task not found

---

GET /v1/public/agents

List agents

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
limit	query	integer	No
offset	query	integer	No
status	query	string	No	Filter by status
role	query	string	No	Filter by role

Responses:

• 200: Paginated agent list

---

POST /v1/public/agents

Create an agent

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
name	string	Yes
emoji	string	No
role	string	Yes
status	idle | working | blocked | offline | paused	No
workspace_path	string	No

Responses:

• 201: Agent created
• 400: Validation error

---

GET /v1/public/agents/{id}

Get an agent by ID

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Agent detail
• 404: Agent not found

---

PATCH /v1/public/agents/{id}

Update an agent

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Request body (application/json):

Field	Type	Required	Description
emoji	string	No
role	string	No
status	idle | working | blocked | offline | paused	No
current_task	string	No
workspace_path	string	No

Responses:

• 200: Agent updated
• 404: Agent not found

---

DELETE /v1/public/agents/{id}

Deactivate an agent (sets status to offline)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Agent deactivated
• 404: Agent not found

---

GET /v1/public/templates

List agent templates

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
limit	query	integer	No
offset	query	integer	No
category	query	string	No	Filter by category
featured	query	boolean	No	Only featured templates

Responses:

• 200: Paginated template list

---

POST /v1/public/templates

Create an agent template

Authentication: Bearer token / API key

Request body (application/json):

Field	Type	Required	Description
name	string	Yes
slug	string	Yes
description	string	No
icon	string	No
category	string	No
model	string	No
interval_sec	integer	No
identity	string	No
tools	string[]	No
capabilities	string[]	No
config	object	No
is_featured	boolean	No
sort_order	integer	No

Responses:

• 201: Template created
• 400: Validation error
• 409: Template slug already exists

---

GET /v1/public/templates/{id}

Get a template by ID

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Template detail
• 404: Template not found

---

PATCH /v1/public/templates/{id}

Update a template

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Request body (application/json):

Field	Type	Required	Description
name	string	No
description	string	No
icon	string	No
category	string	No
model	string	No
interval_sec	integer	No
identity	string	No
tools	string[]	No
capabilities	string[]	No
config	object	No
is_featured	boolean	No
sort_order	integer	No

Responses:

• 200: Template updated
• 404: Template not found

---

DELETE /v1/public/templates/{id}

Archive a template (soft delete)

Authentication: Bearer token / API key

Parameters:

Name	In	Type	Required	Description
id	path	integer	Yes

Responses:

• 200: Template archived
• 404: Template not found

---

Schemas

Error

Field	Type	Description
error	object

ItemResponse

Field	Type	Description
data	object

ListResponse

Field	Type	Description
data	object[]
meta	object

SuccessResponse

Field	Type	Description
data	object
meta	object

DeletedResponse

Field	Type	Description
data	object
meta	object

Task

Field	Type	Description
id	integer	Example: 53430
title	string	Example: Implement OpenAPI docs
description	string
status	todo | in_progress | review | done | blocked | cancelled	Example: todo
priority	P0 | P1 | P2 | P3	Example: P1
assignee	string	Example: felix
product	string	Example: assimetria-os
category	string
tags	string
estimated_minutes	integer
due_date	string
created_at	string
updated_at	string

Agent

Field	Type	Description
id	integer	Example: 1
name	string	Example: felix
display_name	string	Example: Felix
role	string	Example: engineer
status	active | idle | offline | error	Example: active
model	string	Example: claude-sonnet-4-20250514
last_heartbeat	string
created_at	string

Product

Field	Type	Description
id	integer	Example: 1
name	string	Example: UnoSend
slug	string	Example: unosend
description	string
status	idea | building | launched | archived	Example: building
domain	string	Example: unosend.com
created_at	string
updated_at	string

User

Field	Type	Description
id	integer	Example: 1
username	string	Example: rui
email	string	Example: r@assimetria.com
role	admin | member | viewer	Example: admin
avatar_url	string
created_at	string

HealthResponse

Field	Type	Description
status	ok | error	Example: ok
version	string	Example: 1.1.5235
uptime	integer	Process uptime in seconds Example: 86400
db	connected | error	Example: connected
redis	connected | disconnected | not_configured | error	Example: connected

LoginRequest

Field	Type	Description
email	string	Example: user@example.com
password	string	Example: your-password

LoginResponse

Field	Type	Description
success	boolean	Example: true
token	string	Example: eyJhbGciOiJIUzI1NiIs...
refresh_token	string	Example: a1b2c3d4e5f6...
user	User