REST API Reference

The Uchara REST API is versioned under /v1. All endpoints return JSON using a standard envelope. The base URL is https://api.uchara.com.

Base URL

https://api.uchara.com/v1

Authentication

There are three authentication methods, each scoped to a different SDK type.

1. Widget token → visitor JWT (Visitor SDK)

The widget token is public and safe to embed in client-side code. Exchange it for a short-lived visitor JWT:

POST /v1/widget/session

{
  "widget_token": "wgt_abc123",
  "external_id": "user_123",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+6281234567890"
}

Response:

{
  "ok": true,
  "request_id": "req_...",
  "timestamp": "2024-01-01T00:00:00.000000Z",
  "data": {
    "visitor_token": "eyJ...",
    "contact_id": "ct_...",
    "channel_name": "Support",
    "widget_config": {}
  }
}

The returned visitor_token is sent as Authorization: Bearer <token> on subsequent widget calls and as the token query parameter on the WebSocket.

2. Email/password → JWT (Agent SDK)

POST /v1/auth/login
POST /v1/auth/refresh
POST /v1/auth/register
POST /v1/auth/register-user

The access token is sent as Authorization: Bearer <token>.

Direct provisioning: POST /v1/workspace/members creates a human member/agent without registration and is restricted to Server SDK API keys (not ordinary JWTs). It accepts an optional Idempotency-Key header.

Invites

Method	Path	Description
POST	/v1/workspace/invites	Invite a member.
GET	/v1/workspace/invites	List invites.
DELETE	/v1/workspace/invites/{id}	Revoke an invite.

Bots

Bots are a separate resource from human members/agents.

Method	Path	Description
GET	/v1/bots	List bots.
POST	/v1/bots	Create a bot.
PATCH	/v1/bots/{id}	Update a bot.
DELETE	/v1/bots/{id}	Delete a bot.

Canned responses

Method	Path	Description
GET	/v1/canned-responses	List canned responses.
POST	/v1/canned-responses	Create a canned response.
PATCH	/v1/canned-responses/{id}	Update a canned response.
DELETE	/v1/canned-responses/{id}	Delete a canned response.

API keys

Method	Path	Description
POST	/v1/api-keys	Create an API key (raw value returned once).
GET	/v1/api-keys	List API keys.
DELETE	/v1/api-keys/{id}	Revoke an API key.

3. One-time dashboard SSO (Server SDK)

Two endpoints implement a seamless, secure handoff from your own authenticated backend to the Uchara dashboard. Issuance is server-side only (API key); exchange is public and accepts only the opaque one-time ticket.

POST /v1/auth/sso/ticket

Auth: Server SDK API key only (Authorization: Bearer uchara_sk_...). Never call this from the browser.

Request body:

{
  "email": "agent@company.com",
  "channel_ids": ["<channel-uuid>"]
}

channel_ids is optional:

• Omitted → full workspace access.
• Explicit [] → valid zero-channel scope.
• Explicit array → validated against the workspace; unknown or duplicate IDs are rejected.
• Explicit JSON null → rejected (must be omitted or an array).

Response 200 OK:

{
  "ok": true,
  "request_id": "req_...",
  "timestamp": "2024-01-01T00:00:00.000000Z",
  "data": {
    "redirect_url": "https://app.uchara.com#sso_ticket=<one-time-ticket>"
  }
}

The opaque ticket is placed in the URL fragment (#sso_ticket=...) so it is never sent to the server or written to access logs. The ticket is short-lived (60 seconds), one-time, and consumed atomically; only its hash is stored.

Errors: 400 for a missing email or invalid channel_ids; 401 for a missing/invalid API key; 404 when the email is not an active member of the API key’s workspace.

POST /v1/auth/sso/exchange

Auth: Public. Accepts only the opaque one-time ticket — never an API key or JWT.

Request body:

{
  "ticket": "<one-time-ticket>"
}

Response 200 OK:

{
  "ok": true,
  "request_id": "req_...",
  "timestamp": "2024-01-01T00:00:00.000000Z",
  "data": {
    "token": "eyJ...",
    "refresh_token": "eyJ...",
    "member": {},
    "workspace": {},
    "scope": {}
  }
}

The response shape matches POST /v1/auth/agent-token: token, refresh_token, member, workspace, and scope. The ticket is consumed atomically and can be used exactly once.

Errors: 400 for a missing ticket; 401 when the ticket is invalid, expired, or has already been used (reused tickets are rejected without minting any tokens).

Message fields

A message object uses the following key fields:

Field	Type	Description
id	string	Message id.
conversation_id	string	Conversation id.
workspace_id	string	Workspace id.
sender_type	string	agent, contact, or bot.
sender_id	string	Id of the sender.
content_type	string	text, image, file, audio, video, or event.
content	string?	Message text.
attachments	array	Attached files.
metadata	object	Free-form metadata.
created_at	string	ISO-8601 timestamp.

Next steps

• WebSocket Events
• SDK Overview