openapi: 3.0.3
info:
  title: IMS Omni Support REST API
  description: API-first support ticketing and context-tracking server for PHP and JavaScript SDKs.
  version: 1.0.0
servers:
  - url: http://localhost:8000/api/v1
    description: Local development interface server
paths:
  /tickets:
    post:
      summary: Submit a support ticket
      description: Created by application users, frontend widgets, or automated SDK exception logging.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: OBJECT
              required:
                - subject
                - description
                - user_identifier
                - user_email
                - user_name
              properties:
                subject:
                  type: STRING
                  example: "Database Sync Exception"
                description:
                  type: STRING
                  example: "Call to undefined method App\\Models\\User::sync() on inventory cron."
                priority:
                  type: STRING
                  enum: [low, medium, high, critical]
                  default: medium
                category:
                  type: STRING
                  example: "database"
                  description: Category slug or name configured on the application
                user_identifier:
                  type: STRING
                  example: "user_8911"
                  description: The unique ID of the authenticated user in the client app
                user_email:
                  type: STRING
                  example: "jane.doe@example.com"
                user_name:
                  type: STRING
                  example: "Jane Doe"
                tenant_identifier:
                  type: STRING
                  example: "tenant_abc"
                  description: Tenant ID for multi-tenant consuming apps
                context:
                  type: OBJECT
                  description: Structured request, system, browser, and runtime variables
                exception_trace:
                  type: OBJECT
                  description: Stack trace details for automatic exception reports
                attachments:
                  type: ARRAY
                  items:
                    type: OBJECT
                    required:
                      - file_name
                      - content
                      - mime_type
                    properties:
                      file_name:
                        type: STRING
                        example: "error.log"
                      content:
                        type: STRING
                        description: Base64-encoded file contents
                        example: "TG9nZ2VkIGVycm9yIGhlcmU="
                      mime_type:
                        type: STRING
                        example: "text/plain"
      responses:
        '201':
          description: Ticket created successfully
        '401':
          description: Missing or invalid API Key
        '422':
          description: Validation failure
    get:
      summary: Retrieve all tickets
      description: Returns a list of tickets submitted by the authenticated application context.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: user_identifier
          in: query
          required: false
          schema:
            type: STRING
        - name: user_email
          in: query
          required: false
          schema:
            type: STRING
        - name: status
          in: query
          required: false
          schema:
            type: STRING
      responses:
        '200':
          description: List of tickets

  /tickets/{id}:
    get:
      summary: View a single ticket
      description: Retrieve details, diagnostics, history, and replies for a single ticket.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: STRING
            format: uuid
      responses:
        '200':
          description: Ticket details
        '404':
          description: Ticket not found

  /tickets/{id}/comments:
    post:
      summary: Add a comment or reply
      description: Append a message to the ticket conversation.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: STRING
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: OBJECT
              required:
                - content
                - author_type
                - author_id
                - author_name
              properties:
                content:
                  type: STRING
                  example: "We are currently investigating the database pool parameters."
                author_type:
                  type: STRING
                  enum: [external_user, support_agent, system]
                author_id:
                  type: STRING
                  example: "user_8911"
                author_name:
                  type: STRING
                  example: "Jane Doe"
                is_internal:
                  type: BOOLEAN
                  default: false
                attachments:
                  type: ARRAY
                  items:
                    type: OBJECT
                    required:
                      - file_name
                      - content
                      - mime_type
                    properties:
                      file_name:
                        type: STRING
                      content:
                        type: STRING
                        description: Base64-encoded attachment
                      mime_type:
                        type: STRING
      responses:
        '201':
          description: Comment created
        '404':
          description: Ticket not found

  /tickets/{id}/attachments:
    post:
      summary: Upload attachment file
      description: Multipart/form-data upload to attach files to a ticket.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: STRING
            format: uuid
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: OBJECT
              required:
                - file
              properties:
                file:
                  type: STRING
                  format: binary
      responses:
        '201':
          description: File uploaded successfully

  /categories:
    get:
      summary: List application categories
      description: Returns categories configured for the authenticated application key.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: List of categories

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-IMS-OMNI-API-KEY
