POST /v1/rerank
Rerank documents against a query (unit-billed, searches)
Specialty route (route_type: rerank; Cohere/Jina shape). JSON passthrough both ways. Accepted params — model, query, a non-empty documents array, top_n; everything else is unknown_param. Metering: unit_type='searches' — one search per request (one query over N documents); the corpus size is recorded in the ledger's media, unpriced. Idempotency-Key carries replay semantics on this route (contract §8 route-scope).
Request
Request body fields for rerankDocuments | Field | Type | Required | Description |
| model | string | yes | An IronStratum alias whose route_type is rerank. |
| query | string | yes | — |
| documents | array of string | yes | Non-empty (an empty corpus is a 400, not a free no-op). |
| top_n | integer | no | — |
Responses
400 400
400 response fields for rerankDocuments | Field | Type | Required | Description |
| error | object | yes | — |
401 401
401 response fields for rerankDocuments | Field | Type | Required | Description |
| error | object | yes | — |
402 402
402 response fields for rerankDocuments | Field | Type | Required | Description |
| error | object | yes | — |
403 403
403 response fields for rerankDocuments | Field | Type | Required | Description |
| error | object | yes | — |
404 404
404 response fields for rerankDocuments | Field | Type | Required | Description |
| error | object | yes | — |
409 409
409 response fields for rerankDocuments | Field | Type | Required | Description |
| error | object | yes | — |
500 500
500 response fields for rerankDocuments | Field | Type | Required | Description |
| error | object | yes | — |
502 502
502 response fields for rerankDocuments | Field | Type | Required | Description |
| error | object | yes | — |
503 503
503 response fields for rerankDocuments | Field | Type | Required | Description |
| error | object | yes | — |
Status codes
- 200 — The rerank response, passed through verbatim.
Example
curl -X POST https://api.ironstratum.com/v1/rerank \
-H "Authorization: Bearer $IRONSTRATUM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"<model>","query":"<query>","documents":["<documents>"]}'
All operations ·
interactive reference ·
openapi.yaml