Developer Documentation

Augure API

OpenAI-compatible chat completions API with Canadian data residency. Never routed to US providers.

Base URL: https://api.augureai.ca

Data Routing & Residency

All API requests enter through our gateway in Beauharnois, Quebec. Inference runs on Canadian infrastructure and with vetted partners in the European Union under zero-data-retention agreements, and is never routed to providers in the United States. Some model tiers, and failover during outages or peak demand, are served by the EU partners; others run in Canada. A response that was not served by the model’s primary capacity says so in _augure.fallback. Image reading and voice synthesis run on GPU servers Augure manages in Calgary, Alberta. Prompts are encrypted in transit (TLS 1.2+), never logged by Augure, and never used for model training.

Accounts that need every request to stay in Canada can turn on Canadian inference only in the developer dashboard (Settings): requests then stay in Canada or fail with 503 residency_unavailable, never served elsewhere. GET /v1/limits reports it as residency.

Canadian gatewayDisclosed EU failoverNever US providersNo prompt logging
On this page

Authentication

All API endpoints require a Bearer token. Include your API key in the Authorization header of every request.

Example
curl https://api.augureai.ca/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"
Getting a key: Keys are self-serve. Sign in to the developer dashboard, add a payment method, and generate a key. Your key is shown once, so store it somewhere safe. Usage is metered and billed monthly in CAD, and you can set a monthly spend limit in the dashboard’s Billing tab.
REST or MCP? This API is for software you write. If you want Augure inside an assistant you already use (for example Claude Code), connect the MCP server instead. Both bill the same developer account at the same rates.

Models

Seven models plus an auto alias that routes each request to the best available model. Context is the input window; Max output is the per-model cap on completion tokens.

ModelContextMax outputBest for
auto——Letting the gateway choose per request; image inputs
ossington-5256K32,768Newest reasoning model, fastest of the reasoning tiers. Code, structured output, general analysis
rosedale-11M32,768Premium reasoning with a very large context. Whole-document analysis, reliable tool calling and agent loops
ossington-4256K32,768Flagship reasoning. Complex analysis, synthesis, multi-step tasks
ossington-4-1256K32,768Premium reasoning on Canadian infrastructure. Tools and strong bilingual (EN/FR) work
tofino-3256K16,384Light tier, thinking always off, served in Canada with no failover outside Canada. Translation, extraction, classification, chat
open-glm-5-3256K49,152Augure Open (preview): GLM-5.3 open weights, messages reach the model as sent, text only, Canada only
open-qwen-3.8-flash-next256K32,768Augure Open (preview): Qwen3.8-Flash-Next open weights, messages reach the model as sent, text only, Canada only

ossington-4-1: if its Canadian backend is unavailable the request is served by ossington-5, and the response says so (_augure.fallback is set and model names what answered). Canada-only accounts stay in Canada or fail cleanly.

rosedale-1’s 1M window is available to every developer key. Use stream: true for very large inputs: a near-window prompt can take a few minutes before the first token.

Retirements: ossington-3 retired on 2026-10-15 and is replaced by rosedale-1. tofino-2.5 retired on 2026-09-19 and is replaced by tofino-3. After a retirement date a developer key naming the old id gets 400 model_retired with the replacement in the message. See Model lifecycle.
OpenAI compatibility: The aliases gpt-4 and gpt-4o map to ossington-4; gpt-4o-mini and gpt-3.5-turbo map to tofino-3.

Chat completions

POST/v1/chat/completions

Create a chat completion. Accepts the same request format as the OpenAI chat completions endpoint.

Parameters

FieldTypeRequiredDescription
modelstringYesModel ID (see Models)
messagesarrayYesMessage objects: text, images or files (see below)
streambooleanNoStream the response as Server-Sent Events. Default: false
stream_optionsobjectNo{"include_usage": true} adds a final usage chunk before [DONE]
temperaturenumberNoSampling temperature (0.0–2.0)
top_pnumberNoNucleus sampling threshold
seednumberNoDeterministic-sampling seed. temperature: 0 plus a fixed seed maximizes run-to-run repeatability
max_tokensnumberNoMaximum output tokens (global cap 32,768). Omit it on reasoning models; see Reasoning
reasoning_effortstringNonone, minimal, low, medium or high on the reasoning models; see Reasoning
response_formatobjectNo{"type": "json_object"} or {"type": "json_schema", ...}. On reasoning models it is enforced by a prompt-level directive: validate the parsed result and retry once on failure. Not combined with tools on those models
stopstring | arrayNoStop sequence(s)
toolsarrayNoFunctions the model may call; see Tool use
tool_choicestring | objectNonone, auto (default with tools), required, or a specific function
parallel_tool_callsbooleanNoAllow several tool calls in one turn. Default: true

