> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ageneral.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create chat completion

> OpenAI **Chat Completions**–compatible JSON body (`model`, `messages`, optional `stream`, tools, etc.). The server injects **conversation history** for the session, applies a default **model** when needed, and **runs inference** for you. Responses may be JSON or **`text/event-stream`** — server-sent events.

If the last user message is exactly **`/new`**, the API creates a new session and returns a minimal SSE stream **without** calling inference.

**Billing:** Requires spendable balance for the project; otherwise **402**.



## OpenAPI

````yaml /api-reference/ageneral-chat-openapi.json post /v1/chat/completions
openapi: 3.1.0
info:
  title: Chat
  version: 1.0.0
  description: >-
    **Platform chat** for the Ageneral web app: session-backed conversations
    tied to a **project**, with inference using your **project access**. **Base
    URL:** `https://ageneral.ai`.


    **Not** the inference-only host at `models.ageneral.ai` — use
    **`https://models.ageneral.ai`** instead. That host uses **API keys** only —
    no **`Ageneral-Project-Id`** or session headers.


    **Authentication:** `Authorization: Bearer <session JWT>` from Ageneral
    sign-in.


    **Project scope:** Every route requires header **`Ageneral-Project-Id`**
    with a project you can access.


    **Session:** For **`POST /v1/chat/completions`** and **`POST
    /v1/chat/responses`**, send optional **`Ageneral-Session-Id`** to continue
    an existing session; responses echo the active session id in the
    **`Ageneral-Session-Id`** response header. Omit the header to start a new
    session.
  contact:
    name: Ageneral
    url: https://ageneral.ai
servers:
  - url: https://ageneral.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Chat completions
    description: >-
      OpenAI Chat Completions–compatible body; server merges history and
      defaults model.
  - name: Responses
    description: >-
      Streaming responses compatible with OpenAI **Responses**; request uses
      `model` and `messages`.
  - name: Sessions
    description: List, update metadata, and load stored messages for platform chat.
paths:
  /v1/chat/completions:
    post:
      tags:
        - Chat completions
      summary: Create chat completion
      description: >-
        OpenAI **Chat Completions**–compatible JSON body (`model`, `messages`,
        optional `stream`, tools, etc.). The server injects **conversation
        history** for the session, applies a default **model** when needed, and
        **runs inference** for you. Responses may be JSON or
        **`text/event-stream`** — server-sent events.


        If the last user message is exactly **`/new`**, the API creates a new
        session and returns a minimal SSE stream **without** calling inference.


        **Billing:** Requires spendable balance for the project; otherwise
        **402**.
      operationId: platformChatCompletions
      parameters:
        - $ref: '#/components/parameters/AgeneralProjectId'
        - $ref: '#/components/parameters/AgeneralSessionIdOptional'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformChatCompletionRequest'
      responses:
        '200':
          description: >-
            Success. JSON completion object or `text/event-stream` when
            streaming.
          headers:
            Ageneral-Session-Id:
              description: Active platform chat session id after this request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
                description: SSE stream of completion chunks.
        '400':
          description: >-
            Bad request — missing `Ageneral-Project-Id`, invalid JSON or
            messages, or similar.
        '401':
          description: Missing or invalid session JWT.
        '402':
          description: Insufficient balance.
        '403':
          description: User cannot access this project.
        '404':
          description: >-
            `Ageneral-Session-Id` does not match a platform session for this
            user and project.
        '502':
          description: Inference request failed.
        '503':
          description: Billing, model access, or chat persistence not configured.
      security:
        - bearerAuth: []
components:
  parameters:
    AgeneralProjectId:
      name: Ageneral-Project-Id
      in: header
      required: true
      schema:
        type: string
      description: Project id. You must be a member with access.
    AgeneralSessionIdOptional:
      name: Ageneral-Session-Id
      in: header
      required: false
      schema:
        type: string
      description: >-
        Existing platform chat session to continue. Omit to create a new session
        on first non-`/new` turn.
  schemas:
    PlatformChatCompletionRequest:
      type: object
      required:
        - messages
      description: >-
        Aligned with OpenAI **Create chat completion**. The server may override
        or fill **`model`** and merges prior turns from storage.
      properties:
        model:
          type: string
          description: Optional `provider/model`; a default applies when omitted.
          example: openai/gpt-4o-mini
        messages:
          type: array
          items:
            type: object
            additionalProperties: true
        stream:
          type: boolean
        temperature:
          type: number
        max_tokens:
          type: integer
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    ChatCompletionResponse:
      type: object
      description: OpenAI-compatible chat completion object when not streaming.
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Session JWT from Ageneral sign-in. Send as `Authorization: Bearer
        <token>`.

````