APIs

Public Chat API

The Public Chat API allows unauthenticated chat with a published agent. It is intended for public browser experiences and embeds. Configured allowed origins control which browser origins receive CORS access.

Hosted Chat Availability & Branding Endpoint

The KriyaOS hosted chat client uses this endpoint to resolve hosted-chat availability and load agent and workspace branding. It returns 404 unless the agent is published, Public Chat is enabled, and Hosted Chat is enabled.

HTTP Request

GET /api/public/chat/availability

Query Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Unique ID of the workspace.
agentId	string	Yes	Unique ID of the agent.

Example Response (Success)

{
  "available": true,
  "agent": {
    "name": "Support Agent",
    "description": "Answers questions about pricing and services.",
    "imageUrl": "https://example.com/avatar.png"
  },
  "brand": {
    "displayName": "NexTribes Support",
    "tagline": "We respond within minutes",
    "logoUrl": "https://example.com/logo.png",
    "primaryColor": "#2563eb",
    "buttonColor": "#1d4ed8",
    "accentColor": "#60a5fa",
    "websiteUrl": "https://nextribes.com",
    "phone": "+1 (555) 019-2834",
    "address": "123 Agent Way, Suite 100",
    "coverImageUrls": [
      "https://example.com/cover.jpg"
    ]
  }
}

---

Chat Endpoint

Send a message sequence to the published agent to get a generated response, optionally streamed back token-by-token.

HTTP Request

POST /api/public/chat

Query Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Unique ID of the workspace.
agentId	string	Yes	Unique ID of the agent.
stream	string	No	Set to "true" to receive a Server-Sent Events (SSE) streaming response.

Request Headers

• Content-Type: application/json
• Origin: <origin> (Subject to CORS checks)

Request Body Schema

{
  "id": "optional-session-id",
  "countryCode": "US",
  "messages": [
    {
      "id": "optional-message-id",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Hello! What is your pricing?"
        }
      ]
    }
  ]
}

countryCode is optional. Use US, CA, GB, or IN when Product Catalog should use configured country-specific pricing. Use ALL, or any other two-letter value, to fall back to global pricing.

Validation Limits (Caps)

To prevent abuse and control token costs, the public chat endpoint enforces the following limits:

• Maximum Messages: A maximum of 8 messages is allowed per request.
• Maximum Parts: A message cannot exceed 16 parts.
• Maximum Characters: The cumulative length of all text parts across all messages in the request cannot exceed 8,000 characters.

If a request violates any of these, the API returns a 400 Bad Request validation error.

---

Browser Origin Rules (CORS)

If the agent's Public Chat integration is configured with allowed origins:

1. Requests coming from other browser origins are blocked.
2. During local development, the local hosted chat origin defaults to http://localhost:3002.
3. Allowed origins can be configured with or without subdomain matching (e.g. allowing *.example.com).

Important

Allowed origins control browser access through CORS; they do not authenticate server or non-browser requests. Use Secure Chat for private or authenticated integrations.

---

Code Examples

Fetching Availability

const query = new URLSearchParams({
  workspaceId: "ws_12345",
  agentId: "agent_67890"
});

fetch(`/api/public/chat/availability?${query}`)
  .then(res => res.json())
  .then(data => console.log("Availability:", data));

Sending a Non-Streaming Message

const query = new URLSearchParams({
  workspaceId: "ws_12345",
  agentId: "agent_67890"
});

fetch(`/api/public/chat?${query}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    messages: [
      {
        role: "user",
        parts: [{ type: "text", text: "What is KriyaOS?" }]
      }
    ]
  })
})
  .then(res => res.json())
  .then(data => console.log("Response:", data));

Continue Reading

Public Chat Integration

Enable public chat and configure origins and hosted chat.

Streaming and Errors

Learn how the streaming response is structured and how errors appear.