API reference

CreateSessionRequest

no additional properties

• interaction object or object required

CreateSessionResponse

no additional properties

• id string required

  pattern ^ses_[0-9A-HJKMNP-TV-Z]{26}$

• revision integer required

  minimum 1

• human_url string required

SessionResponse

no additional properties

• id string required

  pattern ^ses_[0-9A-HJKMNP-TV-Z]{26}$

• revision integer required

  minimum 1

• interaction object required

  no additional properties

  • mode "display" required

  • title string required

    min length 1 · max length 200 · pattern \S

  • description string optional

    max length 4000

  • source object required

    no additional properties

    • kind "data" required

    • data map of string to string or number or boolean or null or map of string to string or number or boolean or null or array of map of string to string or number or boolean or null required

      min properties 1

InteractiveSessionResponse

no additional properties

• id string required

  pattern ^ses_[0-9A-HJKMNP-TV-Z]{26}$

• status "active" or "responded" or "completed" required

• revision integer required

  The current Surface revision.

  minimum 1

• interaction object required

  no additional properties

  • mode "interactive" required

  • title string required

    min length 1 · max length 200 · pattern \S

  • description string optional

    max length 4000

  • source object required

    no additional properties

    • kind "sess_surface" required

    • components array of object or object or object or object required

  • actions array of object required

    no additional properties

    • id string required

      pattern ^[a-z][a-z0-9_]{0,31}$

    • label string required

      min length 1 · max length 200 · pattern \S

    • intent "submit" or "continue" or "approve" or "reject" or "request_change" optional

  • response_policy "first" required

• response_schema object required

  The JSON Schema 2020-12 the current revision’s responses are validated against.

• responses array of object required

  Every accepted response, in sequence order, each bound to its revision.

  no additional properties

  • event_id string required

    pattern ^evt_[0-9A-HJKMNP-TV-Z]{26}$

  • sequence integer required

    Monotonic per-Session Event sequence.

    minimum 1

  • revision integer required

    The Surface revision it was accepted on.

    minimum 1

  • action_id string required

    pattern ^[a-z][a-z0-9_]{0,31}$

  • data object required

    The normalized typed result, valid against that revision’s response_schema.

  • actor object required

    no additional properties

    • assurance "link_holder" required

  • accepted_at string required

    ISO 8601 UTC time of acceptance.

  • receipt string or null required

    The signed decision receipt: a compact JWS (EdDSA/Ed25519, typ sess-receipt+jwt, kid) over the RFC 8785 canonical claims, verifiable with GET /.well-known/sess-receipt-keys.json. Issued once in the acceptance transaction and never re-signed. Its exp is at least 720 hours after acceptance and, for an owner-key Session that is purged automatically, no earlier than the Session’s latest possible purge (its human link’s expiry plus its retention after it ends). null only for responses accepted before receipts existed.

InteractiveSurfaceResponse

no additional properties

• id string required

  pattern ^ses_[0-9A-HJKMNP-TV-Z]{26}$

• revision integer required

  minimum 1

• interaction object required

  no additional properties

  • mode "interactive" required

  • title string required

    min length 1 · max length 200 · pattern \S

  • description string optional

    max length 4000

  • source object required

    no additional properties

    • kind "sess_surface" required

    • components array of object or object or object or object required

  • actions array of object required

    no additional properties

    • id string required

      pattern ^[a-z][a-z0-9_]{0,31}$

    • label string required

      min length 1 · max length 200 · pattern \S

    • intent "submit" or "continue" or "approve" or "reject" or "request_change" optional

  • response_policy "first" required

• response_schema object required

SessionEventsResponse

no additional properties

• id string required

  pattern ^ses_[0-9A-HJKMNP-TV-Z]{26}$

