openapi: 3.1.0
info:
  title: Omni Developer Platform API
  description: >
    The canonical developer API for Omni — an index-grounded, stateful AI agent platform.
    Connect to https://edge.omnistatic.com with an authenticated `omni_sk_live_*` API key.
  version: 1.0.0

servers:
  - url: https://edge.omnistatic.com
    description: Production Edge Control Plane

security:
  - BearerAuth: []

paths:
  /health:
    get:
      summary: Health check probe
      description: Returns health status of the edge proxy without requiring authentication.
      security: []
      responses:
        "200":
          description: Service is operational.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"

  /v1/me:
    get:
      summary: Verify identity and account standing
      description: Verifies the caller's API key, reports the canonical user UID, and checks client key escrow status.
      responses:
        "200":
          description: Successful authentication.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  userId:
                    type: string
                    example: "usr_94a645d99c3a"
                  profile:
                    type: object
                    properties:
                      userName:
                        type: string
                        nullable: true
                      display_name:
                        type: string
                        nullable: true
                  verifiedAt:
                    type: string
                    format: date-time
        "401":
          $ref: "#/components/responses/UnauthorizedError"

  /v1/models:
    get:
      summary: List curated models
      description: Lists the curated LLM models available on the platform.
      responses:
        "200":
          description: List of models.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    example: "list"
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: "gpt-4o"
                        object:
                          type: string
                          example: "model"
                        owned_by:
                          type: string
                          example: "openai"

  /v1/chat/completions:
    post:
      summary: Execute chat completion with memory context injection
      description: >
        OpenAI-compatible chat completions route. Automatically queries semantic memory and
        injects relevant facts and biographical context into the prompt before execution.
      parameters:
        - in: header
          name: X-Omni-Workspace
          schema:
            type: string
          required: false
          description: Scope completion and memory search to a specific workspace ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messages
              properties:
                model:
                  type: string
                  default: "gpt-4o-mini"
                  example: "gpt-4o"
                messages:
                  type: array
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum: [system, user, assistant, tool]
                      content:
                        type: string
                stream:
                  type: boolean
                  default: false
                temperature:
                  type: number
                  default: 0.7
                memory:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                      default: true
                    limit:
                      type: integer
                      default: 5
      responses:
        "200":
          description: Chat completion response or Server-Sent Events stream.
          headers:
            X-Omni-Shimmer:
              schema:
                type: string
                enum: [injected, skipped, timeout, no-context]
            X-Omni-Memory-Count:
              schema:
                type: string
            X-Omni-Notes-Count:
              schema:
                type: string
        "429":
          $ref: "#/components/responses/RateLimitError"

  /v1/memories:
    get:
      summary: List user memories
      description: Returns a list of all persistent semantic memories for the authenticated user.
      responses:
        "200":
          description: Array of stored memories.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MemoryRecord"
    post:
      summary: Save a persistent memory
      description: Saves a discrete fact or memory into the persistent vector index.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  example: "User prefers dark mode."
                metadata:
                  type: object
      responses:
        "200":
          description: Memory stored successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MemoryRecord"

  /v1/memories/{id}:
    get:
      summary: Fetch single memory
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MemoryRecord"
    delete:
      summary: Delete a memory
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /v1/memories/search:
    post:
      summary: Semantic memory search
      description: Performs vector similarity search across memories.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  example: "UI preferences"
                limit:
                  type: integer
                  default: 10
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      allOf:
                        - $ref: "#/components/schemas/MemoryRecord"
                        - type: object
                          properties:
                            score:
                              type: number
                  mode:
                    type: string
                    example: "semantic"

  /v1/context/build:
    post:
      summary: Assemble context bundle
      description: Assembles relevant memories and workspace notes into an integrated context block.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                workspace_id:
                  type: string
                limit:
                  type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  mode:
                    type: string
                  items:
                    type: array
                    items:
                      type: object
                  contextText:
                    type: string

  /v1/workspaces:
    get:
      summary: List workspaces
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Workspace"
    post:
      summary: Create workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"

  /v1/workspaces/{workspaceId}/documents:
    get:
      summary: List workspace documents
      parameters:
        - in: path
          name: workspaceId
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      type: object
    post:
      summary: Create workspace document
      parameters:
        - in: path
          name: workspaceId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
              properties:
                title:
                  type: string
                markdown:
                  type: string
                document_payload:
                  type: object
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object

  /v1/usage:
    get:
      summary: Query monthly usage
      description: Returns token counts and request metrics for the current month.
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  month:
                    type: string
                  usage:
                    type: object
                    properties:
                      totalTokens:
                        type: integer
                      requestCount:
                        type: integer

  /v1/credits:
    get:
      summary: Query credit balance
      description: Returns remaining token entitlement balance and monthly limits.
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  used:
                    type: integer
                  limit:
                    type: integer
                  remaining:
                    type: integer
                  month:
                    type: string

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: omni_sk_live_*
      description: Omni Developer API Key

  schemas:
    MemoryRecord:
      type: object
      properties:
        id:
          type: string
          example: "mem_01jze9m2xw"
        ownerId:
          type: string
          example: "usr_94a645d99c3a"
        content:
          type: string
        metadata:
          type: object
        createdAt:
          type: string
          format: date-time

    Workspace:
      type: object
      properties:
        id:
          type: string
          example: "ws_01jze9m2xw"
        name:
          type: string
          example: "Engineering"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

  responses:
    UnauthorizedError:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "unauthorized"
                  message:
                    type: string
                    example: "Invalid or revoked API key"

    RateLimitError:
      description: Rate limit or quota exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
            description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    example: "rate_limited"
                  message:
                    type: string
                    example: "Too many requests. Please wait before retrying."