API

JSON API for tasks, projects, tags, templates, attachments, saved views, notifications, AI agents, and account settings. The current version is /api/v2. /api/v1 is a compatibility alias that serves the same handlers, so older clients keep working.

Enable it in Admin → Site settings → Enable external REST API (full mode) or with ORDRYN_BOOTSTRAP_ENABLE_API=true. Redis must be up.

Canonical contract

Do not treat this wiki page as the path-by-path reference.

• Source file: openapi.yaml in the server repo
• On a running instance: GET /openapi.yaml
• In the Vue UI (full mode): /docs/api/v2 (/docs/api/v1 still works)

Authentication

Four mechanisms, same /api/v2 resources:

Mechanism	Who	How
Bearer API key	Scripts, Android, other clients	Authorization: Bearer <key>
Project API key	Integrations limited to one project	Same header. Created by a project manager, limited to that project and the chosen scopes.
Session cookie	Vue SPA	POST /api/v2/auth/login or register; httpOnly cookie; send credentials with requests
Device SSO	Native apps	POST /api/v2/auth/device/code (optional "redirect_uri"), user approves at /auth/device, app receives the token

Personal API keys are created under Settings (or bootstrap). The secret is shown once at creation. Revoked keys stop immediately.

Anonymous GET /api/v2/me returns HTTP 200 with JSON null when there is no session.

Live updates

GET /api/v2/events is a Server-Sent Events stream. The web UI uses it to keep shared projects and other tabs in sync. It needs Redis, and a reverse proxy must not buffer it. See Reverse-proxy.

Smoke tests

Health (no auth):

curl -s http://localhost:8080/api/v2/health | jq .
# {"version":"v3.x.y","mode":"full","api_enabled":true,"redis_ok":true}

Session:

curl -s -c /tmp/ordryn.cookies -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"choose-a-strong-password"}' \
  http://localhost:8080/api/v2/auth/login | jq .

curl -s -b /tmp/ordryn.cookies http://localhost:8080/api/v2/me | jq .

Bearer:

export KEY='paste-key-here'
curl -s -H "Authorization: Bearer $KEY" http://localhost:8080/api/v2/me | jq .
curl -s -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"title":"API smoke task"}' \
  http://localhost:8080/api/v2/tasks | jq .

Invite-only signup: pass invite_token on register, or disable invite-only as admin.

Device authorization (apps)

1. Run Ordryn in api or full mode with the API enabled and Redis.
2. Set HOST=0.0.0.0 so the server accepts connections from other machines (the default 127.0.0.1 is local only), and point the app at http://<lan-ip>:8080, not localhost on the phone.
3. Either paste a Bearer key, or start device SSO: POST /api/v2/auth/device/code with optional "redirect_uri":"ordryn://auth-complete" → open the verification URL → approve in the SPA at /auth/device → the browser returns to the app.

AI agents and MCP

Project managers can add AI agents as project members (project settings → AI agents). Each agent gets its own key, which acts as the agent and is limited by the agent's role and guardrails. An agent connects in one of three ways:

• MCP: POST /api/v2/mcp is a Model Context Protocol server (streamable HTTP). For Claude Code: claude mcp add --transport http ordryn-<handle> https://<host>/api/v2/mcp --header "Authorization: Bearer <agent key>"
• REST queue: GET /api/v2/agent, GET /api/v2/agent/runs, then POST …/runs/{id}/start and …/finish.
• Webhook: a public HTTPS URL that receives each new run, signed with X-Ordryn-Signature.

Operator notes:

• MCP and agent keys need the REST API enabled and Redis.
• Agents running elsewhere need to reach your public URL. Webhook agents need the server to reach out to theirs.
• Full reference: /docs/api/v2#ai-agents on your instance and the AI Agents tag in openapi.yaml.

Other integration endpoints

• Inbound webhooks: POST /api/v2/webhooks/inbound creates tasks or comments from other systems. Turn it on in Admin, then per project.
• Extension callbacks: POST /api/v2/ext/callback with a project-scoped callback token. See Extensions.
• GitHub: OAuth callback at /api/v2/auth/github/callback. See Admin-settings.

Sample programs: Example-clients.