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.