openapi: 3.2.0
info:
  version: 1.0.0
  title: Swagger Jobs API
servers:
- url: https://api.siro.ai/
  description: Siro API Gateway
tags:
- name: Jobs
paths:
  /v1/jobs/siro-noticed/results:
    get:
      summary: List SiroNoticed results for the current user.
      description: Returns the most recent SiroNoticed results generated for the calling user.
      parameters:
      - schema:
          type: string
        required: false
        name: organizationId
        in: query
      responses:
        '200':
          description: List SiroNoticed results for the current user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        userId:
                          type: string
                          description: Job owner
                        organizationId:
                          type: string
                          description: Organization of the job
                        result:
                          type: string
                          description: The result content
                      required:
                      - userId
                      - organizationId
                      - result
                  cursor:
                    anyOf:
                    - type: string
                    - type: number
                    - {}
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type:
                    - number
                    - 'null'
                  hasNextPage:
                    type: boolean
                required:
                - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                  name:
                    type: string
                    enum:
                    - ZodError
                required:
                - issues
                - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                - error
      security:
      - SiroAuthToken: []
      tags:
      - Jobs
  /v1/jobs/siro-noticed:
    get:
      summary: List SiroNoticed jobs for the current user (or org).
      description: By default returns only the caller's own SiroNoticed jobs. Pass fullOrg=true (admin-only) to return all jobs in the caller's org.
      parameters:
      - schema:
          type:
          - boolean
          - 'null'
          description: Admin-only. If true, return all SiroNoticed jobs in the caller's org instead of just the caller's own jobs.
        required: false
        description: Admin-only. If true, return all SiroNoticed jobs in the caller's org instead of just the caller's own jobs.
        name: fullOrg
        in: query
      responses:
        '200':
          description: List SiroNoticed jobs for the current user (or org).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: The unique ID of the scheduled report
                        cron:
                          type: string
                          description: Cron string of the format "* * * * *" representing the schedule
                        cronDescription:
                          type:
                          - string
                          - 'null'
                          description: English description of the cron schedule. In case of drift, cron is the source of truth
                        nextScheduledTime:
                          type: string
                          format: date-time
                          description: When this report is scheduled to run next. ISO 8601 format.
                        owner:
                          type: string
                          description: The user ID of the report owner.
                        organizationId:
                          type: string
                          description: The organization ID that owns this report (derived from owner).
                        createdAt:
                          type: string
                          format: date-time
                          description: When the report was created, ISO 8601 format
                        updatedAt:
                          type: string
                          format: date-time
                          description: When the report was last updated, ISO 8601 format
                        deletedAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                          description: When the report was deleted, if applicable. ISO 8601 format.
                        prompt:
                          type: string
                          description: The prompt used to generate the SiroNoticed insight
                      required:
                      - id
                      - cron
                      - nextScheduledTime
                      - owner
                      - organizationId
                      - createdAt
                      - updatedAt
                      - prompt
                  cursor:
                    anyOf:
                    - type: string
                    - type: number
                    - {}
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type:
                    - number
                    - 'null'
                  hasNextPage:
                    type: boolean
                required:
                - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                  name:
                    type: string
                    enum:
                    - ZodError
                required:
                - issues
                - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                - error
      security:
      - SiroAuthToken: []
      tags:
      - Jobs
    post:
      summary: Create a new SiroNoticed job for the current user.
      description: Creates a SiroNoticed scheduled job owned by the calling user. The server derives `cronDescription` and `nextScheduledTime` from the provided cron string.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cron:
                  type: string
                  description: Cron string of the format "* * * * *" representing the schedule
                prompt:
                  type: string
                  description: SiroNoticed prompt override
              required:
              - cron
      responses:
        '200':
          description: Create a new SiroNoticed job for the current user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: The unique ID of the scheduled report
                      cron:
                        type: string
                        description: Cron string of the format "* * * * *" representing the schedule
                      cronDescription:
                        type:
                        - string
                        - 'null'
                        description: English description of the cron schedule. In case of drift, cron is the source of truth
                      nextScheduledTime:
                        type: string
                        format: date-time
                        description: When this report is scheduled to run next. ISO 8601 format.
                      owner:
                        type: string
                        description: The user ID of the report owner.
                      organizationId:
                        type: string
                        description: The organization ID that owns this report (derived from owner).
                      createdAt:
                        type: string
                        format: date-time
                        description: When the report was created, ISO 8601 format
                      updatedAt:
                        type: string
                        format: date-time
                        description: When the report was last updated, ISO 8601 format
                      deletedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                        description: When the report was deleted, if applicable. ISO 8601 format.
                      prompt:
                        type: string
                        description: The prompt used to generate the SiroNoticed insight
                    required:
                    - id
                    - cron
                    - nextScheduledTime
                    - owner
                    - organizationId
                    - createdAt
                    - updatedAt
                    - prompt
                  cursor:
                    anyOf:
                    - type: string
                    - type: number
                    - {}
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type:
                    - number
                    - 'null'
                  hasNextPage:
                    type: boolean
                required:
                - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                  name:
                    type: string
                    enum:
                    - ZodError
                required:
                - issues
                - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                - error
      security:
      - SiroAuthToken: []
      tags:
      - Jobs
  /v1/jobs/siro-noticed/{id}:
    patch:
      summary: Update a SiroNoticed job (owner only).
      description: Updates the cron schedule and/or prompt for a SiroNoticed job. Only the job owner or an admin may update.
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cron:
                  type: string
                  description: Cron string of the format "* * * * *" representing the schedule
                prompt:
                  type: string
                  description: SiroNoticed prompt override
      responses:
        '200':
          description: Update a SiroNoticed job (owner only).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: The unique ID of the scheduled report
                      cron:
                        type: string
                        description: Cron string of the format "* * * * *" representing the schedule
                      cronDescription:
                        type:
                        - string
                        - 'null'
                        description: English description of the cron schedule. In case of drift, cron is the source of truth
                      nextScheduledTime:
                        type: string
                        format: date-time
                        description: When this report is scheduled to run next. ISO 8601 format.
                      owner:
                        type: string
                        description: The user ID of the report owner.
                      organizationId:
                        type: string
                        description: The organization ID that owns this report (derived from owner).
                      createdAt:
                        type: string
                        format: date-time
                        description: When the report was created, ISO 8601 format
                      updatedAt:
                        type: string
                        format: date-time
                        description: When the report was last updated, ISO 8601 format
                      deletedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                        description: When the report was deleted, if applicable. ISO 8601 format.
                      prompt:
                        type: string
                        description: The prompt used to generate the SiroNoticed insight
                    required:
                    - id
                    - cron
                    - nextScheduledTime
                    - owner
                    - organizationId
                    - createdAt
                    - updatedAt
                    - prompt
                  cursor:
                    anyOf:
                    - type: string
                    - type: number
                    - {}
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type:
                    - number
                    - 'null'
                  hasNextPage:
                    type: boolean
                required:
                - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                  name:
                    type: string
                    enum:
                    - ZodError
                required:
                - issues
                - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                - error
      security:
      - SiroAuthToken: []
      tags:
      - Jobs
    delete:
      summary: Delete a SiroNoticed job (owner only).
      description: Soft-deletes a SiroNoticed job. Only the job owner or an admin may delete.
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Delete a SiroNoticed job (owner only).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: The unique ID of the deleted scheduled report
                    required:
                    - id
                  cursor:
                    anyOf:
                    - type: string
                    - type: number
                    - {}
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type:
                    - number
                    - 'null'
                  hasNextPage:
                    type: boolean
                required:
                - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                  name:
                    type: string
                    enum:
                    - ZodError
                required:
                - issues
                - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                - error
      security:
      - SiroAuthToken: []
      tags:
      - Jobs
components:
  securitySchemes:
    SiroAuthToken:
      type: apiKey
      in: header
      name: x-siro-auth-token
      description: 'OAuth access token for user-scoped requests (Authorization Code or machine-to-machine). Send header `x-siro-auth-token: <oauth-access-token>`. Not an organization API key.'
      x-default: <oauth-access-token>
externalDocs:
  description: View the raw OpenAPI Specification in JSON format
  url: /swagger.json