> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ev-cloud.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ev-cloud.ai/_mcp/server.

# Introduction

## Installation

You can call the API over HTTP from any language, or use the official TypeScript and Python SDKs or the CLI.

To install the TypeScript SDK, run the following command in your Node.js project:

```bash
npm i evcloud-sdk
```

To install the Python SDK:

```bash
pip install evcloud-sdk
```

To install the CLI:

```bash
npm i -g @evcloud/cli
```

## Base URL

The production API is `https://api.ev-cloud.ai`, and the paths in this reference are relative to it. Pass it, or another EV Cloud host, as `environment` (TypeScript), `base_url` (Python) or `--base-url` / `EVCLOUD_CLI_BASE_URL` (CLI).

## Authentication

Every request carries a bearer token that expires:

```http
Authorization: Bearer <token>
```

**`TypeScript`**

```typescript TypeScript
import { EvcloudSDK } from "evcloud-sdk";

const client = new EvcloudSDK({
    environment: "https://api.ev-cloud.ai",
    token: process.env.EVCLOUD_TOKEN!,
});
```

**`Python`**

```python Python
import os
from evcloud_sdk import EvcloudSDK

client = EvcloudSDK(
    base_url="https://api.ev-cloud.ai",
    token=os.environ["EVCLOUD_TOKEN"],
)
```

**`cURL`**

```bash cURL
curl https://api.ev-cloud.ai/cpo/locations \
  -H "Authorization: Bearer $EVCLOUD_TOKEN"
```

Every result is scoped to the token's organization. See [Authentication](/get-started/authentication) for SDK tokens and browser sign-in.

## Domains

| Domain   | SDK namespace     | REST prefix          |
| -------- | ----------------- | -------------------- |
| CPO      | `client.cpo`      | `/cpo`               |
| eMSP     | `client.emsp`     | `/emsp`              |
| Energy   | `client.energy`   | `/energy-management` |
| Webhooks | `client.webhooks` | `/webhook-gateway`   |
| OCPI     | `client.ocpi`     | `/ocpi`              |

## Errors and retries

A `4xx` or `5xx` response raises an error with the status code and the response body. The SDKs retry `408`, `429` and `5xx` responses up to 2 times, but send a `POST` that could act twice only once. See [Errors and retries](/sdks/errors-and-retries).