Stotles Notices API

openapi: 3.2.0
info:
  title: Stotles Public Notices 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: Notices
  description: Public sector procurement notices.
paths:
  /v1/notices/search:
    get:
      description: Search and filter procurement notices. Every parameter is optional, so filters can stand alone without a keyword. Results are ranked by relevance unless `sort` is set, and paginated with `next_cursor`.
      operationId: searchNotices
      parameters:
      - name: query
        required: false
        in: query
        description: Free-text keyword search over the notice (each 2–500 characters). Repeatable; multiple values are combined per `query_operator`.
        schema:
          maxItems: 50
          type: array
          items:
            type: string
            minLength: 2
            maxLength: 500
        style: form
        explode: true
      - name: query_operator
        required: false
        in: query
        description: 'How multiple `query` keywords combine: match all (`and`) or any (`or`). Default `or`.'
        schema:
          default: or
          type: string
          enum:
          - and
          - or
      - name: country_code
        required: false
        in: query
        description: Filter to notices 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: cpv_code
        required: false
        in: query
        description: Filter to notices classified under these CPV codes. Repeatable.
        schema:
          maxItems: 100
          type: array
          items:
            type: string
            minLength: 1
        style: form
        explode: true
      - name: buyer_id
        required: false
        in: query
        description: Filter to notices involving these buyers (by id). Repeatable.
        schema:
          maxItems: 100
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: supplier_id
        required: false
        in: query
        description: Filter to notices awarded to these suppliers (by id). Repeatable.
        schema:
          maxItems: 100
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: stage
        required: false
        in: query
        description: Filter to notices in these stages. Repeatable.
        schema:
          maxItems: 10
          type: array
          items:
            type: string
            enum:
            - pipeline
            - pre_tender
            - stale_pre_tender
            - open_tender
            - closed_tender
            - canceled_tender
            - unknown_tender
            - awarded_contract
            - expired_contract
            - canceled_award
            description: The notice's procurement stage.
            x-enumDescriptions:
              pipeline: An early signal that a procurement is coming — spotted in a buyer's forward plan or contract pipeline, before any formal notice. No tender documents exist yet.
              pre_tender: The buyer has published a formal early-market notice (e.g. a planning or prior-information notice). The tender is not open yet.
              stale_pre_tender: A pre-tender notice that has aged well past the point where a tender would normally have followed. Treat it as unlikely to progress.
              open_tender: Accepting bids — the submission deadline (`close_date`) has not passed.
              closed_tender: The submission deadline has passed and the buyer has not published an award yet.
              canceled_tender: The buyer withdrew or abandoned the procurement before awarding it.
              unknown_tender: A tender notice whose deadline could not be determined from the source, so we can't say whether it is still open.
              awarded_contract: A contract has been awarded. See `contracts` for the suppliers and awarded values.
              expired_contract: The awarded contract has passed the end of its known term. Note that this is derived from the contract record, so an `expired_contract` can still carry a **future** `expiry_date` — don't infer timing from the stage.
              canceled_award: An award that was later cancelled or annulled.
        style: form
        explode: true
      - name: framework_id
        required: false
        in: query
        description: Filter to notices related to these frameworks (by id) — a framework agreement or a call-off against it. Repeatable.
        schema:
          maxItems: 100
          type: array
          items:
            type: string
            format: uuid
        style: form
        explode: true
      - name: framework_activity
        required: false
        in: query
        description: Narrow by framework relationship (agreement vs call-off).
        schema:
          type: string
          enum:
          - only_framework_agreements
          - only_call_offs
          - exclude_framework_agreements
          - exclude_all
          x-enumDescriptions:
            only_framework_agreements: Only notices that establish a framework agreement, excluding the call-offs made under one.
            only_call_offs: Only notices that are call-offs (individual awards) under an existing framework.
            exclude_framework_agreements: Everything except the notices that establish a framework — keeps call-offs and non-framework procurements.
            exclude_all: Only procurements unrelated to any framework.
      - name: publish_date_gte
        required: false
        in: query
        description: Only notices published on or after this date (inclusive).
        schema:
          format: date
          type: string
      - name: publish_date_lte
        required: false
        in: query
        description: Only notices published on or before this date (inclusive).
        schema:
          format: date
          type: string
      - name: close_date_gte
        required: false
        in: query
        description: Only notices whose tender close date is on or after this date (inclusive).
        schema:
          format: date
          type: string
      - name: close_date_lte
        required: false
        in: query
        description: Only notices whose tender close date is on or before this date (inclusive).
        schema:
          format: date
          type: string
      - name: expiry_date_gte
        required: false
        in: query
        description: Only notices whose contract expiry date is on or after this date (inclusive).
        schema:
          format: date
          type: string
      - name: expiry_date_lte
        required: false
        in: query
        description: Only notices whose contract expiry date is on or before this date (inclusive).
        schema:
          format: date
          type: string
      - name: award_date_gte
        required: false
        in: query
        description: Only notices whose award date is on or after this date (inclusive).
        schema:
          format: date
          type: string
      - name: award_date_lte
        required: false
        in: query
        description: Only notices whose award date is on or before this date (inclusive).
        schema:
          format: date
          type: string
      - name: value_gte
        required: false
        in: query
        description: Only notices whose estimated value is greater than or equal to this amount, in the notice's own currency (values are not currency-normalized). Excludes notices with no value.
        schema:
          minimum: 1
          type: number
      - name: value_lte
        required: false
        in: query
        description: Only notices whose estimated value is less than or equal to this amount, in the notice's own currency (values are not currency-normalized). Excludes notices with no value.
        schema:
          minimum: 1
          type: number
      - name: sort
        required: false
        in: query
        description: Sort field. Omitted = relevance ranking. For date sorts (close/award/expiry, often null), notices missing that date sort last in both directions.
        schema:
          type: string
          enum:
          - publish_date
          - close_date
          - award_date
          - expiry_date
          - value
      - name: order
        required: false
        in: query
        description: Sort direction (default desc). Applies when `sort` is set.
        schema:
          default: desc
          type: string
          enum:
          - asc
          - desc
      - 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 notices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticeSearchResponseDto'
              example:
                items:
                - id: 8f14e45f-ea0d-4a3b-9c2e-1d7b6a5c4e30
                  title: Managed Cyber Security Operations Centre (SOC) Services
                  description: The Authority is seeking a supplier to deliver a managed Security Operations Centre, including 24/7 monitoring, threat intelligence and incident response, for an initial term of three years with an optional two-year extension.
                  country_code: GB
                  stage: open_tender
                  source_url: https://www.find-tender.service.gov.uk/Notice/012345-2026
                  publish_date: '2026-07-14'
                  close_date: '2026-08-29'
                  award_date: null
                  expiry_date: null
                  value:
                    amount: 4500000
                    currency: GBP
                  buyers:
                  - id: 3c6e0b8a-9c15-4f2d-8b7a-2e5d1c9f4a60
                    name: Department for Work and Pensions
                  cpv_codes:
                  - code: '72500000'
                    name: Computer-related services
                  - code: '79710000'
                    name: Security services
                  framework: null
                  lots:
                  - id: '1'
                    title: Lot 1 — Monitoring and detection
                    description: 24/7 SOC monitoring, alert triage and detection engineering.
                    value:
                      amount: 3000000
                      currency: GBP
                    cpv_codes:
                    - code: '72500000'
                      name: Computer-related services
                    contract_period:
                      start_date: '2026-11-01'
                      end_date: '2029-10-31'
                      max_extent_date: '2031-10-31'
                  - id: '2'
                    title: Lot 2 — Incident response retainer
                    description: On-call incident response and forensic investigation.
                    value:
                      amount: 1500000
                      currency: GBP
                    cpv_codes:
                    - code: '79710000'
                      name: Security services
                    contract_period:
                      start_date: '2026-11-01'
                      end_date: '2029-10-31'
                      max_extent_date: null
                  contracts: []
                next_cursor: eyJwYWdlIjoyLCJsaW1pdCI6MjB9
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      summary: Search notices by keyword
      tags:
      - Notices
      x-codeSamples:
      - lang: cURL
        label: curl
        source: "curl -G https://api.stotles.com/v1/notices/search \\\n  -H \"x-api-key: $STOTLES_API_KEY\" \\\n  --data-urlencode \"query=cyber security\" \\\n  -d \"stage=open_tender\" \\\n  -d \"country_code=GB\" \\\n  -d \"limit=20\""
  /v1/notices/{id}:
    get:
      description: Fetch a single notice, including its lots and any awarded contracts. The `id` is the same identifier returned by notice search and by the `buyer_id`/`supplier_id` filters.
      operationId: getNotice
      parameters:
      - name: id
        required: true
        in: path
        description: The notice's unique identifier.
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: The notice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticeResponseDto'
              example:
                id: 8f14e45f-ea0d-4a3b-9c2e-1d7b6a5c4e30
                title: Managed Cyber Security Operations Centre (SOC) Services
                description: The Authority is seeking a supplier to deliver a managed Security Operations Centre, including 24/7 monitoring, threat intelligence and incident response, for an initial term of three years with an optional two-year extension.
                country_code: GB
                stage: open_tender
                source_url: https://www.find-tender.service.gov.uk/Notice/012345-2026
                publish_date: '2026-07-14'
                close_date: '2026-08-29'
                award_date: null
                expiry_date: null
                value:
                  amount: 4500000
                  currency: GBP
                buyers:
                - id: 3c6e0b8a-9c15-4f2d-8b7a-2e5d1c9f4a60
                  name: Department for Work and Pensions
                cpv_codes:
                - code: '72500000'
                  name: Computer-related services
                - code: '79710000'
                  name: Security services
                framework: null
                lots:
                - id: '1'
                  title: Lot 1 — Monitoring and detection
                  description: 24/7 SOC monitoring, alert triage and detection engineering.
                  value:
                    amount: 3000000
                    currency: GBP
                  cpv_codes:
                  - code: '72500000'
                    name: Computer-related services
                  contract_period:
                    start_date: '2026-11-01'
                    end_date: '2029-10-31'
                    max_extent_date: '2031-10-31'
                - id: '2'
                  title: Lot 2 — Incident response retainer
                  description: On-call incident response and forensic investigation.
                  value:
                    amount: 1500000
                    currency: GBP
                  cpv_codes:
                  - code: '79710000'
                    name: Security services
                  contract_period:
                    start_date: '2026-11-01'
                    end_date: '2029-10-31'
                    max_extent_date: null
                contracts: []
        '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 notice by id
      tags:
      - Notices
      x-codeSamples:
      - lang: cURL
        label: curl
        source: "curl https://api.stotles.com/v1/notices/8f14e45f-ea0d-4a3b-9c2e-1d7b6a5c4e30 \\\n  -H \"x-api-key: $STOTLES_API_KEY\""
