REST API reference

The REST API lives on each publisher's vanity host (the publisher is
resolved from the hostname). It's available when the publisher enables
public API access — or always, when you authenticate with a
buyer API key (Authorization: Bearer mk_…).

All responses are JSON with permissive CORS.

Search

GET https://oasy.<publisher-domain>/api/v1/articles/search?query=<q>&limit=<n>

Param	Required	Notes
`query` (alias `q`)	yes	1–200 chars
`limit`	no	1–50, default 10

Search is hybrid: semantic (vector) and full-text candidates fused by
reciprocal-rank. The response tells you which legs contributed:

{
  "count": 2,
  "mode": "hybrid",          // "hybrid" | "fts" | "semantic" | "none"
  "results": [
    {
      "id": "cmr…",
      "url": "https://…",
      "title": "…",
      "author": "…",
      "publishedAt": "2026-05-01T09:00:00.000Z",
      "summary": "…",
      "tags": ["…"],
      "match": {               // semantic hits only — WHERE the query landed
        "chunkId": "cmr…#3",
        "section": "Methods",  // heading the matching passage falls under
        "snippet": "…240 chars of the matching passage…"
      }
    }
  ]
}

Articles whose license denies the rag right are excluded from search
results entirely.

Get one article

GET https://oasy.<publisher-domain>/api/v1/articles/<id-or-url>?last_user_prompt=<text>

last_user_prompt is required (1–8000 chars): the verbatim text of your
end user's most recent prompt. Publishers see it in their reader-intent
analytics — it's the audit contract for full-text access, same as the MCP
tool.

A successful response carries the body and the machine-readable license:

{
  "article": { "id": "…", "url": "…", "title": "…", "body": "…", "policy": "OBSERVE", … },
  "license": {
    "licensor": "Publisher Name",
    "rights": { "summarization": "granted", "display": "granted", "rag": "granted", "fine_tuning": "denied" },
    "pricingUsdCents": { "display": 50 },
    "termsUrl": "…/license/<publisherId>",
    "requestVia": "request_license (MCP tool) — publisher approval workflow"
  }
}

Response statuses you must handle

HTTP	`status` field	Meaning
200	—	Full article served
200	`license_limited`	License grants summarization only — you get the summary; cite the URL
200	`blocked`	Publisher blocks this article for AI agents
403	`license_denied`	No AI use licensed; request access via `request_license`
451	`territory_blocked`	Publisher's content rules exclude your region
400	`missing_last_user_prompt`	Add the required param
404	`rest_api_disabled`	Publisher hasn't opted into anonymous REST — authenticate with a buyer key
404	`article_not_found` / `unknown_publisher_host`	Check the id/URL and hostname

Billing on this surface

With a buyer key, reads of per-use-priced content that your licenses don't
already cover accrue metered charges (price snapshotted per read,
settled monthly, hard-capped) — see
Marketplace & buyer API.