Stotles Suppliers API

openapi: 3.2.0
info:
  title: Stotles Public Suppliers API
  description: 'The Stotles Public API gives you programmatic access to UK public sector procurement

    data — notices, buyers, suppliers and framework agreements — as JSON over HTTPS.'
  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:
  schemas:
    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
    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
  responses:
    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.
    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
    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.
    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.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key