---
openapi: 3.0.3
info:
  title: Orpheus Space API
  version: 0.1.0
  description: Schedule management and stored history. Catalog and result endpoints read Orpheus synchronously; writes validate new profile, template and service selections.
  license:
    name: GNU Affero General Public License v3.0 only
    url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: http://localhost:8010
security:
- bearerAuth: []
- browserSession: []
- {}
tags:
- name: Schedules
  description: Shared schedules, settings and cron preview.
- name: Catalogs
  description: Available profiles, templates and services from Orpheus.
- name: Auth
  description: Browser access mode.
paths:
  "/api/v1/schedules":
    get:
      operationId: ListSchedules
      summary: List schedules
      tags:
      - Schedules
      parameters:
      - "$ref": "#/components/parameters/OwnerEmail"
      - "$ref": "#/components/parameters/Unowned"
      - "$ref": "#/components/parameters/Status"
      - "$ref": "#/components/parameters/Limit"
      - "$ref": "#/components/parameters/Cursor"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SchedulePage"
        default:
          "$ref": "#/components/responses/Problem"
    post:
      operationId: CreateSchedule
      summary: Create a schedule
      description: SAML non-admins can create only for their own email; an omitted owner is filled from the session. Explicit null or another owner returns 403 schedule_forbidden. Bearer, anonymous and admins have full access.
      tags:
      - Schedules
      parameters:
      - "$ref": "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateSchedule"
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Schedule"
        default:
          "$ref": "#/components/responses/Problem"
  "/api/v1/schedules/{id}":
    parameters:
    - "$ref": "#/components/parameters/ID"
    get:
      operationId: GetSchedule
      summary: Get a schedule including deleted records
      tags:
      - Schedules
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Schedule"
        default:
          "$ref": "#/components/responses/Problem"
    patch:
      operationId: UpdateSchedule
      summary: Update selected schedule fields
      description: SAML non-admins can update only their own schedules and cannot change or clear the owner. Denied writes return 403 schedule_forbidden.
      tags:
      - Schedules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpdateSchedule"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Schedule"
        default:
          "$ref": "#/components/responses/Problem"
    delete:
      operationId: DeleteSchedule
      summary: Soft delete a schedule
      description: SAML non-admins can delete only their own schedules. Denied writes return 403 schedule_forbidden.
      tags:
      - Schedules
      responses:
        '204':
          description: Success
        default:
          "$ref": "#/components/responses/Problem"
  "/api/v1/profiles":
    get:
      operationId: GetProfiles
      summary: Get a page of Orpheus model profiles
      description: Returns active and inactive profiles. Use available=true for selection and an exact name without availability filters for a stored choice. Name filters are mutually exclusive; cursors are bound to the filters.
      tags: [Catalogs]
      parameters:
      - in: query
        name: active
        schema: {type: boolean}
      - in: query
        name: available
        schema: {type: boolean}
      - in: query
        name: name
        description: Exact case-sensitive profile name.
        schema: {type: string, minLength: 1}
      - in: query
        name: name_contains
        description: Literal case-insensitive substring of the name.
        schema: {type: string, minLength: 1}
      - in: query
        name: limit
        schema: {type: integer, minimum: 1, maximum: 200, default: 50}
      - in: query
        name: cursor
        schema: {type: string, minLength: 1, maxLength: 8192}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Profiles"
        default:
          "$ref": "#/components/responses/Problem"
  "/api/v1/templates":
    get:
      operationId: GetTemplates
      summary: Get a page of Orpheus templates
      description: Returns active and inactive templates. The name filters are mutually exclusive. Cursors are bound to the filters; restart pagination after changing them.
      tags: [Catalogs]
      parameters:
      - in: query
        name: active
        schema: {type: boolean}
      - in: query
        name: name
        description: Exact stored name, including any team slug and tag; case-sensitive.
        schema: {type: string, minLength: 1}
      - in: query
        name: name_contains
        description: Literal case-insensitive substring of the stored name.
        schema: {type: string, minLength: 1}
      - in: query
        name: limit
        schema: {type: integer, minimum: 1, maximum: 200, default: 50}
      - in: query
        name: cursor
        schema: {type: string, minLength: 1, maxLength: 8192}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Templates"
        default:
          "$ref": "#/components/responses/Problem"
  "/api/v1/services":
    get:
      operationId: GetServices
      summary: Get available Orpheus services
      description: All services are available to every caller with read access. Returns ENV names, never values.
      tags: [Catalogs]
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Services"
        default:
          "$ref": "#/components/responses/Problem"
  "/api/v1/schedules/settings":
    get:
      operationId: GetSettings
      summary: Get schedule interface settings
      tags:
      - Schedules
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Settings"
        default:
          "$ref": "#/components/responses/Problem"
  "/api/v1/schedules/preview":
    post:
      operationId: PreviewSchedule
      summary: Preview five future cron occurrences
      tags:
      - Schedules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PreviewInput"
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Preview"
        default:
          "$ref": "#/components/responses/Problem"
  "/api/v1/auth/session":
    get:
      operationId: GetAuthSession
      summary: Get browser access state
      tags:
      - Auth
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AuthSession"
        default:
          "$ref": "#/components/responses/Problem"
  "/api/v1/schedules/{id}/occurrences":
    parameters:
    - "$ref": "#/components/parameters/ID"
    get:
      operationId: ListOccurrences
      summary: Read stored history without calling the core
      tags:
      - Schedules
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OccurrencePage"
        default:
          "$ref": "#/components/responses/Problem"
      parameters:
      - "$ref": "#/components/parameters/Limit"
      - "$ref": "#/components/parameters/Cursor"
  "/api/v1/schedules/{id}/occurrences/{occurrence_id}":
    parameters:
    - "$ref": "#/components/parameters/ID"
    - "$ref": "#/components/parameters/OccurrenceID"
    get:
      operationId: GetOccurrence
      summary: Read a stored occurrence without calling the core
      tags:
      - Schedules
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Occurrence"
        default:
          "$ref": "#/components/responses/Problem"
  "/api/v1/schedules/{id}/occurrences/{occurrence_id}/result":
    parameters:
    - "$ref": "#/components/parameters/ID"
    - "$ref": "#/components/parameters/OccurrenceID"
    get:
      operationId: GetOccurrenceResult
      summary: Explicitly fetch the current result from the Orpheus core
      tags:
      - Schedules
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OccurrenceResult"
        default:
          "$ref": "#/components/responses/Problem"
  "/api/v1/schedules/{id}/run":
    parameters:
    - "$ref": "#/components/parameters/ID"
    post:
      operationId: RunSchedule
      summary: Run a schedule now without changing its timing or activity
      description: Requires permission to edit the schedule. Active and paused schedules can run manually. Returns 409 schedule_busy while an occurrence is unfinished, including an unknown dispatch outcome. A repeated key for this schedule returns the same occurrence with its current state, even after completion or deletion, subject to current permissions. The worker prepares the saved settings through the usual execution path. Acceptance does not mean the agent has started.
      tags:
      - Schedules
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        description: Nonzero UUID identifying this manual command within the schedule. Retrying the same key never creates another occurrence. Keys do not expire.
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: The command was stored, or the same command was already accepted.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Occurrence"
        default:
          "$ref": "#/components/responses/Problem"
  "/api/v1/schedules/{id}/reset-session":
    parameters:
    - "$ref": "#/components/parameters/ID"
    post:
      operationId: ResetSession
      summary: Detach the reusable session for the next occurrence
      description: SAML non-admins can reset only their own schedules. Denied writes return 403 schedule_forbidden.
      tags:
      - Schedules
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Schedule"
        default:
          "$ref": "#/components/responses/Problem"
  /auth/login:
    get:
      operationId: BrowserLogin
      summary: Start SP-initiated SAML login
      security: []
      description: SAML mode only; otherwise 404 auth_not_enabled. next must be a local absolute path (not auth routes); default /api/v1/auth/session. No Host or proxy header trust.
      parameters:
      - in: query
        name: next
        schema:
          type: string
          maxLength: 2048
      responses:
        "302":
          description: Start SP-initiated SAML login
          headers:
            Location:
              schema:
                type: string
              description: SAML IdP URL.
        default:
          description: Invalid return path (400), authentication disabled (404), request validation failed (422), or authentication/storage unavailable (503).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
  /auth/callback:
    post:
      operationId: BrowserCallback
      summary: Consume a signed SAML HTTP-POST response
      security: []
      description: SAML mode only. Body is application/x-www-form-urlencoded with exactly one SAMLResponse and RelayState, at most 1 MiB. One-time request and browser nonce are required. Unsolicited responses are rejected.
      responses:
        "303":
          description: Consume a signed SAML HTTP-POST response
          headers:
            Location:
              schema:
                type: string
              description: Validated local return path.
        default:
          description: Invalid login state (400), invalid SAML response (401), authentication disabled (404), oversized form (413), or authentication/storage unavailable (503).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
  /auth/logout:
    post:
      operationId: BrowserLogout
      summary: Revoke the local browser session
      security: []
      description: Requires the configured Origin and X-Orpheus-CSRF header equal to 1. Idempotent; clears the cookie. Does not terminate the IdP session.
      responses:
        "204":
          description: Revoke the local browser session
        default:
          description: Invalid origin or CSRF header (403), or storage unavailable (503).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
  /saml/metadata:
    get:
      operationId: SamlMetadata
      summary: Read service provider metadata
      security: []
      responses:
        "200":
          description: Read service provider metadata
          content:
            application/samlmetadata+xml:
              schema:
                type: string
        default:
          description: Authentication disabled (404), or metadata unavailable (503).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  securitySchemes:
    browserSession:
      type: apiKey
      in: cookie
      name: __Host-orpheus_space_session
    bearerAuth:
      type: http
      scheme: bearer
  parameters:
    ID:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      schema:
        type: string
        format: uuid
      description: Retries with the same normalized body return the original response.
        Keys do not expire.
    OwnerEmail:
      name: owner_email
      in: query
      style: form
      explode: true
      schema:
        type: array
        items:
          type: string
      description: Repeated email filter; OR semantics, at most 100 distinct normalized
        emails.
    Unowned:
      name: unowned
      in: query
      schema:
        type: boolean
      description: Only schedules without an owner. Cannot be combined with owner_email.
    Status:
      name: status
      in: query
      schema:
        "$ref": "#/components/schemas/Status"
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    Cursor:
      name: cursor
      in: query
      schema:
        type: string
        minLength: 1
        maxLength: 8192
      description: Opaque position bound to normalized filters. New inserts are excluded
        from an ongoing traversal.
    OccurrenceID:
      name: occurrence_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  responses:
    Problem:
      description: Structured API error. 401 credentials, 403 CSRF or schedule_forbidden, 404 missing, 409
        conflict, 422 validation, 503 unavailable.
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Problem"
  schemas:
    Problem:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
          - code
          - message
          - phase
          - details
          properties:
            code:
              type: string
            message:
              type: string
            phase:
              type: string
              nullable: true
            details:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - path
                - code
                properties:
                  path:
                    type: array
                    items:
                      type: string
                  code:
                    type: string
    Status:
      type: string
      enum:
      - active
      - paused
    SessionMode:
      type: string
      enum:
      - new
      - reuse
    ServiceCodes:
      description: Explicit selection of service codes. No defaults; empty clears the selection. Unknown codes return 422 and an unavailable catalog returns 503. Unchanged selections can be preserved without the catalog; resuming validates the full selection.
      type: array
      uniqueItems: true
      items:
        type: string
        pattern: "^[a-z][a-z0-9_-]{0,63}$"
    Service:
      type: object
      additionalProperties: false
      required: [code, name, description, env_from]
      properties:
        code:
          type: string
          pattern: "^[a-z][a-z0-9_-]{0,63}$"
        name: {type: string}
        description: {type: string}
        env_from:
          type: array
          items:
            type: string
          description: Names of worker environment variables included in this service; never values.
    Services:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/Service'}
    Profile:
      type: object
      additionalProperties: false
      required: [id, name, description, harness, account_id, account_name, account_active, active, available, model, codex, instructions, is_default]
      properties:
        id: {type: string, format: uuid}
        account_id: {type: string, format: uuid}
        account_name: {type: string}
        account_active: {type: boolean}
        active: {type: boolean}
        available: {type: boolean}
        name: {type: string}
        description: {type: string, nullable: true}
        harness: {type: string, enum: [codex]}
        model: {type: string, minLength: 1}
        codex: {$ref: '#/components/schemas/CodexProfile'}
        instructions: {type: string}
        is_default: {type: boolean}
    CodexProfile:
      type: object
      additionalProperties: false
      properties:
        effort: {type: string, enum: [none, minimal, low, medium, high, xhigh, max, ultra]}
        summary: {type: string, enum: [auto, concise, detailed, none]}
        personality: {type: string, enum: [none, friendly, pragmatic]}
        service_tier: {type: string, minLength: 1}
    Profiles:
      type: object
      additionalProperties: false
      required: [items, next_cursor, prev_cursor]
      properties:
        next_cursor: {type: string, nullable: true}
        prev_cursor: {type: string, nullable: true}
        items:
          type: array
          items: {$ref: '#/components/schemas/Profile'}
    Template:
      type: object
      additionalProperties: false
      required: [id, name, template_name, tag, description, active, is_default]
      properties:
        id: {type: string, format: uuid}
        name: {type: string}
        template_name: {type: string}
        tag: {type: string, nullable: true}
        description: {type: string, nullable: true}
        active: {type: boolean}
        is_default: {type: boolean}
    Templates:
      type: object
      additionalProperties: false
      required: [items, next_cursor, prev_cursor]
      properties:
        next_cursor: {type: string, nullable: true}
        prev_cursor: {type: string, nullable: true}
        items:
          type: array
          items: {$ref: '#/components/schemas/Template'}
    CreateSchedule:
      type: object
      additionalProperties: false
      required:
      - name
      - prompt
      - cron
      - timezone
      properties:
        profile:
          type: string
          minLength: 1
          description: Exact Orpheus profile name; creation uses the configured default when omitted. Every save except a pure pause requires an active profile and account.
        template:
          type: string
          minLength: 1
          description: Exact Orpheus template name; creation uses the configured default when omitted.
        name:
          type: string
          minLength: 1
          maxLength: 200
        prompt:
          type: string
          minLength: 1
        cron:
          type: string
          minLength: 1
        timezone:
          type: string
          minLength: 1
        status:
          "$ref": "#/components/schemas/Status"
        model:
          type: string
          nullable: true
          minLength: 1
        session_mode:
          "$ref": "#/components/schemas/SessionMode"
        owner_email:
          type: string
          nullable: true
          minLength: 1
          description: SAML non-admins must use their session email; omission fills it, explicit null is forbidden. Full-access callers may use any owner or null.
        services:
          "$ref": "#/components/schemas/ServiceCodes"
    UpdateSchedule:
      type: object
      additionalProperties: false
      properties:
        profile:
          type: string
          minLength: 1
          description: Exact Orpheus profile name; omitted keeps the stored choice; a change starts a new reusable session.
        template:
          type: string
          minLength: 1
          description: Exact Orpheus template name; omitted keeps the stored choice; a change starts a new reusable session.
        name:
          type: string
          minLength: 1
          maxLength: 200
        prompt:
          type: string
          minLength: 1
        cron:
          type: string
          minLength: 1
        timezone:
          type: string
          minLength: 1
        status:
          "$ref": "#/components/schemas/Status"
        model:
          type: string
          nullable: true
          minLength: 1
        session_mode:
          "$ref": "#/components/schemas/SessionMode"
        owner_email:
          type: string
          nullable: true
          minLength: 1
        services:
          "$ref": "#/components/schemas/ServiceCodes"
    Schedule:
      type: object
      additionalProperties: false
      required:
      - id
      - url
      - can_edit
      - name
      - prompt
      - cron
      - timezone
      - status
      - model
      - profile
      - template
      - session_mode
      - owner_email
      - services
      - created_at
      - updated_at
      - next_run_at
      - deleted_at
      - last_occurrence
      properties:
        can_edit:
          type: boolean
          description: Whether this caller may modify the current schedule. False for deleted schedules. Computed from current ownership even on an idempotent creation replay; busy state can still prevent session reset.
        profile:
          type: string
          minLength: 1
          description: Stored Orpheus profile name.
        template:
          type: string
          minLength: 1
          description: Stored Orpheus template name.
        url:
          type: string
          format: uri
          nullable: true
          description: Absolute Space Web card URL from ORPHEUS_PUBLIC_URL, or null when not configured. Computed at response time.
        name:
          type: string
          minLength: 1
          maxLength: 200
        prompt:
          type: string
          minLength: 1
        cron:
          type: string
          minLength: 1
        timezone:
          type: string
          minLength: 1
        status:
          "$ref": "#/components/schemas/Status"
        model:
          type: string
          nullable: true
          minLength: 1
        session_mode:
          "$ref": "#/components/schemas/SessionMode"
        owner_email:
          type: string
          nullable: true
          minLength: 1
        services:
          "$ref": "#/components/schemas/ServiceCodes"
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        next_run_at:
          type: string
          format: date-time
          nullable: true
        deleted_at:
          type: string
          format: date-time
          nullable: true
        last_occurrence:
          "$ref": "#/components/schemas/NullableOccurrence"
    SchedulePage:
      type: object
      additionalProperties: false
      required:
      - items
      - next_cursor
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/Schedule"
        next_cursor:
          type: string
          nullable: true
    Settings:
      type: object
      additionalProperties: false
      required:
      - browser_auth
      - default_template
      - default_profile
      properties:
        default_profile:
          type: string
          description: Configured creation default, independent of catalog filters and pagination. Resolve the exact name before automatically selecting it.
        default_template:
          type: string
          description: Configured creation default. Resolve it with GET /api/v1/templates?name=... without an active filter; it may be absent or inactive.
        browser_auth:
          type: string
          enum:
          - api_only
          - anonymous
          - saml
    PreviewInput:
      type: object
      additionalProperties: false
      required:
      - cron
      - timezone
      properties:
        cron:
          type: string
          minLength: 1
        timezone:
          type: string
          minLength: 1
    Preview:
      type: object
      additionalProperties: false
      required:
      - times
      properties:
        times:
          type: array
          minItems: 5
          maxItems: 5
          items:
            type: string
            format: date-time
    AuthSession:
      type: object
      additionalProperties: false
      required:
      - mode
      - authenticated
      - read_access
      - write_access
      - can_manage_all
      - user
      - expires_at
      properties:
        mode:
          type: string
          enum:
          - api_only
          - anonymous
          - saml
        authenticated:
          type: boolean
        read_access:
          type: boolean
        write_access:
          type: boolean
          description: Can create schedules and modify those available to this caller. SAML users without an email cannot write.
        can_manage_all:
          type: boolean
          description: Can manage all schedules and assign or clear their owners. True for configured SAML admins, valid Bearer keys and anonymous mode.
        user:
          type: object
          nullable: true
          additionalProperties: false
          required: [subject, display_name, email]
          properties:
            subject:
              type: string
            display_name:
              type: string
            email:
              type: string
              nullable: true
              description: Normalized email from the SAML identity, or null when unavailable.
        expires_at:
          type: string
          format: date-time
          nullable: true
    Occurrence:
      type: object
      additionalProperties: false
      required:
      - id
      - schedule_id
      - trigger
      - scheduled_at
      - state
      - created_at
      - updated_at
      - session_id
      - run_id
      - run_status
      - observed_at
      - execution_started_at
      - finished_at
      - run_error_code
      - sync_error_code
      - error_code
      - attempts
      - next_attempt_at
      properties:
        id:
          type: string
          format: uuid
        schedule_id:
          type: string
          format: uuid
        trigger:
          "$ref": "#/components/schemas/OccurrenceTrigger"
        scheduled_at:
          type: string
          format: date-time
          description: Cron due time for a scheduled occurrence, or command acceptance time for a manual occurrence. This is not the execution start time.
        state:
          "$ref": "#/components/schemas/OccurrenceState"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        session_id:
          type: string
          nullable: true
          format: uuid
        run_id:
          type: string
          nullable: true
          format: uuid
        run_status:
          type: string
          nullable: true
        observed_at:
          type: string
          nullable: true
          format: date-time
        execution_started_at:
          type: string
          nullable: true
          format: date-time
        finished_at:
          type: string
          nullable: true
          format: date-time
        run_error_code:
          type: string
          nullable: true
        sync_error_code:
          type: string
          nullable: true
        error_code:
          type: string
          nullable: true
        attempts:
          type: integer
          minimum: 0
        next_attempt_at:
          type: string
          nullable: true
          format: date-time
    OccurrencePage:
      type: object
      additionalProperties: false
      required:
      - items
      - next_cursor
      properties:
        items:
          type: array
          items:
            "$ref": "#/components/schemas/Occurrence"
        next_cursor:
          type: string
          nullable: true
    OccurrenceResult:
      type: object
      additionalProperties: false
      required:
      - run_status
      - fetched_at
      - error
      - final_message
      properties:
        run_status:
          type: string
        fetched_at:
          type: string
          format: date-time
        error:
          type: object
          nullable: true
          additionalProperties: false
          required:
          - code
          - message
          - phase
          properties:
            code:
              type: string
            message:
              type: string
            phase:
              type: string
              nullable: true
        final_message:
          type: object
          nullable: true
          additionalProperties: false
          required:
          - id
          - text
          - created_at
          properties:
            id:
              type: string
              format: uuid
            text:
              type: string
            created_at:
              type: string
              format: date-time
    OccurrenceTrigger:
      type: string
      enum:
      - scheduled
      - manual
    OccurrenceState:
      type: string
      enum:
      - pending
      - dispatching
      - accepted
      - skipped
      - failed
      - cancelled
    NullableOccurrence:
      type: object
      additionalProperties: false
      required:
      - id
      - schedule_id
      - trigger
      - scheduled_at
      - state
      - created_at
      - updated_at
      - session_id
      - run_id
      - run_status
      - observed_at
      - execution_started_at
      - finished_at
      - run_error_code
      - sync_error_code
      - error_code
      - attempts
      - next_attempt_at
      properties:
        id:
          type: string
          format: uuid
        schedule_id:
          type: string
          format: uuid
        trigger:
          "$ref": "#/components/schemas/OccurrenceTrigger"
        scheduled_at:
          type: string
          format: date-time
          description: Cron due time for a scheduled occurrence, or command acceptance time for a manual occurrence. This is not the execution start time.
        state:
          "$ref": "#/components/schemas/OccurrenceState"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        session_id:
          type: string
          nullable: true
          format: uuid
        run_id:
          type: string
          nullable: true
          format: uuid
        run_status:
          type: string
          nullable: true
        observed_at:
          type: string
          nullable: true
          format: date-time
        execution_started_at:
          type: string
          nullable: true
          format: date-time
        finished_at:
          type: string
          nullable: true
          format: date-time
        run_error_code:
          type: string
          nullable: true
        sync_error_code:
          type: string
          nullable: true
        error_code:
          type: string
          nullable: true
        attempts:
          type: integer
          minimum: 0
        next_attempt_at:
          type: string
          nullable: true
          format: date-time
      nullable: true
