Surreel API reference
Authentication and requests
These endpoints support the web application using JSON and session cookies. They
are not a standalone bearer-authenticated inference API. Use the application
origin and the /api/v1/ prefix. HTTPS is required in production.
Fetch CSRF before signing in, send X-CSRFToken on mutations, and refresh it after
session rotation. Most endpoints require an active authenticated user. Signing in
does not grant access to other organisations or projects.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/auth/csrf/ |
Obtain CSRF protection for browser requests. |
| POST | /api/v1/auth/login/ |
Sign in with email and password. An enrolled account must complete the MFA challenge. |
| POST | /api/v1/auth/mfa/challenge/ |
Complete sign-in using the challenge and a TOTP or recovery code. |
| GET | /api/v1/auth/me/ |
Read the current user's profile. |
| POST | /api/v1/auth/logout/ |
End the current session. |
| POST | /api/v1/auth/password/change/ |
Change the authenticated user's password. |
| POST | /api/v1/auth/password/reset/ |
Request password recovery. The response does not disclose whether an account exists. |
| POST | /api/v1/auth/password/reset/confirm/ |
Complete password recovery with the single-use recovery credential. |
| POST | /api/v1/auth/invitations/accept/ |
Redeem an invitation; an existing account must authenticate with its password. |
Keep recovery credentials and session cookies private. Never include them in support requests.
Organisations and projects
GET /api/v1/organisations/ lists organisations where the caller has an active membership.
POST /api/v1/organisations/ creates an organisation and its owner membership.
The following paths are relative to
/api/v1/organisations/{organisation_uuid}/. Replace identifiers with UUIDs
returned by the application. Organisation membership, role capabilities and
project access are checked independently on every request.
| Method | Path | Purpose |
|---|---|---|
| GET | projects/ |
List accessible projects. |
| POST | projects/ |
Create a project with a name and optional description. |
| GET | projects/{project_uuid}/ |
Read an accessible project. |
| GET | memberships/ |
Read memberships permitted by the caller's role. |
| GET | roles/ |
Read roles permitted by the caller's capabilities. |
| GET | invitations/ |
Read invitations within the caller's invitation scope. |
| POST | invitations/ |
Invite an email address using a role from the same organisation. |
Invitations cannot grant capabilities the inviter does not possess. A missing or
inaccessible organisation or project returns 404; a missing capability returns
403. Identifiers alone do not grant access.
Errors
| Status | Meaning |
|---|---|
| 400 | Invalid input. |
| 403 | Authentication, CSRF or capability check failed. |
| 404 | Resource is missing or inaccessible. |
| 429 | Rate limit reached; respect the Retry-After response header. |
| 503 | A required dependency is unavailable. |
This reference covers session and organisation APIs only. It does not promise public SDKs, OAuth sign-in, or bearer-authenticated model invocation.