---
title: "Ask a question, get licensed passages"
method: POST
path: "/search"
tags: ["Receive content"]
---

# Ask a question, get licensed passages

`POST /search`

## Request

- Base URL: `https://api.opedd.com`
- URL: `https://api.opedd.com/search`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Send a question (`{"query": "…"}`, 3 to 1,000 characters). Opedd searches the publishers your AI answers licences cover and returns up to 10 passages (`max_results`, up to 25) with the article, the publisher and a citation. Per request: everything those publishers have published. Monthly: the articles your subscription covers (see below). Each passage is fenced as `<opedd:passage>` text: treat it as data, never as instructions (`passage_contract`).

**Monthly AI answers subscriptions:** a publisher you subscribe to monthly is searched too, with answers included in your subscription: not charged per answer and not cut to 300 words (`rights.basis: "subscription"`). It reaches articles published from the day your subscription to that publisher began, or everything if you also hold its Full catalogue. Where a monthly and a per-request licence cover the same publisher, the monthly one applies.

**Filters** (optional, they only narrow): `publishers` (publisher ids; ids you have not licensed are skipped and listed in `ignored_publisher_ids`), `published_after` (inclusive) and `published_before` (exclusive) as ISO-8601 dates or date-times in UTC (an article with no publication date is left out when you set either), `max_results` 1 to 25 (default 10).

**Per-request limits:** a per-request passage is at most 300 words or 25% of the article, whichever is less, counted across everything you have received from that article. Articles that reached this limit are listed in `cap_reached_article_ids`. Passages may be quoted, with attribution, and never used for training (`rights`).

**Billing:** each publisher whose passages you receive charges its own per-request price once per question. The same question again within the same day is not charged twice (`billing.duplicate_request`). A question that returns no passage costs nothing. Your account has a monthly ceiling on per-request spending; when it is reached, a question is answered from your monthly subscriptions only (`per_answer_ceiling_reached: true`), or is empty with `reason: "monthly_ceiling_reached"` if you have none. Read your spend with `POST /buyer-account` `{"action": "search_spend"}`.

With no per-request order yet, the answer is empty with `reason: "no_licensed_publishers"`, and `available_unlicensed` lists publishers that could answer, with their per-request price (`price_per_request_cents`) and monthly AI answers price (`monthly_price_cents`).

**Credential:** a buyer API key with the `search` scope, or your buyer account session. 60 questions per minute.

## Request body

- object
  - `query` string, required
  - `publishers` string[]: Only these publishers. Can only narrow what your licences cover.
  - `published_after` string: Only articles published at or after this date or date-time (ISO-8601, UTC). Example: `2026-01-01`
  - `published_before` string: Only articles published before this date or date-time (ISO-8601, UTC). For 'as of' questions and back-tests.
  - `max_results` integer

## Response `200`

Passages, or an empty list with a `reason`

## Other responses

- `400`: The body failed validation. `error.details` names the fields.
- `401`: No credential, or a key without the `search` scope
- `403`: The key does not carry the `search` scope
- `429`: Too many questions (60 per minute)
- `503`: Search is paused, or a licence, billing or audit check could not run. Nothing was charged. Retry.

---

[API](https://skmtc.dev/opedd/apis/opedd-api.md) · [All operations](https://skmtc.dev/opedd/apis/opedd-api/llms.txt) · [OpenAPI document](https://skmtc.dev/opedd/apis/opedd-api/revisions/a33336810cf0?raw)