API Reference

REST API documentation for the Riptide Application Manager. The API runs on port 11402 by default.

Live source of truth. This reference is hand-maintained and is intended to cover the most commonly-integrated endpoints with worked request/response examples. The canonical and always-current list of every endpoint, parameter, and response shape is the Swagger / OpenAPI document the API itself exposes at /swagger in the Development environment (Swagger is not served in Production for surface reduction). Endpoints documented here include the trial-user, session, role, configuration, audit-log, dashboard, application, identity-provider, and integration-related routes, plus the 2.0 agent identity, LLM gateway, and cost-governance surfaces (see the sections at the end of this document); the API also exposes auth (/api/auth/login, /api/auth/logout, /api/auth/refresh), security inventory (/api/security/reports), attestation key management (/api/attestation/keys), cloud events, synthetic principals, application self-registration, and other operational endpoints — see Swagger for the full surface and contracts.

Authentication

Most API requests authenticate with an API key passed in the X-Api-Key header:

curl -X GET https://<your-am-host>/api/trial-users \
  -H "X-Api-Key: rtk_your-api-key"

The interactive auth flow used by SDK applications is different — clients call POST /api/auth/login with credentials and receive a session token returned in the response body and as an HttpOnly cookie; subsequent calls include the cookie or pass the token explicitly. POST /api/auth/refresh extends an existing session without forcing a re-login, and POST /api/auth/logout invalidates it.

API keys are issued through the Application Manager Web UI. Each key is prefixed with rtk_ and can be scoped and revoked independently. Configure the service-account key in your application settings under Api:ApiKey or via the RIPTIDE_API_KEY environment variable.

Error Responses

The API uses RFC 7807 Problem Details for error responses:

{
  "type": "https://tools.ietf.org/html/rfc7807#section-3.1",
  "title": "Not Found",
  "status": 404,
  "detail": "Trial user with ID 42 was not found.",
  "traceId": "00-abc123..."
}

Health & Status

GET /health

System health check. No authentication required.

curl http://localhost:11402/health

{
  "status": "healthy",
  "timestamp": "2026-03-11T10:00:00Z",
  "service": "riptide-application-manager-api",
  "version": "1.0.0"
}

GET /api/dashboard/metrics

Dashboard metrics with trend data.

{
  "activeTrialUsers": 24,
  "totalApplications": 5,
  "activeSessions": 12,
  "trends": { }
}

GET /api/dashboard/health

Detailed system health status including database connectivity and service availability.

Trial Users

Manage trial user registration and lifecycle.

GET /api/trial-users

List trial users with optional filtering.

Query Parameters:

Response: 200 OK

[
  {
    "id": 1,
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "isActive": true,
    "emailVerified": true,
    "trialStartDate": "2026-03-01T00:00:00Z",
    "trialEndDate": "2026-03-08T00:00:00Z",
    "createdAt": "2026-03-01T10:30:00Z"
  }
]

GET /api/trial-users/

Get a single trial user by ID.

Response: 200 OK — trial user object (same shape as list items)

Error: 404 Not Found — user does not exist

GET /api/trial-users/by-email/

Look up a trial user by email address.

Response: 200 OK — trial user object

Error: 404 Not Found — no user with that email

POST /api/trial-users

Create a new trial user.

Request Body:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "organization": "Example Corp"
}

Response: 201 Created — created trial user object

Errors:

• 400 Bad Request — validation failure
• 409 Conflict — email already registered

PATCH /api/trial-users/

Update trial user fields.

Request Body:

{
  "firstName": "Janet",
  "isActive": false
}

Response: 200 OK — updated trial user object

DELETE /api/trial-users/

Delete a trial user.

Response: 204 No Content

Sessions

Track and manage user sessions.

GET /api/sessions

List sessions with optional filtering.

Query Parameters:

Response: 200 OK

[
  {
    "id": 1,
    "trialUserId": 1,
    "ipAddress": "192.168.1.100",
    "startedAt": "2026-03-11T09:00:00Z",
    "lastActivityAt": "2026-03-11T10:15:00Z",
    "isActive": true
  }
]