• events array of object required

  Every Event of the Session, in sequence order (append-only; never rewritten).

  no additional properties

  • event_id string required

    pattern ^evt_[0-9A-HJKMNP-TV-Z]{26}$

  • sequence integer required

    Monotonic per-Session sequence.

    minimum 1

  • type "response.accepted" or "revision.published" or "session.completed" required

  • revision integer required

    response.accepted: the revision the response was accepted on; revision.published: the revision published; session.completed: the current revision at completion.

    minimum 1

  • actor object required

    no additional properties

    • assurance "link_holder" or "owner" required

  • action_id string optional

    pattern ^[a-z][a-z0-9_]{0,31}$

  • data object optional

    response.accepted only: the typed result, valid against that revision.

  • created_at string required

    ISO 8601 UTC time the Event was recorded.

  • receipt string or null optional

    The signed decision receipt: a compact JWS (EdDSA/Ed25519, typ sess-receipt+jwt, kid) over the RFC 8785 canonical claims, verifiable with GET /.well-known/sess-receipt-keys.json. Issued once in the acceptance transaction and never re-signed. Its exp is at least 720 hours after acceptance and, for an owner-key Session that is purged automatically, no earlier than the Session’s latest possible purge (its human link’s expiry plus its retention after it ends). null only for responses accepted before receipts existed.

ReceiptKeysResponse

no additional properties

• keys array of object required

  The active signing key and every retained verification key (rotation overlap). A receipt verifies with the key whose kid its protected header names; there is no fallback key.

  no additional properties

  • kty "OKP" required

  • crv "Ed25519" required

  • x string required

  • kid string required

    pattern ^[A-Za-z0-9._-]{1,64}$

  • alg "EdDSA" required

  • use "sig" required

WebhookRegisterRequest

no additional properties

• url string required

  Absolute https:// URL on port 443, without user info or fragment. Registering replaces the current endpoint (which stops receiving new deliveries); the new one receives nothing until verified.

  min length 1 · max length 2048

WebhookRegisterResponse

no additional properties

• endpoint object required

  no additional properties

  • id string required

    pattern ^whe_[0-9A-HJKMNP-TV-Z]{26}$

  • url string required

  • status "pending" or "verified" required

  • created_at string required

  • verified_at string or null required

  • verification_expires_at string or null required

    The verification lapses 30 days after it succeeds; after that the endpoint is pending again (no new deliveries; queued ones fail endpoint_unavailable) until re-verified.

• signing_secret object or null required

  The workspace’s first signing secret when this registration created it, else null.

WebhookResponse

no additional properties

• endpoint object or null required

• signing_secrets array of object required

  Secrets in force, newest first (never the secret values).

  no additional properties

  • kid string required

  • active boolean required

  • retire_at string or null required

• deliveries object required

  no additional properties

  • pending integer required

    minimum 0

  • failed integer required

    minimum 0

  • delivered integer required

    minimum 0

  • oldest_pending_age_seconds integer or null required

WebhookRotateResponse

no additional properties

• signing_secret object required

  no additional properties

  • kid string required

    pattern ^wk_[0-9A-HJKMNP-TV-Z]{26}$

  • secret string required

    Shown once. Store it in the receiver; Sess keeps it only encrypted.

    pattern ^whsec_[A-Za-z0-9+/]{43}=$

• previous object or null required

DeliveriesResponse

no additional properties

• id string required

• deliveries array of object required

  no additional properties

  • delivery_id string required

    pattern ^obx_[0-9A-HJKMNP-TV-Z]{26}$

  • event_id string required

  • kind "accepted" or "redelivery" required

  • status "pending" or "delivered" or "failed" required

  • endpoint_id string required

  • next_attempt_at string or null required

  • deadline_at string required

  • created_at string required

  • finished_at string or null required

  • last_outcome "started" or "delivered" or "server_error" or "rate_limited" or "timeout" or "connection" or "dns" or "signing_unavailable" or "request_timeout" or "too_early" or "rejected" or "redirect" or "egress_refused" or "endpoint_unavailable" or "exhausted" or null required

    The job-level outcome: the last attempt’s, or exhausted when the attempt or time budget ran out, or endpoint_unavailable when its endpoint was replaced, disabled or its verification lapsed.

  • attempts array of object required

    Every started attempt. started with no finish time: the attempt was interrupted (e.g. a crash); the outcome at the endpoint is unknown and the job is retried.

    no additional properties

    • attempt integer required

      minimum 1

    • started_at string required

    • finished_at string or null required

    • outcome "started" or "delivered" or "server_error" or "rate_limited" or "timeout" or "connection" or "dns" or "signing_unavailable" or "request_timeout" or "too_early" or "rejected" or "redirect" or "egress_refused" or "endpoint_unavailable" or "exhausted" required

    • http_status integer or null required

