Trident

Agents API

Trident Web exposes authenticated endpoints under /api/agents for working with agent sessions and checkpoints.

Authentication

Endpoints use Clerk auth. The backend resolves organizationId from orgId (preferred) or userId.

GET /api/agents/sessions

List agent sessions for the current organization.

Query params

  • page (number, default 1)
  • limit (number, default 50, max 200)
  • status (enum: active, paused, completed, failed, expired)
  • agentType (string)

Response

{
  "data": [
    {
      "id": "...",
      "agentType": "serp-analysis",
      "status": "completed",
      "createdAt": "...",
      "updatedAt": "...",
      "expiresAt": "...",
      "lastCheckpointId": "...",
      "_count": { "checkpoints": 3 }
    }
  ],
  "pagination": { "page": 1, "limit": 50, "offset": 0, "total": 10, "hasMore": false }
}

GET /api/agents/sessions/:sessionId

Fetch a session (scoped to the current organization) and its checkpoints.

DELETE /api/agents/sessions/:sessionId

Delete a session and all checkpoints (cascade).

POST /api/agents/sessions/:sessionId/resume

Enqueue a background job to resume a session. The endpoint validates the session is still resumable (active/paused and not expired).

// 202 Accepted
{ "success": true, "jobId": "..." }