Drivings Planning API

openapi: 3.2.0
info:
  title: Drivings Public Agent Planning 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: Planning
  description: Deterministic computation that is not persisted.
paths:
  /api/agent/v1/study-plan:
    post:
      operationId: buildStudyPlanPreview
      summary: Build a deterministic study-plan preview
      description: Computes a bounded schedule and returns it without creating an account, starting a session, or persisting any data.
      tags:
      - Planning
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudyPlanInput'
            example:
              region: uk
              course: car
              weeks: 4
              daysPerWeek: 5
              minutesPerDay: 20
      responses:
        '200':
          description: Non-persistent study-plan preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyPlanPreview'
        '400':
          description: The request was rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: The request was rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          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'
      x-side-effects: none
      x-idempotent: true
components:
  schemas:
    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
    StudyPlanInput:
      type: object
      required:
      - region
      - course
      additionalProperties: false
      properties:
        region:
          $ref: '#/components/schemas/Region'
        course:
          $ref: '#/components/schemas/Course'
        weeks:
          type: integer
          minimum: 1
          maximum: 16
          default: 4
        daysPerWeek:
          type: integer
          minimum: 1
          maximum: 7
          default: 5
        minutesPerDay:
          type: integer
          minimum: 10
          maximum: 120
          default: 20
    StudyPlanPreview:
      type: object
      required:
      - schemaVersion
      - kind
      - persisted
      - region
      - course
      - schedule
      - weeks
      - nextStep
      - disclaimer
      properties:
        schemaVersion:
          type: string
        kind:
          const: study_plan_preview
        persisted:
          const: false
        region:
          $ref: '#/components/schemas/Region'
        course:
          $ref: '#/components/schemas/Course'
        schedule:
          type: object
        weeks:
          type: array
          minItems: 1
          maxItems: 16
          items:
            type: object
        nextStep:
          $ref: '#/components/schemas/BrowserHandoff'
        disclaimer:
          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
    Region:
      type: string
      enum:
      - uk
      - us
    Course:
      type: string
      enum:
      - car
      - motorcycle
      - lgv
      - pcv
      - adi
      - cdl
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Opaque client-generated key echoed back on the response. This operation computes and returns without writing anything, so a retry cannot duplicate a side effect; the key is for correlating an attempt with its reply.
      schema:
        type: string
        maxLength: 255
  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