Ze Harness API

Typed HTTP API for durable agent Sessions and Turns.

66 operations. The full OpenAPI 3.1.0 document is at /openapi.json.

Authentication: operations marked with security use bearer (http Bearer).

System

GET /v1/health

Health check. Reports whether the HTTP service is available.

Operation ID: health

Response 200 (application/json):

{ status: "ok" }

Errors: 400 ValidationErrorEncoded, 403 ForbiddenErrorEncoded, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/capabilities

Host capabilities. Reports the feature flags this host supports.

Operation ID: capabilities

Response 200 (application/json):

{
  backgroundSubagents: boolean;
  protocolVersion?: number;
  harnessVersion?: string;
}

Errors: 400 ValidationErrorEncoded, 403 ForbiddenErrorEncoded, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/logs

Read daemon logs. Reads a bounded, newest-first page of structured daemon log entries. Hosts without a log store report unavailable.

Operation ID: logs

Response 200 (application/json):

{
  entries: {
    timestamp: string;
    level: "debug" | "info" | "warn" | "error";
    run: string;
    service: string;
    event: string;
    fields: Record<string, string>;
  }[];
  truncated: boolean;
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

Sessions

Durable Session and Turn operations.

GET /v1/servers/{server}/sessions/{sessionId}

Get a Session. Returns current Session metadata.

Operation ID: getSession

Response 200 (application/json):

{
  session: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

PUT /v1/servers/{server}/sessions/{sessionId}

Create a Session. Creates a Session with caller-selected identity.

Operation ID: createSession

Request body (application/json):

{
  defaultModel?: string;
  systemPrompt?: string;
  workdir?: string; // max length 1024
  clientWorkdir?: string; // max length 1024
  permissions?: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
  approval?: {
    timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
  };
}

Response 200 (application/json):

{
  session: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

DELETE /v1/servers/{server}/sessions/{sessionId}

Delete a Session. Cancels the Session work, finalizes its private state, and deletes its public history. The exact replay is idempotent and the deleted identity stays retired.

Operation ID: deleteSession

Request body (application/json):

null | { reason?: string }

Response 200 (application/json):

{ deleted: { sessionId: string /* uuid */ } }

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

PUT /v1/servers/{server}/sessions/{sessionId}/title

Set a Session title. Sets the Session display title. The same title is a no-op.

Operation ID: setSessionTitle

Request body (application/json):

{ title: string /* max length 100 */ }

Response 200 (application/json):

{
  session: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

PUT /v1/servers/{server}/sessions/{sessionId}/default-model

Set a Session default model. Sets the Session default model for later Turns. The same model is a no-op.

Operation ID: setSessionDefaultModel

Request body (application/json):

{ defaultModel: string }

Response 200 (application/json):

{
  session: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions

List Sessions. Returns one server’s Sessions, oldest first, optionally filtered by project.

Operation ID: listSessions

Response 200 (application/json):

{
  sessions: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/events

Watch a server. Streams every Session creation, title, deletion, and Turn update on one server, without the live text deltas. Without afterServerCursor the stream starts live from the current cursor and announces it with its first server.cursor; with one it replays every stamped row after that cursor. A caught-up stream repeats its current server.cursor at least every 15 seconds, so a longer silence means the connection is gone.

Operation ID: watchServer

Response 200: no body.

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

DELETE /v1/servers/{server}

Delete a server. Cancels and deletes Sessions on one server, optionally filtered by project. Workspace files stay.

Operation ID: deleteServer

Response 200 (application/json):

{ deleted: { server: string /* max length 128 */; sessionIds: string[] } }

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/children

List Session children. Returns the Sessions spawned directly from one parent, oldest first.

Operation ID: listSessionChildren

Response 200 (application/json):

{
  sessions: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/background

Detach Session sub-agents. Detaches running foreground sub-agent chains to the background. Their results arrive as queued turns.

Operation ID: promoteSessionBackground

Response 200 (application/json):

{ promoted: boolean }

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/configuration

Get Session configuration. Returns the versioned Session permission and approval configuration.

Operation ID: getSessionConfiguration

Response 200 (application/json):

{
  configuration: {
    revision: number; // min 1
    permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
    approval: {
      timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
    };
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

PUT /v1/servers/{server}/sessions/{sessionId}/configuration

Replace Session configuration. Replaces the ordered Session rules when the expected revision is current.

Operation ID: replaceSessionConfiguration

Request body (application/json):

{
  expectedRevision: number; // min 1
  permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
  approval: {
    timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
  };
}

Response 200 (application/json):

{
  configuration: {
    revision: number; // min 1
    permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
    approval: {
      timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
    };
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/permissions/saved

List saved permissions. Returns durable Session-scoped allow grants.

Operation ID: listSavedPermissions

Response 200 (application/json):

{
  permissions: {
    id: string; // uuid
    sessionId: string; // uuid
    action: string;
    resource: string;
    createdAt: number;
    sourcePermissionRequestId: string; // uuid
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

DELETE /v1/servers/{server}/sessions/{sessionId}/permissions/saved/{savedPermissionId}

Remove saved permission. Removes one durable Session-scoped allow grant.

Operation ID: removeSavedPermission

Response 200 (application/json):

{
  permission: {
    id: string; // uuid
    sessionId: string; // uuid
    action: string;
    resource: string;
    createdAt: number;
    sourcePermissionRequestId: string; // uuid
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/forks/{forkedSessionId}

Fork a Session. Copies settled history before an optional Turn into a new Session with caller-selected identity.

Operation ID: forkSession

Request body (application/json):

| null
  | {
    turnId?: string; // uuid
    through?:
      | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
      | { kind: "conversationEntry"; entryId: string /* uuid */ };
    visibility?: {
      floorHistoryRevision?: number;
      excludedTurnIds?: string[];
      excludedEntryIds?: string[];
    };
  }

Response 200 (application/json):

{
  session: {
    id: string; // uuid
    defaultModel?: string;
    systemPrompt?: string;
    title?: string; // max length 100
    workdir: string; // max length 1024
    projectId: string; // max length 128
    forkedFrom?: {
      parentSessionId: string; // uuid
      turnId?: string; // uuid
      through?:
        | { kind: "turnMessage"; turnId: string /* uuid */; messageIndex: number }
        | { kind: "conversationEntry"; entryId: string /* uuid */ };
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    spawnedFrom?: { parentSessionId: string /* uuid */ };
    agent?: string; // max length 128
    configuration: {
      revision: number; // min 1
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      approval: {
        timeoutMs?: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
    };
    createdAt: number;
    updatedAt: number;
    nextSequence: number; // min 1
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/skills

List Session Skills. Returns safe metadata for the effective host and Session Skill catalog.

Operation ID: sessionSkills

Response 200 (application/json):

{
  sessionId: string; // uuid
  skills: {
    id: string; // max length 128
    displayName: string;
    description: string;
    advertised: boolean;
    userInvocable: boolean;
    origin: "host" | "session";
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/turns

List Session Turns. Reads a bounded, stable Session history page.

Operation ID: listSessionTurns

Response 200 (application/json):

{
  sessionId: string; // uuid
  boundary: { throughSequence: number; activityCursor: number };
  turns: {
    activityCursor: number;
    workSequence: number; // min 1
    turn: {
      id: string; // uuid
      sessionId: string; // uuid
      sequence: number; // min 1
      request: {
        sessionId: string; // uuid
        turnId: string; // uuid
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
        model?: string;
        agent?: string; // max length 128
        skills?: string[]; // at least 1
        reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
        visibility?: {
          floorHistoryRevision?: number;
          excludedTurnIds?: string[];
          excludedEntryIds?: string[];
        };
      };
      attribution?: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
      model: string;
      modelLeaseId: string; // max length 68
      requestOptionsId: string; // uuid
      policy: {
        version: 4;
        permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
        permissionMatching: { caseSensitive: boolean };
        approval: {
          timeoutMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
        timeouts: {
          turnMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
        steering: {
          maxBatches:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number;
              origin: "configured" | "provider" | "platform";
            };
        };
        subagents: {
          maxDepth:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number;
              origin: "configured" | "provider" | "platform";
            };
        };
        provider: {
          maxAttempts:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          attemptTimeoutMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          elapsedMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          pacing:
            | { kind: "none" }
            | { kind: "fixed"; delayMs: number }
            | {
              kind: "exponential";
              initialDelayMs: number; // min 1
              maximumDelayMs: number; // min 1
              jitter: boolean;
            };
        };
        context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
        images: {
          maxBase64Bytes:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
      };
      steering: {
        gate: "open" | "closed";
        promotedBatchCount: number;
        steers: {
          sessionId: string; // uuid
          turnId: string; // uuid
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
          state:
            | { state: "accepted" }
            | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
            | {
              state: "undelivered";
              reason: "process_lost" | "turn_cancelled" | "turn_failed";
              undeliveredAt: number;
            };
        }[];
      };
      phase: "pending" | "running" | "completed" | "cancelled" | "failed";
      revision: number;
      parts: Array<
        | {
          type: "text";
          id: string; // uuid
          assistantMessageIndex: number;
          text: string;
        }
        | {
          type: "refusal";
          id: string; // uuid
          assistantMessageIndex: number;
          text: string;
        }
        | {
          type: "reasoning";
          id: string; // uuid
          assistantMessageIndex: number;
          text: string;
          startedAt?: number;
          completedAt?: number;
        }
        | {
          type: "tool";
          id: string; // uuid
          toolCallId: string;
          toolId: string;
          origin?:
            | { kind: "model" }
            | {
              kind: "codemode";
              parentToolCallId: string;
              ordinal: number; // min 1
              ownerPluginId?: string;
              binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
            };
          execution?: { result: unknown; logs: string[] };
          instructions?: Array<
            | {
              kind: "instruction";
              id: string; // max length 512
              revision: string; // max length 512
              order: number;
              role: "system" | "developer" | "user";
              content: string;
              afterToolCallId?: string;
            }
            | {
              kind: "skill";
              id: string; // max length 512
              revision: string; // max length 512
              order: number;
              reference: string; // max length 2048
              content: string;
            }
            | {
              kind: "plugin";
              id: string; // max length 512
              revision: string; // max length 512
              order: number;
              reference: string; // max length 2048
            }
          >;
          assistantMessageIndex: number;
          modelInput?: unknown;
          input: unknown;
          state: "requested" | "completed" | "failed" | "denied";
          output?: unknown;
          fault?: {
            code: string; // max length 128
            message: string; // max length 4096
            providerCode?: string; // max length 128
          };
          canonicalResult?:
            | {
              format: "content";
              // at least 1
              value: Array<
                | { type: "text"; text: string }
                | { type: "json"; value: unknown }
                | {
                  type: "image";
                  source:
                    | {
                      type: "url";
                      url: string;
                      mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                    }
                    | {
                      type: "base64";
                      data: string;
                      mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                    };
                }
              >;
            }
            | { format: "text"; value: string }
            | { format: "json"; value: unknown };
          approval:
            | { state: "none" }
            | {
              state: "pending";
              request: {
                id: string; // uuid
                sessionId: string; // uuid
                turnId: string; // uuid
                toolId: string;
                toolCallId: string;
                action: string;
                resources: string[]; // at least 1
                save?: string[];
                metadata?: unknown;
              };
              requestedAt: number;
            }
            | {
              state: "resolved";
              request: {
                id: string; // uuid
                sessionId: string; // uuid
                turnId: string; // uuid
                toolId: string;
                toolCallId: string;
                action: string;
                resources: string[]; // at least 1
                save?: string[];
                metadata?: unknown;
              };
              requestedAt: number;
              resolvedAt: number;
              decision: "allow" | "deny";
              source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
              reply?: "once" | "always" | "reject";
              replyMessage?: string; // max length 4096
            };
          question?:
            | {
              state: "pending";
              request: {
                id: string; // uuid
                sessionId: string; // uuid
                turnId: string; // uuid
                toolId: string;
                toolCallId: string;
                // at least 1
                questions: {
                  question: string; // max length 4096
                  header: string; // max length 30
                  // at least 1
                  options: {
                    label: string; // max length 256
                    description: string; // max length 4096
                  }[];
                  multiple?: boolean;
                  custom?: boolean;
                }[];
              };
              requestedAt: number;
            }
            | {
              state: "answered";
              request: {
                id: string; // uuid
                sessionId: string; // uuid
                turnId: string; // uuid
                toolId: string;
                toolCallId: string;
                // at least 1
                questions: {
                  question: string; // max length 4096
                  header: string; // max length 30
                  // at least 1
                  options: {
                    label: string; // max length 256
                    description: string; // max length 4096
                  }[];
                  multiple?: boolean;
                  custom?: boolean;
                }[];
              };
              requestedAt: number;
              resolvedAt: number;
              answers: string[][]; // at least 1
            }
            | {
              state: "dismissed";
              request: {
                id: string; // uuid
                sessionId: string; // uuid
                turnId: string; // uuid
                toolId: string;
                toolCallId: string;
                // at least 1
                questions: {
                  question: string; // max length 4096
                  header: string; // max length 30
                  // at least 1
                  options: {
                    label: string; // max length 256
                    description: string; // max length 4096
                  }[];
                  multiple?: boolean;
                  custom?: boolean;
                }[];
              };
              requestedAt: number;
              resolvedAt: number;
            };
          requestedAt: number;
          completedAt?: number;
          activity?: {
            checkpoint: number; // min 1
            updatedAt: number;
            message?: string; // max length 1024
            preview?: string;
            observedBytes: number;
            truncated: boolean;
            artifact?: {
              id: string; // uuid
              path: string;
              observedBytes: number;
              state: "writing" | "complete" | "incomplete";
            };
            childSessionId?: string; // uuid
          };
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
        }
        | {
          type: "steering";
          id: string; // uuid
          batch: number; // min 1
          promotedAt: number;
          steers: {
            steerId: string; // uuid
            sequence: number; // min 1
            // at least 1
            prompt: Array<
              | { type: "text"; text: string }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
              | { type: "content-reference"; reference: string /* max length 2048 */ }
            >;
            attribution: {
              clientId: string; // max length 256
              authorId?: string; // max length 256
            };
            acceptedAt: number;
          }[];
        }
      >;
      usage?: {
        promptTokens: number | "Infinity" | "-Infinity" | "NaN";
        completionTokens: number | "Infinity" | "-Infinity" | "NaN";
        totalTokens: number | "Infinity" | "-Infinity" | "NaN";
        cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
        reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
      };
      contextUse?: { model: string; usedUnits: number; contextUnits: number };
      cancellation?: { reason?: string; requestedAt: number };
      outcome?:
        | { kind: "completed"; turnId: string; text: string }
        | { kind: "cancelled"; turnId: string; reason?: string }
        | {
          kind: "failed";
          turnId: string;
          fault: {
            code: string; // max length 128
            message: string; // max length 4096
            providerCode?: string; // max length 128
          };
        }
        | {
          kind: "limit_reached";
          turnId: string;
          limit:
            | {
              name: "turn_elapsed";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "approval_wait";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "provider_elapsed";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "provider_attempt_timeout";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "steering_batches";
              origin: "configured" | "provider" | "platform";
              value: number;
              unit: "batches";
            }
            | {
              name: "provider_attempts";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "attempts";
            }
            | {
              name: "model_context";
              origin: "configured" | "provider" | "platform";
              value: number;
              unit: "model_units";
              estimatedInputUnits: number;
              outputReserveUnits: number;
              safetyReserveUnits: number;
              availableInputUnits: number;
              estimator: string; // max length 128
            };
          diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
        };
      acceptedAt: number;
      startedAt?: number;
      completedAt?: number;
    };
  }[];
  nextAfterSequence?: number;
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/journal

List Session plugin journal entries. Reads durable plugin-reported facts in record order, optionally for one Turn.

Operation ID: listPluginJournal

Response 200 (application/json):

{
  sessionId: string; // uuid
  entries: {
    sessionId: string; // uuid
    turnId: string; // uuid
    sequence: number; // min 1
    pluginId: string;
    kind: string;
    summary: string;
    data: unknown;
    logicalCallOrdinal?: number; // min 1
    toolCallId?: string;
    recordedAt: number;
  }[];
  next?: { turnSequence: number; sequence: number };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/events

Watch a Session. Streams observational Session updates after a durable cursor. A caught-up stream repeats its current session.cursor at least every 15 seconds, so a longer silence means the connection is gone.

Operation ID: watchSession

Response 200: no body.

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/prompts

Submit a prompt. Durably admits queued work or steering input.

Operation ID: submitPrompt

Request body (application/json):

| {
    delivery: "queue";
    turnId: string; // uuid
    // at least 1
    prompt: Array<
      | { type: "text"; text: string }
      | {
        type: "image";
        source:
          | {
            type: "url";
            url: string;
            mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
          }
          | {
            type: "base64";
            data: string;
            mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
          };
      }
      | { type: "content-reference"; reference: string /* max length 2048 */ }
    >;
    conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
    model?: string;
    agent?: string; // max length 128
    skills?: string[]; // at least 1
    reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    visibility?: {
      floorHistoryRevision?: number;
      excludedTurnIds?: string[];
      excludedEntryIds?: string[];
    };
    authorId?: string; // max length 256
    providerOptions?: unknown;
  }
  | {
    delivery: "steer";
    steerId: string; // uuid
    expectedTurnId: string; // uuid
    // at least 1
    prompt: Array<
      | { type: "text"; text: string }
      | {
        type: "image";
        source:
          | {
            type: "url";
            url: string;
            mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
          }
          | {
            type: "base64";
            data: string;
            mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
          };
      }
      | { type: "content-reference"; reference: string /* max length 2048 */ }
    >;
    authorId?: string; // max length 256
  }

Response 202 (application/json):

{
  receipt:
    | {
      delivery: "queue";
      sessionId: string; // uuid
      turnId: string; // uuid
      modelLeaseId: string; // max length 68
      requestOptionsId: string; // uuid
      sequence: number; // min 1
      acceptedAt: number;
      attribution?: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
    }
    | {
      delivery: "steer";
      sessionId: string; // uuid
      turnId: string; // uuid
      steerId: string; // uuid
      sequence: number; // min 1
      acceptedAt: number;
      attribution: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
    };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/conversation

Append a conversation entry. Appends a durable user message for later work without admitting a Turn or calling a model.

Operation ID: appendConversation

Request body (application/json):

{
  entryId: string; // uuid
  // at least 1
  content: Array<
    | { type: "text"; text: string }
    | { type: "content-reference"; reference: string /* max length 2048 */ }
  >;
  authorId?: string; // max length 256
}

Response 200 (application/json):

{
  receipt: {
    sessionId: string; // uuid
    entryId: string; // uuid
    historyRevision: number; // min 1
    acceptedAt: number;
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/mcp

Get the MCP catalog. Returns the effective host and Session MCP catalog without private metadata.

Operation ID: getMcpCatalog

Response 200 (application/json):

{
  catalog: {
    revision: number;
    servers: {
      origin: "host" | "session";
      serverId: string;
      name: string; // max length 128
      order: number;
      protocolVersion: string;
      capabilities: {
        tools: { supported: boolean; listChanged: boolean };
        resources: { supported: boolean; listChanged: boolean; subscribe: boolean };
        prompts: { supported: boolean; listChanged: boolean };
        logging: boolean;
        completions: boolean;
      };
      instructions?: string;
      catalog: {
        revision: number;
        tools: {
          name: string;
          title?: string;
          description?: string;
          inputSchema: unknown;
          outputSchema?: unknown;
          annotations?: {
            title?: string;
            readOnlyHint?: boolean;
            destructiveHint?: boolean;
            idempotentHint?: boolean;
            openWorldHint?: boolean;
          };
        }[];
        resources: {
          uri: string;
          name: string;
          title?: string;
          description?: string;
          mimeType?: string;
          annotations?: {
            audience?: ("user" | "assistant")[];
            priority?: number; // max 1
            lastModified?: string;
          };
          size?: number;
        }[];
        resourceTemplates: {
          uriTemplate: string;
          name: string;
          title?: string;
          description?: string;
          mimeType?: string;
          annotations?: {
            audience?: ("user" | "assistant")[];
            priority?: number; // max 1
            lastModified?: string;
          };
        }[];
        prompts: {
          name: string;
          title?: string;
          description?: string;
          arguments?: { name: string; title?: string; description?: string; required?: boolean }[];
        }[];
      };
    }[];
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/mcp/{serverName}/prompts/{promptName}

Submit an MCP prompt. Resolves an MCP prompt and durably admits it through the ordinary prompt path.

Operation ID: submitMcpPrompt

Request body (application/json):

{
  turnId: string; // uuid
  arguments?: Record<string, string>;
  model?: string;
  providerOptions?: unknown;
}

Response 202 (application/json):

{
  receipt:
    | {
      delivery: "queue";
      sessionId: string; // uuid
      turnId: string; // uuid
      modelLeaseId: string; // max length 68
      requestOptionsId: string; // uuid
      sequence: number; // min 1
      acceptedAt: number;
      attribution?: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
    }
    | {
      delivery: "steer";
      sessionId: string; // uuid
      turnId: string; // uuid
      steerId: string; // uuid
      sequence: number; // min 1
      acceptedAt: number;
      attribution: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
    };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/mcp/{serverName}/resources/read

Read an MCP resource. Reads one resource advertised by the effective leased MCP catalog.

Operation ID: readMcpResource

Request body (application/json):

{ uri: string }

Response 200 (application/json):

{
  resource: {
    contents: Array<
      | { uri: string; mimeType?: string; text: string }
      | { uri: string; mimeType?: string; blob: string }
    >;
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/compactions

List context compactions. Reads a bounded, stable page of durable Session compactions.

Operation ID: listSessionCompactions

Response 200 (application/json):

{
  sessionId: string; // uuid
  boundary: { throughSequence: number; throughOrdinal: number; activityCursor: number };
  compactions: {
    sequence: number; // min 1
    ordinal: number; // min 1
    compaction: {
      id: string; // uuid
      sessionId: string; // uuid
      sequence: number; // min 1
      request: {
        sessionId: string; // uuid
        compactionId: string; // uuid
        model?: string;
        visibility?: {
          floorHistoryRevision?: number;
          excludedTurnIds?: string[];
          excludedEntryIds?: string[];
        };
      };
      attribution?: {
        clientId: string; // max length 256
        authorId?: string; // max length 256
      };
      trigger:
        | { kind: "manual" }
        | { kind: "preflight"; turnId: string /* uuid */ }
        | { kind: "overflow"; turnId: string /* uuid */ };
      model: string;
      modelLeaseId: string; // max length 68
      requestOptionsId: string; // uuid
      policy: {
        version: 4;
        permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
        permissionMatching: { caseSensitive: boolean };
        approval: {
          timeoutMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
        timeouts: {
          turnMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
        steering: {
          maxBatches:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number;
              origin: "configured" | "provider" | "platform";
            };
        };
        subagents: {
          maxDepth:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number;
              origin: "configured" | "provider" | "platform";
            };
        };
        provider: {
          maxAttempts:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          attemptTimeoutMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          elapsedMs:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
          pacing:
            | { kind: "none" }
            | { kind: "fixed"; delayMs: number }
            | {
              kind: "exponential";
              initialDelayMs: number; // min 1
              maximumDelayMs: number; // min 1
              jitter: boolean;
            };
        };
        context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
        images: {
          maxBase64Bytes:
            | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
            | {
              kind: "finite";
              value: number; // min 1
              origin: "configured" | "provider" | "platform";
            };
        };
      };
      phase: "pending" | "running" | "completed" | "cancelled" | "failed";
      revision: number;
      cancellation?: { reason?: string; requestedAt: number };
      usage?: {
        promptTokens: number | "Infinity" | "-Infinity" | "NaN";
        completionTokens: number | "Infinity" | "-Infinity" | "NaN";
        totalTokens: number | "Infinity" | "-Infinity" | "NaN";
        cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
        reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
      };
      outcome?:
        | {
          kind: "completed";
          checkpoint: {
            id: string; // uuid
            compactionId: string; // uuid
            sessionId: string; // uuid
            throughHistoryRevision: number; // min 1
            throughChronologyRevision: number;
            sourceMessageCount: number; // min 1
            summary: {
              version: 1;
              overview: string; // max length 262144
              keyFacts: string[];
              decisions: string[];
              openTasks: string[];
            };
            chronology: {
              revision: number; // min 1
              historyRevision: number;
              boundaryOrder: number;
              change: "activated" | "updated" | "removed";
              source:
                | {
                  kind: "instruction";
                  id: string; // max length 512
                  revision: string; // max length 512
                  order: number;
                  role: "system" | "developer" | "user";
                  content: string;
                  afterToolCallId?: string;
                }
                | {
                  kind: "skill";
                  id: string; // max length 512
                  revision: string; // max length 512
                  order: number;
                  reference: string; // max length 2048
                  content: string;
                }
                | {
                  kind: "plugin";
                  id: string; // max length 512
                  revision: string; // max length 512
                  order: number;
                  reference: string; // max length 2048
                };
            }[];
            estimate: {
              estimator: string; // max length 128
              inputUnits: number;
              contextUnits: number;
              outputUnits: number;
              safetyReserveUnits: number;
              availableInputUnits: number;
              fits: boolean;
            };
            createdAt: number;
          };
          usage?: {
            promptTokens: number | "Infinity" | "-Infinity" | "NaN";
            completionTokens: number | "Infinity" | "-Infinity" | "NaN";
            totalTokens: number | "Infinity" | "-Infinity" | "NaN";
            cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
            reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
          };
        }
        | {
          kind: "cancelled";
          reason?: string;
          usage?: {
            promptTokens: number | "Infinity" | "-Infinity" | "NaN";
            completionTokens: number | "Infinity" | "-Infinity" | "NaN";
            totalTokens: number | "Infinity" | "-Infinity" | "NaN";
            cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
            reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
          };
        }
        | {
          kind: "failed";
          fault: {
            code: string; // max length 128
            message: string; // max length 4096
            providerCode?: string; // max length 128
          };
          usage?: {
            promptTokens: number | "Infinity" | "-Infinity" | "NaN";
            completionTokens: number | "Infinity" | "-Infinity" | "NaN";
            totalTokens: number | "Infinity" | "-Infinity" | "NaN";
            cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
            reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
          };
        }
        | {
          kind: "no_compressible_history";
          usage?: {
            promptTokens: number | "Infinity" | "-Infinity" | "NaN";
            completionTokens: number | "Infinity" | "-Infinity" | "NaN";
            totalTokens: number | "Infinity" | "-Infinity" | "NaN";
            cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
            reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
          };
        }
        | {
          kind: "limit_reached";
          limit:
            | {
              name: "turn_elapsed";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "approval_wait";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "provider_elapsed";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "provider_attempt_timeout";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "milliseconds";
            }
            | {
              name: "steering_batches";
              origin: "configured" | "provider" | "platform";
              value: number;
              unit: "batches";
            }
            | {
              name: "provider_attempts";
              origin: "configured" | "provider" | "platform";
              value: number; // min 1
              unit: "attempts";
            }
            | {
              name: "model_context";
              origin: "configured" | "provider" | "platform";
              value: number;
              unit: "model_units";
              estimatedInputUnits: number;
              outputReserveUnits: number;
              safetyReserveUnits: number;
              availableInputUnits: number;
              estimator: string; // max length 128
            };
          diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
          usage?: {
            promptTokens: number | "Infinity" | "-Infinity" | "NaN";
            completionTokens: number | "Infinity" | "-Infinity" | "NaN";
            totalTokens: number | "Infinity" | "-Infinity" | "NaN";
            cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
            reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
          };
        };
      acceptedAt: number;
      startedAt?: number;
      completedAt?: number;
    };
  }[];
  next?: { sequence: number /* min 1 */; ordinal: number /* min 1 */ };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/compactions

Compact Session context. Durably admits an ordered manual context compaction.

Operation ID: submitContextCompaction

Request body (application/json):

{
  compactionId: string; // uuid
  model?: string;
  visibility?: {
    floorHistoryRevision?: number;
    excludedTurnIds?: string[];
    excludedEntryIds?: string[];
  };
  authorId?: string; // max length 256
  providerOptions?: unknown;
}

Response 202 (application/json):

{
  receipt: {
    delivery: "compaction";
    sessionId: string; // uuid
    compactionId: string; // uuid
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    sequence: number; // min 1
    acceptedAt: number;
    attribution: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/compactions/{compactionId}

Get context compaction. Returns authoritative context compaction state.

Operation ID: getContextCompaction

Response 200 (application/json):

{
  compaction: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      compactionId: string; // uuid
      model?: string;
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    trigger:
      | { kind: "manual" }
      | { kind: "preflight"; turnId: string /* uuid */ }
      | { kind: "overflow"; turnId: string /* uuid */ };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    cancellation?: { reason?: string; requestedAt: number };
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    outcome?:
      | {
        kind: "completed";
        checkpoint: {
          id: string; // uuid
          compactionId: string; // uuid
          sessionId: string; // uuid
          throughHistoryRevision: number; // min 1
          throughChronologyRevision: number;
          sourceMessageCount: number; // min 1
          summary: {
            version: 1;
            overview: string; // max length 262144
            keyFacts: string[];
            decisions: string[];
            openTasks: string[];
          };
          chronology: {
            revision: number; // min 1
            historyRevision: number;
            boundaryOrder: number;
            change: "activated" | "updated" | "removed";
            source:
              | {
                kind: "instruction";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                role: "system" | "developer" | "user";
                content: string;
                afterToolCallId?: string;
              }
              | {
                kind: "skill";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                reference: string; // max length 2048
                content: string;
              }
              | {
                kind: "plugin";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                reference: string; // max length 2048
              };
          }[];
          estimate: {
            estimator: string; // max length 128
            inputUnits: number;
            contextUnits: number;
            outputUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            fits: boolean;
          };
          createdAt: number;
        };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "cancelled";
        reason?: string;
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "failed";
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "no_compressible_history";
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "limit_reached";
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/compactions/{compactionId}/cancel

Cancel context compaction. Requests cancellation of pending or running context compaction.

Operation ID: cancelContextCompaction

Request body (application/json):

{ reason?: string }

Response 200 (application/json):

{
  compaction: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      compactionId: string; // uuid
      model?: string;
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    trigger:
      | { kind: "manual" }
      | { kind: "preflight"; turnId: string /* uuid */ }
      | { kind: "overflow"; turnId: string /* uuid */ };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    cancellation?: { reason?: string; requestedAt: number };
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    outcome?:
      | {
        kind: "completed";
        checkpoint: {
          id: string; // uuid
          compactionId: string; // uuid
          sessionId: string; // uuid
          throughHistoryRevision: number; // min 1
          throughChronologyRevision: number;
          sourceMessageCount: number; // min 1
          summary: {
            version: 1;
            overview: string; // max length 262144
            keyFacts: string[];
            decisions: string[];
            openTasks: string[];
          };
          chronology: {
            revision: number; // min 1
            historyRevision: number;
            boundaryOrder: number;
            change: "activated" | "updated" | "removed";
            source:
              | {
                kind: "instruction";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                role: "system" | "developer" | "user";
                content: string;
                afterToolCallId?: string;
              }
              | {
                kind: "skill";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                reference: string; // max length 2048
                content: string;
              }
              | {
                kind: "plugin";
                id: string; // max length 512
                revision: string; // max length 512
                order: number;
                reference: string; // max length 2048
              };
          }[];
          estimate: {
            estimator: string; // max length 128
            inputUnits: number;
            contextUnits: number;
            outputUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            fits: boolean;
          };
          createdAt: number;
        };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "cancelled";
        reason?: string;
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "failed";
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "no_compressible_history";
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      }
      | {
        kind: "limit_reached";
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
        usage?: {
          promptTokens: number | "Infinity" | "-Infinity" | "NaN";
          completionTokens: number | "Infinity" | "-Infinity" | "NaN";
          totalTokens: number | "Infinity" | "-Infinity" | "NaN";
          cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
          reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
        };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/turns/{turnId}

Get a Turn. Returns authoritative public Turn state.

Operation ID: getTurn

Response 200 (application/json):

{
  turn: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      turnId: string; // uuid
      // at least 1
      prompt: Array<
        | { type: "text"; text: string }
        | {
          type: "image";
          source:
            | {
              type: "url";
              url: string;
              mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            }
            | {
              type: "base64";
              data: string;
              mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            };
        }
        | { type: "content-reference"; reference: string /* max length 2048 */ }
      >;
      conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
      model?: string;
      agent?: string; // max length 128
      skills?: string[]; // at least 1
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    steering: {
      gate: "open" | "closed";
      promotedBatchCount: number;
      steers: {
        sessionId: string; // uuid
        turnId: string; // uuid
        steerId: string; // uuid
        sequence: number; // min 1
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        attribution: {
          clientId: string; // max length 256
          authorId?: string; // max length 256
        };
        acceptedAt: number;
        state:
          | { state: "accepted" }
          | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
          | {
            state: "undelivered";
            reason: "process_lost" | "turn_cancelled" | "turn_failed";
            undeliveredAt: number;
          };
      }[];
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    parts: Array<
      | {
        type: "text";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "refusal";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "reasoning";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
        startedAt?: number;
        completedAt?: number;
      }
      | {
        type: "tool";
        id: string; // uuid
        toolCallId: string;
        toolId: string;
        origin?:
          | { kind: "model" }
          | {
            kind: "codemode";
            parentToolCallId: string;
            ordinal: number; // min 1
            ownerPluginId?: string;
            binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
          };
        execution?: { result: unknown; logs: string[] };
        instructions?: Array<
          | {
            kind: "instruction";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            role: "system" | "developer" | "user";
            content: string;
            afterToolCallId?: string;
          }
          | {
            kind: "skill";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
            content: string;
          }
          | {
            kind: "plugin";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
          }
        >;
        assistantMessageIndex: number;
        modelInput?: unknown;
        input: unknown;
        state: "requested" | "completed" | "failed" | "denied";
        output?: unknown;
        fault?: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        canonicalResult?:
          | {
            format: "content";
            // at least 1
            value: Array<
              | { type: "text"; text: string }
              | { type: "json"; value: unknown }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
            >;
          }
          | { format: "text"; value: string }
          | { format: "json"; value: unknown };
        approval:
          | { state: "none" }
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
          }
          | {
            state: "resolved";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
            resolvedAt: number;
            decision: "allow" | "deny";
            source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
            reply?: "once" | "always" | "reject";
            replyMessage?: string; // max length 4096
          };
        question?:
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
          }
          | {
            state: "answered";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
            answers: string[][]; // at least 1
          }
          | {
            state: "dismissed";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
          };
        requestedAt: number;
        completedAt?: number;
        activity?: {
          checkpoint: number; // min 1
          updatedAt: number;
          message?: string; // max length 1024
          preview?: string;
          observedBytes: number;
          truncated: boolean;
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
          childSessionId?: string; // uuid
        };
        artifact?: {
          id: string; // uuid
          path: string;
          observedBytes: number;
          state: "writing" | "complete" | "incomplete";
        };
      }
      | {
        type: "steering";
        id: string; // uuid
        batch: number; // min 1
        promotedAt: number;
        steers: {
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
        }[];
      }
    >;
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
    cancellation?: { reason?: string; requestedAt: number };
    outcome?:
      | { kind: "completed"; turnId: string; text: string }
      | { kind: "cancelled"; turnId: string; reason?: string }
      | {
        kind: "failed";
        turnId: string;
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
      }
      | {
        kind: "limit_reached";
        turnId: string;
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/turns/{turnId}/events

Watch a Turn. Streams observational Turn snapshots, content deltas, and durable state events after a revision cursor. The stream starts with the current snapshot, then replays the durable events recorded after afterRevision so observers see missed state transitions, then continues with live Turn revisions. While the Turn is quiet, the stream sends turn.heartbeat at least every 15 seconds, so a longer silence means the connection is gone.

Operation ID: watchTurn

Response 200: no body.

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/turns/{turnId}/cancel

Cancel a Turn. Requests cancellation of active Turn work.

Operation ID: cancelTurn

Request body (application/json):

{ reason?: string }

Response 200 (application/json):

{
  turn: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      turnId: string; // uuid
      // at least 1
      prompt: Array<
        | { type: "text"; text: string }
        | {
          type: "image";
          source:
            | {
              type: "url";
              url: string;
              mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            }
            | {
              type: "base64";
              data: string;
              mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            };
        }
        | { type: "content-reference"; reference: string /* max length 2048 */ }
      >;
      conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
      model?: string;
      agent?: string; // max length 128
      skills?: string[]; // at least 1
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    steering: {
      gate: "open" | "closed";
      promotedBatchCount: number;
      steers: {
        sessionId: string; // uuid
        turnId: string; // uuid
        steerId: string; // uuid
        sequence: number; // min 1
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        attribution: {
          clientId: string; // max length 256
          authorId?: string; // max length 256
        };
        acceptedAt: number;
        state:
          | { state: "accepted" }
          | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
          | {
            state: "undelivered";
            reason: "process_lost" | "turn_cancelled" | "turn_failed";
            undeliveredAt: number;
          };
      }[];
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    parts: Array<
      | {
        type: "text";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "refusal";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "reasoning";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
        startedAt?: number;
        completedAt?: number;
      }
      | {
        type: "tool";
        id: string; // uuid
        toolCallId: string;
        toolId: string;
        origin?:
          | { kind: "model" }
          | {
            kind: "codemode";
            parentToolCallId: string;
            ordinal: number; // min 1
            ownerPluginId?: string;
            binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
          };
        execution?: { result: unknown; logs: string[] };
        instructions?: Array<
          | {
            kind: "instruction";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            role: "system" | "developer" | "user";
            content: string;
            afterToolCallId?: string;
          }
          | {
            kind: "skill";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
            content: string;
          }
          | {
            kind: "plugin";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
          }
        >;
        assistantMessageIndex: number;
        modelInput?: unknown;
        input: unknown;
        state: "requested" | "completed" | "failed" | "denied";
        output?: unknown;
        fault?: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        canonicalResult?:
          | {
            format: "content";
            // at least 1
            value: Array<
              | { type: "text"; text: string }
              | { type: "json"; value: unknown }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
            >;
          }
          | { format: "text"; value: string }
          | { format: "json"; value: unknown };
        approval:
          | { state: "none" }
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
          }
          | {
            state: "resolved";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
            resolvedAt: number;
            decision: "allow" | "deny";
            source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
            reply?: "once" | "always" | "reject";
            replyMessage?: string; // max length 4096
          };
        question?:
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
          }
          | {
            state: "answered";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
            answers: string[][]; // at least 1
          }
          | {
            state: "dismissed";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
          };
        requestedAt: number;
        completedAt?: number;
        activity?: {
          checkpoint: number; // min 1
          updatedAt: number;
          message?: string; // max length 1024
          preview?: string;
          observedBytes: number;
          truncated: boolean;
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
          childSessionId?: string; // uuid
        };
        artifact?: {
          id: string; // uuid
          path: string;
          observedBytes: number;
          state: "writing" | "complete" | "incomplete";
        };
      }
      | {
        type: "steering";
        id: string; // uuid
        batch: number; // min 1
        promotedAt: number;
        steers: {
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
        }[];
      }
    >;
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
    cancellation?: { reason?: string; requestedAt: number };
    outcome?:
      | { kind: "completed"; turnId: string; text: string }
      | { kind: "cancelled"; turnId: string; reason?: string }
      | {
        kind: "failed";
        turnId: string;
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
      }
      | {
        kind: "limit_reached";
        turnId: string;
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/permissions/{permissionRequestId}/reply

Reply to permission request. Records once, always, or reject for a durable pending permission request. A reply addressed to an ancestor Session is forwarded to the descendant sub-agent Session that owns the request, and the returned Turn is the owning Turn.

Operation ID: replyPermission

Request body (application/json):

{ reply: "once" | "always" | "reject"; message?: string /* max length 4096 */ }

Response 200 (application/json):

{
  requestId: string; // uuid
  turn: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      turnId: string; // uuid
      // at least 1
      prompt: Array<
        | { type: "text"; text: string }
        | {
          type: "image";
          source:
            | {
              type: "url";
              url: string;
              mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            }
            | {
              type: "base64";
              data: string;
              mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            };
        }
        | { type: "content-reference"; reference: string /* max length 2048 */ }
      >;
      conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
      model?: string;
      agent?: string; // max length 128
      skills?: string[]; // at least 1
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    steering: {
      gate: "open" | "closed";
      promotedBatchCount: number;
      steers: {
        sessionId: string; // uuid
        turnId: string; // uuid
        steerId: string; // uuid
        sequence: number; // min 1
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        attribution: {
          clientId: string; // max length 256
          authorId?: string; // max length 256
        };
        acceptedAt: number;
        state:
          | { state: "accepted" }
          | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
          | {
            state: "undelivered";
            reason: "process_lost" | "turn_cancelled" | "turn_failed";
            undeliveredAt: number;
          };
      }[];
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    parts: Array<
      | {
        type: "text";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "refusal";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "reasoning";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
        startedAt?: number;
        completedAt?: number;
      }
      | {
        type: "tool";
        id: string; // uuid
        toolCallId: string;
        toolId: string;
        origin?:
          | { kind: "model" }
          | {
            kind: "codemode";
            parentToolCallId: string;
            ordinal: number; // min 1
            ownerPluginId?: string;
            binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
          };
        execution?: { result: unknown; logs: string[] };
        instructions?: Array<
          | {
            kind: "instruction";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            role: "system" | "developer" | "user";
            content: string;
            afterToolCallId?: string;
          }
          | {
            kind: "skill";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
            content: string;
          }
          | {
            kind: "plugin";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
          }
        >;
        assistantMessageIndex: number;
        modelInput?: unknown;
        input: unknown;
        state: "requested" | "completed" | "failed" | "denied";
        output?: unknown;
        fault?: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        canonicalResult?:
          | {
            format: "content";
            // at least 1
            value: Array<
              | { type: "text"; text: string }
              | { type: "json"; value: unknown }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
            >;
          }
          | { format: "text"; value: string }
          | { format: "json"; value: unknown };
        approval:
          | { state: "none" }
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
          }
          | {
            state: "resolved";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
            resolvedAt: number;
            decision: "allow" | "deny";
            source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
            reply?: "once" | "always" | "reject";
            replyMessage?: string; // max length 4096
          };
        question?:
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
          }
          | {
            state: "answered";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
            answers: string[][]; // at least 1
          }
          | {
            state: "dismissed";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
          };
        requestedAt: number;
        completedAt?: number;
        activity?: {
          checkpoint: number; // min 1
          updatedAt: number;
          message?: string; // max length 1024
          preview?: string;
          observedBytes: number;
          truncated: boolean;
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
          childSessionId?: string; // uuid
        };
        artifact?: {
          id: string; // uuid
          path: string;
          observedBytes: number;
          state: "writing" | "complete" | "incomplete";
        };
      }
      | {
        type: "steering";
        id: string; // uuid
        batch: number; // min 1
        promotedAt: number;
        steers: {
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
        }[];
      }
    >;
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
    cancellation?: { reason?: string; requestedAt: number };
    outcome?:
      | { kind: "completed"; turnId: string; text: string }
      | { kind: "cancelled"; turnId: string; reason?: string }
      | {
        kind: "failed";
        turnId: string;
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
      }
      | {
        kind: "limit_reached";
        turnId: string;
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/permissions/descendants/pending

List descendant approvals. Returns the pending permission requests owned by descendant sub-agent Sessions, oldest first.

Operation ID: listDescendantPendingApprovals

Response 200 (application/json):

{
  approvals: {
    request: {
      id: string; // uuid
      sessionId: string; // uuid
      turnId: string; // uuid
      toolId: string;
      toolCallId: string;
      action: string;
      resources: string[]; // at least 1
      save?: string[];
      metadata?: unknown;
    };
    requestedAt: number;
    agent?: string; // max length 128
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/questions/{questionRequestId}/reply

Reply to question request. Records answers for a durable pending user question. A reply addressed to an ancestor Session is forwarded to the descendant sub-agent Session that owns the request, and the returned Turn is the owning Turn.

Operation ID: replyQuestion

Request body (application/json):

{ answers: string[][] /* at least 1 */ }

Response 200 (application/json):

{
  requestId: string; // uuid
  turn: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      turnId: string; // uuid
      // at least 1
      prompt: Array<
        | { type: "text"; text: string }
        | {
          type: "image";
          source:
            | {
              type: "url";
              url: string;
              mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            }
            | {
              type: "base64";
              data: string;
              mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            };
        }
        | { type: "content-reference"; reference: string /* max length 2048 */ }
      >;
      conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
      model?: string;
      agent?: string; // max length 128
      skills?: string[]; // at least 1
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    steering: {
      gate: "open" | "closed";
      promotedBatchCount: number;
      steers: {
        sessionId: string; // uuid
        turnId: string; // uuid
        steerId: string; // uuid
        sequence: number; // min 1
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        attribution: {
          clientId: string; // max length 256
          authorId?: string; // max length 256
        };
        acceptedAt: number;
        state:
          | { state: "accepted" }
          | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
          | {
            state: "undelivered";
            reason: "process_lost" | "turn_cancelled" | "turn_failed";
            undeliveredAt: number;
          };
      }[];
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    parts: Array<
      | {
        type: "text";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "refusal";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "reasoning";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
        startedAt?: number;
        completedAt?: number;
      }
      | {
        type: "tool";
        id: string; // uuid
        toolCallId: string;
        toolId: string;
        origin?:
          | { kind: "model" }
          | {
            kind: "codemode";
            parentToolCallId: string;
            ordinal: number; // min 1
            ownerPluginId?: string;
            binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
          };
        execution?: { result: unknown; logs: string[] };
        instructions?: Array<
          | {
            kind: "instruction";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            role: "system" | "developer" | "user";
            content: string;
            afterToolCallId?: string;
          }
          | {
            kind: "skill";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
            content: string;
          }
          | {
            kind: "plugin";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
          }
        >;
        assistantMessageIndex: number;
        modelInput?: unknown;
        input: unknown;
        state: "requested" | "completed" | "failed" | "denied";
        output?: unknown;
        fault?: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        canonicalResult?:
          | {
            format: "content";
            // at least 1
            value: Array<
              | { type: "text"; text: string }
              | { type: "json"; value: unknown }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
            >;
          }
          | { format: "text"; value: string }
          | { format: "json"; value: unknown };
        approval:
          | { state: "none" }
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
          }
          | {
            state: "resolved";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
            resolvedAt: number;
            decision: "allow" | "deny";
            source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
            reply?: "once" | "always" | "reject";
            replyMessage?: string; // max length 4096
          };
        question?:
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
          }
          | {
            state: "answered";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
            answers: string[][]; // at least 1
          }
          | {
            state: "dismissed";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
          };
        requestedAt: number;
        completedAt?: number;
        activity?: {
          checkpoint: number; // min 1
          updatedAt: number;
          message?: string; // max length 1024
          preview?: string;
          observedBytes: number;
          truncated: boolean;
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
          childSessionId?: string; // uuid
        };
        artifact?: {
          id: string; // uuid
          path: string;
          observedBytes: number;
          state: "writing" | "complete" | "incomplete";
        };
      }
      | {
        type: "steering";
        id: string; // uuid
        batch: number; // min 1
        promotedAt: number;
        steers: {
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
        }[];
      }
    >;
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
    cancellation?: { reason?: string; requestedAt: number };
    outcome?:
      | { kind: "completed"; turnId: string; text: string }
      | { kind: "cancelled"; turnId: string; reason?: string }
      | {
        kind: "failed";
        turnId: string;
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
      }
      | {
        kind: "limit_reached";
        turnId: string;
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/questions/{questionRequestId}/reject

Reject question request. Dismisses a durable pending user question; the waiting tool fails with question_dismissed. Forwarding matches the question reply.

Operation ID: rejectQuestion

Response 200 (application/json):

{
  requestId: string; // uuid
  turn: {
    id: string; // uuid
    sessionId: string; // uuid
    sequence: number; // min 1
    request: {
      sessionId: string; // uuid
      turnId: string; // uuid
      // at least 1
      prompt: Array<
        | { type: "text"; text: string }
        | {
          type: "image";
          source:
            | {
              type: "url";
              url: string;
              mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            }
            | {
              type: "base64";
              data: string;
              mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
            };
        }
        | { type: "content-reference"; reference: string /* max length 2048 */ }
      >;
      conversationEntry?: { entryId: string /* uuid */; historyRevision: number /* min 1 */ };
      model?: string;
      agent?: string; // max length 128
      skills?: string[]; // at least 1
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      visibility?: {
        floorHistoryRevision?: number;
        excludedTurnIds?: string[];
        excludedEntryIds?: string[];
      };
    };
    attribution?: {
      clientId: string; // max length 256
      authorId?: string; // max length 256
    };
    model: string;
    modelLeaseId: string; // max length 68
    requestOptionsId: string; // uuid
    policy: {
      version: 4;
      permissions: { action: string; resource: string; effect: "allow" | "ask" | "deny" }[];
      permissionMatching: { caseSensitive: boolean };
      approval: {
        timeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      timeouts: {
        turnMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
      steering: {
        maxBatches:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      subagents: {
        maxDepth:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number;
            origin: "configured" | "provider" | "platform";
          };
      };
      provider: {
        maxAttempts:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        attemptTimeoutMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        elapsedMs:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
        pacing:
          | { kind: "none" }
          | { kind: "fixed"; delayMs: number }
          | {
            kind: "exponential";
            initialDelayMs: number; // min 1
            maximumDelayMs: number; // min 1
            jitter: boolean;
          };
      };
      context: { safetyReserve: { units: number; origin: "configured" | "platform" } };
      images: {
        maxBase64Bytes:
          | { kind: "unlimited"; origin: "absent" | "configured" | "provider" | "platform" }
          | {
            kind: "finite";
            value: number; // min 1
            origin: "configured" | "provider" | "platform";
          };
      };
    };
    steering: {
      gate: "open" | "closed";
      promotedBatchCount: number;
      steers: {
        sessionId: string; // uuid
        turnId: string; // uuid
        steerId: string; // uuid
        sequence: number; // min 1
        // at least 1
        prompt: Array<
          | { type: "text"; text: string }
          | {
            type: "image";
            source:
              | {
                type: "url";
                url: string;
                mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              }
              | {
                type: "base64";
                data: string;
                mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
              };
          }
          | { type: "content-reference"; reference: string /* max length 2048 */ }
        >;
        attribution: {
          clientId: string; // max length 256
          authorId?: string; // max length 256
        };
        acceptedAt: number;
        state:
          | { state: "accepted" }
          | { state: "promoted"; batch: number /* min 1 */; promotedAt: number }
          | {
            state: "undelivered";
            reason: "process_lost" | "turn_cancelled" | "turn_failed";
            undeliveredAt: number;
          };
      }[];
    };
    phase: "pending" | "running" | "completed" | "cancelled" | "failed";
    revision: number;
    parts: Array<
      | {
        type: "text";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "refusal";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
      }
      | {
        type: "reasoning";
        id: string; // uuid
        assistantMessageIndex: number;
        text: string;
        startedAt?: number;
        completedAt?: number;
      }
      | {
        type: "tool";
        id: string; // uuid
        toolCallId: string;
        toolId: string;
        origin?:
          | { kind: "model" }
          | {
            kind: "codemode";
            parentToolCallId: string;
            ordinal: number; // min 1
            ownerPluginId?: string;
            binding?: { snapshotId: string; bindingId: string; modelMessageId: string };
          };
        execution?: { result: unknown; logs: string[] };
        instructions?: Array<
          | {
            kind: "instruction";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            role: "system" | "developer" | "user";
            content: string;
            afterToolCallId?: string;
          }
          | {
            kind: "skill";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
            content: string;
          }
          | {
            kind: "plugin";
            id: string; // max length 512
            revision: string; // max length 512
            order: number;
            reference: string; // max length 2048
          }
        >;
        assistantMessageIndex: number;
        modelInput?: unknown;
        input: unknown;
        state: "requested" | "completed" | "failed" | "denied";
        output?: unknown;
        fault?: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
        canonicalResult?:
          | {
            format: "content";
            // at least 1
            value: Array<
              | { type: "text"; text: string }
              | { type: "json"; value: unknown }
              | {
                type: "image";
                source:
                  | {
                    type: "url";
                    url: string;
                    mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  }
                  | {
                    type: "base64";
                    data: string;
                    mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                  };
              }
            >;
          }
          | { format: "text"; value: string }
          | { format: "json"; value: unknown };
        approval:
          | { state: "none" }
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
          }
          | {
            state: "resolved";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              action: string;
              resources: string[]; // at least 1
              save?: string[];
              metadata?: unknown;
            };
            requestedAt: number;
            resolvedAt: number;
            decision: "allow" | "deny";
            source: "config" | "saved" | "hook" | "callback" | "remote" | "default" | "timeout" | "terminal";
            reply?: "once" | "always" | "reject";
            replyMessage?: string; // max length 4096
          };
        question?:
          | {
            state: "pending";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
          }
          | {
            state: "answered";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
            answers: string[][]; // at least 1
          }
          | {
            state: "dismissed";
            request: {
              id: string; // uuid
              sessionId: string; // uuid
              turnId: string; // uuid
              toolId: string;
              toolCallId: string;
              // at least 1
              questions: {
                question: string; // max length 4096
                header: string; // max length 30
                // at least 1
                options: {
                  label: string; // max length 256
                  description: string; // max length 4096
                }[];
                multiple?: boolean;
                custom?: boolean;
              }[];
            };
            requestedAt: number;
            resolvedAt: number;
          };
        requestedAt: number;
        completedAt?: number;
        activity?: {
          checkpoint: number; // min 1
          updatedAt: number;
          message?: string; // max length 1024
          preview?: string;
          observedBytes: number;
          truncated: boolean;
          artifact?: {
            id: string; // uuid
            path: string;
            observedBytes: number;
            state: "writing" | "complete" | "incomplete";
          };
          childSessionId?: string; // uuid
        };
        artifact?: {
          id: string; // uuid
          path: string;
          observedBytes: number;
          state: "writing" | "complete" | "incomplete";
        };
      }
      | {
        type: "steering";
        id: string; // uuid
        batch: number; // min 1
        promotedAt: number;
        steers: {
          steerId: string; // uuid
          sequence: number; // min 1
          // at least 1
          prompt: Array<
            | { type: "text"; text: string }
            | {
              type: "image";
              source:
                | {
                  type: "url";
                  url: string;
                  mimeType?: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                }
                | {
                  type: "base64";
                  data: string;
                  mimeType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
                };
            }
            | { type: "content-reference"; reference: string /* max length 2048 */ }
          >;
          attribution: {
            clientId: string; // max length 256
            authorId?: string; // max length 256
          };
          acceptedAt: number;
        }[];
      }
    >;
    usage?: {
      promptTokens: number | "Infinity" | "-Infinity" | "NaN";
      completionTokens: number | "Infinity" | "-Infinity" | "NaN";
      totalTokens: number | "Infinity" | "-Infinity" | "NaN";
      cachedPromptTokens?: number | "Infinity" | "-Infinity" | "NaN";
      reasoningCompletionTokens?: number | "Infinity" | "-Infinity" | "NaN";
    };
    contextUse?: { model: string; usedUnits: number; contextUnits: number };
    cancellation?: { reason?: string; requestedAt: number };
    outcome?:
      | { kind: "completed"; turnId: string; text: string }
      | { kind: "cancelled"; turnId: string; reason?: string }
      | {
        kind: "failed";
        turnId: string;
        fault: {
          code: string; // max length 128
          message: string; // max length 4096
          providerCode?: string; // max length 128
        };
      }
      | {
        kind: "limit_reached";
        turnId: string;
        limit:
          | {
            name: "turn_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "approval_wait";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_elapsed";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "provider_attempt_timeout";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "milliseconds";
          }
          | {
            name: "steering_batches";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "batches";
          }
          | {
            name: "provider_attempts";
            origin: "configured" | "provider" | "platform";
            value: number; // min 1
            unit: "attempts";
          }
          | {
            name: "model_context";
            origin: "configured" | "provider" | "platform";
            value: number;
            unit: "model_units";
            estimatedInputUnits: number;
            outputReserveUnits: number;
            safetyReserveUnits: number;
            availableInputUnits: number;
            estimator: string; // max length 128
          };
        diagnostic: { code: string /* max length 128 */; message: string /* max length 4096 */ };
      };
    acceptedAt: number;
    startedAt?: number;
    completedAt?: number;
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/questions/descendants/pending

List descendant questions. Returns the pending user questions owned by descendant sub-agent Sessions, oldest first.

Operation ID: listDescendantPendingQuestions

Response 200 (application/json):

{
  questions: {
    request: {
      id: string; // uuid
      sessionId: string; // uuid
      turnId: string; // uuid
      toolId: string;
      toolCallId: string;
      // at least 1
      questions: {
        question: string; // max length 4096
        header: string; // max length 30
        // at least 1
        options: {
          label: string; // max length 256
          description: string; // max length 4096
        }[];
        multiple?: boolean;
        custom?: boolean;
      }[];
    };
    requestedAt: number;
    agent?: string; // max length 128
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/plugins

Get Session plugin status. Returns the redacted desired and active Session plugin revisions, activation state, and the effective runtime plugin inventory.

Operation ID: sessionPlugins

Response 200 (application/json):

{
  status: {
    sessionId: string; // uuid
    desired?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    desiredActivation?: {
      revisionId: string;
      state: "pending" | "started" | "active" | "failed";
      failure?: string;
    };
    active?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    plugins: {
      source: string;
      generationId: string;
      pluginId?: string;
      packageVersion?: string;
      status: "active" | "failed";
      registrations: string[];
      error?: string;
    }[];
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

PUT /v1/servers/{server}/sessions/{sessionId}/plugins

Add a Session plugin. Records an idempotent desired Session plugin revision that replaces the previous one and requests its activation.

Operation ID: addSessionPlugin

Request body (application/json):

{
  id: string;
  source:
    | { _tag: "Package"; name: string; requestedVersion?: string }
    | { _tag: "File"; uri: string }
    | { _tag: "Git"; url: string; ref?: string }
    | { _tag: "Bundle"; url: string }
    | { _tag: "Static"; id: string };
  resolved: { pluginId: string; version?: string; integrity?: string };
  options: unknown;
  mcpServers: Array<
    | {
      kind: "local";
      id: string; // max length 128
      name: string; // max length 128
      enabled?: boolean;
      order?: number;
      resourceReadTool?: boolean;
      protocolVersions: string[]; // at least 1
      clientCapabilities?: { roots: false; sampling: false; elicitation: false };
      limits?: {
        startupMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        catalogMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        executionMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
      reconnect?:
        | { kind: "manual" }
        | {
          kind: "retry";
          delayMs: number; // min 1
          maxAttempts: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        };
      transport: {
        kind: "stdio";
        command: string;
        arguments: string[];
        environment: Record<string,
          | { kind: "environment"; reference: string /* max length 256 */ }
          | { kind: "secret"; reference: string /* max length 256 */ }
          | { kind: "oauth"; reference: string /* max length 256 */ }
        >;
      };
    }
    | {
      kind: "remote";
      id: string; // max length 128
      name: string; // max length 128
      enabled?: boolean;
      order?: number;
      resourceReadTool?: boolean;
      protocolVersions: string[]; // at least 1
      clientCapabilities?: { roots: false; sampling: false; elicitation: false };
      limits?: {
        startupMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        catalogMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        executionMs: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
      };
      reconnect?:
        | { kind: "manual" }
        | {
          kind: "retry";
          delayMs: number; // min 1
          maxAttempts: { kind: "unlimited" } | { kind: "finite"; value: number /* min 1 */ };
        };
      transport: {
        kind: "streamable-http";
        endpoint: string; // max length 2048
        headers: Record<string,
          | { kind: "environment"; reference: string /* max length 256 */ }
          | { kind: "secret"; reference: string /* max length 256 */ }
          | { kind: "oauth"; reference: string /* max length 256 */ }
        >;
        oauth?: { kind: "oauth"; reference: string /* max length 256 */ };
      };
    }
  >;
  skills: Array<
    | {
      kind: "declaration";
      declaration: {
        id: string; // max length 128
        displayName: string;
        description: string;
        body: string;
        version: string;
        modelAdvertisement: { advertised: boolean; userInvocable: boolean };
        publicMetadata: { author?: string; license?: string; homepage?: string; tags: string[] };
        files?: string[];
      };
    }
    | {
      kind: "source";
      source:
        | { kind: "workspace"; id: string /* max length 128 */; directory: string }
        | {
          kind: "http";
          id: string; // max length 128
          catalogUrl: string; // max length 2048
          headers: { name: string /* max length 128 */; value: string /* max length 4096 */ }[];
        };
    }
  >;
}

Response 200 (application/json):

{
  status: {
    sessionId: string; // uuid
    desired?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    desiredActivation?: {
      revisionId: string;
      state: "pending" | "started" | "active" | "failed";
      failure?: string;
    };
    active?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    plugins: {
      source: string;
      generationId: string;
      pluginId?: string;
      packageVersion?: string;
      status: "active" | "failed";
      registrations: string[];
      error?: string;
    }[];
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

DELETE /v1/servers/{server}/sessions/{sessionId}/plugins

Remove the Session plugin. Clears the Session overlay so later Turns use the host baseline.

Operation ID: removeSessionPlugin

Request body (application/json):

unknown

Response 200 (application/json):

{
  status: {
    sessionId: string; // uuid
    desired?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    desiredActivation?: {
      revisionId: string;
      state: "pending" | "started" | "active" | "failed";
      failure?: string;
    };
    active?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    plugins: {
      source: string;
      generationId: string;
      pluginId?: string;
      packageVersion?: string;
      status: "active" | "failed";
      registrations: string[];
      error?: string;
    }[];
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/plugins/reload

Reload the Session plugin. Requests lazy reconstruction and activation of the desired overlay revision.

Operation ID: reloadSessionPlugin

Request body (application/json):

unknown

Response 200 (application/json):

{
  status: {
    sessionId: string; // uuid
    desired?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    desiredActivation?: {
      revisionId: string;
      state: "pending" | "started" | "active" | "failed";
      failure?: string;
    };
    active?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    plugins: {
      source: string;
      generationId: string;
      pluginId?: string;
      packageVersion?: string;
      status: "active" | "failed";
      registrations: string[];
      error?: string;
    }[];
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/plugins/refresh

Refresh the Session plugin. Re-resolves the active overlay source; only this mutation may adopt a newer unpinned artifact.

Operation ID: refreshSessionPlugin

Request body (application/json):

{ id: string }

Response 200 (application/json):

{
  status: {
    sessionId: string; // uuid
    desired?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    desiredActivation?: {
      revisionId: string;
      state: "pending" | "started" | "active" | "failed";
      failure?: string;
    };
    active?: {
      id: string;
      sequence: number;
      source:
        | { _tag: "Package"; name: string; requestedVersion?: string }
        | { _tag: "File"; uri: string }
        | { _tag: "Git"; url: string; ref?: string }
        | { _tag: "Bundle"; url: string }
        | { _tag: "Static"; id: string };
      resolved: { pluginId: string; version: string; integrity?: string };
      mcpServers: {
        serverId: string;
        name: string;
        kind: "local" | "remote";
        resourceReadTool: boolean;
      }[];
      skills: Array<
        | { kind: "declaration"; id: string; version: string }
        | { kind: "source"; id: string; sourceKind: "workspace" | "http" }
      >;
      createdAt: number;
    };
    plugins: {
      source: string;
      generationId: string;
      pluginId?: string;
      packageVersion?: string;
      status: "active" | "failed";
      registrations: string[];
      error?: string;
    }[];
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/mcp-credentials/{serverName}/authorize

Start MCP OAuth authorization. Starts or idempotently resumes user authorization for one remote MCP server and returns only the pending status and the authorization URL.

Operation ID: startMcpCredential

Request body (application/json):

{
  resource?: string;
  challenge?: {
    scheme: "Bearer";
    resourceMetadata: string;
    error?: "invalid_token" | "insufficient_scope";
    scope?: string;
  };
  authorizationServer?: string;
  client?: { clientId: string; tokenEndpointAuthMethod: "none" };
}

Response 202 (application/json):

{
  status: { kind: "pending"; generation: number /* min 1 */ };
  authorizationUrl: string;
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/mcp-credentials/{serverName}

Get MCP OAuth credential status. Returns the secret-free status of one Session MCP server credential.

Operation ID: getMcpCredential

Response 200 (application/json):

{
  status:
    | { kind: "absent"; generation: number }
    | { kind: "pending"; generation: number /* min 1 */ }
    | { kind: "authorized"; generation: number /* min 1 */ }
    | { kind: "expired"; generation: number /* min 1 */; expiredAtEpochMs: number }
    | {
      kind: "authorization-required";
      generation: number; // min 1
      reason: "client-registration-uncertain" | "authorization-code-uncertain" | "refresh-uncertain";
    }
    | {
      kind: "forgotten";
      generation: number; // min 1
      revocation: "completed" | "unsupported" | "not-applicable" | "not-attempted" | "failed" | "uncertain";
    };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/mcp-credentials/{serverName}/callback

Complete MCP OAuth callback. Completes one external OAuth callback through the private lifecycle; the exchanged token never appears in the response.

Operation ID: completeMcpCredentialCallback

Request body (application/json):

{
  callback:
    | { kind: "success"; state: string; code: string; issuer?: string }
    | {
      kind: "denied";
      state: string;
      error: "access_denied" | "consent_required" | "interaction_required" | "invalid_request" | "invalid_scope" | "login_required" | "server_error" | "temporarily_unavailable" | "unauthorized_client" | "unsupported_response_type";
      issuer?: string;
    };
}

Response 200 (application/json):

{
  status:
    | { kind: "absent"; generation: number }
    | { kind: "pending"; generation: number /* min 1 */ }
    | { kind: "authorized"; generation: number /* min 1 */ }
    | { kind: "expired"; generation: number /* min 1 */; expiredAtEpochMs: number }
    | {
      kind: "authorization-required";
      generation: number; // min 1
      reason: "client-registration-uncertain" | "authorization-code-uncertain" | "refresh-uncertain";
    }
    | {
      kind: "forgotten";
      generation: number; // min 1
      revocation: "completed" | "unsupported" | "not-applicable" | "not-attempted" | "failed" | "uncertain";
    };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/mcp-credentials/{serverName}/cancel

Cancel MCP OAuth authorization. Cancels a pending MCP OAuth authorization and returns the resulting status.

Operation ID: cancelMcpCredential

Request body (application/json):

{ generation?: number /* min 1 */ }

Response 200 (application/json):

{
  status:
    | { kind: "absent"; generation: number }
    | { kind: "pending"; generation: number /* min 1 */ }
    | { kind: "authorized"; generation: number /* min 1 */ }
    | { kind: "expired"; generation: number /* min 1 */; expiredAtEpochMs: number }
    | {
      kind: "authorization-required";
      generation: number; // min 1
      reason: "client-registration-uncertain" | "authorization-code-uncertain" | "refresh-uncertain";
    }
    | {
      kind: "forgotten";
      generation: number; // min 1
      revocation: "completed" | "unsupported" | "not-applicable" | "not-attempted" | "failed" | "uncertain";
    };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/servers/{server}/sessions/{sessionId}/mcp-credentials/{serverName}/forget

Forget MCP OAuth credential. Revokes and forgets one Session MCP server credential and retires its live connections.

Operation ID: forgetMcpCredential

Request body (application/json):

unknown

Response 200 (application/json):

{
  generation: number; // min 1
  revocation: "completed" | "unsupported" | "not-applicable" | "not-attempted" | "failed" | "uncertain";
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/models

Get Session models. Returns the adopted host catalog snapshot for the Session.

Operation ID: sessionModels

Response 200 (application/json):

{
  hostRevision: string; // max length 128
  defaultModel?: string; // max length 641
  providers: {
    id: string; // max length 128
    displayName: string; // max length 256
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
  }[];
  models: {
    providerId: string; // max length 128
    ref: string; // max length 641
    id: string; // max length 512
    upstreamId: string; // max length 512
    displayName: string; // max length 256
    capabilities: {
      input: ("text" | "image")[]; // at least 1
      output: "text"[]; // at least 1
      tools: boolean;
      image?: {
        referenceTypes: ("url" | "base64")[]; // at least 1
        mimeTypes: ("image/jpeg" | "image/png" | "image/gif" | "image/webp")[]; // at least 1
      };
      // at least 1
      reasoningEfforts?: ("none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max")[];
    };
    limits: { contextUnits: number; outputUnits: number };
    pricing:
      | {
        version: "v1";
        currency: string; // max length 3
        unit: "million_model_units";
        rates: {
          input: string; // max length 128
          output: string; // max length 128
          cacheReadInput?: string; // max length 128
          cacheWriteInput?: string; // max length 128
        };
      }
      | { version: "unknown" };
    defaults: {
      temperature?: number;
      topP?: number; // max 1
      maxOutputUnits?: number; // min 1
      stopSequences?: string[]; // at least 1
      seed?: number;
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    };
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/models/events

Stream Session model revision events. Streams revision-only SSE events whenever the Session adopts a new host catalog revision.

Operation ID: sessionModelEvents

Response 200: no body.

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/servers/{server}/sessions/{sessionId}/agents

List Session agents. Returns the effective host and Session agents with their display metadata and modes.

Operation ID: sessionAgents

Response 200 (application/json):

{
  defaultAgent?: string; // max length 128
  agents: {
    id: string; // max length 128
    displayName: string;
    description: string;
    model?: string; // max length 641
    mode: "primary" | "subagent" | "all";
    origin: "host" | "session";
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

Runtime

GET /v1/runtime/plugins

List runtime plugins. Returns safe plugin registration metadata.

Operation ID: plugins

Response 200 (application/json):

{
  plugins: {
    source: string;
    generationId: string;
    pluginId?: string;
    packageVersion?: string;
    status: "active" | "failed";
    registrations: string[];
    error?: string;
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/runtime/skills

List runtime Skills. Returns safe host Skill metadata.

Operation ID: skills

Response 200 (application/json):

{
  skills: {
    id: string; // max length 128
    displayName: string;
    description: string;
    advertised: boolean;
    userInvocable: boolean;
    origin: "host" | "session";
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/runtime/reload

Reload runtime. Requests a trusted runtime plugin reload.

Operation ID: reload

Request body (application/json):

unknown

Response 200 (application/json):

{
  result: "reloaded" | "rejected";
  plugins: {
    source: string;
    generationId: string;
    pluginId?: string;
    packageVersion?: string;
    status: "active" | "failed";
    registrations: string[];
    error?: string;
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/runtime/models

List runtime models. Returns the current host model catalog snapshot.

Operation ID: models

Response 200 (application/json):

{
  hostRevision: string; // max length 128
  defaultModel?: string; // max length 641
  providers: {
    id: string; // max length 128
    displayName: string; // max length 256
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
  }[];
  models: {
    providerId: string; // max length 128
    ref: string; // max length 641
    id: string; // max length 512
    upstreamId: string; // max length 512
    displayName: string; // max length 256
    capabilities: {
      input: ("text" | "image")[]; // at least 1
      output: "text"[]; // at least 1
      tools: boolean;
      image?: {
        referenceTypes: ("url" | "base64")[]; // at least 1
        mimeTypes: ("image/jpeg" | "image/png" | "image/gif" | "image/webp")[]; // at least 1
      };
      // at least 1
      reasoningEfforts?: ("none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max")[];
    };
    limits: { contextUnits: number; outputUnits: number };
    pricing:
      | {
        version: "v1";
        currency: string; // max length 3
        unit: "million_model_units";
        rates: {
          input: string; // max length 128
          output: string; // max length 128
          cacheReadInput?: string; // max length 128
          cacheWriteInput?: string; // max length 128
        };
      }
      | { version: "unknown" };
    defaults: {
      temperature?: number;
      topP?: number; // max 1
      maxOutputUnits?: number; // min 1
      stopSequences?: string[]; // at least 1
      seed?: number;
      reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    };
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/runtime/models/refresh

Refresh provider models. Re-discovers models from the provider (one, or every discovery provider) and returns the resulting catalog. Connecting a provider, and a prompt naming a model the catalog lacks, refresh the same way.

Operation ID: refreshProviderModels

Request body (application/json):

{ providerId?: string /* max length 128 */ }

Response 200 (application/json):

{
  providers: {
    providerId: string; // max length 128
    status: "updated" | "unchanged" | "failed";
    message?: string;
  }[];
  snapshot: {
    hostRevision: string; // max length 128
    defaultModel?: string; // max length 641
    providers: {
      id: string; // max length 128
      displayName: string; // max length 256
      availability:
        | { status: "available" }
        | {
          status: "unavailable";
          reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
        };
    }[];
    models: {
      providerId: string; // max length 128
      ref: string; // max length 641
      id: string; // max length 512
      upstreamId: string; // max length 512
      displayName: string; // max length 256
      capabilities: {
        input: ("text" | "image")[]; // at least 1
        output: "text"[]; // at least 1
        tools: boolean;
        image?: {
          referenceTypes: ("url" | "base64")[]; // at least 1
          mimeTypes: ("image/jpeg" | "image/png" | "image/gif" | "image/webp")[]; // at least 1
        };
        // at least 1
        reasoningEfforts?: ("none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max")[];
      };
      limits: { contextUnits: number; outputUnits: number };
      pricing:
        | {
          version: "v1";
          currency: string; // max length 3
          unit: "million_model_units";
          rates: {
            input: string; // max length 128
            output: string; // max length 128
            cacheReadInput?: string; // max length 128
            cacheWriteInput?: string; // max length 128
          };
        }
        | { version: "unknown" };
      defaults: {
        temperature?: number;
        topP?: number; // max 1
        maxOutputUnits?: number; // min 1
        stopSequences?: string[]; // at least 1
        seed?: number;
        reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      };
      availability:
        | { status: "available" }
        | {
          status: "unavailable";
          reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
        };
    }[];
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/runtime/models/events

Stream runtime model revision events. Streams revision-only SSE events whenever the runtime model catalog revision changes.

Operation ID: modelEvents

Response 200: no body.

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/runtime/providers

List runtime providers. Returns safe runtime provider summaries and connection status.

Operation ID: providers

Response 200 (application/json):

{
  providers: {
    id: string; // max length 128
    displayName: string;
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
    source: "stored" | "environment" | "none" | "via";
    via?: string; // max length 128
    connection?: {
      connectionId: string; // max length 128
      providerId: string; // max length 128
      label: string; // max length 256
      method: "api_key" | "oauth";
      status: "ready" | "reconnect_required";
      createdAt: number;
      updatedAt: number;
    };
    methods: ("api_key" | "oauth")[];
    logins: {
      id: string;
      label: string;
      notice?: { text: string; links: { label: string; url: string }[] };
    }[];
  }[];
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/runtime/providers/{providerId}

Get runtime provider. Returns a safe runtime provider summary by ID.

Operation ID: getProvider

Response 200 (application/json):

{
  provider: {
    id: string; // max length 128
    displayName: string;
    availability:
      | { status: "available" }
      | {
        status: "unavailable";
        reason: "missing_credentials" | "reconnect_required" | "disabled" | "unsupported" | "temporarily_unavailable";
      };
    source: "stored" | "environment" | "none" | "via";
    via?: string; // max length 128
    connection?: {
      connectionId: string; // max length 128
      providerId: string; // max length 128
      label: string; // max length 256
      method: "api_key" | "oauth";
      status: "ready" | "reconnect_required";
      createdAt: number;
      updatedAt: number;
    };
    methods: ("api_key" | "oauth")[];
    logins: {
      id: string;
      label: string;
      notice?: { text: string; links: { label: string; url: string }[] };
    }[];
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/runtime/providers/{providerId}/connect/key

Connect provider API key. Stores an API key for the provider, replacing any previous key atomically.

Operation ID: connectProviderKey

Request body (application/json):

{ apiKey: string; label?: string /* max length 256 */ }

Response 200 (application/json):

{
  connection: {
    connectionId: string; // max length 128
    providerId: string; // max length 128
    label: string; // max length 256
    method: "api_key" | "oauth";
    status: "ready" | "reconnect_required";
    createdAt: number;
    updatedAt: number;
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

POST /v1/runtime/providers/{providerId}/logins

Start provider login. Starts a host-held login and returns the prompt to show the user. The host completes the provider exchange.

Operation ID: startProviderLogin

Request body (application/json):

{ methodId?: string }

Response 200 (application/json):

| {
    status: "pending";
    loginId: string; // max length 128
    methodId: string;
    prompt: { kind: "device"; verificationUrl: string; userCode: string };
    expiresAt: number | "Infinity" | "-Infinity" | "NaN";
  }
  | {
    status: "connected";
    loginId: string; // max length 128
    connection: {
      connectionId: string; // max length 128
      providerId: string; // max length 128
      label: string; // max length 256
      method: "api_key" | "oauth";
      status: "ready" | "reconnect_required";
      createdAt: number;
      updatedAt: number;
    };
  }
  | {
    status: "failed";
    loginId: string; // max length 128
    reason: "denied" | "expired" | "cancelled" | "error";
    message: string;
  }

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

GET /v1/runtime/providers/{providerId}/logins/{loginId}

Get provider login. Returns the login status, optionally waiting up to waitMs for it to change.

Operation ID: getProviderLogin

Response 200 (application/json):

| {
    status: "pending";
    loginId: string; // max length 128
    methodId: string;
    prompt: { kind: "device"; verificationUrl: string; userCode: string };
    expiresAt: number | "Infinity" | "-Infinity" | "NaN";
  }
  | {
    status: "connected";
    loginId: string; // max length 128
    connection: {
      connectionId: string; // max length 128
      providerId: string; // max length 128
      label: string; // max length 256
      method: "api_key" | "oauth";
      status: "ready" | "reconnect_required";
      createdAt: number;
      updatedAt: number;
    };
  }
  | {
    status: "failed";
    loginId: string; // max length 128
    reason: "denied" | "expired" | "cancelled" | "error";
    message: string;
  }

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

DELETE /v1/runtime/providers/{providerId}/logins/{loginId}

Cancel provider login. Cancels a pending login.

Operation ID: cancelProviderLogin

Response 200 (application/json):

| {
    status: "pending";
    loginId: string; // max length 128
    methodId: string;
    prompt: { kind: "device"; verificationUrl: string; userCode: string };
    expiresAt: number | "Infinity" | "-Infinity" | "NaN";
  }
  | {
    status: "connected";
    loginId: string; // max length 128
    connection: {
      connectionId: string; // max length 128
      providerId: string; // max length 128
      label: string; // max length 256
      method: "api_key" | "oauth";
      status: "ready" | "reconnect_required";
      createdAt: number;
      updatedAt: number;
    };
  }
  | {
    status: "failed";
    loginId: string; // max length 128
    reason: "denied" | "expired" | "cancelled" | "error";
    message: string;
  }

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

PATCH /v1/runtime/providers/{providerId}/connections/{connectionId}

Update provider connection label. Updates the metadata label for a provider connection.

Operation ID: updateProviderConnection

Request body (application/json):

{ label: string /* max length 256 */ }

Response 200 (application/json):

{
  connection: {
    connectionId: string; // max length 128
    providerId: string; // max length 128
    label: string; // max length 256
    method: "api_key" | "oauth";
    status: "ready" | "reconnect_required";
    createdAt: number;
    updatedAt: number;
  };
}

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

DELETE /v1/runtime/providers/{providerId}/connections/{connectionId}

Delete provider connection. Deletes the provider connection by matching provider ID and connection ID.

Operation ID: deleteProviderConnection

Response 200 (application/json):

{ success: boolean }

Errors: 400 ValidationErrorEncoded, 401 UnauthorizedErrorEncoded, 403 ForbiddenErrorEncoded, 404 NotFoundErrorEncoded, 409 ConflictErrors, 500 InternalServerErrorEncoded, 503 UnavailableErrorEncoded.

Shared schemas

UnauthorizedErrorEncoded

{ _tag: "UnauthorizedError"; message: string }

UnavailableErrorEncoded

{
  _tag: "UnavailableError";
  message: string;
  reason?: "model_unavailable" | "service_unavailable";
}

InternalServerErrorEncoded

{ _tag: "InternalServerError"; message: string }

ConflictErrors

| ConflictErrorEncoded
  | SteerConflictErrorEncoded
  | TurnNotActiveErrorEncoded
  | TurnNotSteerableErrorEncoded

TurnNotSteerableErrorEncoded

{ _tag: "TurnNotSteerableError"; message: string }

TurnNotActiveErrorEncoded

{ _tag: "TurnNotActiveError"; message: string }

SteerConflictErrorEncoded

{ _tag: "SteerConflictError"; message: string }

ConflictErrorEncoded

{ _tag: "ConflictError"; message: string }

NotFoundErrorEncoded

{
  _tag: "NotFoundError";
  message: string;
  resource?: "session" | "turn" | "tool_call" | "mcp_server" | "mcp_prompt" | "mcp_resource" | "context_compaction" | "permission_request" | "question_request" | "saved_permission" | "endpoint" | "provider_login" | "provider" | "connection";
}

ForbiddenErrorEncoded

{ _tag: "ForbiddenError"; message: string }

ValidationErrorEncoded

{ _tag: "ValidationError"; message: string }