{"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"],"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":{"parameters":{"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://drivings.com/api/mcp","x-agent-safety":{"sideEffects":"none","humanConfirmationRequiredForBrowserHandoffs":true}}