Each message has a role (system, user, assistant or tool) and a content that is a string, an array of parts (text, image_url, file), or null when the assistant message carries tool_calls.

Context windows. Every chat model accepts a 256K-token context; rosedale-1 accepts up to 1M (1,048,576 tokens). max_tokens caps output only. A prompt over the model’s window returns 400 context_length_exceeded. Always check finish_reason: "length" means the output budget ran out and the answer is truncated.

Example request

curl
curl -X POST https://api.augureai.ca/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ossington-5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the Civil Code of Quebec?"}
    ]
  }'

Example response

Response
{
  "id": "chatcmpl-a9adf17e-5ff3-4804-b01e-f7cbd30ae996",
  "object": "chat.completion",
  "created": 1771286577,
  "model": "ossington-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The Civil Code of Quebec (Code civil du Québec) is..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 150,
    "total_tokens": 174
  },
  "_augure": {
    "gateway_region": "ca-montreal-1",
    "inference_region": "ca-on-toronto",
    "request_id": "a9adf17e-5ff3-4804-b01e-f7cbd30ae996"
  }
}

Usage and cost

Every response carries a usage object with prompt_tokens, completion_tokens and total_tokens; multiply by the per-model rates on the developer page to price a call. Your developer dashboard shows the same numbers per model, per day and per key, with the cost in CAD. Text extracted from an attached PDF counts toward prompt tokens like any other input.

Reasoning

ossington-5, ossington-4, ossington-4-1 and rosedale-1 think before they answer. The thinking is returned separately as reasoning_content (delta.reasoning_content when streaming), so content stays a clean final answer. Clients that don’t recognise reasoning_content can ignore it.

Thinking uses most of the output budget, so a tight max_tokens can truncate the visible answer. Omit max_tokens on these models, or set it to the model’s maximum.

Turning thinking off

For short mechanical tasks (correction, extraction, classification, reformatting), send "reasoning_effort": "none" on ossington-5, ossington-4 or ossington-4-1. The model answers immediately with no reasoning_content, typically 10–50× faster, and you are billed only for the visible answer.

Request body
{
  "model": "ossington-5",
  "reasoning_effort": "none",
  "messages": [
    {"role": "user", "content": "Fix the typos: 'Teh contract was sined on Tuesady.'"}
  ]
}

On rosedale-1, send "low" instead: it has no true thinking-off mode, so "none" is served as "low". For hard multi-step reasoning, leave the field unset. tofino-3 always runs with thinking off and ignores the field.

Streaming

Set "stream": true to receive Server-Sent Events. Each event is a JSON chunk with a delta object containing incremental content; the stream ends with data: [DONE]. Add "stream_options": {"include_usage": true} to receive a final chunk carrying the usage object (with empty choices) just before it.

Streaming request
curl -N -X POST https://api.augureai.ca/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tofino-3",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Errors inside a stream

A stream commits HTTP 200 before generation finishes, so a failure mid-way arrives inside the stream as an error event, followed by data: [DONE]:

Error event
data: {"error":{"message":"This conversation is too long for the model. Start a new session or shorten your message, then try again.","type":"upstream_error","code":"context_length_exceeded"}}

data: [DONE]
  • Treat any event with a top-level error object as a failed turn and surface error.code.
  • A stream that ends with no finish_reason and no error event lost its connection: treat it as a failure, not an empty answer.
  • Retry quota_exceeded and capacity_exceeded with backoff; never retry context_length_exceeded (reduce the input). An error before any content means nothing was generated, so a retry is always safe.
  • Long prompts may produce SSE comment lines (: keepalive); standard SSE parsers ignore them.

Images and documents

content can be an array of parts. Alongside text parts, a user message may carry image_url parts and file parts, each as a base64 data URL. Requests stay plain JSON: there is no multipart/form-data endpoint.

Images

Images work with any model. With model: "auto" the gateway routes the image to our vision engine, which runs on Augure-operated servers in Calgary (inference_region: ca-ab-calgary). If you pin another model, the image is read into text first and handed to that model. PNG, JPEG, WebP and GIF (first frame) are accepted, several per message. Don’t send images as file parts; they are rejected with 400 invalid_attachment.