WebhookDelivery

no additional properties

• type "response.accepted" required

• event_id string required

  Stable across retries and redeliveries: deduplicate on it.

• session_id string required

• sequence integer required

• revision integer required

• action_id string required

• data object required

• accepted_at string required

• receipt string or null required

  The stored signed decision receipt (identical on every delivery).

WebhookVerification

no additional properties

• type "sess.webhook.verification" required

• challenge string required

PatchSessionRequest

no additional properties

• interaction object required

  no additional properties

  • mode "interactive" required

  • title string required

    min length 1 · max length 200 · pattern \S

  • description string optional

    max length 4000

  • source object required

    no additional properties

    • kind "sess_surface" required

    • components array of object required

      min items 1 · max items 100

      • type string required

        min length 1 · max length 64

  • actions array of object required

    min items 1 · max items 5

    no additional properties

    • id string required

      pattern ^[a-z][a-z0-9_]{0,31}$

    • label string required

      min length 1 · max length 200 · pattern \S

    • intent "submit" or "continue" or "approve" or "reject" or "request_change" optional

  • response_policy "first" optional

    One accepted response per revision (the only P1 policy; the default).

SurfaceComponent

Type: object or object or object or object

HumanSubmissionForm

properties named ^data\.[a-z][a-z0-9_]{0,63}$: string · no additional properties

• client_event_id string required

  pattern ^[A-Za-z0-9_-]{16,64}$

• surface_revision string required

  pattern ^[1-9][0-9]{0,8}$

• action_id string required

  pattern ^[a-z][a-z0-9_]{0,31}$

Error

no additional properties

• error object required

  no additional properties

  • code "INVALID_SCHEMA" or "PAYLOAD_TOO_LARGE" or "UNAUTHORIZED" or "SESSION_NOT_FOUND" or "NOT_FOUND" or "INTERNAL" or "UNKNOWN_COMPONENT" or "SESSION_REVISION_CONFLICT" or "IDEMPOTENCY_CONFLICT" or "PRECONDITION_REQUIRED" or "SESSION_COMPLETED" or "ACTION_NOT_ALLOWED" or "ACTION_NOT_FOUND" or "VALIDATION_FAILED" or "RESPONSE_LIMIT_REACHED" or "SERVICE_UNAVAILABLE" or "RATE_LIMITED" or "TRIAL_UNAVAILABLE" or "SIGN_IN_UNAVAILABLE" or "WEBHOOK_INVALID_URL" or "WEBHOOK_VERIFICATION_FAILED" or "WEBHOOK_NOT_CONFIGURED" required

  • message string required

  • request_id string required

    min length 1

  • reason string optional

    A stable machine-readable refinement of some codes (P1 A4 webhook errors).

    pattern ^[a-z_]{1,40}$

HealthOk

no additional properties

• status "ok" required

HealthUnavailable

no additional properties

• status "unavailable" required

VersionResponse

no additional properties

• git_sha string or null required

  The deployed commit, from SESS_GIT_SHA. null when SESS_GIT_SHA is missing, empty or not exactly 40 lower-case hex characters; readiness then answers 503. Never derived from a checkout or normalized.

• build_id string or null required

  SESS_BUILD_ID, else the BUILD_ID file at the workspace root of the image. null when neither supplies a valid one; readiness then answers 503.

• build_time string or null required

  ISO 8601 UTC build time, from SESS_BUILD_TIME, else the BUILD_TIME file at the workspace root of the image. Valid when it has real calendar components and is not more than 5 s after the current time, checked on every request. null when neither supplies a valid one, and readiness then answers 503; never the start time.

• node_version string required

  The Node.js version (process.version).

