> ## Documentation Index > Fetch the complete documentation index at: https://docs.albus.sh/llms.txt > Use this file to discover all available pages before exploring further. # Run or resume a session > Runs the session with the given ID, creating it if it does not exist and resuming it otherwise. Each call is a single invocation, optionally identified by the Idempotency-Key header. Supplying a key makes the call safe to retry: retrying with the same key and an identical body re-attaches to the in-flight invocation and returns its current state; a differing body for the same key returns 409; a new key while another invocation is still running returns 423. Omitting the header starts a fresh, non-idempotent invocation each time; the server generates a key and returns it in the Idempotency-Key response header. With `wait=true` the request long-polls: it blocks until the invocation's assistant response is available and returns it in `messages`. `wait_timeout` bounds the wait in seconds; when omitted the request waits indefinitely (until the response arrives or the client disconnects). If the timeout elapses first, the request fails with 504 and a JSON body, letting the client distinguish an expected server-side timeout from a transport error; the client may retry. ## OpenAPI ````yaml /openapi/openapi.yaml post /sessions/{id} openapi: 3.0.3 info: title: Albus API description: Albus service REST API version: 1.0.0 servers: - url: https://albus.sh/api description: Production server - url: http://localhost:8080 description: Local development server security: - bearerAuth: [] - apiKeyAuth: [] tags: - name: Auth description: Identify the authenticated user. - name: Health description: Check service availability. - name: Secrets description: Manage secrets available to agent sessions. - name: Sessions description: Run and inspect agent sessions. - name: Tokens description: Manage organization API keys. paths: /sessions/{id}: parameters: - $ref: '#/components/parameters/SessionID' post: tags: - Sessions summary: Run or resume a session description: > Runs the session with the given ID, creating it if it does not exist and resuming it otherwise. Each call is a single invocation, optionally identified by the Idempotency-Key header. Supplying a key makes the call safe to retry: retrying with the same key and an identical body re-attaches to the in-flight invocation and returns its current state; a differing body for the same key returns 409; a new key while another invocation is still running returns 423. Omitting the header starts a fresh, non-idempotent invocation each time; the server generates a key and returns it in the Idempotency-Key response header. With `wait=true` the request long-polls: it blocks until the invocation's assistant response is available and returns it in `messages`. `wait_timeout` bounds the wait in seconds; when omitted the request waits indefinitely (until the response arrives or the client disconnects). If the timeout elapses first, the request fails with 504 and a JSON body, letting the client distinguish an expected server-side timeout from a transport error; the client may retry. operationId: runSession parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/Wait' - $ref: '#/components/parameters/WaitTimeout' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunSessionRequest' responses: '200': description: Session run or resumed headers: Idempotency-Key: description: > The effective idempotency key for this invocation — the value sent in the request header, or a server-generated one when the header was omitted. Use it to reference or safely retry this invocation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/SessionResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrBadRequest' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrUnauthorized' '409': description: Idempotency key reused with a different request body content: application/json: schema: $ref: '#/components/schemas/ErrConflict' '423': description: Another invocation is currently running for this session content: application/json: schema: $ref: '#/components/schemas/ErrLocked' '429': description: The organization has reached its invocation quota content: application/json: schema: $ref: '#/components/schemas/ErrQuotaExceeded' '502': description: > The harness run failed instead of producing a response (only possible with wait=true, or when replaying a failed invocation). The body carries the failure kind and detail. content: application/json: schema: $ref: '#/components/schemas/ErrRunFailed' '504': description: Timed out waiting for the assistant response content: application/json: schema: $ref: '#/components/schemas/ErrTimeout' security: - bearerAuth: [] - apiKeyAuth: [] components: parameters: SessionID: name: id in: path required: true description: >- Client-provided session identifier. Use the same value across requests to continue the same agent session. schema: type: string minLength: 2 maxLength: 100 pattern: ^[0-9a-zA-Z._:-]+$ IdempotencyKey: name: Idempotency-Key in: header required: false description: > Optional but strongly encouraged. Uniquely identifies this invocation of the session; reuse the same value to safely retry a request, and a new value starts a new invocation. When omitted, the server generates a key for the invocation and returns it in the Idempotency-Key response header, but the request is not retry-safe. schema: type: string minLength: 1 maxLength: 255 Wait: name: wait in: query required: false description: > When true, long-poll: block until the invocation's assistant response is available before returning. schema: type: boolean default: false WaitTimeout: name: wait_timeout in: query required: false description: > Maximum time in seconds to block when wait=true. Omit to wait indefinitely. Ignored when wait is false. schema: type: integer format: int64 minimum: 1 schemas: RunSessionRequest: type: object required: - user_prompt - model properties: user_prompt: type: string description: The user prompt driving this invocation. model: $ref: '#/components/schemas/Model' tools: type: array items: type: string description: Names of the tools the model may call (e.g. "WEB_SEARCH"). system_prompt: type: string description: System instructions for the model. Uses a default if omitted. max_steps: type: integer minimum: 1 description: Max model steps before the run stops. Uses a default if omitted. mcp_servers: type: array items: $ref: '#/components/schemas/MCPServer' description: MCP servers whose tools are offered to the model. SessionResponse: type: object required: - session - messages properties: session: $ref: '#/components/schemas/Session' messages: type: array items: $ref: '#/components/schemas/SessionMessage' ErrBadRequest: type: object required: - message properties: message: type: string description: Human-readable error message example: Invalid request parameters ErrUnauthorized: type: object required: - message properties: message: type: string description: Human-readable error message example: Invalid or expired token ErrConflict: type: object required: - message properties: message: type: string description: Human-readable error message example: Idempotency key reused with a different request body ErrLocked: type: object required: - message properties: message: type: string description: Human-readable error message example: Another invocation is currently running for this session ErrQuotaExceeded: type: object required: - message properties: message: type: string description: Human-readable error message example: organization invocation quota exceeded ErrRunFailed: type: object required: - message - kind properties: message: type: string description: Human-readable failure detail example: 'harness run failed (crash): signal 9' kind: type: string description: > Failure classification: "crash" (unexpected exit or signal), "no_progress" (the harness stalled and was force-killed), or "interrupted" (the run could not continue), or "internal" (the run could not start). example: crash ErrTimeout: type: object required: - message properties: message: type: string description: Human-readable error message example: Timed out waiting for the assistant response Model: type: object required: - name properties: name: type: string description: Model identifier (e.g. "gemini-2.5-flash", "claude-opus-4"). provider: $ref: '#/components/schemas/Provider' MCPServer: type: object required: - name - url properties: name: type: string description: > Unique alias for the server. It prefixes the server's tool names (e.g. "github" exposes its search tool as "github__search"). url: type: string description: The server's Streamable HTTP endpoint. headers: type: object additionalProperties: type: string description: > HTTP headers sent to the server. Values are secret references (e.g. "albus.sh/secrets/github-mcp"), not raw secret values. allowed_tools: type: array items: type: string description: | The server tools the model may call. Omit to allow all of them. Session: type: object required: - id - state - invocation_count - created_at - updated_at properties: id: type: string minLength: 2 maxLength: 100 pattern: ^[0-9a-zA-Z._:-]+$ description: Client-provided session identifier. state: type: string enum: - RUNNING - DONE - FAILED - CANCELED description: Lifecycle state of the session. current_invocation_id: type: string description: > The invocation currently running, if any. Omitted when the session is idle. invocation_count: type: integer format: int64 description: Number of times this session has been run. created_at: type: string format: date-time updated_at: type: string format: date-time SessionMessage: type: object required: - cursor - invocation_id - role - content - created_at properties: cursor: type: integer format: int64 description: Monotonic per-session position of this message. invocation_id: type: string description: The invocation that produced this message. role: type: string enum: - user - assistant content: type: string created_at: type: string format: date-time Provider: type: object required: - name - credential properties: name: type: string description: Provider name (e.g. "openai", "gemini", "vertex"). url: type: string description: Optional base URL override for the provider endpoint. credential: type: string description: > Secret reference the provider authenticates with (e.g. "albus.sh/secrets/my-key"), not a raw secret value. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT apiKeyAuth: type: http scheme: bearer description: Org-scoped API key issued via POST /tokens ````