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:

X-API-Key: sk_live_...

To create and manage your API keys, read our complete guide on API Key Management, or generate a secret key directly in your dashboard under API Keys.

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 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) 

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:

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:

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