{
  "openapi": "3.1.0",
  "info": {
    "title": "Alter Public API (OpenAI Compatible)",
    "version": "1.0.0",
    "description": "Public-facing OpenAI-compatible endpoints."
  },
  "servers": [
    {
      "url": "https://alterhq.com/api"
    }
  ],
  "paths": {
    "/v1/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List available models",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "A list of models.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/v1/completions": {
      "post": {
        "operationId": "createCompletion",
        "summary": "Create a completion",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompletionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The completion response or stream.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/CompletionResponse"
                    },
                    {
                      "$ref": "#/components/schemas/CompletionChunk"
                    }
                  ]
                }
              },
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/CompletionChunk"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "summary": "Create a chat completion",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The chat completion response or stream.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ChatCompletionResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ChatCompletionChunk"
                    }
                  ]
                }
              },
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionChunk"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Alter token",
        "description": "Bearer token issued by the Alter macOS app."
      }
    },
    "responses": {
      "BadRequestError": {
        "description": "Bad request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "UnauthorizedError": {
        "description": "Unauthorized.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "Model": {
        "type": "object",
        "required": [
          "id",
          "object",
          "created",
          "owned_by"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "model"
          },
          "created": {
            "type": "integer"
          },
          "owned_by": {
            "type": "string"
          }
        }
      },
      "ModelList": {
        "type": "object",
        "required": [
          "object",
          "data"
        ],
        "properties": {
          "object": {
            "type": "string",
            "const": "list"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Model"
            }
          }
        }
      },
      "CompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "prompt"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "prompt": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2
          },
          "top_p": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "n": {
            "type": "integer",
            "minimum": 1
          },
          "stream": {
            "type": "boolean"
          },
          "stop": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "presence_penalty": {
            "type": "number",
            "minimum": -2,
            "maximum": 2
          },
          "frequency_penalty": {
            "type": "number",
            "minimum": -2,
            "maximum": 2
          },
          "logit_bias": {
            "type": "object"
          },
          "user": {
            "type": "string"
          }
        }
      },
      "CompletionChoice": {
        "type": "object",
        "required": [
          "text",
          "index",
          "finish_reason"
        ],
        "properties": {
          "text": {
            "type": "string"
          },
          "index": {
            "type": "integer"
          },
          "logprobs": {
            "type": [
              "object",
              "null"
            ]
          },
          "finish_reason": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CompletionResponse": {
        "type": "object",
        "required": [
          "id",
          "object",
          "created",
          "model",
          "choices"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "text_completion"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompletionChoice"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "CompletionChunkChoice": {
        "type": "object",
        "required": [
          "text",
          "index",
          "finish_reason"
        ],
        "properties": {
          "text": {
            "type": "string"
          },
          "index": {
            "type": "integer"
          },
          "finish_reason": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "CompletionChunk": {
        "type": "object",
        "required": [
          "id",
          "object",
          "created",
          "model",
          "choices"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "text_completion"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompletionChunkChoice"
            }
          }
        }
      },
      "ChatMessage": {
        "type": "object",
        "required": [
          "role",
          "content"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "user",
              "assistant",
              "tool"
            ]
          },
          "content": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type"
                  ]
                }
              }
            ]
          },
          "name": {
            "type": "string"
          },
          "tool_call_id": {
            "type": "string"
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            }
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2
          },
          "top_p": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "n": {
            "type": "integer",
            "minimum": 1
          },
          "stream": {
            "type": "boolean"
          },
          "stop": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 1
          },
          "presence_penalty": {
            "type": "number",
            "minimum": -2,
            "maximum": 2
          },
          "frequency_penalty": {
            "type": "number",
            "minimum": -2,
            "maximum": 2
          },
          "logit_bias": {
            "type": "object"
          },
          "user": {
            "type": "string"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "const": "function"
                },
                "function": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "parameters": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "name",
                    "parameters"
                  ]
                }
              },
              "required": [
                "type",
                "function"
              ]
            }
          }
        }
      },
      "ChatCompletionChoice": {
        "type": "object",
        "required": [
          "index",
          "message",
          "finish_reason"
        ],
        "properties": {
          "index": {
            "type": "integer"
          },
          "message": {
            "$ref": "#/components/schemas/ChatMessage"
          },
          "finish_reason": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "required": [
          "id",
          "object",
          "created",
          "model",
          "choices"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "chat.completion"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatCompletionChoice"
            }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        }
      },
      "ChatCompletionDelta": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "assistant",
              "tool",
              "system",
              "user"
            ]
          },
          "content": {
            "type": "string"
          },
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "ChatCompletionChunkChoice": {
        "type": "object",
        "required": [
          "index",
          "delta",
          "finish_reason"
        ],
        "properties": {
          "index": {
            "type": "integer"
          },
          "delta": {
            "$ref": "#/components/schemas/ChatCompletionDelta"
          },
          "finish_reason": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ChatCompletionChunk": {
        "type": "object",
        "required": [
          "id",
          "object",
          "created",
          "model",
          "choices"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string",
            "const": "chat.completion.chunk"
          },
          "created": {
            "type": "integer"
          },
          "model": {
            "type": "string"
          },
          "choices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChatCompletionChunkChoice"
            }
          }
        }
      },
      "Usage": {
        "type": "object",
        "required": [
          "prompt_tokens",
          "completion_tokens",
          "total_tokens"
        ],
        "properties": {
          "prompt_tokens": {
            "type": "integer"
          },
          "completion_tokens": {
            "type": "integer"
          },
          "total_tokens": {
            "type": "integer"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "param": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "code": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "message",
              "type"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}