TrialCreateSessionRequest

no additional properties

• interaction object required

  no additional properties

  • mode "interactive" required

  • title string required

    min length 1 · max length 200 · pattern \S

  • description string optional

    max length 4000

  • source object required

    no additional properties

    • kind "sess_surface" required

    • components array of object required

      min items 1 · max items 100

      • type string required

        min length 1 · max length 64

  • actions array of object required

    min items 1 · max items 5

    no additional properties

    • id string required

      pattern ^[a-z][a-z0-9_]{0,31}$

    • label string required

      min length 1 · max length 200 · pattern \S

    • intent "submit" or "continue" or "approve" or "reject" or "request_change" optional

  • response_policy "first" optional

    One accepted response per revision (the only P1 policy; the default).

TrialCreateSessionResponse

no additional properties

• id string required

  pattern ^ses_[0-9A-HJKMNP-TV-Z]{26}$

• revision integer required

  minimum 1

• human_url string required

  The human link (a capability): share it only with the responder.

• workspace_id string required

  The trial workspace this Session belongs to.

• management_credential string optional

  Returned once, only when this request created the trial (no Authorization header). It reads this trial’s results and creates further Sessions in it; it is never retrievable again. Keep it secret; never put it in a URL.

  pattern ^sess_mg_[A-Za-z0-9_-]{43}$

• action_expires_at string required

  After this instant the human link accepts no response.

• result_available_until string required

  Until this instant the result can be read with the management credential.

• trial_expires_at string required

  After this instant the trial creates no further Session.

TrialSessionResponse

no additional properties

• id string required

  pattern ^ses_[0-9A-HJKMNP-TV-Z]{26}$

• status "active" or "responded" or "completed" required

• revision integer required

  The current Surface revision.

  minimum 1

• interaction object required

  no additional properties

  • mode "interactive" required

  • title string required

    min length 1 · max length 200 · pattern \S

  • description string optional

    max length 4000

  • source object required

    no additional properties

    • kind "sess_surface" required

    • components array of object or object or object or object required

  • actions array of object required

    no additional properties

    • id string required

      pattern ^[a-z][a-z0-9_]{0,31}$

    • label string required

      min length 1 · max length 200 · pattern \S

    • intent "submit" or "continue" or "approve" or "reject" or "request_change" optional

  • response_policy "first" required

• response_schema object required

  The JSON Schema 2020-12 the current revision’s responses are validated against.

• responses array of object required

  Every accepted response, in sequence order, each bound to its revision.

  no additional properties

  • event_id string required

    pattern ^evt_[0-9A-HJKMNP-TV-Z]{26}$

  • sequence integer required

    Monotonic per-Session Event sequence.

    minimum 1

  • revision integer required

    The Surface revision it was accepted on.

    minimum 1

  • action_id string required

    pattern ^[a-z][a-z0-9_]{0,31}$

  • data object required

    The normalized typed result, valid against that revision’s response_schema.

  • actor object required

    no additional properties

    • assurance "link_holder" required

  • accepted_at string required

    ISO 8601 UTC time of acceptance.

  • receipt string or null required

    The signed decision receipt: a compact JWS (EdDSA/Ed25519, typ sess-receipt+jwt, kid) over the RFC 8785 canonical claims, verifiable with GET /.well-known/sess-receipt-keys.json. Issued once in the acceptance transaction and never re-signed. Its exp is at least 720 hours after acceptance and, for an owner-key Session that is purged automatically, no earlier than the Session’s latest possible purge (its human link’s expiry plus its retention after it ends). null only for responses accepted before receipts existed.

• trial object required

  no additional properties

  • workspace_id string required

  • action_expires_at string required

    After this instant the human link accepts no response.

  • result_available_until string required

    Until this instant this result remains readable.

EmailLinkRequest

no additional properties

• email string required

  The address to send a sign-in link to. Trimmed and lower-cased.

  min length 3 · max length 254

EmailLinkAccepted

no additional properties

• status "accepted" required

  The link was handed to the email provider. The same answer for every address: it never says whether an account exists.