> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargerdojo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Automate ChargerDojo with an API key: partner endpoints, conformance runs, charging journeys, and the graded reports and usage they produce.

ChargerDojo has one public API. It is the HTTP surface you automate with an
**API key** against the deployed service:

```text theme={null}
https://chargerdojo.com
```

All operations live under `/api/v1` and authenticate with a Bearer API key that starts
with `cdojo_`. There is no other supported base URL and no environment selector.

Operation reference: [`GET /connections`](https://docs.chargerdojo.com/api-reference/connections/list-owned-connections).

```bash theme={null}
curl -fsS "https://chargerdojo.com/api/v1/connections" \
  -H "Authorization: Bearer $DOJO_KEY"
```

## What you can automate

| Area | Operations |
| - | - |
| Connections | Create a partner endpoint, register it (the live OCPI credentials handshake), list and read your endpoints. |
| Suites | List the conformance suites available to run. |
| Conformance runs | Start a run, wait for or poll it, list runs, read the full report, delete a run, mint a share link. |
| Manual command | Send one bounded OCPI request through a registered connection and get the exact exchange back. |
| Charging journeys | Browse the catalogue, preview a plan, start a run idempotently, stream its events, cancel it, and resolve a recovery decision. |
| Usage | Read your plan tier, current usage and ceilings. |

Only the operations in the API reference section of this site are public API. Everything
else the application does (the interactive simulator, entity editing, account and
key management) is browser functionality, not part of this contract.

## Operation reference

| Method and path | Operation |
| - | - |
| `POST /connections` | [Create a partner endpoint](https://docs.chargerdojo.com/api-reference/connections/create-a-partner-endpoint.md) |
| `GET /connections` | [List owned connections](https://docs.chargerdojo.com/api-reference/connections/list-owned-connections.md) |
| `POST /connections/{id}/register` | [Run the OCPI credentials handshake for an owned connection](https://docs.chargerdojo.com/api-reference/connections/run-the-ocpi-credentials-handshake-for-an-owned-connection.md) |
| `PUT /connections/{id}/address` | [Change a connection's address](https://docs.chargerdojo.com/api-reference/connections/change-a-connections-address.md) |
| `GET /connections/{id}` | [Read one owned connection](https://docs.chargerdojo.com/api-reference/connections/read-one-owned-connection.md) |
| `GET /connections/{id}/schedule` | [Read the run schedule of an owned connection](https://docs.chargerdojo.com/api-reference/connections/read-the-run-schedule-of-an-owned-connection.md) |
| `GET /testing/suites` | [List runnable conformance suites](https://docs.chargerdojo.com/api-reference/testing/list-runnable-conformance-suites.md) |
| `POST /testing/runs` | [Start a conformance run against an owned connection](https://docs.chargerdojo.com/api-reference/testing/start-a-conformance-run-against-an-owned-connection.md) |
| `GET /testing/runs` | [List owned run reports (conformance and journeys)](https://docs.chargerdojo.com/api-reference/reports/list-owned-run-reports-conformance-and-journeys.md) |
| `GET /testing/runs/{id}` | [Read one owned report, optionally long-polling an active run](https://docs.chargerdojo.com/api-reference/reports/read-one-owned-report-optionally-long-polling-an-active-run.md) |
| `DELETE /testing/runs/{id}` | [Delete a report you own](https://docs.chargerdojo.com/api-reference/reports/delete-a-report-you-own.md) |
| `GET /testing/runs/{id}/regression-diff` | [Compare an owned run with its previous comparable run](https://docs.chargerdojo.com/api-reference/reports/compare-an-owned-run-with-its-previous-comparable-run.md) |
| `DELETE /testing/runs/{id}/share` | [Revoke the public share token of an owned report](https://docs.chargerdojo.com/api-reference/reports/revoke-the-public-share-token-of-an-owned-report.md) |
| `POST /testing/runs/{id}/share` | [Issue a public share token for an owned report](https://docs.chargerdojo.com/api-reference/reports/issue-a-public-share-token-for-an-owned-report.md) |
| `POST /testing/command` | [Send one bounded OCPI command through an owned registered connection](https://docs.chargerdojo.com/api-reference/testing/send-one-bounded-ocpi-command-through-an-owned-registered-connection.md) |
| `GET /usage` | [Read the key owner's plan limits and current usage](https://docs.chargerdojo.com/api-reference/usage/read-the-key-owners-plan-limits-and-current-usage.md) |
| `GET /testing/journeys` | [Browse the journey catalogue for a target](https://docs.chargerdojo.com/api-reference/journeys/browse-the-journey-catalogue-for-a-target.md) |
| `POST /testing/journeys/preview` | [Preview a journey plan before running it](https://docs.chargerdojo.com/api-reference/journeys/preview-a-journey-plan-before-running-it.md) |
| `POST /testing/journey-runs` | [Start a journey run from a previewed plan (idempotent)](https://docs.chargerdojo.com/api-reference/journeys/start-a-journey-run-from-a-previewed-plan-idempotent.md) |
| `GET /testing/journey-runs/{id}` | [Read a journey run's status and recovery options](https://docs.chargerdojo.com/api-reference/journeys/read-a-journey-runs-status-and-recovery-options.md) |
| `POST /testing/journey-runs/{id}/cancel` | [Cancel a journey run you own](https://docs.chargerdojo.com/api-reference/journeys/cancel-a-journey-run-you-own.md) |
| `POST /testing/journey-runs/{id}/recovery` | [Apply a server-offered recovery decision](https://docs.chargerdojo.com/api-reference/journeys/apply-a-server-offered-recovery-decision.md) |
| `GET /testing/journey-runs/{id}/events` | [Page a journey run's events by sequence](https://docs.chargerdojo.com/api-reference/journeys/page-a-journey-runs-events-by-sequence.md) |
| `GET /testing/journey-runs/{id}/stream` | [Replay then follow run events over SSE](https://docs.chargerdojo.com/api-reference/journeys/replay-then-follow-run-events-over-sse.md) |

Each operation page includes its request, response and error statuses. API-key creation and inbound-token revocation remain app actions; they are outside this public API.

## Authentication

Every request sends the key in the `Authorization` header:

```text theme={null}
Authorization: Bearer $DOJO_KEY
```

API keys are created and revoked in the app, in **Settings, then Credentials**, and require
a paid plan. There is no API for managing keys: a key cannot mint, list or revoke other
keys. See [Create an API key](https://docs.chargerdojo.com/guide/create-an-api-key.md).

## Response envelope

Every response is JSON, except the journey event stream, which is `text/event-stream`.
Successes wrap their payload:

```json theme={null}
{ "success": true, "data": {} }
```

Errors carry an HTTP 4xx or 5xx status and a message:

```json theme={null}
{ "success": false, "message": "Report not found" }
```

Two statuses deserve a special mention because CI scripts get them wrong:

* A `202` means the work was accepted and is **still going**. It is not a success verdict
  and not a failure. Poll or wait for the result instead of gating on it.
* A `503` on a charging journey start means **our runner is unavailable**. It is a statement
  about our service, never a verdict about your partner's implementation.

The full status-code table is in [Troubleshooting](https://docs.chargerdojo.com/guide/troubleshooting.md).

## Limits and usage

Plans set ceilings on runs per minute and in flight, and on the connections every self-serve
tier buys. Report retention differs between free and paid. Each organisation shares a cap of 10
active keys across its members, on every plan. Read your own numbers instead of hardcoding them:

Operation reference: [`GET /usage`](https://docs.chargerdojo.com/api-reference/usage/read-the-key-owners-plan-limits-and-current-usage).

```bash theme={null}
curl -fsS "https://chargerdojo.com/api/v1/usage" \
  -H "Authorization: Bearer $DOJO_KEY" | jq '.data'
```

The response reports your tier, active connections against their cap, active keys against
their cap, in-flight and per-minute run ceilings, and your report retention window.
`connections.cap` comes back `null` on a plan priced on a quote, where connections are fair use
rather than a rung you are sold. Read that absence as no published ceiling, never as zero.
A run over its rate or in-flight ceiling returns `429` with a `Retry-After` header. A resource cap
never does, because waiting will not help. The connection cap answers `402` where your plan
publishes a rung, carrying `limit` with what you hold and what the plan allows, so free a slot or
move up. The active-key cap answers `409`, and so does the connection cap on a plan priced on a
quote, where there is no rung to move to. An
in-flight charging journey holds one run slot until it reaches a terminal state, and a
run waiting on a recovery decision keeps holding its slot until you decide.

## Where to go next

> [card] [Create an API key](https://docs.chargerdojo.com/guide/create-an-api-key.md)
>
> Sign in, create the key in Settings, store it once.

> [card] [Quickstart](https://docs.chargerdojo.com/guide/quickstart.md)
>
> A complete conformance run from the command line.

> [card] [Connect a partner](https://docs.chargerdojo.com/guide/connect-a-partner.md)
>
> Register a real partner endpoint and run against it.

> [card] [Run a charging journey](https://docs.chargerdojo.com/guide/run-a-charging-journey.md)
>
> Drive a full charging story and watch it live.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.