{
  "openapi": "3.1.0",
  "info": {
    "title": "Interfaze API",
    "version": "1.0.0",
    "description": "The Interfaze Chat Completion API Documentation",
    "contact": {
      "name": "Interfaze Support",
      "email": "support@interfaze.ai",
      "url": "https://interfaze.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.interfaze.ai/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "summary": "Create chat completion",
        "description": "Creates a model response for the given chat conversation.",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "required": true,
            "schema": { "type": "string" },
            "description": "`Bearer <your-api-key>`"
          },
          {
            "name": "Content-Type",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "default": "application/json" },
            "description": "`application/json`"
          },
          {
            "name": "x-show-additional-info",
            "in": "header",
            "required": false,
            "schema": { "type": "string", "enum": ["true", "false"], "default": "false" },
            "description": "Set to `true` to include [precontext](https://interfaze.ai/docs/precontext) inline at the start of a streamed response. Defaults to `false`."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful chat completion response.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" }
              },
              "text/event-stream": {
                "description": "Server-sent events stream when `stream: true`. Each event is a `ChatCompletionChunk`.",
                "schema": { "$ref": "#/components/schemas/ChatCompletionChunk" }
              }
            }
          },
          "400": {
            "description": "The request body is malformed or missing required fields.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
              }
            }
          },
          "401": {
            "description": "The API key is missing, invalid, or revoked.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
              }
            }
          },
          "402": {
            "description": "Your account has insufficient credits.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
              }
            }
          },
          "413": {
            "description": "Request body or input file exceeds size limits.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
              }
            }
          },
          "429": {
            "description": "You exceeded the rate limit. Retry with exponential backoff.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
              }
            }
          },
          "500": {
            "description": "Server-side failure. Safe to retry.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
              }
            }
          },
          "503": {
            "description": "Temporary capacity issue. Retry with backoff.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "bash",
            "label": "cURL",
            "source": "curl https://api.interfaze.ai/v1/chat/completions \\\n  -H \"Authorization: Bearer $INTERFAZE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"interfaze\",\n    \"messages\": [\n      { \"role\": \"user\", \"content\": \"Who is the founder of Interfaze?\" }\n    ]\n  }'"
          },
          {
            "lang": "typescript",
            "label": "fetch",
            "source": "const response = await fetch(\"https://api.interfaze.ai/v1/chat/completions\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": `Bearer ${process.env.INTERFAZE_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    model: \"interfaze\",\n    messages: [\n      { role: \"user\", content: \"Who is the founder of Interfaze?\" },\n    ],\n  }),\n});\n\nconst data = await response.json();\nconsole.log(data.choices[0].message.content);"
          },
          {
            "lang": "typescript",
            "label": "OpenAI SDK",
            "source": "import OpenAI from \"openai\";\n\nconst interfaze = new OpenAI({\n  baseURL: \"https://api.interfaze.ai/v1\",\n  apiKey: process.env.INTERFAZE_API_KEY,\n});\n\nconst response = await interfaze.chat.completions.create({\n  model: \"interfaze\",\n  messages: [\n    { role: \"user\", content: \"Who is the founder of Interfaze?\" },\n  ],\n});\n\nconsole.log(response.choices[0].message.content);"
          },
          {
            "lang": "typescript",
            "label": "Vercel AI SDK",
            "source": "import { createInterfaze } from \"@interfaze-ai/ai-sdk\";\nimport { generateText } from \"ai\";\n\nconst interfaze = createInterfaze({\n  apiKey: process.env.INTERFAZE_API_KEY,\n});\n\nconst { text } = await generateText({\n  model: interfaze(\"interfaze\"),\n  prompt: \"Who is the founder of Interfaze?\",\n});\n\nconsole.log(text);"
          },
          {
            "lang": "typescript",
            "label": "LangChain SDK",
            "source": "import { ChatOpenAI } from \"@langchain/openai\";\n\nconst interfaze = new ChatOpenAI({\n  configuration: {\n    baseURL: \"https://api.interfaze.ai/v1\",\n  },\n  apiKey: process.env.INTERFAZE_API_KEY,\n  model: \"interfaze\",\n});\n\nconst response = await interfaze.invoke(\"Who is the founder of Interfaze?\");\n\nconsole.log(response.content);"
          },
          {
            "lang": "python",
            "label": "requests",
            "source": "import os\nimport requests\n\nresponse = requests.post(\n    \"https://api.interfaze.ai/v1/chat/completions\",\n    headers={\n        \"Authorization\": f\"Bearer {os.environ['INTERFAZE_API_KEY']}\",\n        \"Content-Type\": \"application/json\",\n    },\n    json={\n        \"model\": \"interfaze\",\n        \"messages\": [\n            {\"role\": \"user\", \"content\": \"Who is the founder of Interfaze?\"},\n        ],\n    },\n)\n\nprint(response.json()[\"choices\"][0][\"message\"][\"content\"])"
          },
          {
            "lang": "python",
            "label": "OpenAI SDK",
            "source": "import os\nfrom openai import OpenAI\n\ninterfaze = OpenAI(\n    base_url=\"https://api.interfaze.ai/v1\",\n    api_key=os.environ[\"INTERFAZE_API_KEY\"],\n)\n\nresponse = interfaze.chat.completions.create(\n    model=\"interfaze\",\n    messages=[\n        {\"role\": \"user\", \"content\": \"Who is the founder of Interfaze?\"},\n    ],\n)\n\nprint(response.choices[0].message.content)"
          },
          {
            "lang": "python",
            "label": "LangChain SDK",
            "source": "import os\nfrom langchain_openai import ChatOpenAI\n\ninterfaze = ChatOpenAI(\n    base_url=\"https://api.interfaze.ai/v1\",\n    api_key=os.environ[\"INTERFAZE_API_KEY\"],\n    model=\"interfaze\",\n)\n\nresponse = interfaze.invoke(\"Who is the founder of Interfaze?\")\n\nprint(response.content)"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key obtained from the [dashboard](https://interfaze.ai/dashboard)."
      }
    },
    "schemas": {
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": {
            "type": "string",
            "description": "Model id to use. Currently the only supported value is `interfaze`.",
            "enum": ["interfaze"],
            "example": "interfaze"
          },
          "messages": {
            "type": "array",
            "description": "A list of messages making up the conversation so far.",
            "items": { "$ref": "#/components/schemas/Message" }
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "If `true`, partial message deltas are sent as server-sent events. The stream terminates with `data: [DONE]`."
          },
          "response_format": {
            "$ref": "#/components/schemas/ResponseFormat"
          },
          "tools": {
            "type": "array",
            "description": "A list of tools (functions) the model may call. Follows the [OpenAI function calling](https://developers.openai.com/api/docs/guides/function-calling?api-mode=chat) schema.",
            "items": { "$ref": "#/components/schemas/Tool" }
          },
          "tool_choice": {
            "$ref": "#/components/schemas/ToolChoice"
          },
          "reasoning_effort": {
            "type": "string",
            "enum": ["low", "medium", "high"],
            "description": "Enables extended reasoning. The model spends more compute and thinking tokens before producing a final answer. `low` = light reasoning pass, `medium` = moderate reasoning, `high` = deep reasoning (recommended for math, science, complex agents). When set, the response contains a `reasoning` field. In streaming mode, reasoning tokens stream first inside `<think>...</think>` tags. Off by default."
          },
          "max_tokens": {
            "type": "integer",
            "default": 32000,
            "minimum": 1,
            "maximum": 32000,
            "description": "Maximum number of tokens to generate in the completion. Hard upper bound of 32,000 tokens."
          },
          "temperature": {
            "type": "number",
            "default": 1,
            "minimum": 0,
            "maximum": 2,
            "description": "Sampling temperature between `0` and `2`. Higher values produce more random output, lower values make the output more focused and deterministic."
          },
          "top_p": {
            "type": "number",
            "default": 1,
            "minimum": 0,
            "maximum": 1,
            "description": "Nucleus sampling. The model considers only the tokens whose cumulative probability mass is `top_p`. `0.1` means only the top 10% of probability mass is sampled from. Generally only adjust one of `temperature` or `top_p`."
          }
        }
      },
      "Message": {
        "type": "object",
        "required": ["role", "content"],
        "description": "A single message in the conversation.",
        "properties": {
          "role": {
            "type": "string",
            "enum": ["system", "user", "assistant", "tool"],
            "description": "The role of the message author."
          },
          "content": {
            "description": "The message content. Either a plain string or an array of content parts for multimodal input.",
            "oneOf": [
              { "type": "string" },
              {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ContentPart" }
              }
            ]
          },
          "name": {
            "type": "string",
            "description": "Optional name of the participant."
          },
          "tool_calls": {
            "type": "array",
            "description": "Assistant-only. Tool calls the model wants the caller to execute.",
            "items": { "$ref": "#/components/schemas/ToolCall" }
          },
          "tool_call_id": {
            "type": "string",
            "description": "Tool-message-only. The id of the tool call this message is responding to."
          }
        }
      },
      "ContentPart": {
        "description": "A typed content part for multimodal input. Discriminated by `type`.",
        "oneOf": [
          { "$ref": "#/components/schemas/TextPart" },
          { "$ref": "#/components/schemas/ImagePart" },
          { "$ref": "#/components/schemas/FilePart" }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "text": "#/components/schemas/TextPart",
            "image_url": "#/components/schemas/ImagePart",
            "file": "#/components/schemas/FilePart"
          }
        }
      },
      "TextPart": {
        "type": "object",
        "required": ["type", "text"],
        "properties": {
          "type": {
            "type": "string",
            "const": "text",
            "description": "Must be `\"text\"`."
          },
          "text": {
            "type": "string",
            "description": "The text content."
          }
        }
      },
      "ImagePart": {
        "type": "object",
        "required": ["type", "image_url"],
        "properties": {
          "type": {
            "type": "string",
            "const": "image_url",
            "description": "Must be `\"image_url\"`."
          },
          "image_url": {
            "type": "object",
            "required": ["url"],
            "description": "Wrapper object containing the image source.",
            "properties": {
              "url": {
                "type": "string",
                "description": "Publicly accessible URL or base64 data URL (`data:image/jpeg;base64,...`)."
              }
            }
          }
        }
      },
      "FilePart": {
        "type": "object",
        "required": ["type", "file"],
        "properties": {
          "type": {
            "type": "string",
            "const": "file",
            "description": "Must be `\"file\"`."
          },
          "file": {
            "type": "object",
            "required": ["filename", "file_data"],
            "description": "Wrapper object containing the file source.",
            "properties": {
              "filename": {
                "type": "string",
                "description": "Filename including extension. Used for MIME inference."
              },
              "file_data": {
                "type": "string",
                "description": "Publicly accessible URL or base64 data URL (`data:<mime>;base64,...`)."
              }
            }
          }
        }
      },
      "ResponseFormat": {
        "description": "Constrains the model output to a specific format. Follows the [OpenAI structured output specification](https://developers.openai.com/api/docs/guides/structured-outputs?api-mode=chat).",
        "oneOf": [
          {
            "type": "object",
            "title": "Text",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "const": "text",
                "description": "Default — plain text output."
              }
            }
          },
          {
            "type": "object",
            "title": "JSON Schema",
            "required": ["type", "json_schema"],
            "properties": {
              "type": {
                "type": "string",
                "const": "json_schema",
                "description": "JSON schema–constrained output."
              },
              "json_schema": {
                "type": "object",
                "required": ["name", "schema"],
                "description": "The JSON schema configuration.",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Identifier for the schema (e.g. `\"id_schema\"`)."
                  },
                  "schema": {
                    "type": "object",
                    "description": "A valid JSON Schema definition describing the output shape.",
                    "additionalProperties": true
                  },
                  "strict": {
                    "type": "boolean",
                    "default": false,
                    "description": "Whether to strictly enforce the schema."
                  }
                }
              }
            }
          }
        ]
      },
      "Tool": {
        "type": "object",
        "required": ["type", "function"],
        "description": "A tool the model may call.",
        "properties": {
          "type": {
            "type": "string",
            "const": "function",
            "description": "Always `\"function\"`."
          },
          "function": {
            "$ref": "#/components/schemas/ToolFunction"
          }
        }
      },
      "ToolFunction": {
        "type": "object",
        "required": ["name"],
        "description": "The function definition for a tool.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Unique function name (snake_case recommended)."
          },
          "description": {
            "type": "string",
            "description": "What the function does. Helps the model decide when to call it."
          },
          "parameters": {
            "type": "object",
            "description": "JSON Schema describing the function's arguments.",
            "additionalProperties": true
          }
        }
      },
      "ToolChoice": {
        "description": "Controls which (if any) tool the model calls. `\"auto\"` = model decides, `\"none\"` = no tool calls, `\"required\"` = must call at least one tool, or an object to force a specific function.",
        "oneOf": [
          {
            "type": "string",
            "title": "String",
            "enum": ["auto", "none", "required"]
          },
          {
            "type": "object",
            "title": "Named function",
            "required": ["type", "function"],
            "properties": {
              "type": {
                "type": "string",
                "const": "function"
              },
              "function": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The name of the function to force."
                  }
                }
              }
            }
          }
        ]
      },
      "ToolCall": {
        "type": "object",
        "required": ["id", "type", "function"],
        "description": "A tool call requested by the assistant.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique id for this tool call."
          },
          "type": {
            "type": "string",
            "const": "function"
          },
          "function": {
            "type": "object",
            "required": ["name", "arguments"],
            "properties": {
              "name": {
                "type": "string",
                "description": "The function name to call."
              },
              "arguments": {
                "type": "string",
                "description": "JSON-encoded arguments for the function."
              }
            }
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "description": "A successful non-streaming chat completion response.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the completion.",
            "example": "interfaze-1775270750639"
          },
          "object": {
            "type": "string",
            "const": "chat.completion",
            "description": "Always `chat.completion`."
          },
          "model": {
            "type": "string",
            "description": "The model used.",
            "example": "interfaze"
          },
          "choices": {
            "type": "array",
            "description": "A list of completion choices.",
            "items": { "$ref": "#/components/schemas/Choice" }
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          },
          "reasoning": {
            "type": "string",
            "description": "Present when `reasoning_effort` is set. The model's thinking trace."
          },
          "precontext": {
            "type": "array",
            "description": "Raw outputs from any internal tasks the model ran (OCR, STT, web search, etc.).",
            "items": { "$ref": "#/components/schemas/PrecontextEntry" }
          },
          "vcache": {
            "type": "boolean",
            "description": "Whether the response was served from the model's verified cache."
          }
        },
        "example": {
          "id": "interfaze-1775270750639",
          "object": "chat.completion",
          "model": "interfaze",
          "choices": [
            {
              "index": 0,
              "message": {
                "role": "assistant",
                "content": "{\"name\":\"Yoeven D Khemlani\"}"
              },
              "finish_reason": "stop"
            }
          ],
          "usage": {
            "prompt_tokens": 10512,
            "completion_tokens": 7056,
            "total_tokens": 17568
          },
          "vcache": false,
          "precontext": [
            {
              "name": "web_search",
              "result": [
                {
                  "title": "Interfaze | Y Combinator",
                  "url": "https://www.ycombinator.com/companies/interfaze",
                  "description": "AI model built for deterministic developer tasks."
                }
              ]
            }
          ]
        }
      },
      "Choice": {
        "type": "object",
        "description": "A single completion choice.",
        "properties": {
          "index": {
            "type": "integer",
            "description": "The index of this choice in the `choices` array."
          },
          "message": {
            "$ref": "#/components/schemas/Message"
          },
          "finish_reason": {
            "type": "string",
            "enum": ["stop", "length", "tool_calls"],
            "description": "The reason the model stopped generating. `stop` = natural end or stop sequence, `length` = max tokens reached, `tool_calls` = model wants to call a tool."
          }
        }
      },
      "Usage": {
        "type": "object",
        "description": "Token usage statistics.",
        "properties": {
          "prompt_tokens": {
            "type": "integer",
            "description": "Number of tokens in the prompt."
          },
          "completion_tokens": {
            "type": "integer",
            "description": "Number of tokens in the completion."
          },
          "total_tokens": {
            "type": "integer",
            "description": "Total tokens used (prompt + completion)."
          }
        }
      },
      "PrecontextEntry": {
        "type": "object",
        "description": "Raw output from an internal task the model performed.",
        "properties": {
          "name": {
            "type": "string",
            "description": "The task that produced this result (e.g. `ocr`, `stt`, `translate`, `web_search`, `scraper`, `object_detection`, `guardrails`, `code_sandbox`)."
          },
          "result": {
            "description": "The structured metadata for the task. Shape varies per task type."
          }
        }
      },
      "ChatCompletionChunk": {
        "type": "object",
        "description": "A single chunk in a streaming response.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the completion."
          },
          "object": {
            "type": "string",
            "const": "chat.completion.chunk"
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": { "type": "integer" },
                "delta": {
                  "type": "object",
                  "description": "Partial message content.",
                  "properties": {
                    "role": { "type": "string" },
                    "content": { "type": "string" }
                  }
                },
                "finish_reason": {
                  "type": ["string", "null"],
                  "enum": ["stop", "length", "tool_calls", null]
                }
              }
            }
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "description": "Error response wrapper.",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorObject"
          }
        },
        "example": {
          "error": {
            "message": "Invalid API key provided.",
            "type": "invalid_request_error",
            "code": "invalid_api_key"
          }
        }
      },
      "ErrorObject": {
        "type": "object",
        "description": "Error details.",
        "properties": {
          "message": {
            "type": "string",
            "description": "A human-readable error message."
          },
          "type": {
            "type": "string",
            "description": "Error type (e.g. `invalid_request_error`, `authentication_error`, `rate_limit_error`).",
            "enum": [
              "invalid_request_error",
              "authentication_error",
              "insufficient_quota",
              "payload_too_large",
              "rate_limit_error",
              "internal_error",
              "service_unavailable"
            ]
          },
          "code": {
            "type": "string",
            "description": "A machine-readable error code."
          }
        }
      }
    }
  }
}