---
title: "Chat completion (OpenAI-compatible)"
method: POST
path: "/v1/chat/completions"
tags: ["OpenAI Compatibility"]
---

# Chat completion (OpenAI-compatible)

`POST /v1/chat/completions`

## Request

- Base URL: `https://api.johnsessentials.com`
- URL: `https://api.johnsessentials.com/v1/chat/completions`
- Auth: HTTP bearer

Drop-in for OpenAI's chat completions. Set your OpenAI SDK's
`base_url` to `https://api.johnsessentials.com/v1` and the rest
of your code is unchanged.

- **Auth:** `Authorization: Bearer je_live_sk_…` (same header OpenAI uses).
- **Models:** `johns-agent` (default — runs our orchestrator with the full tool catalogue). `johns-fast`/`johns-smart` are accepted aliases; today all values (including free-form ones) route through the same provider pool, so `model` is a forward-compatible hint rather than a hard selector.
- **Streaming:** set `stream: true` → response is `text/event-stream` with OpenAI's `data: {…}\n\n` … `data: [DONE]\n\n` shape.
- **Tools:** when `tools=[…]` is present, BYPASSES our orchestrator and calls the LLM provider directly with your tool definitions. ~40× cheaper per request.
- **Cost cap:** if your key's monthly USD cap is reached, returns 402 in OpenAI's error envelope shape, NOT 429.

**⚠ "Try it" caveat — streaming:** Scalar's in-page request runner
renders one-shot JSON responses cleanly but is not built for
SSE. If you send `stream: true` from the Try it button you will
see raw event-stream bytes accumulating rather than a parsed
chunk-by-chunk view. For interactive streaming evaluation, use
the OpenAI Python or TypeScript SDK with `base_url` swapped to
ours — copy the snippet from this page's code-sample switcher.

## Request body

- OAIChatRequest
  - `max_tokens` integer
  - `messages` OAIMessage[], required
    - `content` unknown
    - `name` string
    - `role` 'system' | 'user' | 'assistant' | 'tool', required
    - `tool_call_id` string
    - `tool_calls` OAIToolCall[]
      - `function` object, required
        - `arguments` string, required: JSON-encoded string per OpenAI's wire shape — NOT an object.
        - `name` string, required
      - `id` string, required
      - `type` 'function', required
  - `model` string, required: `johns-agent` (default — runs our orchestrator with the full tool catalogue). `johns-fast` and `johns-smart` are accepted aliases reserved for low-latency / high-quality routes; today they and any other value (e.g. `gpt-4o`) route through the same health-ordered provider pool. Treat `model` as a forward-compatible hint — your code keeps working unchanged.
  - `stop` unknown
  - `stream` boolean
  - `temperature` number
  - `tool_choice` unknown
  - `tools` OAITool[]: When present, BYPASSES our orchestrator and calls the LLM provider directly with your tool definitions. Response will include `tool_calls` in the OpenAI shape; you execute the tools on your side. ~40× cheaper per request than the orchestrator path.
    - `function` OAIFunctionDef, required
      - `description` string
      - `name` string, required
      - `parameters` object: JSON Schema for the function's arguments.
    - `type` 'function', required
  - `user` string: End-user identifier for abuse tracking.

## Response `200`

Completion result (non-stream) OR opening SSE chunk (stream).

- OAIChatResponse
  - `choices` OAIChoice[], required
    - `delta` OAIMessage
      - `content` unknown
      - `name` string
      - `role` 'system' | 'user' | 'assistant' | 'tool', required
      - `tool_call_id` string
      - `tool_calls` OAIToolCall[]
        - `function` object, required
          - `arguments` string, required: JSON-encoded string per OpenAI's wire shape — NOT an object.
          - `name` string, required
        - `id` string, required
        - `type` 'function', required
    - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter', required
    - `index` integer, required
    - `logprobs` unknown
    - `message` OAIMessage
      - `content` unknown
      - `name` string
      - `role` 'system' | 'user' | 'assistant' | 'tool', required
      - `tool_call_id` string
      - `tool_calls` OAIToolCall[]
        - `function` object, required
          - `arguments` string, required: JSON-encoded string per OpenAI's wire shape — NOT an object.
          - `name` string, required
        - `id` string, required
        - `type` 'function', required
  - `created` integer, required: Unix seconds.
  - `id` string, required
  - `model` string, required
  - `object` 'chat.completion' | 'chat.completion.chunk', required
  - `system_fingerprint` string
  - `usage` OAIUsage
    - `completion_tokens` integer
    - `prompt_tokens` integer
    - `total_tokens` integer

## Other responses

- `400`: Invalid request (OpenAI error envelope).
- `401`: Auth failed (OpenAI error envelope).
- `402`: Monthly cost cap reached (OpenAI error envelope, code `quota_cost_exceeded`).
- `429`: Rate limited (OpenAI error envelope, type `rate_limit_exceeded`).

---

[API](https://skmtc.dev/johnsessentials/apis/john-s-essentials-api.md) · [All operations](https://skmtc.dev/johnsessentials/apis/john-s-essentials-api/llms.txt) · [OpenAPI document](https://skmtc.dev/johnsessentials/apis/john-s-essentials-api/revisions/56586ff78e6d?raw)