# API (Immortal Only)

The Delphi API lets you integrate your Digital Mind directly into your own app, platform, or workflow. You have control to the full experience — create conversations, stream responses, manage tags, and track usage through simple HTTP requests.

**Base URL:** `https://api.delphi.ai`

**Current version:** v3

## Getting started

{% stepper %}
{% step %}

### Get an API key

API access is available on the **Immortal** plan. To get started, reach out to your Delphi contact or email **<support@delphi.ai>**.

> **Important:** Store your key securely. It is only shown once and cannot be retrieved later.
> {% endstep %}

{% step %}

### Authenticate

Include your API key in the `x-api-key` header on every request:

```bash
curl https://api.delphi.ai/v3/conversation/list?email=user@example.com \
  -H "x-api-key: YOUR_API_KEY"
```

{% endstep %}

{% step %}

### Start a conversation

```bash
curl -X POST https://api.delphi.ai/v3/conversation \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"user_email": "user@example.com"}'
```

This returns a `conversation_id` and the clone's initial greeting.
{% endstep %}
{% endstepper %}

## Authentication

All endpoints require an API key passed in the `x-api-key` header. The key is scoped to a single clone — you can only interact with conversations and users belonging to that clone.

| Header      | Value        |
| ----------- | ------------ |
| `x-api-key` | Your API key |

## Rate limits

* **120 requests** per **60 seconds** per API key
* Rate limiting is applied across all endpoints
* If you exceed the limit, you'll receive a `429 Too Many Requests` response

## Available endpoints

* [**Audience**](https://docs.delphi.ai/advanced/api-immortal-only/audience) - Store and manage contextual information about users in your audience.
* [**Conversations**](https://docs.delphi.ai/advanced/api-immortal-only/conversations) — Create conversations, stream responses, view history, and manage conversation lifecycle.
* [**Clone**](https://docs.delphi.ai/advanced/api-immortal-only/clone) - Retrieve your clone's public profile information.
* [**Questions**](https://docs.delphi.ai/advanced/api-immortal-only/questions) — Retrieve suggested questions configured for your clone.
* [**Tags**](https://docs.delphi.ai/advanced/api-immortal-only/tags) — Create tags and organize your audience.
* [**Usage**](https://docs.delphi.ai/advanced/api-immortal-only/usage) — Track consumption metrics and access tiers for your users.
* [**Voice**](https://docs.delphi.ai/advanced/api-immortal-only/voice) — Stream voice responses as real-time PCM audio.