> ## Documentation Index > Fetch the complete documentation index at: https://docs.clinikehr.com/llms.txt > Use this file to discover all available pages before exploring further. # Search by medicine identity across every listed pharmacy this key's workspace can reach. > A clinic-owned key always gets an empty result. For a workspace TEST key this searches the workspace's own seeded fictional items instead. Fail-closed allow-list — an unlinked or excluded item never appears, code or text search alike. Never an exact quantity; band only. Capped at 50 results. ## OpenAPI ````yaml /openapi/ehr-api.v1.yaml post /v1/listings/search openapi: 3.1.0 info: title: ClinikEHR API version: 1.0.0 description: >- Server-to-server REST API for a clinic's own data, reached with a key the clinic (or a developer workspace) creates in the developer portal. Authenticate every request with `Authorization: Bearer `. Test keys reach only your workspace's own synthetic sandbox; live keys reach the clinic that created them. Lists wrap their rows as `{ data, has_more, next_cursor }`; single resources are returned directly. Errors are `application/problem+json` (RFC 9457) with a stable `code`. Write requests accept an `Idempotency-Key` header so a retry never repeats a change. See the guides for authentication, permissions, pagination, rate limits and retries. servers: - url: https://api.clinikehr.com/v1 security: - ApiKey: [] paths: /v1/listings/search: post: tags: - Listing summary: >- Search by medicine identity across every listed pharmacy this key's workspace can reach. description: >- A clinic-owned key always gets an empty result. For a workspace TEST key this searches the workspace's own seeded fictional items instead. Fail-closed allow-list — an unlinked or excluded item never appears, code or text search alike. Never an exact quantity; band only. Capped at 50 results. operationId: postListingSearch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ListingSearchRequest' example: item: q: Paracetamol near: lat: 6.5244 lng: 3.3792 radius_km: 20 limit: 25 responses: '200': description: OK. content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/ListingSearchResult' example: data: - clinic_id: 45715198-88e4-498c-8271-57e652c60246 display_name: SANDBOX Pharmacy 01 item_id: 9c1e6f2a-9b2b-4a36-8f6a-2f7b1e8b9a02 match: text band: in_stock distance_km: 1.2 as_of: '2026-09-20T10:00:00.000Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' security: - ApiKey: [] components: schemas: ListingSearchRequest: type: object additionalProperties: false required: - item properties: item: $ref: '#/components/schemas/ListingSearchRequestItem' near: type: object additionalProperties: false properties: lat: type: number lng: type: number radius_km: type: number limit: type: integer minimum: 1 maximum: 50 default: 25 ListingSearchResult: type: object required: - band properties: clinic_id: type: - string - 'null' format: uuid display_name: type: - string - 'null' item_id: type: - string - 'null' format: uuid match: type: - string - 'null' enum: - code - text - null description: >- Equivalence confidence label, never a license to surface an unlinked or excluded item. band: $ref: '#/components/schemas/ListingBand' distance_km: type: - number - 'null' description: >- Null when the pharmacy has no owner-placed pin, or no `near` was given — ranked last, never excluded. as_of: type: - string - 'null' format: date-time ListingSearchRequestItem: description: Exactly one of an identifier {system, value} or a free-text {q}. oneOf: - type: object additionalProperties: false required: - system - value properties: system: type: string enum: - gtin - nafdac - ndc - rxcui - partner value: type: string - type: object additionalProperties: false required: - q properties: q: type: string description: >- Free-text name match. Labelled as a text match, never as equivalence. ListingBand: type: - string - 'null' enum: - out - low - in_stock - unknown - null description: >- Unlike inventory availability's band, listing carries a fourth value, `unknown` — the till heartbeat is missing or stale during open hours. Never coerced to another value; a listing route never returns an exact quantity. Problem: type: object description: RFC 9457 application/problem+json. required: - type - title - status - code - request_id properties: type: type: string format: uri title: type: string status: type: integer detail: type: string code: type: string request_id: type: string errors: type: array items: type: object required: - pointer - message properties: pointer: type: string message: type: string responses: BadRequest: description: >- The request failed validation (unknown query parameter, limit out of range, malformed body). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unauthorized: description: >- Missing, malformed, unknown, revoked or expired key, or the wrong secret. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: >- The key or connection lacks the required scope, the plan does not include this resource, the request came from an address this key's IP allow-list does not permit, a TEST-environment workspace key asked for a clinic_id other than its own workspace's sandbox (`sandbox_only`), or a LIVE workspace key asked for a real clinic while its workspace's verification has lapsed (`not_verified`) — the response never names which addresses ARE allowed, nor which clinic actually is the sandbox. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' TooManyRequests: description: Rate limited. See the Retry-After header. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: ehr_live__ or ehr_test__ ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.