components:
  schemas:
    NoticeResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The notice's unique identifier.
        title:
          type: string
          description: The notice's title.
        description:
          type: string
          description: The notice's description.
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code the notice relates to.
        stage:
          type: string
          enum:
          - pipeline
          - pre_tender
          - stale_pre_tender
          - open_tender
          - closed_tender
          - canceled_tender
          - unknown_tender
          - awarded_contract
          - expired_contract
          - canceled_award
          description: The notice's procurement stage.
          x-enumDescriptions:
            pipeline: An early signal that a procurement is coming — spotted in a buyer's forward plan or contract pipeline, before any formal notice. No tender documents exist yet.
            pre_tender: The buyer has published a formal early-market notice (e.g. a planning or prior-information notice). The tender is not open yet.
            stale_pre_tender: A pre-tender notice that has aged well past the point where a tender would normally have followed. Treat it as unlikely to progress.
            open_tender: Accepting bids — the submission deadline (`close_date`) has not passed.
            closed_tender: The submission deadline has passed and the buyer has not published an award yet.
            canceled_tender: The buyer withdrew or abandoned the procurement before awarding it.
            unknown_tender: A tender notice whose deadline could not be determined from the source, so we can't say whether it is still open.
            awarded_contract: A contract has been awarded. See `contracts` for the suppliers and awarded values.
            expired_contract: The awarded contract has passed the end of its known term. Note that this is derived from the contract record, so an `expired_contract` can still carry a **future** `expiry_date` — don't infer timing from the stage.
            canceled_award: An award that was later cancelled or annulled.
        source_url:
          type: string
          description: URL of the notice on the original source.
        publish_date:
          type: string
          format: date
          description: Date this notice was published (its phase's release date).
        close_date:
          type:
          - string
          - 'null'
          format: date
          description: Bid submission deadline (tender close). Indicative on pre-tender notices; null on award/contract notices (the deadline is on the sibling tender notice).
        award_date:
          type:
          - string
          - 'null'
          format: date
          description: Date the contract was awarded. Best-effort (may fall back to contract start); earliest across awards. Null before award.
        expiry_date:
          type:
          - string
          - 'null'
          format: date
          description: Earliest expected contract end date. Excludes extensions/options, so it is the earliest — not latest — end. Null when not applicable or unknown.
        value:
          type:
          - object
          - 'null'
          properties:
            amount:
              type: number
              description: The amount as a JSON number, byte-aligned with the upstream feed. Parse with a big-decimal library — do not rely on IEEE-754 float arithmetic.
            currency:
              type:
              - string
              - 'null'
              description: ISO 4217 currency code (e.g. GBP). Null when the source didn't specify one.
          required:
          - amount
          - currency
          description: Estimated total value of the notice; null when no amount is known.
        buyers:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: The buyer's unique identifier.
              name:
                type: string
                description: The buyer's name.
            required:
            - id
            - name
          description: Buyers associated with the notice.
        cpv_codes:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                description: The CPV code.
              name:
                type: string
                description: Human-readable label for the CPV code.
            required:
            - code
            - name
          description: CPV classification codes for the notice.
        framework:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
              format: uuid
              description: The related framework's unique identifier.
            relationship:
              type: string
              enum:
              - framework_agreement
              - call_off
              description: 'How this notice relates to the framework: `framework_agreement` = it establishes the framework; `call_off` = it is a call-off under it.'
              x-enumDescriptions:
                framework_agreement: This notice establishes the framework.
                call_off: This notice is a call-off (an individual award) made under the framework.
          required:
          - id
          - relationship
          description: The framework this notice relates to; null when it is unrelated to any framework.
        lots:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: The lot's identifier within the notice.
              title:
                type: string
                description: The lot's title.
              description:
                type: string
                description: The lot's description.
              value:
                type:
                - object
                - 'null'
                properties:
                  amount:
                    type: number
                    description: The amount as a JSON number, byte-aligned with the upstream feed. Parse with a big-decimal library — do not rely on IEEE-754 float arithmetic.
                  currency:
                    type:
                    - string
                    - 'null'
                    description: ISO 4217 currency code (e.g. GBP). Null when the source didn't specify one.
                required:
                - amount
                - currency
                description: Estimated value of the lot; null when no amount is known.
              cpv_codes:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: The CPV code.
                    name:
                      type: string
                      description: Human-readable label for the CPV code.
                  required:
                  - code
                  - name
                description: CPV classification codes for the lot.
              contract_period:
                type: object
                properties:
                  start_date:
                    type:
                    - string
                    - 'null'
                    format: date
                    description: Start of the contract period. Null when unknown.
                  end_date:
                    type:
                    - string
                    - 'null'
                    format: date
                    description: Earliest expected end of the contract period. Null when unknown.
                  max_extent_date:
                    type:
                    - string
                    - 'null'
                    format: date
                    description: Latest date the period can be extended to (excl. is the earliest end). Null when unknown.
                required:
                - start_date
                - end_date
                - max_extent_date
                description: The lot's contract period.
            required:
            - id
            - title
            - description
            - value
            - cpv_codes
            - contract_period
          description: Lots the notice is divided into.
        contracts:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
                description: The contract's title.
              description:
                type: string
                description: The contract's description.
              value:
                type:
                - object
                - 'null'
                properties:
                  amount:
                    type: number
                    description: The amount as a JSON number, byte-aligned with the upstream feed. Parse with a big-decimal library — do not rely on IEEE-754 float arithmetic.
                  currency:
                    type:
                    - string
                    - 'null'
                    description: ISO 4217 currency code (e.g. GBP). Null when the source didn't specify one.
                required:
                - amount
                - currency
                description: Awarded value of the contract; null when no amount is known.
              award_date:
                type:
                - string
                - 'null'
                format: date
                description: Date the contract was awarded. Null when unknown.
              contract_period:
                type: object
                properties:
                  start_date:
                    type:
                    - string
                    - 'null'
                    format: date
                    description: Start of the contract period. Null when unknown.
                  end_date:
                    type:
                    - string
                    - 'null'
                    format: date
                    description: Earliest expected end of the contract period. Null when unknown.
                  max_extent_date:
                    type:
                    - string
                    - 'null'
                    format: date
                    description: Latest date the period can be extended to (excl. is the earliest end). Null when unknown.
                required:
                - start_date
                - end_date
                - max_extent_date
                description: The contract's period.
              cpv_codes:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      type: string
                      description: The CPV code.
                    name:
                      type: string
                      description: Human-readable label for the CPV code.
                  required:
                  - code
                  - name
                description: CPV classification codes for the contract.
              suppliers:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: The supplier's unique identifier.
                    name:
                      type: string
          

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stotles/refs/heads/main/openapi/stotles-notices-api-openapi.yml