openapi: 3.1.0
info:
  title: Memtro API
  version: "1.0"
  description: |
    OpenAI-compatible chat completions with Memtro's memory, connector tools, routing, agent mode and jobs.
    Authenticate with `Authorization: Bearer sk-memtro-…` (create keys at https://platform.memtro.com/dashboard/keys).
servers:
  - url: https://platform.memtro.com/v1
security:
  - bearer: []
paths:
  /chat/completions:
    post:
      summary: Chat completion
      description: The OpenAI chat-completions shape plus the `memtro` options object. Streams when `stream` is true.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatRequest"
            examples:
              agent:
                value:
                  model: auto
                  messages: [{ role: user, content: "Have a look at Help Scout ticket #2450" }]
                  memtro: { mode: agent, memory: org }
      responses:
        "200":
          description: A chat completion (or a server-sent event stream of chunks when `stream` is true).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatResponse"
            text/event-stream:
              schema:
                type: string
        "400": { $ref: "#/components/responses/Error" }
        "401": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }
        "503": { $ref: "#/components/responses/Error" }
  /models:
    get:
      summary: List models
      description: The ids you can use - `memtro`, `auto`, `auto/<provider>` and `provider/model` for every provider you have a key for.
      responses:
        "200":
          description: Model list
          content:
            application/json:
              schema:
                type: object
                properties:
                  object: { type: string, const: list }
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, example: anthropic/claude-opus-5 }
                        object: { type: string, const: model }
                        created: { type: integer }
                        owned_by: { type: string }
  /embeddings:
    post:
      summary: Embeddings
      description: Embeddings through your OpenAI or Google key. `model` may be `memtro` for the default embedding model.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                model: { type: string, example: openai/text-embedding-3-small }
                input:
                  oneOf:
                    - { type: string }
                    - { type: array, items: { type: string } }
                encoding_format: { type: string, enum: [float, base64] }
      responses:
        "200":
          description: Embeddings in the OpenAI shape
          content:
            application/json:
              schema:
                type: object
                properties:
                  object: { type: string }
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        index: { type: integer }
                        embedding: { type: array, items: { type: number } }
                  model: { type: string }
                  usage: { type: object }
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: A Memtro API key (`sk-memtro-…`).
  responses:
    Error:
      description: OpenAI-style error envelope
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  message: { type: string }
                  type: { type: string, example: invalid_request_error }
                  code:
                    type: string
                    enum: [invalid_api_key, provider_not_configured, model_not_found, routing_unavailable, unsupported_tools, engine_unavailable, upstream_error]
  schemas:
    Message:
      type: object
      required: [role]
      properties:
        role: { type: string, enum: [system, developer, user, assistant, tool] }
        content:
          oneOf:
            - { type: string }
            - type: array
              items:
                type: object
                properties:
                  type: { type: string, enum: [text, image_url] }
                  text: { type: string }
                  image_url: { type: object, properties: { url: { type: string } } }
        name: { type: string }
        tool_call_id: { type: string }
    MemtroOptions:
      type: object
      description: Memtro-specific options. `brain` is accepted as an older name for this field.
      properties:
        mode: { type: string, enum: [chat, agent], description: "agent runs the multi-step harness; default chat or the organisation's setting" }
        memory: { type: string, enum: [org, personal, off], description: "Where facts learned from this exchange are stored; a ceiling, since personal facts are classified as such within org requests" }
        retrieve: { type: boolean, default: true, description: Inject relevant memories and graph context }
        tools: { type: boolean, default: true, description: Expose memory and connector tools to the model }
        show_progress: { type: boolean, default: true, description: Stream tool activity as reasoning_content in agent mode }
        engine: { type: string, enum: [native, opencode, claude-code], description: Which harness runs agent mode }
        cache: { type: boolean, default: true, description: Serve identical connector calls from the short-lived cache }
    ChatRequest:
      type: object
      required: [messages]
      properties:
        model:
          type: string
          default: memtro
          description: "`auto`, `auto/<provider>`, `memtro`, `provider/model`, `claude-code/<alias>`, `compat:<label>/<model>`; append `:agent` or `:chat` to force a mode"
        messages: { type: array, items: { $ref: "#/components/schemas/Message" } }
        stream: { type: boolean }
        stream_options: { type: object, properties: { include_usage: { type: boolean } } }
        temperature: { type: number }
        top_p: { type: number }
        max_tokens: { type: integer }
        max_completion_tokens: { type: integer }
        stop: { oneOf: [{ type: string }, { type: array, items: { type: string } }] }
        tools:
          type: array
          description: Client-declared tools (OpenAI function format); returned as tool_calls for you to execute. Not available with claude-code/* models.
          items: { type: object }
        tool_choice: {}
        memtro: { $ref: "#/components/schemas/MemtroOptions" }
    ChatResponse:
      type: object
      properties:
        id: { type: string }
        object: { type: string, const: chat.completion }
        created: { type: integer }
        model: { type: string, description: The model that answered, e.g. anthropic/claude-opus-5 }
        choices:
          type: array
          items:
            type: object
            properties:
              index: { type: integer }
              message:
                type: object
                properties:
                  role: { type: string }
                  content: { type: string }
                  tool_calls: { type: array, items: { type: object } }
              finish_reason: { type: string }
        usage:
          type: object
          properties:
            prompt_tokens: { type: integer }
            completion_tokens: { type: integer }
            total_tokens: { type: integer }
        memtro:
          type: object
          description: Memtro metadata
          properties:
            mode: { type: string }
            engine: { type: string }
            sandbox: { type: string }
            engine_note: { type: string }
            routing:
              type: object
              properties:
                requested: { type: string }
                model: { type: string }
                complexity: { type: integer, minimum: 1, maximum: 5 }
                method: { type: string, enum: [heuristic, classifier, fallback] }
                reason: { type: string }
            tools:
              type: array
              description: Every server tool call made while answering
              items:
                type: object
                properties:
                  tool: { type: string }
                  input: {}
                  ok: { type: boolean }
                  summary: { type: string }