API Overview
Codality exposes a REST API for all operations. The web UI uses this API exclusively.
Authentication
All API routes (except auth, setup, webhooks, and health) require a session cookie. Obtain one via the OTP login flow:
bash# Request OTP
curl -X POST https://codality.example.com/api/auth/request-otp \
-H 'Content-Type: application/json' \
-d '{"email": "user@example.com"}'
# Verify OTP and get session
curl -X POST https://codality.example.com/api/auth/verify-otp \
-H 'Content-Type: application/json' \
-d '{"email": "user@example.com", "code": "123456"}' \
-c cookies.txt
# Use session cookie for authenticated requests
curl -b cookies.txt https://codality.example.com/api/projects
Public endpoints
| Method |
Path |
Description |
GET |
/healthz |
Health check. Returns version and setup status. |
POST |
/api/auth/request-otp |
Request an OTP code via email. |
POST |
/api/auth/verify-otp |
Verify OTP and create session. |
POST |
/api/setup/verify |
Verify setup code (first-time only). |
GET |
/api/setup/status |
Check if setup is required. |
POST |
/api/github/webhooks |
GitHub webhook receiver. |
Project endpoints
| Method |
Path |
Description |
GET |
/api/projects |
List all projects |
POST |
/api/projects |
Create a project |
GET |
/api/projects/{slug} |
Get project details |
PUT |
/api/projects/{slug} |
Update project |
GET |
/api/projects/{slug}/files |
List project files |
GET |
/api/projects/{slug}/browse |
Browse repository tree |
GET |
/api/projects/{slug}/blob/ |
Get file contents |
Ticket endpoints
| Method |
Path |
Description |
GET |
/api/projects/{slug}/tickets |
List tickets (supports status filter) |
POST |
/api/projects/{slug}/tickets |
Create a ticket |
GET |
/api/projects/{slug}/tickets/{number} |
Get ticket details |
PUT |
/api/projects/{slug}/tickets/{number} |
Update ticket |
PATCH |
/api/projects/{slug}/tickets/{number}/status |
Update ticket status |
PATCH |
/api/projects/{slug}/tickets/{number}/assign |
Assign ticket |
GET |
/api/projects/{slug}/tickets/search |
Search tickets by text |
Agent endpoints
| Method |
Path |
Description |
POST |
/api/projects/{slug}/tickets/{number}/agent/start |
Start agent on ticket |
POST |
/api/projects/{slug}/tickets/{number}/agent/stop |
Stop running agent |
GET |
/api/projects/{slug}/tickets/{number}/agent/status |
Get agent status |
POST |
/api/projects/{slug}/tickets/{number}/agent/message |
Send message to running agent |
Plan endpoints
| Method |
Path |
Description |
GET |
/api/projects/{slug}/plans |
List plans |
POST |
/api/projects/{slug}/plans |
Create a plan |
GET |
/api/projects/{slug}/plans/{id} |
Get plan |
PUT |
/api/projects/{slug}/plans/{id} |
Update plan |
DELETE |
/api/projects/{slug}/plans/{id} |
Delete plan |
POST |
/api/projects/{slug}/plans/{id}/approve |
Approve plan |
POST |
/api/projects/{slug}/plans/{id}/ai/suggest |
Get AI suggestions |
POST |
/api/projects/{slug}/plans/{id}/ai/check-ready |
Check plan readiness |
POST |
/api/projects/{slug}/plans/{id}/ai/extract-tickets |
Extract tickets from plan |
| Method |
Path |
Description |
GET |
/api/projects/{slug}/tickets/{number}/comments |
List ticket comments |
POST |
/api/projects/{slug}/tickets/{number}/comments |
Create a comment |
Review endpoints
| Method |
Path |
Description |
GET |
/api/projects/{slug}/tickets/{number}/diff |
Get unified diff for ticket branch |
GET |
/api/projects/{slug}/tickets/{number}/diff/stats |
Get diff statistics |
GET |
/api/projects/{slug}/tickets/{number}/reviews |
List reviews |
POST |
/api/projects/{slug}/tickets/{number}/reviews |
Submit a review (approved/changes_requested/commented) |
GET |
/api/projects/{slug}/tickets/{number}/reviews/comments |
List review comments |
GET |
/api/projects/{slug}/tickets/{number}/merge-diff |
Get captured merge diff (post-merge historical view) |
GET |
/api/projects/{slug}/tickets/{number}/merge-diff/stats |
Get merge diff statistics |
Worktree endpoints
| Method |
Path |
Description |
POST |
/api/projects/{slug}/tickets/{number}/worktree/merge |
Merge worktree into default branch |
POST |
/api/projects/{slug}/tickets/{number}/worktree/discard |
Discard worktree and branch |
Pull request endpoints
| Method |
Path |
Description |
GET |
/api/projects/{slug}/pull-requests |
List all PRs for project |
POST |
/api/projects/{slug}/tickets/{number}/pull-request |
Create PR |
GET |
/api/projects/{slug}/tickets/{number}/pull-request |
Get PR for ticket |
GET |
/api/projects/{slug}/tickets/{number}/pull-request/status |
PR + live CI checks + review state |
GET |
/api/projects/{slug}/tickets/{number}/pull-request/comments |
Sync PR comments from GitHub |
POST |
/api/projects/{slug}/tickets/{number}/pull-request/update |
Re-push branch and update PR SHA |
POST |
/api/projects/{slug}/tickets/{number}/pull-request/merge |
Merge PR on GitHub |
Discovery endpoints
| Method |
Path |
Description |
GET |
/api/projects/{slug}/discover/conversations |
List discovery conversations |
POST |
/api/projects/{slug}/discover/conversations |
Create a new conversation |
GET |
/api/projects/{slug}/discover/conversations/{id} |
Get conversation with messages |
PUT |
/api/projects/{slug}/discover/conversations/{id} |
Update conversation title |
DELETE |
/api/projects/{slug}/discover/conversations/{id} |
Delete conversation |
POST |
/api/projects/{slug}/discover/conversations/{id}/messages |
Send a message (triggers AI response) |
POST |
/api/projects/{slug}/discover/conversations/{id}/actions/{actionId} |
Confirm/reject a pending action |
Work queue endpoints
| Method |
Path |
Description |
GET |
/api/projects/{slug}/discover/queues |
List work queues |
GET |
/api/projects/{slug}/discover/queues/{id} |
Get queue with items |
PUT |
/api/projects/{slug}/discover/queues/{id} |
Update queue name/description |
DELETE |
/api/projects/{slug}/discover/queues/{id} |
Delete queue |
POST |
/api/projects/{slug}/discover/queues/{id}/start |
Start sequential execution |
POST |
/api/projects/{slug}/discover/queues/{id}/cancel |
Cancel queue execution |
POST |
/api/projects/{slug}/discover/queues/{id}/release |
Reset queue to pending |
GitHub App endpoints
| Method |
Path |
Description |
POST |
/api/github/app/manifest |
Generate GitHub App manifest + redirect URL |
GET |
/api/github/app/callback |
Exchange manifest code for App credentials (public) |
GET |
/api/github/app/setup |
Post-installation redirect (public) |
GET |
/api/github/app/status |
Connection health check |
GET |
/api/github/app/repos |
List installation repositories |
POST |
/api/github/app/repos |
Create a new repository via App |
POST |
/api/github/detect-remote |
Auto-detect GitHub owner/repo from git remote |
GET |
/api/github/webhooks/events |
List recent webhook events |
POST |
/api/projects/{slug}/github/link |
Link project to GitHub repo |
POST |
/api/projects/{slug}/github/unlink |
Remove GitHub link |
Settings endpoints
| Method |
Path |
Description |
GET |
/api/settings |
Get all settings |
PUT |
/api/settings |
Update settings |
GET |
/api/settings/defaults |
Get default values |
GET |
/api/settings/env |
List environment variables |
PUT |
/api/settings/env |
Update environment variables |
POST |
/api/settings/restart |
Restart the service |
Profile endpoints
| Method |
Path |
Description |
GET |
/api/auth/me |
Get current user info |
PUT |
/api/me/profile |
Update display name |
PUT |
/api/me/git-identity |
Update git name and email |
GET |
/api/me/ssh-key |
Get SSH public key |
POST |
/api/me/ssh-key |
Generate new SSH keypair |
User management endpoints (admin only)
| Method |
Path |
Description |
GET |
/api/users |
List all users |
POST |
/api/users |
Invite a user |
PATCH |
/api/users/{id}/role |
Update user role |
DELETE |
/api/users/{id} |
Remove a user |
SSE (Server-Sent Events)
| Method |
Path |
Description |
GET |
/api/events?channel={channel} |
Real-time event stream |
Channels
Subscribe to specific channels via the channel query parameter (can be repeated). Omit to receive all events (*).
| Channel pattern |
Events |
ticket:{ticketID} |
Agent activity, comments, status changes for a specific ticket |
project:{projectID} |
Ticket updates, PR creation, queue changes for a project |
* |
All events |
Event types
| Event |
Description |
agent:started |
Agent session began |
agent:stopped |
Agent session ended (with status and summary) |
agent:text_delta |
Streaming text from agent |
agent:thinking_delta |
Streaming reasoning/thinking from agent |
agent:tool_call |
Tool invocation (tool name + arguments) |
agent:tool_result |
Tool execution result |
agent:error |
Agent error |
agent:user_message |
User sent a message to running agent |
comment:created |
New comment posted on a ticket |
ticket:updated |
Ticket state change |
pr:created |
Pull request created for a ticket |
github:webhook |
GitHub webhook received (check_run, review, etc.) |
discover:message |
Discovery conversation message |
discover:tool_call |
Discovery agent tool call |
discover:delta |
Discovery agent streaming text |
queue:started |
Work queue execution started |
queue:advanced |
Work queue advanced to next ticket |
queue:completed |
Work queue completed all tickets |
queue:paused |
Work queue paused (agent failure) |
feedback:started |
Feedback loop triggered agent session |