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

    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: 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:
  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
    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
    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
  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