Drivings Discovery API

openapi: 3.2.0
info:
  title: Drivings Public Agent Discovery API
  version: '2026-07-22'
  description: Public, side-effect-free endpoints for discovering Drivings study options and source-backed test-centre information, plus computing a non-persistent study-plan preview. This API cannot book tests, buy products, send messages, or change accounts or learner data.
  contact:
    name: Drivings support
    email: support@drivings.com
    url: https://drivings.com/contact
servers:
- url: https://drivings.com
  description: Production
security: []
tags:
- name: Discovery
  description: Public catalog and evidence retrieval with no side effects.
paths:
  /api/agent/v1/capabilities:
    get:
      operationId: getAgentCapabilities
      summary: Inspect the public agent safety and capability contract
      description: Returns the operations, transports, discovery links, unavailable operations, and human-confirmation boundary.
      tags:
      - Discovery
      responses:
        '200':
          description: Capability contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Capabilities'
  /api/agent/v1/courses:
    get:
      operationId: listStudyOptions
      summary: List published study options for a region
      description: Returns canonical course pages and a confirmation-required browser handoff. It does not create a learner session or save answers.
      tags:
      - Discovery
      parameters:
      - $ref: '#/components/parameters/Region'
      responses:
        '200':
          description: Published study options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyOptions'
        '400':
          description: The request was rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: The request was rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/agent/v1/test-centres:
    get:
      operationId: findTestCentres
      summary: Find source-backed driving test centres
      description: Searches the published UK or US directory. Results contain verification dates, evidence URLs, coverage limits and optional official browser handoffs. The API never books or changes a test.
      tags:
      - Discovery
      parameters:
      - $ref: '#/components/parameters/Region'
      - name: query
        in: query
        required: false
        description: Centre name, locality, address, postcode/ZIP, alias, or identifier. Omit for an alphabetical listing.
        schema:
          type: string
          minLength: 2
          maxLength: 100
        example: Birmingham
      - name: service
        in: query
        required: false
        description: Limit results to the requested published directory.
        schema:
          $ref: '#/components/schemas/TestService'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 10
          default: 5
      responses:
        '200':
          description: Ranked centre matches and evidence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestCentreSearch'
        '400':
          description: The request was rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: The request was rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    StudyOptions:
      type: object
      required:
      - schemaVersion
      - region
      - options
      - independenceNotice
      properties:
        schemaVersion:
          type: string
        region:
          $ref: '#/components/schemas/Region'
        regionName:
          type: string
        options:
          type: array
          items:
            type: object
            required:
            - id
            - name
            - courseUrl
            - onboardingHandoff
            properties:
              id:
                $ref: '#/components/schemas/Course'
              name:
                type: string
              courseUrl:
                type: string
                format: uri
              onboardingHandoff:
                $ref: '#/components/schemas/BrowserHandoff'
        independenceNotice:
          type: string
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            issues:
              type: array
              items:
                type: object
    TestCentreSearch:
      type: object
      required:
      - schemaVersion
      - query
      - count
      - totalMatches
      - results
      - coverage
      - safetyNotice
      properties:
        schemaVersion:
          type: string
        query:
          type: object
        matchMethod:
          type: string
        count:
          type: integer
        totalMatches:
          type: integer
        results:
          type: array
          maxItems: 10
          items:
            type: object
            required:
            - id
            - name
            - canonicalUrl
            - address
            - operationalStatus
            - services
            - lastVerifiedAt
            - evidence
            properties:
              id:
                type: string
              name:
                type: string
              pageTitle:
                type: string
              canonicalUrl:
                type: string
                format: uri
              address:
                type: string
              jurisdiction:
                type: object
              coordinates:
                oneOf:
                - type: object
                - type: 'null'
              operationalStatus:
                type: string
              classification:
                type: string
              services:
                type: object
              official:
                type: object
              lastVerifiedAt:
                type: string
                format: date-time
              evidence:
                type: array
                items:
                  type: object
        coverage:
          type: object
        safetyNotice:
          type: string
    BrowserHandoff:
      type: object
      required:
      - url
      - kind
      - requiresHumanConfirmation
      properties:
        url:
          type: string
          format: uri
        kind:
          type: string
        requiresHumanConfirmation:
          const: true
        note:
          type: string
        warning:
          type: string
      additionalProperties: true
    TestService:
      type: string
      enum:
      - theory
      - practical
    Region:
      type: string
      enum:
      - uk
      - us
    Capabilities:
      type: object
      required:
      - schemaVersion
      - service
      - operations
      - safety
      - discovery
      properties:
        schemaVersion:
          type: string
        service:
          type: string
        description:
          type: string
        authentication:
          const: none
        operations:
          type: array
          items:
            type: object
        safety:
          type: object
        discovery:
          type: object
        contact:
          type: string
          format: email
    Course:
      type: string
      enum:
      - car
      - motorcycle
      - lgv
      - pcv
      - adi
      - cdl
  parameters:
    Region:
      name: region
      in: query
      required: true
      description: Published Drivings market.
      schema:
        $ref: '#/components/schemas/Region'
  securitySchemes:
    drivingsOAuth:
      type: oauth2
      description: Not required by any operation in this document. It gates one MCP tool, the learner's own progress, and is listed so an agent can see the whole permission surface in one place.
      flows:
        authorizationCode:
          authorizationUrl: https://xqvjkpkownkftsdofpbb.supabase.co/auth/v1/authorize
          tokenUrl: https://xqvjkpkownkftsdofpbb.supabase.co/auth/v1/token
          scopes:
            openid: Identify the signed-in learner.
            email: Read the learner's email address.
            profile: Read the learner's study target and recent activity.
externalDocs:
  description: Drivings LLM reference
  url: https://drivings.com/llms.txt
x-llms-txt: https://drivings.com/llms.txt
x-mcp-server: https://mcp.drivings.com/mcp
x-agent-safety:
  sideEffects: none
  humanConfirmationRequiredForBrowserHandoffs: true