API Reference

Interact with your EchoSDK agent programmatically using our REST API.

Authentication

We support two methods of authentication depending on the endpoint and use case:

API Key: Used for backend/admin operations like ingestion. Passed via X-API-Key header. Keys use the format echo_ followed by 32 alphanumeric characters.
Origin Verification: Used for public frontend queries. Configure allowed domains in your dashboard.
Firebase Bearer Token: Used for dashboard and admin operations. Passed via Authorization: Bearer header.

Rate Limits

All endpoints are rate-limited per IP address and per app to ensure fair usage:

Endpoint	Per IP	Per App
/query	60 requests / minute	1,000 requests / hour
/ingest	10 requests / minute	100 requests / hour

When rate-limited, you will receive a 429 status with a Retry-After header.

POST

/api/:appId/ingest

Ingest content into your agent's knowledge base. This endpoint accepts either a URL to crawl or raw text. Content is automatically chunked (1,000 chars with 200-char overlap), embedded, and stored for RAG queries.

Requires an Admin API Key or Firebase Bearer Token (app owner).

Request Body

textThe raw text content to ingest, max 100KB (required if url not provided).

urlA URL to crawl. HTML will be extracted and converted to text (required if text not provided).

Response (200)

successtrue

chunksProcessedNumber of chunks successfully embedded and stored.

chunksFailedNumber of chunks that failed during embedding.

sourceIdUnique identifier for the ingested source.

Example Request

curl -X POST https://echosdk.com/api/your-app-id/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: echo_your32charalphanumerickey0123" \
  -d '{
    "text": "EchoSDK is a headless support platform...",
    "url": "https://docs.echosdk.com/intro"
  }'

Example Response

{
  "success": true,
  "chunksProcessed": 42,
  "chunksFailed": 0,
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

POST

/api/:appId/query

Ask a question to your agent. Returns a streamed text/plain response for web widget usage. The response is generated using RAG over your ingested knowledge base.

Publicly accessible (protected by CORS whitelist or Firebase Bearer Token).

Request Body

questionThe user's question to answer (required, max 500 characters).

appIdYour app ID (optional if provided in URL path).

Response

The response is streamed as text/plain with Transfer-Encoding: chunked. Source documents referenced in the answer are returned via the x-echo-sources response header as a JSON array.

Example Request

curl -X POST https://echosdk.com/api/your-app-id/query \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I install the SDK?"
  }'

POST

/api/handover

Escalate a conversation to human support. Creates a support ticket in your dashboard and sends notifications via configured integrations (Slack, email).

Publicly accessible (protected by CORS whitelist).

Request Body

appIdYour app ID (required).

emailUser's email address for follow-up (required).

questionThe user's question or issue description (required).

urlThe page URL where the request originated (optional).

historyArray of previous conversation messages for context (optional).

Response (200)

successtrue

ticketIdThe ID of the created support ticket.

Example Request

curl -X POST https://echosdk.com/api/handover \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "your-app-id",
    "email": "user@example.com",
    "question": "I need help with billing",
    "url": "https://myapp.com/pricing",
    "history": [
      { "role": "user", "text": "How much does the pro plan cost?" },
      { "role": "assistant", "text": "The pro plan is $49/month." }
    ]
  }'

Example Response

{
  "success": true,
  "ticketId": "abc123def456"
}

DELETE

/api/apps/sources

Delete a source and all its associated chunks from your agent's knowledge base.

Requires a Firebase Bearer Token (app owner only).

Query Parameters

appIdYour app ID (required).

idThe ID of the source to delete (required).

Response (200)

successtrue

Example Request

curl -X DELETE "https://echosdk.com/api/apps/sources?appId=your-app-id&id=source-id-here" \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN"

Example Response

{
  "success": true
}