openapi: 3.0.3
info:
  title: CodXER OpenAI-compatible API (public surface sketch)
  version: "1.0"
  description: |
    Sketch of the public CodXER API at https://api.codxer.com.
    Authoritative product docs: https://codxer.com/legal/api-docs.html
    Evolution rotation: https://codxer.com/docs/evolution-rotation/
  contact:
    name: CodXER
    email: contact@codxer.com
    url: https://codxer.com/legal/contact.html
servers:
  - url: https://api.codxer.com/v1
    description: Production OpenAI-compatible base
paths:
  /models:
    get:
      summary: List models
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Model list (OpenAI-compatible shape)
  /chat/completions:
    post:
      summary: Create chat completion
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, messages]
              properties:
                model:
                  type: string
                  description: Catalog model id or published Evolution id (evo_*)
                messages:
                  type: array
                  items:
                    type: object
                conversation_id:
                  type: string
                  description: Optional; required for Evolution turn continuity in API clients
            example:
              model: evo_YOUR_PUBLISHED_ID
              messages:
                - role: user
                  content: Hello
      responses:
        "200":
          description: Chat completion; may include _codxer Evolution metadata
          content:
            application/json:
              schema:
                type: object
              example:
                id: chatcmpl-example
                object: chat.completion
                model: evo_YOUR_PUBLISHED_ID
                choices:
                  - index: 0
                    message:
                      role: assistant
                      content: ping
                    finish_reason: stop
                _codxer:
                  rotation_strategy: handoff_summary_v1
                  handoff:
                    evolutionCoreId: core_1
                agixer_trace:
                  - selected_index: 0
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Account API key (cx_live_…)
