APIs
API Integration Quickstart
Use this guide to choose the correct chat surface, prepare the agent, and make your first request.
Choose an API
| Caller | Use | Authentication |
|---|---|---|
| Public website or browser embed | Public Chat API | No API key; browser CORS policy can restrict approved origins |
| Backend, automation, or internal system | Secure Chat API | Workspace API key in a Bearer authorization header |
| Shareable KriyaOS-hosted page | Hosted Chat | No custom API integration required |
Use Secure Chat for Private Integrations
CORS is enforced by browsers. It does not authenticate requests from servers or other non-browser clients. Use Secure Chat when the caller or conversation must be authenticated.
Prepare the Agent
Before calling either API:
- Configure prompts, knowledge, and required Kriyas.
- Test the draft in the Playground.
- Publish the agent.
- Enable the matching Public Chat or Secure Chat integration.
- Copy the workspace ID and agent ID.
- For Secure Chat, create a workspace API key and store it only on the server.
Make a Secure Chat Request
curl -X POST "https://api.kriyaos.com/api/secure/chat?workspaceId=WORKSPACE_ID&agentId=AGENT_ID" \
-H "Authorization: Bearer $KRIYAOS_WORKSPACE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{
"role": "user",
"parts": [{ "type": "text", "text": "What can you help me with?" }]
}
]
}'
The response contains the assistant message, optional session ID, finish reason, and retrieved knowledge metadata.
Continue a Conversation
When a response includes session.id, send it as the next request body's id.
The published agent's memory settings determine whether the session is persisted.
Add Streaming
Append &stream=true to either chat endpoint to receive the Vercel AI SDK UI
message stream over SSE. Streaming responses can include tool-activity events
when the agent invokes a Kriya or MCP tool.