API reference

ODEN docs

One POST call turns a query into a synthesized answer plus ranked, citation-backed JSON — built to drop straight into a model's context window. This is everything you need to make your first call and read what comes back.

Overview

The API has a single endpoint. You send a query, ODEN searches the open web with its own retrieval stack, honors robots.txt and EU TDM opt-out at the source, then returns a synthesized answer and a ranked list of citations as JSON. No HTML, no scraped page bodies — just the distilled result and the metadata your model needs to attribute it.

POST https://api.oden-api.com/search

All requests are POST, send and receive application/json, and require a bearer token.

Authentication

Pass your key in the Authorization header as a bearer token. Create and rotate keys from your dashboard. Keep keys server-side — anyone with the key can spend your quota.

Header

Authorization: Bearer oden_live_••••••••••••••••

Lost a key? Rotate it from the dashboard — generate a new one and delete the old. A revoked key stops working immediately.

Quickstart

Send a query and read the response. Pick your language.

$ curl https://api.oden-api.com/search \
  -H "Authorization: Bearer $ODEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "what are the moons of saturn?"}'

import os, requests

resp = requests.post(
    "https://api.oden-api.com/search",
    headers={"Authorization": f"Bearer {os.environ['ODEN_KEY']}"},
    json={"query": "what are the moons of saturn?", "answer": True},
)
data = resp.json()
print(data["results"]["answer"])

const resp = await fetch("https://api.oden-api.com/search", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ODEN_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "what are the moons of saturn?", answer: true }),
});
const data = await resp.json();
console.log(data.results.answer);

On Windows PowerShell, curl mangles inner quotes. Use Invoke-RestMethod with ConvertTo-Json for the body, or run the curl example from WSL / Git Bash.

POST /search

The one endpoint. Send a JSON body with your query; receive a synthesized answer and ranked citations.

POST https://api.oden-api.com/search

Request

A JSON object. The body is small on purpose.

Field	Type	Required	Description
query	string	Required	The question or search phrase. Natural language works best. Max 500 characters.
answer	boolean	Optional	Set `true` to include a synthesized answer in `results.answer`. Defaults to `false` (citations only).
depth	string	Optional	`advanced` (default) does full passage extraction; `basic` returns faster snippet-level results.
include_snippets	boolean	Optional	Set `true` to add one attributed sentence per citation in `citations[].snippet`.

Body

{
  "query": "capital of sweden"
}

Response

A JSON object with request metadata and a results object holding the answer and its sources.

Field	Type	Description
query	string	Your query, echoed back.
trace_id	string	Unique ID for this request. Include it when reporting an issue.
execution_time_ms	number	Server-side processing time in milliseconds.
cached	boolean	`true` when the result was served from cache. Cached calls are much faster.
results	object	The answer and its citations.
results.answer	string	Synthesized answer. Present only when `answer: true` was sent.
results.citations	array	Ranked source list, highest relevance first.
results.citations[].title	string	Title of the source page.
results.citations[].url	string	Canonical URL of the source.
results.citations[].score	number	Relevance from 0 to 1. Higher is closer to the query.
results.citations[].snippet	string	One attributed sentence. Present only when `include_snippets: true` was sent.

Example response

200 OK

{
  "query": "what are the moons of saturn?",
  "trace_id": "oden-mquycpae-p3thrk",
  "execution_time_ms": 2992,
  "cached": false,
  "results": {
    "answer": "Saturn has 274 confirmed moons — more than any other
                              planet. The largest, Titan, is bigger than
                              Mercury and the only moon with a dense atmosphere.",
    "citations": [
      {
        "title": "Moons of Saturn — Wikipedia",
        "url":   "https://en.wikipedia.org/wiki/Moons_of_Saturn",
        "score": 0.854
      }
    ]
  }
}

Errors

Errors return a JSON object with an error field and the matching HTTP status.

Status	error	What happened
400	Invalid JSON body	The request body wasn't valid JSON. Check your quoting and that `Content-Type` is `application/json`.
401	Unauthorized	The key is missing, malformed, or revoked. Send it as `Authorization: Bearer <key>`.
429	Rate limit exceeded	You've sent too many requests. Slow down and retry — see rate limits below.

Rate limits

Requests are rate limited per key. When you go over, the API returns 429 — back off and retry. Your current quota is shown in your dashboard.

Building an agent? Cache repeated queries on your side and watch the cached flag — cached calls return in tens of milliseconds and are the cheapest path to the same answer.