Fifteen verbs run a driver's whole ev.energy account
Module:
None(driver-facing, no workspace module required) | Role: EV driver | Licence: Free+ | Auth: ev.energy account login (Clerk OAuth)
The Connect MCP server at https://eve.ev.energy/connect/mcp exposes exactly 15 enrollment verbs for EV drivers. Every verb acts on the OAuth'd driver's own ev.energy account; there is no admin or multi-account surface. For the driver-facing overview see Connect; to wire an AI client to this surface see connecting a client.
All verbs take an optional provider parameter (string, defaults to "ev.energy"). Today only ev.energy is wired; other providers return a clear "not yet supported" error. When the driver isn't signed in, every verb returns a clean requires_login response rather than raising.
Returns. Most verbs return a dict with success (boolean), provider, and either data (on success) or error (on failure). Verb-specific fields are noted below.
Confirmation gating. Destructive verbs require a two-step confirm: the first call returns a requires_confirmation payload with a user_message to show the driver; the client retries with confirmed=true after an explicit yes.
Writes work, with two limits. Account and device writes complete live against your account: update_account saves your home address and tariff, and update_device sets your car's charge limit.
What a connected AI can't change. A confirmation that your own AI sets on your behalf isn't proof that you agreed, so some writes go to the ev.energy app instead. Those calls return success: false, requires_app_action: true and error_type: "agent_write_refused", plus a line telling you where to make the change in the app.
- Payout method: never set through Eve or any connected AI, because it decides where your earnings go.
- Over
/connect/mcpand A2A: changing your tariff or a charge limit, removing a vehicle or charger, joining, switching or leaving a programme, activating a charging card, and removing a card or reporting one lost. Eve in chat and on a call still does these, after asking you.
Device control (boost / pause / lock / dispatch) is coming soon. Acting on a device right now, whether that is boosting a charge, pausing it, locking a charger or dispatching a battery, is reserved for a future generalized
controlverb. It is not live yet: it's waiting on a device-control action that ev.energy is still building. Everything else below is live today.
One verb covers your account and profile
update_account saves your address and tariff
Update account-wide settings: your home address and tariff. Your payout method and your phone number are set in the ev.energy app: neither is a parameter you can write here, and a call that sends one anyway changes nothing and gets the app hand-off. Over MCP or A2A a tariff change also hands off to the app. These are live writes, saving against your account immediately, no app round-trip. Charging-schedule fields (departure time, target SOC, day overrides) live on the device, not the account, and return a clear "not on this verb" message.
| Parameter | Type | Required | Description |
|---|---|---|---|
home_location | string | no | Free-text home address; parsed into street / city / postcode / country before saving. |
tariff_id | string | no | Tariff to set as the default. Changing it is confirmation-gated, and over MCP or A2A it hands off to the app. |
phone | string | no | Not written here. Any value hands off to the ev.energy app, the same shape as payout_method. |
target_soc | integer | no | Not on this verb. Charging targets are a per-device setting; use update_device. |
departure_time | string | no | Not on this verb; see update_device. |
weekday_overrides | object | no | Not on this verb; see update_device. |
weekend_overrides | object | no | Not on this verb; see update_device. |
schedule | object | no | Not on this verb; see update_device. |
solar_mode | string | no | Not on this verb. |
confirmed | boolean | no | Set true to confirm a tariff change after the confirmation prompt. |
provider | string | no | Defaults to ev.energy. |
Returns: success, fields_updated, and persisted_fields (the fields the backend echoed back as saved). If a sent field isn't echoed, success demotes to false and unpersisted_fields lists it: the write is treated as not-persisted. A pure address update needs no confirmation; a tariff change does.
Eve onboards, tunes and removes your devices
connect_device onboards a vehicle from a free-text description
It matches the description against the vehicle-make catalogue, walks make → model → trim to resolve the OEM provider, and returns an OEM auth URL the driver opens to authorise. The vehicle registers automatically once OEM auth completes.
Vehicles only, today. The wire path is the v1
/vehicle-authorization/flow over the legacy car-make catalogue, so a charger, home battery or solar inverter description has nothing to match against and returns"Couldn't match … to a vehicle make."Chargers, batteries and solar are paired in the ev.energy app; Eve should say so rather than offer a link she cannot produce. Removing an already-paired charger works (remove_deviceis polymorphic); it is only the onboarding side that is vehicle-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
description | string | yes | Free-text vehicle description, e.g. "a 2024 Tesla Model Y", "Hyundai Ioniq 5". |
provider | string | no | Defaults to ev.energy. |
Returns: success plus a data object with matched_make, oem_provider, authorization_request_id, onboarding_url (the OEM auth URL to send the driver), instructions, and a ui_hint for chat clients. On a near-miss it returns error_type: "needs_clarification" (asking for the model or trim) or error_type: "transport_failure" (asking the driver to retry).
onboarding_url is the only source of an onboarding link. The catalogue rows returned by discover(scope="vehicle_makes") have their onboarding_url stripped deliberately: v2's prebuilt wizard URL 403s in a cross-origin popup from askeve.energy (the V2_ONBOARDING_WAF_403 anti-pattern), so a URL taken from anywhere but this verb is a dead end.
update_device sets your car's charge limit
It updates settings on one device. Today the only writable setting is the vehicle charge limit (maximum_charge_limit_percentage, 50 to 100), reached via aliases like target_soc or max_charge. Charger (EVSE) settings aren't writable on the public API yet and are reported honestly. Confirmation-gated; over MCP or A2A it hands off to the app.
| Parameter | Type | Required | Description |
|---|---|---|---|
device_id | string | yes | The vehicle ID to update. |
settings | object | yes | e.g. {"charge_limit": 80} or {"target_soc": 90}. Unknown keys return a clear error. |
confirmed | boolean | no | Set true to apply after the confirmation prompt. |
provider | string | no | Defaults to ev.energy. |
Returns: success, device_id, device_type, fields_updated. A 404 surfaces as a "couldn't find that car" message.
remove_device takes a vehicle or charger off the account
It is polymorphic, looking the device up first to decide vehicle vs. EVSE. Destructive, confirmation-gated (re-pairing from scratch is required to use it again); over MCP or A2A it hands off to the app.
| Parameter | Type | Required | Description |
|---|---|---|---|
device_id | string | yes | The device to remove. |
confirmed | boolean | no | Set true to confirm. |
provider | string | no | Defaults to ev.energy. |
Returns: success, device_id, device_type (vehicle or evse).
Four verbs manage your charging cards and payment cards
A charging card is an ev.energy RFID card you tap at a public charger. A payment card is the bank card those charges are paid from. Cards are a separate thing from devices: connect_device stays cars only, and these four verbs cover the card lifecycle (activate or add, update, remove). They call the same card layer as the card pages at /connect/rfid-cards and /connect/payment-cards, so a verb and a page always agree on a card's status, what it allows, and the wording.
What an AI sees of a card. Every card is named by a masked label ("Charging card ending AB12", "Visa ending 4242") and an opaque handle: rfc_… for a charging card, pmc_… for a payment card. A handle only works for the signed-in driver; another driver's handle and a made-up one both answer the same card_not_found. A charging card's chip uid never reaches the model, and the id printed on a card is never logged.
When the card verbs are listed. Only while the card service is configured. When it isn't, the four verbs are absent from every surface's tool list and can't be called, so a client never sees a verb it can't use.
activate_charging_card adds a charging card you are holding
ev.energy charging cards are handed out unassigned, and the first account to activate one keeps it. The id printed on the card is the proof that you hold it. In Eve's own chat and voice, the first call reads the masked card back ("Charging card ending 9ZX2") with a reminder that every charge started with it is paid from your account; the card is activated on a second call with confirmed=true after you say yes. Over /connect/mcp and A2A nothing changes: the call returns requires_app_action: true and an absolute link to /connect/rfid-cards/activate, where you confirm the card is in your hand.
| Parameter | Type | Required | Description |
|---|---|---|---|
printed_id | string | yes | The id printed on the charging card (letters and numbers), exactly as read. Never a bank card number. |
confirmed | boolean | no | Set true to activate after the confirmation prompt. |
provider | string | no | Defaults to ev.energy. |
Returns: success, a message, and data.card (the activated card, in the my_account shape below). A 13 to 19 digit, all-numeric value that passes the Luhn check is refused on every surface as a probable bank card number (reason: "bank_card_number"), before anything is sent or recorded; the hint points at add_payment_card.
add_payment_card gives you the secure page to add a bank card
It takes no card details, and none are ever taken in conversation: you type the card into the payment provider's own form on /connect/payment-cards/add. What comes back depends on the surface:
- Chat and web voice (a screen):
data.urlplus aui_hintof kindaccount_link, which the surface renders as an Add a payment card button. - A phone call (no screen):
data.spoken_routeonly ("In the ev.energy app or at ev.energy on the web, open Account, then Payment cards, then Add a card."). No link is read out. /connect/mcpand A2A:data.urlas an absolute link.
| Parameter | Type | Required | Description |
|---|---|---|---|
provider | string | no | Defaults to ev.energy. |
Returns: success and data (url and/or spoken_route, an instruction, and ui_hint on a first-party screen). A new card can take a moment to show in my_account.
update_card makes a card the default, or freezes and unfreezes a charging card
One change per call. default=true makes the card the one used first, for either kind. frozen=true pauses a charging card so it starts no charge, and frozen=false resumes it; payment cards can't be frozen. A card the driver's workspace or ev.energy froze is theirs to unfreeze: frozen=false on it is refused with reason frozen_by_operator. A driver's own change is reversible, so there is no confirmation step. It runs in Eve's own chat and voice, over /connect/mcp and over A2A. A request from any other caller is handed to the card page.
| Parameter | Type | Required | Description |
|---|---|---|---|
card | string | yes | The card's handle from my_account().data.cards (rfc_… or pmc_…). Never a number printed on a card. |
default | boolean | no | true to make this the default card. |
frozen | boolean | no | Charging cards only. true to freeze, false to unfreeze. |
provider | string | no | Defaults to ev.energy. |
Returns: success, a message, and data.card with its new status. Sending neither or both of default and frozen returns error_type: "invalid_arguments". A change the card's state doesn't allow is refused with reason: "card_state"; the card's can list says what it allows.
remove_card removes a card, or reports a charging card lost
remove_card(card) takes a charging or payment card off your account. remove_card(card, lost=true) reports a charging card lost or stolen and blocks it for good; it is for charging cards only. Both are destructive and confirmation-gated in Eve's own chat and voice: the first call reads the card and the consequence back, and the change happens on a retry with confirmed=true. Over /connect/mcp and A2A nothing changes: the call hands off to the card page. A payment card holding funds for a charge can't be removed until that charge settles.
| Parameter | Type | Required | Description |
|---|---|---|---|
card | string | yes | The card's handle from my_account().data.cards. |
lost | boolean | no | Charging cards only. true to report it lost and block it permanently. |
confirmed | boolean | no | Set true to confirm. |
provider | string | no | Defaults to ev.energy. |
Returns: success, a message, and data.card.
my_account().data.cards lists your cards
The dashboard carries cards = {available, charging_cards, payment_cards}. Each card has:
| Field | What it is |
|---|---|
card | The opaque handle (rfc_… / pmc_…) the card verbs take. |
kind | charging_card or payment_card. |
label | The masked name, e.g. "Charging card ending AB12" or "Visa ending 4242". |
status | Charging cards only: the card page's status, Active, Paused or Reported lost. |
default | Whether this is the default card of its kind. |
expires | Payment cards only: the expiry date. |
can | What the card allows right now, from the pages' own action tables: any of default, freeze, unfreeze, report_lost, remove. |
When cards can't be read, available is false with reason unconfigured (the card service isn't set up on this server; note says so in words to repeat) or unreadable (neither list could be read in time). If only one list could be read, the other is null, never []: an empty list would claim you have no cards.
On the account page alone (surface page), my_account also carries public_charging = {available, sessions}: the newest three public charging sessions, each in the view="sessions" row shape plus paid_by ("you", or the name of the workspace that paid). Unread, it is available: false with reason unconfigured or unreadable, never an empty list. No agent surface reads it: Eve asks my_transactions(view="sessions") instead.
One verb reads your notifications
my_notifications tells you what happened on your account
Your notifications, newest first: a public charge completed, a card declined, a refund, a hold released. Each one's title and body are written by the service that sent it, in your locale and time zone, ready to read out as they are. Notifications only inform: none of them changes anything on your account, and none asks you to act here.
Showing them marks them read. Unless you pass peek=true, the notifications returned are marked read up to the newest one, everywhere you use Eve (chat, a call, a connected AI and the bell on the Connect pages share one read state), once every unread one has been returned (if there are more unread than one page holds, nothing is marked until you page back to them, so nothing is marked read unseen). If marking fails, they stay unread; the list is still returned.
On a call, Eve also tells you when a new notification arrives while you are talking, once there is a pause. Telling you does not mark it read.
| Parameter | Type | Required | Description |
|---|---|---|---|
unread_only | boolean | no | Only notifications you have not seen yet. Default false. |
limit | integer | no | How many, 1 to 50. Default 20. |
before | string | no | The next a previous call returned, for older notifications. |
peek | boolean | no | Read without marking them read. Default false. |
provider | string | no | Defaults to ev.energy. |
Returns: success and data, {summary: {unread, marked}, items, next}. Each item is {id, type, occurred_at, title, body, reference, read, display}: display.when is when it happened, already written in your time zone and locale (Sun 4 Oct, 11:25; Sun, Oct 4, 11:25 AM in en-US), the text to quote, while occurred_at is the exact instant (if occurred_at can't be read, display is empty and occurred_at is still there); reference is the charge's reference (EVE-…) when the notification is about a charge, the one to quote to support; read says whether it had already been seen when it was returned. summary.unread is how many are still unread after this call, and summary.marked whether the ones returned are now marked read (false with peek, when more are unread than this page shows, or when marking failed). next is null on the last page.
my_account carries a summary too, data.notifications = {available, unread, latest} (the newest three), and reading it never marks anything. A limit outside 1 to 50 is clamped; a limit that is not a whole number, or a before that is not a next this verb returned, answers error_type: "invalid_arguments". When notifications can't be read, the verb answers success: false with error_type: "notifications_unavailable" and a reason, and the summary reads available: false with the same reason. While notifications aren't set up on this server, the reason is unconfigured and the summary also carries a note saying so.
Joining and leaving a programme are one verb each
join_program joins a programme and leaves the one you were in
It opts the driver into a smart-charging or demand-response programme, or finishes a join that still needs utility-account verification. A driver is in one programme at a time, so joining a new one automatically leaves the current one (enforced server-side): this is a switch, not a stack. Over MCP or A2A it hands off to the app. Eligibility and compatibility checks run server-side; errors surface verbatim. Programmes with no in-app default tier (community / innovation trials) return an external_signup_url instead, and Eve hands the driver to the sponsor's sign-up page.
| Parameter | Type | Required | Description |
|---|---|---|---|
program_id | string | yes | A programme ID from discover(scope="programs"). |
verification_data | object | no | Only to finish a program_verification deferred action: the collected fields keyed by each required_inputs name, e.g. {"account_number": "…", "postal_code": "95405"}. |
verification_type | string | no | post_enrollment or user_verification, taken from the deferred action's resume.args_template. Only sent alongside verification_data. |
provider | string | no | Defaults to ev.energy. |
Returns: success, program_id, plus previous_program_id / previous_program_name naming whatever the join just left (both null when the driver was in nothing), so a switch is narratable and auditable after the fact. On an in-app join failure where the programme has one, external_signup_url carries the sponsor's sign-up page.
Verification is a sub-step of joining, not a separate verb. Some US CCA schemes (Sonoma Clean Power, Clean Power Alliance, Marin Clean Energy) admit the driver on join but need proof of utility-account ownership before earnings switch on. That surfaces as a program_verification entry in my_account().data.deferred_actions; collecting the named fields and calling join_program again with verification_data finishes it in-conversation, with no website hand-off. A verification call that arrives without verification_data fails loudly rather than falling through to a re-join, which would silently leave and re-join the programme.
leave_program leaves the one programme the driver is in
A driver is in at most one programme, so this leaves whichever one they're in. Destructive, confirmation-gated (over MCP or A2A it hands off to the app): earnings from that programme stop and pending programme payments may be forfeited, and the confirmation message says so. Your smart-charging savings are a property of your account, not the programme, so they continue for as long as you keep smart charging.
| Parameter | Type | Required | Description |
|---|---|---|---|
program_id | string | yes | The enrolled programme to leave (a driver has at most one). |
confirmed | boolean | no | Set true to confirm. |
provider | string | no | Defaults to ev.energy. |
Returns: success, program_id.
Changing tariff or supplier is handled by
update_accountviaupdate_account(tariff_id=…). There is no separate supplier verb.
Device control (boost / lock / dispatch) is not yet a verb on this surface. It is coming soon as a future generalized
controlverb, waiting on a device-control action ev.energy is still building. Rebates accrue automatically intomy_transactions, so there is noredeem_rewardverb (the evidence-required case surfaces as an in-app nudge).
One verb hands the driver their referral link
refer_friend returns the driver's own code, link and QR
It returns the real code on their account, e.g. NICK59, plus its share link and QR URL. Non-destructive, so no confirmation gate. When a friend signs up with the code, ev.energy credits both of them.
| Parameter | Type | Required | Description |
|---|---|---|---|
handle | string | no | Email or ev.energy handle the driver wants to invite. See the note below: this does not send an email. |
program_id | string | no | Mint a programme link: whoever follows it is signed in, credited to this driver, and enrolled in that programme in one tap. Get the id from discover(scope="programs"). Omit for a plain link that lets the friend pick their own programme. |
provider | string | no | Defaults to ev.energy. |
Returns: success, the referral code, its share link (/connect/r/<code>) and qr_url, a hint in driver-words, and a ui_hint (kind: referral_share) that the chat surface renders as a scannable QR + link card. With program_id, the link carries the programme; the hint explains that a friend already on a different programme is asked first rather than switched.
handledoes not send anything. Core has no "email an invite on the driver's behalf" endpoint, so passinghandleechoes it back and rewrites thehintto "Send <handle> your referral link below … (I can't send the invite directly from here.)" Eve must relay that, never claim an invite was sent. This is the same phantom-endpoint discipline asPROGRAM_JOIN_PHANTOM_ENDPOINT: the verb refuses to fire at a path that has never existed.
Three verbs read your account, the catalogues and your history
my_account is the canonical first call in any conversation
Without target: a composite dashboard snapshot covering vehicles, chargers, programmes, location, tariff, and the next_step the driver needs (e.g. connect_a_car, set_home_location, join_a_program). With target=device_id: full detail for one device.
| Parameter | Type | Required | Description |
|---|---|---|---|
target | string | no | A device ID for single-thing detail; omit for the dashboard. |
provider | string | no | Defaults to ev.energy. |
Returns: success, provider, and a data object. The dashboard data carries exactly:
| Field | What it is |
|---|---|
setup | The checklist: account, device, location, tariff, program, complete. complete drives which prompt overlay Eve loads. |
next_step | One of connect_a_car, connect_a_charger, set_home_location, set_tariff, join_a_program, or null. |
vehicles | id, make, model, trim, maximum_charge_limit_percentage, and a live sub-object (plug state, SoC, charging) when the live read succeeded. |
chargers | id, cpid, make, model. No live state: plug-in / charging status is not exposed for chargers today. |
program | Your one enrolled programme (singular), or null — you are in at most one. Hydrated with the catalogue record (benefits, description, eligibility_criteria, payment_*) folded over your membership, so an enrolled driver gets the same detail a prospect does. Carries joined_at, the ISO 8601 moment this driver joined this programme — not their account signup date, and it resets on a tier change. Anything scoped to the programme measures from there. |
subscriptions | Account offerings, {id, offering}. Not programmes. |
location, tariff | Normalised summaries. Read these before falling back to raw profile. |
deferred_actions | Anything still needing a field from the driver (program_verification; program_utility_signin when a programme still needs the driver's utility sign-in, with a signin_url to it). |
preferences, profile | Raw pass-through, so a new upstream field surfaces with no code change. |
cards | Your charging cards and payment cards, {available, charging_cards, payment_cards}, each list in the same order on every surface: the default, then usable cards before paused, expired or lost ones, then newest first. See my_account().data.cards. |
account | Your details as core holds them: name, email, phone, home_address (from default_location), tariff (its name), programme (its name) and degraded. Any of name/email/home_address/tariff/programme can read null because you have none on file, OR because the profile fetch failed — check degraded: true means "couldn't be read right now", never "empty". phone is read from the same call as referral (a separate read from the one degraded covers), so its own failure does not set degraded; a null phone means no phone on file or that read failing. phone reaches every surface, MCP and A2A included — approving a client's consent covers it, and the consent screen says so. phone is read-only here — update_account(phone=…) always hands off to the ev.energy app. |
referral | Your referral link for your own programme, the payload refer_friend returns: code, short_link, qr_url, nfc_url, share_text, web_link. null when core has no referral code for you. |
notifications | Your notifications summary, {available, unread, latest}: how many are unread and the newest three, as my_notifications returns them. Reading it never marks them read. |
connected_apps | The apps you have let use Eve for you: {id, name, connected_at} each, nothing else. Over MCP or A2A this is always null — a third-party model is never shown the driver's OTHER connected clients, which is enumeration it has no legitimate use for. On a first-party surface, null means they could not be read just now, never "none". name is self-declared by the app at registration and is not verified; on chat and voice it is wrapped as explicit untrusted data (untrusted, self-declared app name: "...") before Eve ever sees it, since the model reads this projection directly there. |
ui_hint | Reserved for an assisted utility handoff, which Eve does not currently offer. When present, the surface renders it, never model prose. |
my_account does not return a transactions or savings snapshot, easy as that is to assume: use my_transactions. The driver's own things — devices, enrolled programme, subscriptions — are all on my_account, never on discover: discover is available catalogues only.
discover reads any available catalogue by scope
Paginated read of an available catalogue by scope — things the driver could add or join, never the driver's own things (those are on my_account). Same operation across scopes; the corpus changes.
| Parameter | Type | Required | Description |
|---|---|---|---|
scope | string | yes | What to list (see scopes below). |
filters | object | no | Scope-specific constraints, e.g. {"make_id": "..."} for vehicle_models. |
provider | string | no | Defaults to ev.energy. |
Scopes, the complete set of 8. Anything else returns an Unknown scope error:
vehicle_makes,vehicle_models(filtermake_id),vehicle_trims(filtermodel_id),charger_makes,charger_models(filtermake_id),programs,tariffs,suppliers.
The driver's OWN devices, enrolled programme and subscriptions are not discover scopes — they moved to my_account (my_account().data.vehicles, my_account().data.chargers, my_account().data.program, my_account().data.subscriptions). Asking discover for my_devices, my_programs or subscriptions is an Unknown scope error that points you at my_account.
charger_makes and charger_models are a read-only compatibility catalogue ("will my charger work?"), not an onboarding path: chargers are still paired in the ev.energy app (see connect_device). The catalogue is deliberately not narrowed to your account, because it is not exhaustive (myenergi/Zappi integrates via its own API and the generic OCPP path is not listed), so a charger that is missing from it can still be supported.
A programme (discover(scope="programs"), joined via join_program) is different from a subscription (an account offering read on my_account, with no programme link — SUBSCRIPTIONS_NOT_PROGRAM_MEMBERSHIP).
programs and tariffs are narrowed to the driver's saved location, so a GB driver never sees Connecticut programmes. Pass an ad-hoc location in filters, either {"postcode": "SW1A 1AA"} or {"zipcode": "06010", "country": "US"}, to search near there without writing to the driver's profile. That is the "what could I earn near me?" lookup, and it works before any device is connected.
Returns: success, scope, and data (a list).
my_transactions is your account
The driver's one account on ev.energy for a time window: what they earned, what they spent, what smart charging saved them, the energy they charged, what is still pending, and the items behind every figure. One call, one shape:
{
"balance": null,
"earned": {"value": 2600, "currency": "GBP"},
"spent": {"value": 1550, "currency": "GBP"},
"saved": {"value": 700, "currency": "GBP"},
"energy": {"kwh": 46.5},
"pending": {"earned": null, "spent": {"value": 4000, "currency": "GBP"}},
"items": [
{"date": "2026-09-20T18:00:00Z", "status": "settled", "kind": "session",
"where": "Instavolt, Reading services", "kwh": 21.5,
"amount": {"value": -940, "currency": "GBP"}, "funded_by": "card", "card": "Visa ending 4242",
"charge": "EVE-01J9ZCF7Q1V8X3K2M4N6P8R0ST", "invoice": "EVEGB-0001043", "credit_notes": [],
"invoice_url": "/connect/invoices/EVEGB-0001043"},
{"date": "2026-09-01T10:00:00Z", "status": "settled", "kind": "session", "where": "Home",
"kwh": 9.0, "amount": null, "saved": {"value": 500, "currency": "GBP"}}
],
"window": {"name": "last_30_days", "start": "...", "end": "...", "timezone": "Europe/London", "sessions": 12},
"notes": ["Your balance isn't available yet."],
"locale": {"locale": "en-GB", "timezone": "Europe/London", "currency": "GBP", "country": "GB", "source": "profile"}
}
A public charging session you paid has its VAT invoice. invoice is its number and credit_notes the numbers of any credit notes against it (a correction of the charge's price, VAT rate or energy: when the price falls, or when the invoice is credited whole and issued afresh; each note gives the date of the invoice it credits); invoice_url opens the invoice on your ev.energy account, to view and print or save as a PDF. A session your workspace paid has none: it says who paid (paid_by).
Money is one format everywhere: {value, currency}, value an integer in minor units (pence, cents). The totals — earned, spent, saved, pending.* — are positive amounts. Only an item's amount carries a sign, like a bank statement: money in is +, money out is -.
locale is the driver's own — their language (BCP 47), timezone (IANA) and home currency (ISO 4217), from the country on their ev.energy home address (the UK's when the country is unknown or unsupported). my_account returns the same object as data.locale. Write amounts and dates the way it says; an amount that names its own currency keeps it.
balanceisnullwith the note "Your balance isn't available yet" until the earnings balance and payouts can be read. It is never a guessed figure.earnedis the rewards settled in the window: charging incentives plus rebates paid to the account.spentis the public charging the driver paid for through their ev.energy account, settled in the window. Sessions their organisation paid for are items at0and never inspent.savedis what smart charging saved at home against a standard tariff.energy.kwhis home plus public charging. A public session whose kWh wasn't reported haskwh: null, is left out of the total (never counted as 0), and is counted inenergy.sessions_without_kwh.pending.earnedisnullwhen a reward is pending with no amount yet (a note says so) — different from having earned nothing.pending.spentis public charging still in progress.itemsare the lines behind the figures, newest first:date,status(settled/pending),kind(session/reward/payment/refund/written_off/adjustment/other),where("Home", the charging network and site, or "Public charging"),kwhon sessions, andamount. A home session'samountisnull— it's paid to the driver's energy supplier, not this account — and it carriessavedinstead. A public item carriesfunded_byand the card by its masked name only ("Visa ending 4242"); a split payment is one item with itspartsinside. A public charging item about a charge carries itscharge(EVE-…), the reference to quote to support about it. Settled public lines fall in the window their session ended in. Awritten_offitem is a debt ev.energy wrote off, never a payment the driver made, and itsnotesays so; anadjustmentreverses an earlier payment or write-off; anotheritem is an entry the account doesn't recognise yet, shown with a neutralnoteand never as a payment.
The account's only filter is the time window (view="sessions" adds state and after; view="invoices" adds after). window.sessions counts every charging session in it; on a programme window window.program names the programme and window.qualifying_sessions says how many of those sessions qualify under its published rules, or window.qualifying_note says why it can't be counted. A part that can't be read — the charging history, rewards, or public charging — is null with a note in notes, never an error and never a 0.
| Parameter | Type | Required | Description |
|---|---|---|---|
window | string | no | Friendly window, defaults to last_30_days. Rolling spans: last_7_days, last_week, last_30_days, last_month (30 days), last_90_days, last_year. Named months: this_month, last_calendar_month — use these for "in August" or "last month", which a rolling span answers over the wrong period. Programme: current_program (aliases since_joining, this_program) measures from the day the driver joined their current programme, and answers window.available: false when they are on none. all_time for whole-history questions (slower — reads every session). Bounds are resolved in the driver's own timezone (locale.timezone), so a named month is that month where they live, not the UTC month. |
period | string | no | A calendar month, YYYY-MM, instead of window. |
start_date | string | no | From this date, YYYY-MM-DD, instead of window. |
end_date | string | no | To this date inclusive, YYYY-MM-DD. |
provider | string | no | Defaults to ev.energy. |
view | string | no | account (the default), sessions or invoices (below). |
state | string | no | view="sessions" only: authorised, started, completed, awaiting_bill, settled or released. |
after | string | no | view="sessions" or view="invoices": the next the previous page returned. |
Returns: success and data ({balance, earned, spent, saved, energy, pending, items, window, notes}).
view="sessions" lists every public charging session instead, on every account the driver has, newest opened first, one row per charge: its id (EVE-…), state (authorised, started, completed, awaiting_bill, settled, released) and status (authorised, plugged_in, charging, no_recent_update, ended, billed, nothing_charged), which text.state says in words ("Charging", "Plugged in. Latest information from the charger: 22:10", "Ended, waiting for the final price"), held, opened_at / started_at / ended_at, where, payer and paid_from, price (net, vat, gross and the VAT rate, null until priced), collected, written_off (what ev.energy wrote off on it) and owed (per currency), place (where it ran, as OCPI keys it: country_code, party_id, location_id, evse_uid, connector_id), energy_kwh (the kWh its bill states), hold (what is held for it, and its status; null when nothing was), so_far (while it is not priced, the kWh and cost the charge point has reported so far, never a price: said as "still running" while the session may run, and as "before its bill" once it has ended), paid_by (you, or the name of the workspace that paid, never its key), invoice_url when it has a VAT invoice, and text with each said in the driver's locale (text.line is the whole row in one line). The window bounds when each session opened; state narrows it and after pages it (next). A row never names the card's chip, the bill, the workspace's key or the partner. Returns: data ({view, available, sessions, complete, next, as_of, window, locale}), or available: false with a note when public charging can't be read.
view="invoices" lists the driver's VAT invoices and credit notes instead, as one list, newest issued first: each has kind (invoice or credit_note), number, issued_at, amount and display (amount, issued, and for a credited invoice total_after_credits, in the driver's currency, locale and timezone). An invoice carries invoice_url, its credit notes and, once credited, total_after_credits; a credit note names the invoice it credits and that invoice's invoice_url. With no window it covers the last 30 days, like the account; window="all_time", a period or dates widen it, and the window bounds each by its date of issue (after its start, up to and including its end). count (invoices, credit_notes, and more when next has further pages) counts each answer's own documents, and on the first answer display.summary ("2 invoices and 1 credit note", "at least 20 invoices") says how many; a window with none says so in note, offering to look further back, and one that could not be read in full says it can't say there are none. A document whose date can't be read is listed only under all_time; under any other window it is left out and complete is false. One after pages the whole list (next). all_invoices_url is /connect/public-charging?payer=you, Public charging on the account page showing the sessions you paid, and chat and web voice draw a "My invoices" button to it. Returns: data ({view, available, documents, count, display, complete, next, all_invoices_url, window, locale}), or available: false with a note when the invoices can't be read, never an empty list in its place.
Every verb is live today except device control
| Verb | Group | Write? | Status |
|---|---|---|---|
my_account | Info | read | live |
discover | Info | read | live |
my_transactions | Info | read | live (earned, spent, saved, energy, pending and the items behind them, home and public charging on ev.energy cards; balance not available yet; view="sessions", every public charging session and its status; view="invoices", every VAT invoice and credit note) |
connect_device | Devices | write | live (OEM auth handoff, vehicles only) |
update_device | Devices | write | live (charge limit only) |
remove_device | Devices | write | live (vehicle or charger) |
update_account | Account | write | live (address + tariff + payout) |
join_program | Programmes | write | live (join + verification resume) |
leave_program | Programmes | write | live |
refer_friend | Referrals | read | live (returns a link, sends no email) |
activate_charging_card | Cards | write | live (in the call on first-party chat and voice; hands off to the activate page on MCP / A2A) |
add_payment_card | Cards | read | live (returns the secure add-card page; takes no card data) |
update_card | Cards | write | live (default for both kinds; freeze / unfreeze charging cards) |
remove_card | Cards | write | live (remove, or report a charging card lost; hands off on MCP / A2A) |
my_notifications | Notifications | write (marks read) | live (your notifications; showing them marks them read unless peek) |
control | Charging control | write | coming soon, waiting on an ev.energy device-control action |
The fifteen verbs reach every surface from one registry. Hosted chat, voice and /connect/mcp all dispatch this same registry against the same backend, so a verb behaves identically everywhere. Two exceptions to the list itself: voice leaves out update_device and adds its own offer_sign_in, so a call sees 15 tools; and the four card verbs and my_notifications are listed only while the card service is configured. What differs is the instructions wrapped around it: chat loads Eve's full prompt plus a lifecycle overlay, voice loads the prompt plus a voice transport delta, and MCP publishes the prompt as server instructions (which a client may or may not honour). Any behaviour that must hold everywhere therefore belongs in the verb's own result, not in prose.