{
  "openapi": "3.1.1",
  "info": {
    "title": "Converse HTTP API",
    "version": "1.0.0",
    "description": "HTTP endpoints used to prepare Converse realtime voice sessions. The realtime conversation protocol is described by asyncapi.json."
  },
  "servers": [
    {
      "url": "https://converse.trelis.com"
    }
  ],
  "paths": {
    "/api/v1/session-keys": {
      "post": {
        "operationId": "createSessionKey",
        "summary": "Create a scoped realtime session credential",
        "description": "Exchange a server-held persistent ck_ key for a short-lived credential bound to exactly one session_id. Call this only from a trusted backend.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionKeyRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Scoped credential created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionKeyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid session_id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, unknown, expired or revoked persistent key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Content-Type must be application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/voices": {
      "get": {
        "operationId": "listVoices",
        "summary": "List available character voices",
        "security": [],
        "responses": {
          "200": {
            "description": "Current voice roster",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VoiceRoster"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Persistent Converse API key beginning ck_. Keep it on your server."
      }
    },
    "schemas": {
      "SessionId": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$",
        "minLength": 1,
        "maxLength": 64
      },
      "SessionKeyRequest": {
        "type": "object",
        "required": [
          "session_id"
        ],
        "properties": {
          "session_id": {
            "$ref": "#/components/schemas/SessionId"
          }
        },
        "additionalProperties": false
      },
      "SessionKeyResponse": {
        "type": "object",
        "required": [
          "api_key",
          "session_id",
          "expires_in"
        ],
        "properties": {
          "api_key": {
            "type": "string",
            "description": "Short-lived credential for the matching session_id."
          },
          "session_id": {
            "$ref": "#/components/schemas/SessionId"
          },
          "expires_in": {
            "type": "integer",
            "minimum": 1,
            "description": "Credential lifetime in seconds."
          }
        },
        "additionalProperties": false
      },
      "Voice": {
        "type": "object",
        "required": [
          "key",
          "name"
        ],
        "properties": {
          "key": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "VoiceRoster": {
        "type": "object",
        "required": [
          "voices",
          "default"
        ],
        "properties": {
          "voices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Voice"
            }
          },
          "default": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  }
}