# API Reference

Integrate AIsh.li agents, real-time streaming conversations, and conversational forms directly into your backends, mobile apps, or custom frontends.

All platform features accessible through the AIsh.li web portal are powered by our open, OpenAPI-documented REST API.

## Authentication

Every API request requires an authorized API Key passed via the `X-API-Key` request header:

```http
X-API-Key: sk_live_...
```

To create and manage your API keys, read our complete guide on **[API Key Management](api-key.md)**, or generate a secret key directly in your dashboard under **[API Keys](/keys/api)**.

> [!CAUTION]
> Always treat your API keys as confidential secrets. Never expose them in public GitHub repositories or client-side frontend code. For public website integrations, use our secure [Embeddable Chat Widget](widget.md) with domain whitelisting instead.

## Key Endpoints

| Endpoint               | Method | Description                                                                       |
| :--------------------- | :----- | :-------------------------------------------------------------------------------- |
| `/v1/responses`        | `POST` | Execute an agent turn with optional real-time Server-Sent Events (SSE) streaming. |
| `/v1/ai/agents`        | `GET`  | List all available demo and user-configured AI agents.                            |
| `/v1/ai/agents/{id}`   | `GET`  | Retrieve an agent's configuration, prompt, and tool settings.                     |
| `/v1/form`             | `POST` | Initialize a conversational form session and progressively validate fields.       |
| `/v1/form/{sessionId}` | `POST` | Submit the next user turn into an active form session.                            |

## Quickstart: Streaming Agent Chat

You can invoke any configured agent using standard HTTP clients (such as `curl`, Node.js `fetch`, Python `requests`, or the Vercel AI SDK).

### Request Example (cURL)

```bash
curl -N -X POST 'https://api.aish.li/v1/responses' \
  -H 'X-API-Key: sk_live_...' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{
    "model": "demo/gemini",
    "stream": true,
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": "What are three fun facts about Switzerland?"
      }
    ]
  }'
```

### Response Stream (SSE)

The server streams Server-Sent Events in real time:

```text
data: {"type":"response.text.delta","delta":"1. Switzerland has over 1,500 lakes..."}

data: {"type":"response.text.delta","delta":"\n2. It has four official national languages..."}

data: {"type":"response.text.delta","delta":"\n3. CERN's Large Hadron Collider is located here..."}

data: {"type":"response.completed","usage":{"input_tokens":18,"output_tokens":72}}
```

## Conversational Forms API

If you are building structured intake flows (such as customer onboarding, booking reservations, or lead generation), use our dedicated **[Forms API](form-api.md)**:

```bash
curl -X POST 'https://api.aish.li/v1/form?agent=demo%2Ftransport' \
  -H 'X-API-Key: sk_live_...' \
  -d 'John Doe, traveling from Paris to Rome tomorrow' \
  | jq .
```

The endpoint returns the updated form state, indicating which fields were recognized and what question the agent recommends asking next.

## Interactive API Explorer

You can test every endpoint directly inside your browser using our Swagger-powered OpenAPI explorer:

👉 **Open the [Interactive API Reference](/docs/api)**