openapi: 3.1.0
info:
  title: Riddle Actions API
  version: 1.0.0
servers:
  - url: https://api.riddledc.com
paths:
  /v1/run/actions:
    post:
      operationId: runActions
      summary: Run a browser job (Actions-safe)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunActionsRequest'
      responses:
        '202':
          description: Job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunActionsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunActionsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunActionsResponse'
  /v1/jobs/{job_id}:
    get:
      operationId: getJob
      summary: Get job status
      security:
        - bearerAuth: []
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
  /v1/jobs/{job_id}/artifacts:
    get:
      operationId: getJobArtifacts
      summary: Get job artifacts manifest
      security:
        - bearerAuth: []
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [actions]
      responses:
        '200':
          description: Artifacts manifest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactsResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    RunActionsRequest:
      type: object
      additionalProperties: true
      properties:
        url:
          type: string
        urls:
          type: array
          items:
            type: string
        steps:
          type: array
          items:
            type: object
            additionalProperties: true
        script:
          type: string
        include:
          type: array
          description: Artifacts to inline in the response. By default, only URLs are returned. Specify which artifacts to fetch and include directly in the response payload.
          items:
            type: string
            enum: [final_screenshot, screenshots, console, har, html]
        sync:
          type: boolean
          description: Whether to wait for job completion and return results inline (default true). Set to false for async mode where you get a job_id and must poll for status.
          default: true
        timeout_sec:
          type: integer
        options:
          type: object
          additionalProperties: true
    Artifacts:
      type: object
      additionalProperties: false
      properties:
        final_screenshot_url:
          type: string
          nullable: true
        screenshots:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactEntry'
        console_url:
          type: string
          nullable: true
        har_url:
          type: string
          nullable: true
        html_url:
          type: string
          nullable: true
    ArtifactEntry:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        url:
          type: string
        content_type:
          type: string
        bytes:
          type: integer
          nullable: true
    Limits:
      type: object
      additionalProperties: false
      properties:
        retention_seconds:
          type: integer
        expires_at:
          type: string
          nullable: true
    Error:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
        message:
          type: string
        details:
          nullable: true
    RunActionsResponse:
      type: object
      additionalProperties: false
      properties:
        job_id:
          type: string
        status:
          type: string
          enum: [queued, running, completed, failed]
        artifacts:
          $ref: '#/components/schemas/Artifacts'
        limits:
          $ref: '#/components/schemas/Limits'
        error:
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'
        status_url:
          type: string
        artifacts_url:
          type: string
    JobStatusResponse:
      type: object
      additionalProperties: false
      properties:
        job_id:
          type: string
        status:
          type: string
          enum: [queued, running, completed, failed]
        created_at:
          type: string
          nullable: true
        duration_ms:
          type: integer
          nullable: true
        error:
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'
    ArtifactsResponse:
      type: object
      additionalProperties: false
      properties:
        job_id:
          type: string
        status:
          type: string
          enum: [queued, running, completed, failed]
        artifacts:
          $ref: '#/components/schemas/Artifacts'
        limits:
          $ref: '#/components/schemas/Limits'
        error:
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'