openapi: 3.1.0
info:
  title: Silo AI API
  version: 1.0.0
  description: User-scoped text, voice, wallet, usage, and SiloDrive memory API.
servers:
  - url: https://silocloud.ai/api/v1/ai
security:
  - siloIdBearer: []
paths:
  /models:
    get:
      summary: List available model routes
      responses: {"200": {description: Model routes}}
  /wallet:
    get:
      summary: Get the current user's AI wallet
      responses: {"200": {description: Wallet}}
  /memory:
    get:
      summary: Get the current user's SiloDrive memory status
      responses: {"200": {description: Memory status}}
  /sessions:
    post:
      summary: Create an assistant session
      parameters: [{in: header, name: Idempotency-Key, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tier: {type: string, default: text_standard}
                reserve_minor: {type: integer, minimum: 1, maximum: 5000}
                retain_transcript: {type: boolean, description: Enables private SiloDrive memory for this session.}
      responses: {"201": {description: Session created}}
  /sessions/{sessionId}:
    get:
      summary: Get a session
      parameters: [{$ref: '#/components/parameters/SessionId'}]
      responses: {"200": {description: Session}}
  /sessions/{sessionId}/messages:
    post:
      summary: Send a message
      parameters: [{$ref: '#/components/parameters/SessionId'}, {in: header, name: Idempotency-Key, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties: {message: {type: string, maxLength: 20000}}
      responses: {"200": {description: Assistant response}}
  /sessions/{sessionId}/end:
    post:
      summary: End and reconcile a session
      parameters: [{$ref: '#/components/parameters/SessionId'}, {in: header, name: Idempotency-Key, required: true, schema: {type: string}}]
      responses: {"200": {description: Session ended}}
  /sessions/{sessionId}/usage:
    get:
      summary: Get session usage
      parameters: [{$ref: '#/components/parameters/SessionId'}]
      responses: {"200": {description: Usage}}
  /sessions/{sessionId}/receipt:
    get:
      summary: Get session receipt
      parameters: [{$ref: '#/components/parameters/SessionId'}]
      responses: {"200": {description: Receipt}}
  /sessions/{sessionId}/webrtc-offer:
    post:
      summary: Exchange a WebRTC offer for realtime voice
      parameters: [{$ref: '#/components/parameters/SessionId'}, {in: header, name: Idempotency-Key, required: true, schema: {type: string}}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {type: object, required: [sdp], properties: {sdp: {type: string}}}
      responses: {"200": {description: WebRTC answer}}
components:
  securitySchemes:
    siloIdBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived SiloID assertion with audience siloai and required scopes.
  parameters:
    SessionId: {in: path, name: sessionId, required: true, schema: {type: string}}