GET /api/sessions/

Get a single session by ID.

POST /api/sessions

Create a new session.

Request Body:

{
  "trialUserId": 1,
  "ipAddress": "192.168.1.100"
}

Response: 201 Created

DELETE /api/sessions/

Terminate a session (logout).

Response: 204 No Content

Roles

Manage roles and capability assignments.

GET /api/roles

List roles with optional application filtering.

Query Parameters:

Response: 200 OK

[
  {
    "id": 1,
    "name": "Reviewer",
    "description": "Can view and approve permits",
    "applicationId": 3,
    "capabilities": ["permits:view", "permits:approve"]
  }
]

GET /api/roles/

Get a single role by ID.

POST /api/roles

Create a new role.

Request Body:

{
  "name": "Reviewer",
  "description": "Can view and approve permits",
  "applicationId": 3,
  "capabilities": ["permits:view", "permits:approve"]
}

Response: 201 Created

PATCH /api/roles/

Update a role's name, description, or capabilities.

DELETE /api/roles/

Delete a role.

Response: 204 No Content

Configuration

Manage application configuration files with version control.

GET /api/configuration/

Get a file node by ID (metadata and content).

GET /api/configuration/tree

Get the configuration file tree for an application.

Query Parameters:

Response: 200 OK — hierarchical file/folder structure

GET /api/configuration/

Get the version history for a configuration file.

Response: 200 OK

[
  {
    "version": 3,
    "content": "{ ... }",
    "createdAt": "2026-03-11T10:00:00Z",
    "createdBy": "admin"
  },
  {
    "version": 2,
    "content": "{ ... }",
    "createdAt": "2026-03-10T14:30:00Z",
    "createdBy": "admin"
  }
]

POST /api/configuration

Create a new file or folder in the configuration tree.

Request Body:

{
  "applicationId": 3,
  "parentId": null,
  "name": "appsettings.json",
  "type": "file",
  "content": "{ \"key\": \"value\" }"
}

Response: 201 Created

PUT /api/configuration/

Update a file's content. Automatically creates a new version.

Request Body:

{
  "content": "{ \"key\": \"updated-value\" }"
}

Response: 200 OK

POST /api/configuration/

Roll back a file to a specific version number.

Response: 200 OK — the restored file content

Audit Logs

Query the system audit trail.

GET /api/audit-logs

List audit log entries with filtering.

Query Parameters:

Response: 200 OK — paginated audit log entries

GET /api/audit-logs/

Get a single audit log entry with full detail.

Agent Identity

Manage AI-agent principals, their credentials, public keys, and delegation grants. Agents are tenant-scoped: a tenant-scoped API key may only operate on agents in its own tenant, while a service-account (system) key may operate across tenants. See use cases UC-025 through UC-027 for end-to-end flows.

Example — register an agent:

curl -X POST https://<your-am-host>/api/agents \
  -H "X-Api-Key: rtk_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-summarizer",
    "ownerUserId": "user-123",
    "scopeCeiling": ["llm:complete", "llm:embed"],
    "maxCredentialTtlSeconds": 900,
    "allowedTaskTypes": ["summarization"],
    "defaultTaskType": "summarization"
  }'

Agent Plans (Budget Lifecycle)

Per-agent spend "plans" meter and cap LLM usage. Routed under a specific agent. See UC-033.

LLM Gateway

The data plane that routes agent/application LLM traffic to the configured provider, metered against budgets. Authenticated by the gateway policy (Llm:Gateway:Auth — API key and/or agent bearer; see the Configuration Reference). See UC-030.

Compatibility passthrough

Drop-in compatible endpoints so existing OpenAI/Anthropic SDKs can target the gateway by changing only the base URL. See UC-031.

Cost Governance

Budget caps, spend reservation/reconciliation, provider subscriptions, and usage insights. Tenant-scoped callers see their own tenant; system callers see all. See use cases UC-032, UC-034–UC-038.

Budgets (/api/budgets)

Spend (/api/spend)

Subscriptions (/api/subscriptions)

Insights (/api/insights)