Skip to content
aptrouter

Run a search

POST
/v1/search
 
curl --request POST \
  --url https://api.aptrouter.com/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "query": "statins and breast cancer survival", "limit": 5 }'

Returns up to limit verbatim-cited results for query. Each result is the highest-scoring source sentence plus its identifier and metadata. Debits 1 prepaid credit ($0.005) from the key’s balance; if the search produces no usable result (server error or timeout) the credit is refunded. Requires Content-Type: application/json.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
query
required

The search query. Tokenised FTS + dense retrieval; not a boolean DSL.

string
>= 1 characters <= 2048 characters
limit

Max results to return (clamped to 1–50).

integer
default: 8 >= 1 <= 50
fields

Comma-separated opt-in heavier fields. Currently only abstract (adds the full ab field to each result). Default omits it to stay token-lean.

string
Examples

Minimal query

{
  "query": "statins and breast cancer survival",
  "limit": 5
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Search results.

Media type application/json
object
n
required

Number of results returned.

integer
c
required

Corpus confidence — cosine similarity (0–1) of the best local semantic match. A low value means the local index had nothing close, so a fallback lane was used (see each result’s src).

number format: double
results
required
Array<object>

One result. Keys are abbreviated to minimise tokens.

object
d
required

Identifier — DOI (or source id) of the document.

string
t
required

Title.

string
y
required

Publication year (0 if unknown).

integer
a
required

Authors (first few).

Array<string>
s
required

Relevance score in [0,1], rounded to 3 decimals.

number format: double
q
required

The verbatim cited sentence(s) — quotable as-is.

string
ab

Full abstract. Present only when fields=abstract was requested.

string
src
required

Provenance of this result: corpus (the local scholarly index), or the fallback lane that served it — arxiv, semantic_scholar, or web.

string
Examples
Example ok 
{
  "n": 2,
  "c": 0.871,
  "results": [
    {
      "d": "MED-10",
      "t": "Statin Use and Breast Cancer Survival: A Nationwide Cohort Study from Finland",
      "y": 2014,
      "a": [
        "Murtola TJ",
        "Visvanathan K"
      ],
      "s": 1,
      "q": "Recent studies have suggested that statins could delay or prevent breast cancer recurrence but the effect on disease-specific mortality remains unclear.",
      "src": "corpus"
    },
    {
      "d": "MED-14",
      "t": "Statin use after diagnosis of breast cancer and survival: a population-based cohort study.",
      "y": 2016,
      "a": [
        "Smith A"
      ],
      "s": 0.984,
      "q": "Preclinical studies have shown that statins can prevent growth in breast cancer cell lines and animal models.",
      "src": "corpus"
    }
  ]
}

Headers

Section titled “Headers ”
X-Token-Budget
integer

Estimated token count of this response body (~4 chars/token).

X-Credit-Balance
integer

Prepaid credits remaining after this call’s debit.

X-Content-Type-Options
string
Allowed values: nosniff

400

Section titled “400 ”

Invalid request: empty query (empty query), query longer than 2048 characters (query too long), or limit of 0 (limit must be >= 1).

Media type text/plain
string
Example 
empty query

401

Section titled “401 ”

Missing, invalid, or revoked API key.

Media type text/plain
string
Example 
invalid or revoked api key

402

Section titled “402 ”

Prepaid credit balance is zero. Top up in the dashboard to continue.

Media type text/plain
string
Example 
insufficient credit balance — top up to continue

Headers

Section titled “Headers ”
X-Credit-Balance
integer
Allowed values: 0

415

Section titled “415 ”

Request body was sent without Content-Type: application/json.

Media type text/plain
string
Example 
Expected request with `Content-Type: application/json`

429

Section titled “429 ”

Per-key burst rate limit exceeded, or too many concurrent in-flight requests for this key. Honour Retry-After.

Media type text/plain
string
Example 
rate limit exceeded

Headers

Section titled “Headers ”
Retry-After
integer
RateLimit-Limit
integer

500

Section titled “500 ”

Internal error (the charged credit is automatically refunded).

Media type text/plain
string

503

Section titled “503 ”

The server is shedding load (global in-flight cap reached). Honour Retry-After.

Media type text/plain
string
Example 
server at capacity, retry shortly

Headers

Section titled “Headers ”
Retry-After
integer

504

Section titled “504 ”

The search exceeded the per-request wall-clock timeout (credit refunded).

Media type text/plain
string
Example 
search timed out