Read an image
curl -X POST https://api.augureai.ca/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Extract all text from this image, preserving layout as Markdown."},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."}}
      ]
    }]
  }'

For verbatim text with no description, add "augure_ocr": true to the image part:

Pure OCR
{ "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBOR..." }, "augure_ocr": true }

PDFs and spreadsheets

A file part carries a PDF, which is read on the gateway: the text layer is extracted directly, and scanned documents are OCR’d automatically. Send the PDF itself rather than rendering it to an image; you keep the exact text, and it works with every model.

PDF attachment
curl -X POST https://api.augureai.ca/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ossington-5",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Extract the invoice number, date, vendor and total as JSON."},
        {"type": "file", "file": {
          "filename": "invoice-2041.pdf",
          "file_data": "data:application/pdf;base64,JVBERi0xLjQK..."
        }}
      ]
    }]
  }'
Python
import base64
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.augureai.ca/v1")
pdf = base64.b64encode(open("invoice-2041.pdf", "rb").read()).decode()

response = client.chat.completions.create(
    model="ossington-5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Extract the invoice number, date, vendor and total as JSON."},
            {"type": "file", "file": {
                "filename": "invoice-2041.pdf",
                "file_data": f"data:application/pdf;base64,{pdf}",
            }},
        ],
    }],
)
print(response.choices[0].message.content)

When layout, tables, signatures or stamps matter, set "augure_render": "image" on the file part with model: "auto": each page is rendered and sent to the vision engine (up to 50 pages, and it uses noticeably more tokens than text mode). A pinned chat model falls back to text extraction.

Page-as-image rendering
{
  "type": "file",
  "file": {
    "filename": "contract.pdf",
    "file_data": "data:application/pdf;base64,JVBERi0xLjQK...",
    "augure_render": "image"
  }
}

Each PDF may be up to 25 MB and 200 pages, within the 35 MB request body (after base64 encoding). A file part also accepts spreadsheets (.xlsx or .csv data URLs, first 100 rows of each sheet). The gateway keeps no copy of a file once the request completes.

List models

GET/v1/models

Returns the models available to your key.

curl
curl https://api.augureai.ca/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "object": "list",
  "data": [
    { "id": "auto",          "object": "model", "owned_by": "augure" },
    { "id": "rosedale-1",    "object": "model", "owned_by": "augure" },
    { "id": "ossington-4-1", "object": "model", "owned_by": "augure" },
    { "id": "ossington-5",   "object": "model", "owned_by": "augure" },
    { "id": "ossington-4",   "object": "model", "owned_by": "augure" },
    { "id": "tofino-3",      "object": "model", "owned_by": "augure" }
  ]
}
POST/v1/search

Search the public web through Augure’s self-hosted search. This is a standalone endpoint: /v1/chat/completions does not call it, and there is no built-in web-search tool. To ground a model in live results, call /v1/search yourself and pass the results into your next message.

FieldTypeRequiredDescription
querystringYesSearch query
countnumberNoNumber of results, 1–20. Default: 5
langstringNoen or fr (mapped to en-CA / fr-CA). Default: en
curl
curl -X POST https://api.augureai.ca/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Quebec Law 25 enforcement 2026", "count": 5, "lang": "en" }'
Response
{
  "results": [
    { "title": "…", "url": "https://…", "description": "…" }
  ]
}

Errors: 400 empty or missing query · 503 search not configured · 502 / 504 upstream error or timeout.

When your latest user message includes a URL, Augure fetches the page server-side and hands its text to the model, so you can ask about a page without pasting it. HTML is converted to clean Markdown; linked PDFs are extracted (with OCR fallback). Link reading follows URLs you provide; it does not search.

Links that were read are listed under _augure.fetched_urls, so a client can show its sources:

Response excerpt
"_augure": {
  "fetched_urls": [
    { "url": "https://…", "title": "…", "ok": true, "kind": "html" }
  ]
}

Fetching is bounded (a few URLs per message, size and time caps) and fails soft: an unreadable link never fails the request, and the model is told the page couldn’t be read.

Memories

A per-user long-term memory store, the same memory the Augure apps use. These endpoints need a key tied to a user account; a key with no user returns 401.

MethodPathBodyResult
GET/v1/memories—{ "memories": [ { "id", "content", "createdAt", ... } ] }
POST/v1/memories{ "content": "…" }{ "success": true, "id": "…" }
PATCH/v1/memories{ "id": "…", "content": "…" }{ "success": true }
DELETE/v1/memories{ "id": "…" }{ "success": true }

