Chat API quickstart

Use Vulgate's Library-grounded chat via the OpenAI-compatible Chat Completions interface.

May 21, 2026

The Chat API is OpenAI-compatible. It implements the same /chat/completions shape as the OpenAI Chat Completions API, so any client that speaks that protocol — the official openai SDKs, the Vercel ai SDK, your own fetch calls — works by pointing at Vulgate.

Under the hood, Vulgate runs retrieval against the Libraries your API key has access to and feeds the relevant passages to the model. Responses include citations referencing the source passages.

The full reference lives at /docs/chat/overview. This is the minimum to get started.

A minimal request

curl -X POST "https://vulgate.ai/api/chat/completions" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vulgate-1",
    "messages": [
      {"role": "user", "content": "Summarize the council teachings on Eucharistic adoration."}
    ]
  }'

Response (truncated):

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "vulgate-1",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The councils teach that Eucharistic adoration..."
    },
    "finish_reason": "stop"
  }],
  "citations": [
    {
      "cited_text": "<p>...</p>",
      "document_title": "Ecclesia de Eucharistia",
      "document_index": 0,
      "document_author": "John Paul II",
      "source_url": null
    }
  ]
}

Streaming

Set stream: true and you'll get server-sent events in the OpenAI chat.completion.chunk shape:

curl -X POST "https://vulgate.ai/api/chat/completions" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vulgate-1",
    "stream": true,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Each chunk is a JSON object prefixed with data: , ending with data: [DONE]. Identical to OpenAI; existing parsers work.

Libraries

Unlike the Search API, the Chat API does not take a libraries parameter. The AI automatically searches the Libraries your API key's team has access to.

Using the OpenAI Python SDK

The OpenAI SDK works directly — just point base_url at Vulgate:

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["VULGATE_API_KEY"],
    base_url="https://vulgate.ai/api",
)

response = client.chat.completions.create(
    model="vulgate-1",
    messages=[{"role": "user", "content": "Summarize the canon on confirmation."}],
)
print(response.choices[0].message.content)

Models

Pass vulgate-1 (or the alias vulgate) in the model field. See /docs/chat/overview for the current list.

Rate limits and timeouts

  • 10 requests per 10 seconds per team (sliding window).
  • 120 seconds per request.

Exceeding the rate limit returns 429 with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Errors

The API uses standard HTTP status codes:

  • 401 — invalid or missing API key.
  • 429 — rate limit exceeded.
  • 400 — request body malformed; the response body explains what's wrong.
  • 500 / 502 — Vulgate-side issue; retry with exponential backoff.

Related

Search help