Skip to main content
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.
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.

​
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
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:
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 for search behavior and Search locations within a rectangle 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, followed by Get user when you need to rehydrate state. Use the Users guide 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. This matters because remote charging uses the virtual key flow, while physical card flows live in the Charging Keys guide.

​
4. Start the remote session

Call Start a remote charging session 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 to poll the current state. If you want asynchronous updates later, add Session events.

​
6. Stop the session

Use Stop a remote charging session 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 and 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

​
Generate server-side code from the OpenAPI contract

​
Search the documentation with MCP

​
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