Memory content is 1 to 2,000 characters.

Add a memory
curl -X POST https://api.augureai.ca/v1/memories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Client prefers responses in French." }'

Tool use

Augure accepts the OpenAI-compatible tools (function-calling) schema, streaming and non-streaming. For reliable structured tool calling and agent loops, use rosedale-1, with reasoning_effort: "low" when you want tool calls with minimal thinking. ossington-4-1 also calls tools well when you need deeper analysis in the loop. tofino-3 suits simple single-shot calls, not multi-step agent loops. If your application drives an agent loop, pin rosedale-1 rather than relying on auto.

When the model calls a tool, finish_reason is "tool_calls" and the assistant message carries tool_calls[]. Run the function yourself, append a role: "tool" message with the result, and call the API again.

Request with tools
curl -X POST https://api.augureai.ca/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rosedale-1",
    "reasoning_effort": "low",
    "messages": [
      {"role": "user", "content": "What grants is my client eligible for?"}
    ],
    "tools": [{
      "type": "function",
      "function": {
        "name": "search_grant_programs",
        "description": "Search the grant database by client profile",
        "parameters": {
          "type": "object",
          "properties": {
            "discipline": {"type": "string"},
            "province": {"type": "string"}
          },
          "required": ["discipline"]
        }
      }
    }]
  }'
Response: the model calls the tool
{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "search_grant_programs",
          "arguments": "{\"discipline\":\"visual arts\",\"province\":\"QC\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}
Follow-up with the tool result
{
  "model": "rosedale-1",
  "messages": [
    {"role": "user", "content": "What grants is my client eligible for?"},
    {"role": "assistant", "content": null, "tool_calls": [/* ...from previous response... */]},
    {"role": "tool", "tool_call_id": "call_abc123", "name": "search_grant_programs", "content": "[{\"id\":\"CALQ-2026\",\"name\":\"...\"}]"}
  ],
  "tools": [/* same tools array */]
}

Streaming: tool calls arrive as deltas in choices[0].delta.tool_calls[] with an index; concatenate the function.arguments fragments per index and dispatch when finish_reason: "tool_calls" arrives. Parallel calls are on by default; set parallel_tool_calls: false for one call per turn.

Tools and MCP: The API does not connect to MCP servers itself; MCP lives in the client (the “MCP host”), which turns its MCP tools into ordinary tools entries. Any MCP-capable client that accepts a custom OpenAI-compatible base URL works with Augure. To use Augure’s own tools from an assistant, see the MCP server.

Augure metadata

Every response includes an _augure block with routing and traceability information.

FieldDescription
gateway_regionAPI gateway region (ca-montreal-1, OVHcloud)
inference_regionWhere inference ran, e.g. ca-on-toronto or ca-ab-calgary
request_idUnique request id, also in the X-Request-ID header. Log it: support uses it to find a failed request
fetched_urlsLinks that were read; see Link reading
fallback / fallback_reasonPresent only when the turn was not served by the model's primary capacity, with the reason
fallback_contextRare: "truncated" when a conversation over 256K was served with middle content elided; treat the response as partial
auto_routed / auto_route_reasonWith model: "auto": which model was picked, and why
deprecationOn a model scheduled for retirement: { model, retires_at, replacement, message }
retiredWhen a retired id was served by its replacement (for example the gpt-4o-mini alias)
outbound_filterPresent only when the outbound link filter removed something; counts per rule

Text a model reads but you didn’t write (an attachment, a fetched page, an earlier turn) can try to make it emit an image or link whose URL carries conversation data. The gateway rewrites the assistant’s output: remote images outside Augure’s domains become [image removed: external image], and links whose URL carries an identifier from the conversation or a long opaque token become [link removed: may contain conversation data]. Ordinary links, and links you pasted yourself, are returned unchanged. If your integration needs remote images in model output (for example from your own CDN), contact support to allowlist a host.

Client libraries

Use any OpenAI-compatible SDK. Point it to https://api.augureai.ca/v1 as the base URL.

Python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.augureai.ca/v1"
)

response = client.chat.completions.create(
    model="ossington-5",
    messages=[
        {"role": "user", "content": "Explain Quebec privacy law"}
    ]
)
print(response.choices[0].message.content)
JavaScript / TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.augureai.ca/v1",
});

