> ## Documentation Index > Fetch the complete documentation index at: https://developer.plugsurfing.com/llms.txt > Use this file to discover all available pages before exploring further. # AI Integration Playbook This guide is for teams using AI assistants to integrate Plugsurfing's Drive API faster, with the docs and OpenAPI spec as the source of truth. > ⚠️ **Drive API only** > > This playbook applies to Drive API. It does not apply to Roam OCPI. If you are integrating Roam OCPI, use the [Roam OCPI docs](/docs/roam-ocpi/about-roam-ocpi). Use it when you want an assistant to help you discover the right guides, inspect the API contract, generate integration code, or test a stage flow. ## What this guide is for This guide focuses on external developers integrating Drive API. It is designed for common assistant-supported tasks such as: * discovering the correct endpoints for a feature * generating server-side integration code from the public contract * testing the stage flow before building production logic If you are working with EMP-only flows, use this guide for the general AI workflow and then continue with the dedicated [EMP guide](/docs/drive-api/emp). ## The canonical Drive API sources Use these public Drive API sources together: * the Drive API guides on `https://plugsurfing.mintlify.site` * `https://plugsurfing.mintlify.site/reference/openapi.json` * `https://plugsurfing.mintlify.site/mcp` They serve different purposes: * the Drive API guides explain the flows, caveats, and setup steps * `openapi.json` is the authoritative API contract behind the generated API Reference * `/mcp` lets compatible AI clients search and read the published Drive API docs and OpenAPI contract ## Recommended workflow Use this order when working with an AI assistant: 1. Start with the relevant Drive API guides to understand the flow you want to build. 2. Use `openapi.json` for the exact endpoints, parameters, request bodies, response fields, and `X-API-Key` requirement. 3. If your AI client supports MCP, use `/mcp` to search the published docs and retrieve the relevant contract details. 4. Use these Drive API base URLs: * Stage: `https://drive-api-stage.plugsurfing.com/drive` * Production: `https://drive-api.plugsurfing.com/drive` 5. Build and test on stage first, then move to production once the flow is stable. When copying paths from `openapi.json`, remember that OpenAPI paths already include the product prefix, such as `/drive` or `/emp`. Do not append an OpenAPI path that starts with `/drive` to a base URL that already ends with `/drive`. For example, the OpenAPI path `/drive/v1/geosearch/radius` maps to `https://drive-api-stage.plugsurfing.com/drive/v1/geosearch/radius` on stage. EMP paths use their own `/emp/v1/...` prefix, for example `https://{environment}.plugsurfing.com/emp/v1/charging-keys`. ### Minimal stage smoke test Use this minimal request when you want a copy-paste starting point: ```bash theme={null} curl --request POST \ --url 'https://drive-api-stage.plugsurfing.com/drive/v1/geosearch/radius?latitude=59.33&longitude=18.07&distance=5000' \ --header "X-API-Key: $API_KEY" \ --header 'Content-Type: application/json' \ --data '{}' ``` This is a good first check that your API key works, the stage host is reachable, and your client can send the expected query parameters and JSON body together. ## End-to-end task recipe This is a suggested path for integrating Drive API with AI assistance. ### 1. Search for a compatible charger Use the geosearch endpoints to find locations and connectors. If you plan to start sessions remotely, filter for connectors or EVSEs that support `REMOTE_START_STOP_CAPABLE`. Use the [Geosearch guide](/docs/drive-api/geosearch) for search behavior and [Search locations within a rectangle](/reference/searchLocationsByRectangle) for the request schema. ### 2. Create or retrieve the user Use the same stable user identifier that your system already owns. In most integrations, the first user operation is [Create user](/reference/createUser), followed by [Get user](/reference/getUser) when you need to rehydrate state. Use the [Users guide](/docs/drive-api/user) for identifier strategy and deletion constraints. ### 3. Confirm the virtual charging key exists When a user is created, a virtual charging key is created automatically. Confirm that with [Get user's charging keys](/reference/listUserChargingKeys). This matters because remote charging uses the virtual key flow, while physical card flows live in the [Charging Keys guide](/docs/drive-api/charging-keys). ### 4. Start the remote session Call [Start a remote charging session](/reference/startRemoteSession) with the user ID and connector ID. If the request is accepted, the response contains the new `sessionId`. Remote start is only valid for chargers that support `REMOTE_START_STOP_CAPABLE`. ### 5. Monitor the session Start with [Get session by id](/reference/getSessionById) to poll the current state. If you want asynchronous updates later, add [Session events](/docs/drive-api/events). ### 6. Stop the session Use [Stop a remote charging session](/reference/stopRemoteSession) for sessions started remotely. ## Safety rails Keep these rules in every AI-assisted integration: * Never expose `X-API-Key` in client-side code, browser prompts, or shared snippets. * Treat unknown event names and enum values as expected forward-compatibility cases. * Design webhook consumers to ignore unknown fields and process requests idempotently. * Expect operational delays when starting or stopping sessions. * Expect session events to arrive out of order or not at all. For webhook behavior and HMAC verification, continue with [Webhooks](/docs/drive-api/webhooks) and [Verifying HMAC Signature](/docs/drive-api/verifying-hmac-signature). ## Prompt templates Use these as starting points and replace the placeholders with your own task details. ### Discover the correct endpoints for a task ```text theme={null} Use the Drive API docs on https://plugsurfing.mintlify.site to find the relevant Drive API guides and reference pages for this task: . Example tasks: - show chargers on a map with geosearch rectangle - create a user and start a remote charging session - poll a session until it is completed Return: 1. the exact docs pages I should read first 2. the exact endpoints I will probably call 3. the key operational caveats I should not miss ``` ### Generate server-side code from the OpenAPI contract ```text theme={null} Use https://plugsurfing.mintlify.site/reference/openapi.json as the source of truth. Generate server-side code for this Drive API task: . Example tasks: - geosearch rectangle for a map view - create a user and list the user's charging keys - start a remote charging session and poll it by session id Requirements: - authenticate with X-API-Key - keep secrets server-side only - use the stage base URL first ``` ### Search the documentation with MCP ```text theme={null} Connect to https://plugsurfing.mintlify.site/mcp and help me research this Drive API task: . Use MCP to: - find the relevant guides and API-reference pages - identify the endpoint, request fields, and response fields I need - list the operational caveats I should handle Do not execute Drive API requests or ask for my API key. I will run stage requests from my server-side integration. ``` ## Limitations and when to fall back to the guides The AI entrypoints are useful, but they are not a substitute for the full documentation. Fall back to the guides when: * you need the business flow around a feature, not just the request schema * you need webhook delivery semantics, retries, or HMAC guidance * you need payment behavior details such as 3DS handling * you need EMP- or OCPI-specific integration guidance * you need confirmation of manual setup steps with Plugsurfing For most integrations, the best pattern is: 1. use the guides to understand behavior 2. use `openapi.json` to verify the contract 3. use `/mcp` to search and read the published documentation from an AI client This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.