openapi: 3.2.0 info: title: Stotles Public Suppliers API description: "The Stotles Public API gives you programmatic access to UK public sector procurement\ndata — notices, buyers, suppliers and framework agreements — as JSON over HTTPS.\n\n## Base URL\n\nAll endpoints live under a versioned path:\n\n```\nhttps://api.stotles.com/v1\n```\n\n## Authentication\n\nEvery request needs an API key, sent in the `x-api-key` header:\n\n```bash\ncurl -G https://api.stotles.com/v1/notices/search \\\n -H \"x-api-key: $STOTLES_API_KEY\" \\\n --data-urlencode \"query=cyber security\"\n```\n\nKeys are issued by Stotles — ask your Customer Success Manager. A key identifies\nyour organization, so treat it as a secret: keep it server-side and out of source\ncontrol.\n\nRequests without a valid key get a `401`.\n\n## Rate limits\n\nEach API key may make **1,000 requests per hour**, and no more than\n**3 requests per second**. Both apply at once, so a burst of parallel\nrequests can be throttled well inside your hourly allowance.\n\nOver either limit you get a `429` carrying a `Retry-After` header — the number of\nseconds to wait. Honour it and retry; a client that retries immediately will keep\ngetting `429`s. If these limits don't fit your use case, talk to your Customer\nSuccess Manager.\n\n## Pagination\n\nList endpoints (`/search`) return an `items` array plus a top-level\n`next_cursor`:\n\n```json\n{ \"items\": [ … ], \"next_cursor\": \"eyJwYWdlIjoyLCJsaW1pdCI6MjB9\" }\n```\n\nTo read the next page, pass that value back as `?cursor=…`. Keep going until\n`next_cursor` is `null`, which means you have reached the last page.\n\nTwo things to get right:\n\n- **A short page is not the last page.** A page can contain fewer than `limit`\n items and still have more results behind it. Only `next_cursor: null` ends the\n loop.\n- **Cursors are opaque.** Pass them back byte-for-byte. Don't decode, construct or\n persist them — the encoding is an implementation detail and may change.\n\n## Errors\n\nErrors use [RFC 9457 problem details](https://www.rfc-editor.org/rfc/rfc9457) with\nthe `application/problem+json` content type:\n\n```json\n{\n \"type\": \"https://api.stotles.com/problems/validation\",\n \"title\": \"Request validation failed\",\n \"status\": 400,\n \"detail\": \"The request parameters failed validation. See the 'errors' array for details.\",\n \"errors\": [{ \"parameter\": \"limit\", \"detail\": \"Too big: expected number to be <=50\" }]\n}\n```\n\n- **Branch on `type`**, not on `title` or `detail` — `type` is a stable\n identifier per error category; the human-readable fields may be reworded.\n- On validation failures, `errors[]` locates each problem: `parameter` for a\n query or path parameter, `pointer` for a request body field, `header` for a\n header.\n\n## Conventions\n\n- **Field names and query parameters are `snake_case`.**\n- **Identifiers are UUIDs.** The `id` a resource returns is the same `id` you\n filter by (`buyer_id`, `supplier_id`, `framework_id`).\n- **Dates are calendar dates**, `YYYY-MM-DD`, never timestamps. There is no\n meaningful empty date, so an unknown date is `null`.\n- **Money is a decimal amount plus a currency** — `{ \"amount\": 4500000, \"currency\": \"GBP\" }`\n — not integer minor units. Amounts can be large and are estimates, so parse them\n with a big-decimal type rather than a float. `currency` can be `null` when the\n source didn't state one.\n- **Country codes are ISO 3166-1 alpha-2** (`GB`, `IE`).\n- **Multi-value filters repeat the parameter**: `?stage=open_tender&stage=closed_tender`\n matches either. Don't comma-join values.\n- **Range filters carry an explicit operator suffix** — `publish_date_gte`,\n `value_lte`. Both bounds are inclusive.\n- **Unknown optional text is an empty string** where blank is meaningful, and\n `null` where absence is meaningful. Each field's description says which.\n\n## Versioning and stability\n\nThe version is in the path (`/v1`). Within a version we make only additive\nchanges — new endpoints, new optional parameters, new response fields — so **write\nclients that ignore fields they don't recognize**. Anything breaking (removing or\nrenaming a field, changing a type, tightening validation) goes in a new version,\nand we will contact you before retiring one.\n\n## Support\n\nFor questions, bug reports, or requests for data we don't expose yet, contact your\nStotles Customer Success Manager." version: '1.0' contact: name: Stotles API Support url: https://www.stotles.com servers: - url: https://api.stotles.com description: Production security: - apiKey: [] tags: - name: Suppliers description: Suppliers bidding for and winning public sector contracts. paths: /v1/suppliers/search: get: description: Find suppliers that bid for or win public sector contracts, ranked by relevance to the query. `award_count` reflects the awards we have indexed for the supplier. operationId: searchSuppliers parameters: - name: query required: true in: query description: Free-text search over the supplier name (2–200 characters). schema: minLength: 2 maxLength: 200 type: string - name: country_code required: false in: query description: Filter to suppliers in these ISO 3166-1 alpha-2 countries. Repeatable. schema: maxItems: 100 type: array items: type: string pattern: ^[A-Za-z]{2}$ style: form explode: true - name: limit required: false in: query description: Maximum results per page (1–50, default 20). Ignored when `cursor` is set. schema: minimum: 1 maximum: 50 default: 20 type: integer - name: cursor required: false in: query description: Opaque pagination cursor from a previous response's `next_cursor`. Carries the page and page size, so `limit` is ignored when it is present. schema: type: string responses: '200': description: A page of matching suppliers. content: application/json: schema: $ref: '#/components/schemas/SupplierSearchResponseDto' example: items: - id: b2d4f6a8-1c3e-4d5f-8a9b-0c1d2e3f4a5b name: Northbridge Digital Services Ltd location: country_code: GB award_count: 37 - id: c3e5a7b9-2d4f-4e6a-9b0c-1d2e3f4a5b6c name: Northbridge Consulting Group Ltd location: country_code: GB award_count: 4 next_cursor: null '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthenticated' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' summary: Search suppliers by name tags: - Suppliers x-codeSamples: - lang: cURL label: curl source: "curl -G https://api.stotles.com/v1/suppliers/search \\\n -H \"x-api-key: $STOTLES_API_KEY\" \\\n --data-urlencode \"query=northbridge digital\"" /v1/suppliers/{id}: get: description: Fetch a single supplier. Use the `id` as the `supplier_id` filter on notice search to see the contracts it has been awarded. operationId: getSupplier parameters: - name: id required: true in: path description: The supplier's unique identifier. schema: format: uuid type: string responses: '200': description: The supplier. content: application/json: schema: $ref: '#/components/schemas/SupplierDto' example: id: b2d4f6a8-1c3e-4d5f-8a9b-0c1d2e3f4a5b name: Northbridge Digital Services Ltd location: country_code: GB award_count: 37 '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' summary: Get a supplier by id tags: - Suppliers x-codeSamples: - lang: cURL label: curl source: "curl https://api.stotles.com/v1/suppliers/b2d4f6a8-1c3e-4d5f-8a9b-0c1d2e3f4a5b \\\n -H \"x-api-key: $STOTLES_API_KEY\"" components: responses: Unauthenticated: description: Missing or invalid API key. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://api.stotles.com/problems/unauthenticated title: Unauthenticated status: 401 detail: Missing or invalid API key. ValidationError: description: The request failed validation. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://api.stotles.com/problems/validation title: Request validation failed status: 400 detail: The request parameters failed validation. See the 'errors' array for details. errors: - parameter: id detail: Invalid uuid InternalError: description: An unexpected error occurred. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://api.stotles.com/problems/internal title: Internal server error status: 500 RateLimited: description: The client has sent too many requests in a given amount of time. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://api.stotles.com/problems/rate-limited title: Too many requests status: 429 detail: Rate limit exceeded. Retry later. NotFound: description: The requested resource does not exist. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://api.stotles.com/problems/not-found title: Not found status: 404 detail: No notice exists with the given id. schemas: SupplierDto: type: object properties: id: type: string format: uuid description: The supplier's unique identifier. name: type: string description: The supplier's name. location: type: object properties: country_code: type: string description: ISO 3166-1 alpha-2 country code. required: - country_code description: The supplier's location. award_count: type: integer description: All-time count of contracts awarded to this supplier. required: - id - name - location - award_count SupplierSearchResponseDto: type: object properties: items: type: array items: type: object properties: id: type: string format: uuid description: The supplier's unique identifier. name: type: string description: The supplier's name. location: type: object properties: country_code: type: string description: ISO 3166-1 alpha-2 country code. required: - country_code description: The supplier's location. award_count: type: integer description: All-time count of contracts awarded to this supplier. required: - id - name - location - award_count description: The matching suppliers, most relevant first. next_cursor: type: - string - 'null' description: Opaque cursor for the next page of results; null when this is the last page. required: - items - next_cursor ProblemDetails: type: object properties: type: type: string description: Stable category identifier — clients branch on this. format: uri title: type: string description: Short, human-readable summary of the category. Stable per `type`. status: type: integer minimum: 100 maximum: 599 description: HTTP status code, duplicated in the body so the payload is self-contained. detail: description: Human-readable, occurrence-specific detail. Omitted on 5xx so we never leak internals. type: string errors: description: Per-field validation failures; present only on validation (400) problems. type: array items: anyOf: - type: object properties: detail: type: string description: Human-readable description of this field error. pointer: type: string required: - detail - pointer additionalProperties: false - type: object properties: detail: type: string description: Human-readable description of this field error. parameter: type: string required: - detail - parameter additionalProperties: false - type: object properties: detail: type: string description: Human-readable description of this field error. header: type: string required: - detail - header additionalProperties: false required: - type - title - status additionalProperties: true securitySchemes: apiKey: type: apiKey in: header name: x-api-key