Stotles Frameworks API

openapi: 3.2.0
info:
  title: Stotles Public Frameworks 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: Frameworks
  description: Framework agreements and dynamic purchasing systems.
paths:
  /v1/frameworks/search:
    get:
      description: Search and filter framework agreements and dynamic purchasing systems. Every parameter is optional. Use a framework's `id` as the `framework_id` filter on notice search to find the call-offs made under it.
      operationId: searchFrameworks
      parameters:
      - name: query
        required: false
        in: query
        description: Free-text search over the framework name (2–500 characters).
        schema:
          minLength: 2
          maxLength: 500
          type: string
      - name: stage
        required: false
        in: query
        description: Filter to frameworks in these procurement stages. Repeatable.
        schema:
          maxItems: 10
          type: array
          items:
            type: string
            enum:
            - stale
            - upcoming
            - tendering
            - closed
            - awarded
            - live
            - expired
            - canceled
            x-enumDescriptions:
              stale: Announced, but aged past the point where tendering would normally have started. Treat it as unlikely to progress.
              upcoming: Announced or planned. Suppliers cannot apply yet.
              tendering: Open for suppliers to apply to be appointed to the framework.
              closed: The application deadline has passed; the buyer has not yet announced which suppliers were appointed.
              awarded: Suppliers have been appointed, but the agreement isn't available to buy from yet (typically its start date is in the future).
              live: In force — buyers can run call-offs against it, and appointed suppliers can win work.
              expired: Past its end date. No new call-offs are expected.
              canceled: Withdrawn or abandoned before it came into force.
        style: form
        explode: true
      - name: start_date_gte
        required: false
        in: query
        description: Only frameworks whose contract start date is on or after this date (inclusive).
        schema:
          format: date
          type: string
      - name: start_date_lte
        required: false
        in: query
        description: Only frameworks whose contract start date is on or before this date (inclusive).
        schema:
          format: date
          type: string
      - name: end_date_gte
        required: false
        in: query
        description: Only frameworks whose contract end date is on or after this date (inclusive).
        schema:
          format: date
          type: string
      - name: end_date_lte
        required: false
        in: query
        description: Only frameworks whose contract end date is on or before this date (inclusive).
        schema:
          format: date
          type: string
      - name: sort
        required: false
        in: query
        description: Sort field. Omitted = relevance ranking.
        schema:
          type: string
          enum:
          - title
          - start_date
          - end_date
          - stage
          - 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 framework agreements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FrameworkSearchResponseDto'
              example:
                items:
                - id: 7d9b1f3a-5c2e-4a8b-9d0f-3e6c1a4b7d92
                  title: Technology Products & Associated Services 2
                  description: An agreement for the supply of hardware, software and associated services to public sector buyers, divided into lots covering devices, networking and audio-visual equipment.
                  service_provider:
                    id: e1a3c5b7-9d2f-4b6a-8c0e-5f7a9b1c3d40
                    name: Crown Commercial Service
                  stage: live
                  procedure_type: framework
                  value:
                    amount: 1200000000
                    currency: GBP
                  start_date: '2025-04-01'
                  end_date: '2029-03-31'
                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 frameworks by name, stage and date
      tags:
      - Frameworks
      x-codeSamples:
      - lang: cURL
        label: curl
        source: "curl -G https://api.stotles.com/v1/frameworks/search \\\n  -H \"x-api-key: $STOTLES_API_KEY\" \\\n  --data-urlencode \"query=technology products\" \\\n  -d \"stage=live\""
  /v1/frameworks/{id}:
    get:
      description: Fetch a single framework agreement, including its procurement stage and contract period.
      operationId: getFramework
      parameters:
      - name: id
        required: true
        in: path
        description: The framework's unique identifier.
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: The framework agreement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FrameworkResponseDto'
              example:
                id: 7d9b1f3a-5c2e-4a8b-9d0f-3e6c1a4b7d92
                title: Technology Products & Associated Services 2
                description: An agreement for the supply of hardware, software and associated services to public sector buyers, divided into lots covering devices, networking and audio-visual equipment.
                service_provider:
                  id: e1a3c5b7-9d2f-4b6a-8c0e-5f7a9b1c3d40
                  name: Crown Commercial Service
                stage: live
                procedure_type: framework
                value:
                  amount: 1200000000
                  currency: GBP
                start_date: '2025-04-01'
                end_date: '2029-03-31'
        '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 framework by id
      tags:
      - Frameworks
      x-codeSamples:
      - lang: cURL
        label: curl
        source: "curl https://api.stotles.com/v1/frameworks/7d9b1f3a-5c2e-4a8b-9d0f-3e6c1a4b7d92 \\\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:
    FrameworkSearchResponseDto:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: The framework's unique identifier.
              title:
                type: string
                description: The framework's title.
              description:
                type: string
                description: The framework's description; empty when unknown.
              service_provider:
                type:
                - object
                - 'null'
                properties:
                  id:
                    type: string
                    format: uuid
                    description: The provider organisation's unique identifier.
                  name:
                    type: string
                    description: The provider organisation's name.
                required:
                - id
                - name
                description: The framework's service provider organization; null when unknown.
              stage:
                type: string
                enum:
                - stale
                - upcoming
                - tendering
                - closed
                - awarded
                - live
                - expired
                - canceled
                description: The framework's procurement stage.
                x-enumDescriptions:
                  stale: Announced, but aged past the point where tendering would normally have started. Treat it as unlikely to progress.
                  upcoming: Announced or planned. Suppliers cannot apply yet.
                  tendering: Open for suppliers to apply to be appointed to the framework.
                  closed: The application deadline has passed; the buyer has not yet announced which suppliers were appointed.
                  awarded: Suppliers have been appointed, but the agreement isn't available to buy from yet (typically its start date is in the future).
                  live: In force — buyers can run call-offs against it, and appointed suppliers can win work.
                  expired: Past its end date. No new call-offs are expected.
                  canceled: Withdrawn or abandoned before it came into force.
              procedure_type:
                type:
                - string
                - 'null'
                enum:
                - framework
                - dynamic_purchasing_system
                - null
                description: Whether this is a framework agreement or a dynamic purchasing system; null when 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 framework; null when no amount is known.
              start_date:
                type:
                - string
                - 'null'
                format: date
                description: Contract start date (YYYY-MM-DD); null when unknown.
              end_date:
                type:
                - string
                - 'null'
                format: date
                description: Contract end date (YYYY-MM-DD); null when unknown.
            required:
            - id
            - title
            - description
            - service_provider
            - stage
            - procedure_type
            - value
            - start_date
            - end_date
          description: The matching frameworks, 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
    FrameworkResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The framework's unique identifier.
        title:
          type: string
          description: The framework's title.
        description:
          type: string
          description: The framework's description; empty when unknown.
        service_provider:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
              format: uuid
              description: The provider organisation's unique identifier.
            name:
              type: string
              description: The provider organisation's name.
          required:
          - id
          - name
          description: The framework's service provider organization; null when unknown.
        stage:
          type: string
          enum:
          - stale
          - upcoming
          - tendering
          - closed
          - awarded
          - live
          - expired
          - canceled
          description: The framework's procurement stage.
          x-enumDescriptions:
            stale: Announced, but aged past the point where tendering would normally have started. Treat it as unlikely to progress.
            upcoming: Announced or planned. Suppliers cannot apply yet.
            tendering: Open for suppliers to apply to be appointed to the framework.
            closed: The application deadline has passed; the buyer has not yet announced which suppliers were appointed.
            awarded: Suppliers have been appointed, but the agreement isn't available to buy from yet (typically its start date is in the future).
            live: In force — buyers can run call-offs against it, and appointed suppliers can win work.
            expired: Past its end date. No new call-offs are expected.
            canceled: Withdrawn or abandoned before it came into force.
        procedure_type:
          type:
          - string
          - 'null'
          enum:
          - framework
          - dynamic_purchasing_system
          - null
          description: Whether this is a framework agreement or a dynamic purchasing system; null when 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 framework; null when no amount is known.
        start_date:
          type:
          - string
          - 'null'
          format: date
          description: Contract start date (YYYY-MM-DD); null when unknown.
        end_date:
          type:
          - string
          - 'null'
          format: date
          description: Contract end date (YYYY-MM-DD); null when unknown.
      required:
      - id
      - title
      - description
      - service_provider
      - stage
      - procedure_type
      - value
      - start_date
      - end_date
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key