docs
v0.7.12
Docs Reference API Overview

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

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 + CI checks + review state
POST /api/projects/{slug}/tickets/{number}/pull-request/merge Merge PR

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

User 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

Method Path Description
GET /api/events Server-Sent Events stream for real-time updates

The SSE stream delivers events for agent activity, ticket updates, PR status changes, and feedback loop triggers.