const response = await client.chat.completions.create({
  model: "tofino-3",
  messages: [{ role: "user", content: "Summarize PIPEDA" }],
});
console.log(response.choices[0].message.content);
Streaming (Python)
stream = client.chat.completions.create(
    model="rosedale-1",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

Rate limits and quotas

Request rate, per API key. Developer keys carry X-RateLimit-Limit and X-RateLimit-Remaining headers; a 429 also carries Retry-After (seconds).

TierRequests / min
standard (default)60
elevated200
unlimited1,000

ossington-4 also has a hard cap of 10 requests per minute on every tier. Contact us to move a key to a higher tier.

Concurrency. Each developer key can have 20 requests in flight by default (429 concurrency_limit_exceeded beyond that), and each account has a share of every model’s primary capacity across all its keys. Beyond that share a request is served by the model’s backup capacity when it has room, or refused with 429 capacity_exceeded and Retry-After.

Daily spend cap. Developer keys have a hard ceiling of $100 CAD per day ($25 CAD per day until the account’s first successful charge), weighted by model. Over the cap, requests return 429 quota_exceeded. The counter resets at 00:00 UTC; contact support to raise it.

Limits

Request body

35 MB max

PDF attachment

25 MB / 200 pages

Messages per request

256 max

Max output tokens

32,768 (tofino-3: 16,384)

Response time, non-streaming

~240 s, then 504

Prompt processing, streaming

up to 12 min

For large inputs, use stream: true: a streamed response stays alive with keepalives while a long prompt is processed.

Teams and labs

One developer account serves a whole team. The account owner creates one key per person, usage and cost show per key, and one monthly spend limit covers them all. Billing is by usage in CAD, with no per-seat fee and no minimum. On an account with an Ultra plan, keys draw that plan’s shared allowance instead of being metered, and stop when it runs out.

What you getWhere
One named key per person (up to 50 active keys on an account)Dashboard → Overview
Usage and cost per key, per model and per dayDashboard → Usage
One monthly spend limit for the account, with warnings at 75, 90 and 100 %Dashboard → Billing
Canada-only processing, applied once at the account level to every key, present and futureDashboard → Settings → Canadian inference only
The full long context of rosedale-1, the same as in the appsNo setup
Plan tokens are not team keys: The “Connect a coding tool” tokens on Max and Ultra are personal: five per account, meant for one person’s machines, all drawing on that one subscription’s weekly allowance. For a group, give each person a developer key on the team’s account, or their own Max or Ultra seat: Ultra is now available as a team seat too, on Augure for Teams.
Claude Code: Augure does not serve the Anthropic Messages API. Claude Code reaches Augure through a LiteLLM proxy with rosedale-1; the IDE guide has the setup. OpenCode, Continue and Cline connect directly.

Errors

All errors return a JSON object with an error field, matching the OpenAI error format. param names the offending field when there is one.

Error response
{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
StatuscodeWhenRetry?
400invalid_json · missing_field · invalid_value · invalid_attachmentMalformed request, or an unsupported or oversized file partNo: fix the request
400context_length_exceededThe prompt exceeds the model's context windowNo: reduce the input or use rosedale-1
400model_retiredThe model id was retired; the message names its replacementNo
401invalid_api_keyMissing or unrecognised API keyNo
402billing_inactiveBilling on the account is not in good standing (no card, or past due)No
404model_not_found · not_foundUnknown model or endpointNo
413request_too_largeRequest body over 35 MBNo
429rate_limit_exceeded · quota_exceededPer-minute rate exceeded; spend cap or token quota reached; or shared capacity temporarily exhaustedYes: honour Retry-After, back off
429concurrency_limit_exceededToo many requests in flight for this keyYes, when one finishes
429capacity_exceededThe model is at capacity for your account and its backup is fullYes: honour Retry-After
503residency_unavailableCanada-only account: Canadian capacity unavailable, request not served elsewhereYes: honour Retry-After
500internal_error · server_errorInternal errorYes, once
502upstream_error · empty_completionUpstream inference error, or the model returned nothingYes, with backoff
504timeoutA non-streaming request ran past ~240 sUse stream: true or a smaller input

Streaming requests deliver mid-generation failures inside the stream with these same codes; see Errors inside a stream.

Versioning

The API is versioned by the /v1 path prefix. Additive changes (new response fields, new models, new optional parameters) ship without a version bump, so clients should ignore fields they don’t recognise. A breaking change would ship under a new prefix and be announced to registered developers in advance.

See the changelog for dated changes and Model lifecycle for retirement dates and replacements.

Ready to integrate?

Get your API key and start building with Augure.

Get API Access