Sessions API

Endpoints for listing sessions, inspecting stored images, and streaming tool execution logs tied to a session.

Overview

Every image generation or edit is associated with a sessionId. Sessions let you group related operations (for example, an iterative editing workflow) and later fetch the images or execution logs for that session.

Query sessions, get details, stream execution logs

List Sessions

Retrieve sessions for the current tenant.

GET /api/sessions

Query Parameters

Parameter	Type	Default	Description
limit	integer	20	Items per page (max: 100)
offset	integer	0	Pagination offset

Request

curl -X GET "https://gobananasai.com/api/sessions?limit=10&offset=0" \
  -H "X-API-Key: sk_live_xxx"

Response

{
  "data": [
    {
      "sessionId": "sess_abc123",
      "isActive": true,
      "createdAt": "2024-01-15T09:00:00.000Z",
      "lastActivityAt": "2024-01-15T10:30:00.000Z",
      "totalImages": 15,
      "totalEdits": 8,
      "totalBytes": 15728640,
      "totalMegabytes": 15.0,
      "totalTokens": 32100
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 10,
    "offset": 0
  }
}

Get Session Details

Fetch a session record plus all images in that session.

GET /api/sessions/:sessionId

Request

curl -X GET "https://gobananasai.com/api/sessions/sess_abc123" \
  -H "X-API-Key: sk_live_xxx"

Response

session is the raw row from the sessions table (snake_case keys). images are normalized to camelCase plus URLs.

{
  "data": {
    "session": {
      "session_id": "sess_abc123",
      "tenant_id": "acme-corp",
      "is_active": 1,
      "created_at": "2024-01-15T09:00:00.000Z",
      "last_activity_at": "2024-01-15T10:30:00.000Z"
    },
    "images": [
      {
        "id": 42,
        "sessionId": "sess_abc123",
        "prompt": "A sunset with dramatic clouds",
        "negativePrompt": null,
        "aspectRatio": "landscape",
        "operation": "edit",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "sizeBytes": 524288,
        "thumbnailSizeBytes": 65536,
        "r2Key": "acme-corp/2024-01-15/edit-a1b2c3d4.png",
        "r2ThumbnailKey": "acme-corp/2024-01-15/edit-a1b2c3d4-thumb.jpg",
        "fullUrl": "https://pub-xxx.r2.dev/...",
        "thumbnailUrl": "https://pub-xxx.r2.dev/..."
      }
    ]
  }
}

Session Logs (REST)

Get tool execution history for a session.

GET /api/sessions/:sessionId/logs

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Max executions to return

Response

This endpoint is legacy and includes a top‑level success flag.

{
  "success": true,
  "sessionId": "sess_abc123",
  "executions": [
    {
      "executionId": "exec_01H...",
      "sessionId": "sess_abc123",
      "toolName": "generate_image",
      "toolSource": "tenant_api",
      "status": "completed",
      "progressPercent": 100,
      "startedAt": "2024-01-15T10:20:00.000Z",
      "completedAt": "2024-01-15T10:21:10.000Z",
      "durationMs": 70123,
      "resultSummary": "1 image generated"
    }
  ],
  "total": 1
}

Session Logs (SSE)

Stream real‑time logs for all active executions in a session.

GET /api/sessions/:sessionId/logs/stream

Query Parameters

Parameter	Type	Default	Description
interval	integer	1000	Poll interval in ms

The response is an SSE stream with events: log, status, complete, error, and periodic heartbeat.

Execution Logs

Execution logs are also addressable directly.

List Active Executions

GET /api/executions/active

Response (legacy envelope):

{
  "success": true,
  "executions": [
    {
      "executionId": "exec_01H...",
      "sessionId": "sess_abc123",
      "toolName": "edit_image",
      "status": "running",
      "progressPercent": 40,
      "currentStep": "uploading"
    }
  ],
  "total": 1
}

Get Execution Details

GET /api/executions/:executionId

{
  "success": true,
  "execution": {
    "executionId": "exec_01H...",
    "sessionId": "sess_abc123",
    "toolName": "generate_image",
    "status": "completed",
    "logEntries": [
      { "timestamp": "2024-01-15T10:20:10.000Z", "message": "Starting generation..." }
    ]
  }
}

Stream Execution Logs

GET /api/executions/:executionId/stream

Returns an SSE stream for a single execution (same event types as session stream).

Error Responses

404 Session Not Found

{ "error": "Session not found" }

401 Unauthorized

{ "error": "Invalid or missing API key" }

Next Steps

• Images API →
• Error Codes →