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.

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://developer.plugsurfing.com
• https://developer.plugsurfing.com/openapi/openapi.json
• https://developer.plugsurfing.com/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 is mainly for AI agents. It adds a tool layer for endpoint discovery and interactive request execution

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 endpoints and try requests from the same workflow.
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.

Minimal stage smoke test

Use this minimal request when you want a copy-paste starting point:

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 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

Use the Drive API docs on https://developer.plugsurfing.com to find the relevant Drive API guides and reference pages for this task: <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

Use https://developer.plugsurfing.com/openapi/openapi.json as the source of truth.

Generate server-side <language> code for this Drive API task: <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

Use MCP to inspect and test the stage flow

Connect to https://developer.plugsurfing.com/mcp and help me implement this Drive API task in stage: <task>.

Use MCP to:
- discover the right endpoints
- inspect endpoint details
- execute a stage request safely when secrets are configured correctly
- explain which secrets stay server-side
- list the non-obvious operational caveats from the docs that I must handle

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 inspect and test