{"openapi":"3.1.1","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Drivings Public Agent 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"}],"externalDocs":{"description":"Drivings LLM reference","url":"https://drivings.com/llms.txt"},"security":[],"tags":[{"name":"Discovery","description":"Public catalog and evidence retrieval with no side effects."},{"name":"Planning","description":"Deterministic computation that is not persisted."}],"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"}}}}}}},"/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":{"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."}}}}},"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}},"Region":{"name":"region","in":"query","required":true,"description":"Published Drivings market.","schema":{"$ref":"#/components/schemas/Region"}}},"schemas":{"Region":{"type":"string","enum":["uk","us"]},"Course":{"type":"string","enum":["car","motorcycle","lgv","pcv","adi","cdl"]},"TestService":{"type":"string","enum":["theory","practical"]},"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},"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"}}},"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"}}},"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"}}},"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"}}},"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"}}}}}}}},"x-llms-txt":"https://drivings.com/llms.txt","x-mcp-server":"https://mcp.drivings.com/mcp","x-agent-safety":{"sideEffects":"none","humanConfirmationRequiredForBrowserHandoffs":true}}