Skip to content

HTTP API conventions ​

Supply a service key through Authorization: Bearer …. In examples, ORPHEUS_URL is the server origin and method paths start with /api/v1.

Requests ​

  • Set Content-Type: application/json for JSON bodies.
  • Use Idempotency-Key for session creation, run creation and clarifications.
  • 202 confirms admission. Read run state to obtain the outcome.
  • Timestamps use RFC3339. Session and run identifiers are UUIDs.
  • Cursors are opaque. Follow next_cursor and has_more where present. Start from the first page after changing filters.

Errors ​

HTTPCheck
400Request or cursor format
401Bearer key or browser session
403Access mode, browser Origin and CSRF for template changes
404Resource identifier
409Session state, idempotency conflict or exhausted budget
413Request size
415Content-Type
422Field paths in error.details
503Execution capacity or service availability

Read error.code for the exact category. Retry uncertain transport outcomes with the same body and key. Fix invalid requests before retrying.

An explicitly invalid Authorization header does not fall back to browser authentication. Empty PUBLIC_API_KEYS disables service commands in anonymous and saml modes.

Complete reference · Reliable integration

Service selection ​

Service codes are order-insensitive and must be unique. An unknown code returns 422 unknown_service before acceptance. A retry with the same idempotency key and input replays the accepted result without consulting the current catalog. Responses contain immutable service snapshots and the combined ENV names, never secret values.

Stored agent output ​

Actual NUL characters in stored agent messages and tool JSON inputs/results are replaced with Unicode U+FFFD (�). This lets history remain readable when agent output contains such characters. Literal text containing a backslash followed by u0000 is preserved.

Template selection ​

New sessions require the exact name of an active catalog entry. Unknown and inactive names return 422 unknown_template, with template_not_found or template_inactive in error.details. Accepted sessions and idempotent replays keep their saved name. Continuation runs do not recheck the catalog.

The template list returns items, next_cursor and prev_cursor, with a default limit of 50 and a maximum of 200. Use active, exact name or literal name_contains filters. The name filters cannot be combined. Keep filters unchanged when following a cursor.