REST API reference

About 725 wordsAbout 2 min

Spora exposes a JSON REST API at /api/v1/. Most routes require a session cookie (PHPSESSID) and a X-CSRF-Token header (the value of data.csrf_token returned by GET /api/v1/auth/me). The unauthenticated exceptions are the pre-auth flows (/auth/login, /auth/register, /auth/forgot-password, /auth/reset-password, /auth/email/confirm, /auth/verify/{selector}, /auth/verification/resend) and GET /health. The plugin install endpoints additionally require admin (currentUser.isAdmin = true).

For the canonical, comprehensive reference, see Concepts → Error handling (envelope shape, error code registry, severity mapping) and the per-endpoint docs in Operations → Day-2 ops (plugin install API in detail).

Endpoint summary

The API surface splits into three areas: auth, agents, and tools/plugins. Auth and agents cover the most-used paths. Plugins have a separate write API gated by SPORA_PLUGIN_INSTALL_ENABLED.

Auth

MethodPathAuthPurpose
POST/api/v1/auth/login—Authenticate (issues data.csrf_token)
POST/api/v1/auth/logout+ CSRFEnd session
GET/api/v1/auth/me+ CSRFCurrent user (returns data.csrf_token)
POST/api/v1/auth/register—Create account (gated by SPORA_ALLOW_REGISTRATION)
POST/api/v1/auth/forgot-password—Start password reset flow
POST/api/v1/auth/reset-password—Complete password reset
PATCH/api/v1/auth/password+ CSRFChange current user’s password
PATCH/api/v1/auth/account+ CSRFChange current user’s account name / email
POST/api/v1/auth/email/change-request+ CSRFRequest an email change (triggers confirmation)
POST/api/v1/auth/email/confirm—Confirm an email change (verifies the new address)
GET/api/v1/auth/verify/{selector}—Verify initial signup email (link in the welcome)
POST/api/v1/auth/verification/resend—Resend the initial signup verification email

Agents

MethodPathAuthPurpose
GET/api/v1/agentssessionList agents
POST/api/v1/agents+ CSRFCreate agent
GET/api/v1/agents/{id}sessionGet one agent
PATCH/api/v1/agents/{id}+ CSRFUpdate agent
DELETE/api/v1/agents/{id}+ CSRFDelete agent

To send a message to an agent, create a task via POST /api/v1/tasks — there’s no /chat sub-resource. The agent picks up the task and processes it asynchronously.

Tasks

MethodPathAuthPurpose
GET/api/v1/taskssessionList tasks
POST/api/v1/tasks+ CSRFCreate a task (use this to send a message to an agent)
GET/api/v1/tasks/{taskId}sessionGet one task (includes history)
POST/api/v1/tasks/{taskId}/approve+ CSRFApprove a pending tool call
POST/api/v1/tasks/{taskId}/reject+ CSRFReject a pending tool call
POST/api/v1/tasks/{taskId}/retry+ CSRFRetry a failed task
POST/api/v1/tasks/{taskId}/continue+ CSRFContinue a completed/failed task
DELETE/api/v1/tasks/{taskId}/retry-chain+ CSRFCancel a scheduled retry chain
DELETE/api/v1/tasks/{taskId}+ CSRFDelete a task (and cancel if in flight)

Plugins (operator, gated by SPORA_PLUGIN_INSTALL_ENABLED)

MethodPathAuthPurpose
GET/api/v1/pluginssessionList installed plugins
POST/api/v1/pluginsadmin + CSRFInstall (full envelope: error codes, status)
DELETE/api/v1/plugins/{package}admin + CSRFUninstall
PATCH/api/v1/plugins/{package}admin + CSRFUpdate to latest matching constraint

Full envelope, error codes, and per-endpoint contract: Install API. Implementation: app/Http/PluginsController.php.

Notifications, recipes, LLM drivers, tools, users

See Concepts → Architecture for the full HTTP surface. The Vue admin UI consumes these endpoints; the same X-CSRF-Token middleware protects all state-changing routes.

Envelope

Success:

{ "data": { ... } }

Error:

{
  "error": {
    "code": "MACHINE_CODE",
    "message": "Human-readable description."
  }
}

Rate-limited responses carry Retry-After as an HTTP header. For the full error code registry (codes, HTTP statuses, severities, mapping to UI), see Concepts → Error handling.

Auth stack

  • AuthMiddleware — validates the PHPSESSID cookie, populates $currentUser for the request. Applied to all routes that need a session.
  • CsrfMiddleware — validates X-CSRF-Token against $_SESSION['csrf_token']. Applied to all state-changing (POST/PUT/PATCH/DELETE) routes.
  • AdminMiddleware — additionally requires currentUser.isAdmin = true. Applied to plugin install, user management.

The public plugin install endpoints follow this same stack: [AuthMiddleware, CsrfMiddleware, AdminMiddleware]. When SPORA_PLUGIN_INSTALL_ENABLED=false, the same routes return 403 FEATURE_DISABLED.

Health endpoint

GET /health is the unauthenticated health check used by Docker’s healthcheck directive and load balancers. Returns 200 OK if the app is up, regardless of DB state. Returns 503 NOT_CONFIGURED if the Mercure subsystem is configured but unreachable.

Versioning

The API is mounted at /api/v1/. Breaking changes require a version bump (e.g. /api/v2/). Additions within v1 are non-breaking and don’t require a version bump — new endpoints, new optional fields, new error codes.

What’s next