Send messages

The chat endpoint is the heart of the API: you send a user’s message and get back the bot’s reply, generated over your own knowledge base (RAG). Along with the reply we return the sources it was grounded on and the request metrics.

Authentication

Every request is authenticated with your public API key in the X-API-Key header. Each endpoint is scoped to your account: you only ever touch your own bots and conversations. Create and manage keys from your YepClerk dashboard, under Settings → API.

Send a message

Base path: /v1/public/v1/chat

Method	Path	Purpose
POST	/chat	Send a message and get the bot’s reply with its sources.

Body parameters

Field	Type	Required	Description
message	string	Yes	The end user’s message. Up to 2000 characters.
conversation_id	UUID	No	Continue an existing conversation. Omit it to start a new one.
user_ref	string	No	Your own reference for the end user (email, id, phone). Up to 100 characters.

Request

POST /v1/public/v1/chat
X-API-Key: <your-api-key>
Content-Type: application/json

{
  "message": "What are your opening hours?",
  "user_ref": "customer@example.com"
}

Response (200 OK)

{
  "conversation_id": "a3f1c2e0-1b2c-4d5e-8f90-1a2b3c4d5e6f",
  "response": "We're open Monday to Friday, 9am to 6pm.",
  "sources": [{ "filename": "opening-hours.pdf", "score": 0.94 }],
  "tokens_used": 312,
  "latency_ms": 840
}

Field	Type	Description
conversation_id	UUID	The conversation this reply belongs to. Reuse it to continue the thread.
response	string	The bot’s reply, grounded in your knowledge base.
sources	array	Knowledge-base chunks that grounded the answer, each with a filename and a relevance score (0–1).
tokens_used	integer	Tokens consumed generating the reply.
latency_ms	integer	Server processing time, in milliseconds.

Continuing a conversation

If you don’t send conversation_id, a new conversation is created and its id comes back in the response. Store that id and pass it on the next request so the bot keeps the thread’s context:

{
  "message": "And on weekends?",
  "conversation_id": "a3f1c2e0-1b2c-4d5e-8f90-1a2b3c4d5e6f"
}

The user_ref field is your identifier for the end user: use it to reconcile conversations with your own system. If you omit it, one is generated automatically.

Errors

Code	Meaning
401	The X-API-Key header is missing or the key is invalid.
403	Your plan doesn’t include public API access.
404	The conversation_id doesn’t exist or doesn’t belong to your account.
422	The body is invalid (e.g. message is empty or exceeds 2000 characters).