Skip to main content

Getting Started with the Chat API

Prerequisites​

  • An active Zeta Alpha account with API access
  • An API key with the necessary permissions

Base URLs:

EndpointURL
Streaming (SSE)https://api.zeta-alpha.com/v0/service/chat/stream
Non-streaming (REST)https://api.zeta-alpha.com/v0/service/chat/response
Self-hosted deployments

If your organization runs a self-hosted Zeta Alpha instance, replace api.zeta-alpha.com with your deployment's domain — e.g. https://api.<your-domain>/v0/service/chat/stream.

The full Chat API specification is available at api.zeta-alpha.com/v0/docs/#tag/chat.

Overview​

The Chat API exposes configurable agents that combine LLM reasoning with a composable set of capabilities — search and retrieval, web browsing, data analysis, persistent memory, skill-based workflows, delegation to specialist agents, and connections to external tools via MCP. Each agent is assembled from these capabilities through configuration (and possibly custom code). Agents are configured per tenant — contact the Zeta Alpha support team to select or customize agents for your use case, or build your own following the Configure Agents guide.

Authentication​

All requests require an API key passed via the X-Auth header:

X-Auth: your-api-key

Alternatively, use a Bearer token via the Authorization header.

Quickstart: Streaming​

pip install requests sseclient-py
import json
import os

import requests
import sseclient

TENANT = "zetaalpha"
CHAT_STREAMING_ENDPOINT = (
    f"https://api.zeta-alpha.com/v0/service/chat/stream?tenant={TENANT}"
)

headers = {
    "accept": "text/event-stream",
    "Content-Type": "application/json",
    "X-Auth": os.getenv("ZETA_ALPHA_API_KEY"),
}

response = requests.post(
    CHAT_STREAMING_ENDPOINT,
    headers=headers,
    json={
        "agent_identifier": "chat_with_dynamic_retrieval",
        "conversation": [
            {"sender": "user", "content": "What is BERT?"}
        ],
    },
    stream=True,
)
response.raise_for_status()

client = sseclient.SSEClient(response)
for event in client.events():
    message = json.loads(event.data)
    # Each event contains the full message so far
    print(message["content"])

Each SSE event carries a complete ChatMessage — as tokens are generated, the content field grows. The final event contains the complete response with evidences and content_parts. See Streaming for details on the protocol, reconnection, and cancellation.

Quickstart: Non-Streaming​

pip install requests
import os

import requests

TENANT = "zetaalpha"
CHAT_REST_ENDPOINT = (
    f"https://api.zeta-alpha.com/v0/service/chat/response?tenant={TENANT}"
)

headers = {
    "accept": "application/json",
    "Content-Type": "application/json",
    "X-Auth": os.getenv("ZETA_ALPHA_API_KEY"),
}

response = requests.post(
    CHAT_REST_ENDPOINT,
    headers=headers,
    json={
        "agent_identifier": "chat_with_dynamic_retrieval",
        "conversation": [
            {"sender": "user", "content": "What is BERT?"}
        ],
    },
)
response.raise_for_status()

data = response.json()
agent_message = data["conversation"][-1]

print(agent_message["content"])
print(agent_message["evidences"])

The non-streaming endpoint returns a ChatResponseItem containing the full conversation (including the agent's response appended as the last message).

Response Structure​

The agent's response message contains:

FieldDescription
contentThe generated text response
content_partsStructured parts: text, context found, tool calls, tables
evidencesCitations linking answer spans to source documents
message_idUnique identifier for this message (used for feedback)

See API Reference for the full schema, Handling Citations for evidence parsing, and Content Parts for rendering tool and context parts.

Next Steps​