API Reference
REST API for Supaspec. All endpoints accept and return JSON.
Authentication
Authenticate via session cookie (browser) or API key header:
X-Api-Key: ss_your_api_key_here
Projects
| GET | /api/projects | List all accessible projects |
| POST | /api/projects | Create a new project (name, description) |
| GET | /api/projects/:id | Get project details |
| PATCH | /api/projects/:id | Update project metadata |
| DELETE | /api/projects/:id | Delete project and all contents |
Sections
| GET | /api/projects/:id/sections | List all sections in a project |
| POST | /api/projects/:id/sections | Create a new section |
| GET | /api/sections/:id | Get section with full content |
| PATCH | /api/sections/:id | Update content (mode: "commit" or "propose") |
| DELETE | /api/sections/:id | Delete a section |
| PATCH | /api/sections/:id/status | Change section status |
| PATCH | /api/projects/:id/sections/reorder | Reorder sections |
Versions
| GET | /api/sections/:id/versions | List all versions of a section |
| GET | /api/sections/:id/versions/:n | Get a specific version |
| GET | /api/sections/:id/diff?from=N&to=M | Compare two versions (unified diff) |
| POST | /api/sections/:id/restore | Restore to a previous version |
| GET | /api/projects/:id/activity | Project-wide revision history |
Proposals
| GET | /api/projects/:id/proposals | List all proposals in a project |
| GET | /api/proposals/:id | Get proposal with changes and comments |
| POST | /api/proposals/:id/accept | Accept a proposal (applies changes) |
| POST | /api/proposals/:id/reject | Reject a proposal |
| POST | /api/proposals/:id/close | Close a proposal without applying |
| POST | /api/proposals/:id/comments | Add a comment to a proposal |
| POST | /api/proposals/:id/revisions | Push a new revision to a proposal |
Agents & Keys
| GET | /api/projects/:id/agents | List all agents for a project |
| POST | /api/user/api-key | Generate a new API key |
| DELETE | /api/user/api-key | Revoke current API key |
Assets
| GET | /api/projects/:id/assets | List all project assets |
| POST | /api/projects/:id/assets | Upload an asset (max 500KB) |
| GET | /api/assets/:id | Get asset metadata |
| GET | /api/assets/:id/download | Download asset file |
| DELETE | /api/assets/:id | Delete an asset |
Secrets
| GET | /api/projects/:id/secrets | List all secrets (values masked) |
| POST | /api/projects/:id/secrets | Create or update a secret |
| GET | /api/secrets/:id | Get secret with revealed value |
| DELETE | /api/secrets/:id | Delete a secret |
| GET | /api/projects/:id/secrets/env | Export all secrets as .env format |