API reference

Embed AI Chat

Let your users chat with a trained AI assistant directly on your website. No TribePeer registration required — guests verify via email OTP and start chatting instantly. Train the AI with your own documents, FAQs, and instructions.

Base: https://www.tribepeer.com/api. Embed auth routes use a publishable key (same as widget keys). After verification, all routes need Authorization: Bearer <embed_jwt>. Training routes use a partner JWT with ai:chat scope.

Authentication flow

The embed auth is a single-entry flow — no separate login/register. The API determines the next step based on the email:

1. Send email	`POST /embed/v1/auth/init` with `publishable_key` + `email`
Known email	OTP sent immediately → `{ status: "otp_sent" }`
New email	Returns `{ status: "name_required" }` → collect name → re-call init with `name`
2. Verify OTP	`POST /embed/v1/auth/verify` → returns JWT + user info
3. Chat	`POST /embed/v1/chat` with Bearer token

Initialise — email check & OTP

POST /embed/v1/auth/init

Send email to start the auth flow. API decides if name is needed.

Request body

`publishable_key`	string, required	Your widget/embed publishable key
`email`	string, required	Guest's email address
`name`	string, optional	Required only when `requires_name` was `true`

POST /api/embed/v1/auth/init

# Step 1: Send email (check if name required)
curl -s https://www.tribepeer.com/api/embed/v1/auth/init \
  -H "Content-Type: application/json" \
  -H "Origin: https://your-site.com" \
  -d '{
    "publishable_key": "pk_live_abc123...",
    "email": "patient@example.com"
  }'

# Step 1b: If requires_name is true, resend with name
curl -s https://www.tribepeer.com/api/embed/v1/auth/init \
  -H "Content-Type: application/json" \
  -H "Origin: https://your-site.com" \
  -d '{
    "publishable_key": "pk_live_abc123...",
    "email": "patient@example.com",
    "name": "John Doe"
  }'

Responses

200 — OTP sent

{ "status": "otp_sent", "requires_name": false, "message": "A verification code has been sent to your email." }

200 — Name required (new user)

{ "status": "name_required", "requires_name": true, "message": "This email is not registered. Please provide your name." }

Verify OTP

POST /embed/v1/auth/verify

Verify the OTP and receive an embed JWT.

Request body

`publishable_key`	string, required	Same key from init
`email`	string, required	Same email from init
`otp`	string, required, 6 digits	Code from email

POST /api/embed/v1/auth/verify

curl -s https://www.tribepeer.com/api/embed/v1/auth/verify \
  -H "Content-Type: application/json" \
  -H "Origin: https://your-site.com" \
  -d '{
    "publishable_key": "pk_live_abc123...",
    "email": "patient@example.com",
    "otp": "482916"
  }'

Success response `200`

application/json

{
  "status": "verified",
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-09-19T06:00:00+00:00",
  "user": { "name": "John Doe", "email": "patient@example.com", "is_platform_user": false }
}

Chat

POST /embed/v1/chat

Send a message and get an AI response. Omit conversation_uuid to start a new conversation.

Headers

Authorization Bearer <embed_jwt>

Request body

`message`	string, required, max 4000	The user's message
`conversation_uuid`	uuid, optional	Continue an existing conversation

POST /api/embed/v1/chat

curl -s https://www.tribepeer.com/api/embed/v1/chat \
  -H "Authorization: Bearer $EMBED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the symptoms of malaria?"
  }'

Success response `200`

application/json

{
  "reply": "Malaria symptoms typically include fever, chills, headache...",
  "conversation_uuid": "a1b2c3d4-...",
  "model": "...",
  "usage": { "quota": 2000, "used": 10, "remaining": 1990 }
}

Pass conversation_uuid from the response in subsequent messages to maintain context:

Continue conversation

curl -s https://www.tribepeer.com/api/embed/v1/chat \
  -H "Authorization: Bearer $EMBED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How is it treated?",
    "conversation_uuid": "uuid-from-previous-response"
  }'

Conversations

GET /embed/v1/conversations

List the guest's past conversations for this institution.

Success response `200`

application/json

{
  "conversations": [
    { "uuid": "a1b2...", "title": "What are the symptoms...", "last_message_at": "2026-09-19T05:00:00+00:00", "created_at": "..." }
  ]
}

GET /embed/v1/conversations/{uuid}/messages

Get messages for a specific conversation. Supports cursor pagination via ?before=id&limit=50.

AI Configuration (training)

Configure how the AI behaves for your institution. Use your Partner API token with ai:chat scope.

PUT /partner/v1/ai/config

Scope: ai:chat

Set the AI's purpose, instructions, persona, and greeting message.

Request body

`purpose`	string, max 2000	What the AI is for (e.g. "medical assistant for XYZ Clinic")
`instructions`	string, max 4000	Behavioural rules for the AI
`persona_name`	string, max 100	Display name (e.g. "Dr. Assistant")
`persona_tone`	string, max 40	e.g. "professional", "friendly"
`greeting_message`	string, max 1000	First message shown to guests
`fallback_message`	string, max 1000	What AI says when it can't answer
`collect_fields`	array of strings	Optional fields to collect (e.g. ["symptoms", "age"])

PUT /api/partner/v1/ai/config

curl -s https://www.tribepeer.com/api/partner/v1/ai/config \
  -X PUT \
  -H "Authorization: Bearer $PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "You are a medical assistant for Lagos Health Clinic. Help patients understand symptoms and treatments.",
    "instructions": "Always recommend consulting a doctor for serious symptoms. Never diagnose conditions definitively.",
    "persona_name": "Dr. Assistant",
    "persona_tone": "professional and empathetic",
    "greeting_message": "Hello! I am the Lagos Health Clinic assistant. How can I help you today?",
    "fallback_message": "I am not sure about that. Please contact our front desk at 08012345678 for further assistance."
  }'

Knowledge Base

Add FAQs, documents, and text snippets that the AI uses to answer questions accurately.

POST /partner/v1/ai/knowledge

Scope: ai:chat

Add a knowledge item (FAQ, document, or text).

Request body

`type`	`faq` \| `document` \| `text`	Required
`title`	string, max 255	Display title
`question`	string, max 500	Required for `faq` type
`content`	string, required, max 50000	The answer (FAQ) or document body
`is_active`	boolean	Default: true
`sort_order`	integer	Lower = higher priority

POST /api/partner/v1/ai/knowledge (FAQ)

curl -s https://www.tribepeer.com/api/partner/v1/ai/knowledge \
  -H "Authorization: Bearer $PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "faq",
    "title": "Visiting hours",
    "question": "What are the clinic visiting hours?",
    "content": "Our clinic is open Monday to Friday, 8am to 6pm. Saturday 9am to 2pm. Closed on Sundays and public holidays."
  }'

File Upload

POST /partner/v1/ai/knowledge/upload

Scope: ai:chat

Upload a PDF or Word document. Text is automatically extracted for AI context.

Request body (multipart/form-data)

`file`	file, required	PDF, DOC, or DOCX — max 20 MB
`title`	string, optional	Defaults to filename
`description`	string, optional	Short description

Upload PDF

curl -s https://www.tribepeer.com/api/partner/v1/ai/knowledge/upload \
  -H "Authorization: Bearer $PARTNER_TOKEN" \
  -F "file=@/path/to/patient-guide.pdf" \  # also accepts .doc, .docx
  -F "title=Patient Guide"

Additional endpoints: GET /partner/v1/ai/knowledge (list), GET /…/{uuid} (show), PATCH /…/{uuid} (update), DELETE /…/{uuid} (delete).

Errors

`401`	Missing / invalid JWT or publishable key
`403`	Origin not allowed / institution inactive
`402`	`ai_quota_exceeded` or `live_key_required`
`422`	Validation / invalid OTP
`429`	Rate limit
`503`	Could not send OTP email / AI offline

Best practices

Store the embed JWT in memory or sessionStorage — it expires after 1 hour. Use POST /embed/v1/auth/refresh to extend.
Always pass conversation_uuid from the first response to maintain multi-turn context.
Train the AI via PUT /partner/v1/ai/config — set purpose, instructions, and fallback messages before going live.
Upload FAQs first — they have the highest priority in context injection.
Keep knowledge base entries focused and factual. The AI will not hallucinate information that's in your knowledge base.
Use collect_fields in config to tell the AI to collect info like symptoms, age, etc. from the guest.
Never expose your tp_sec_ client secret in frontend code. Use publishable keys for embed.

AI · TribeMate API Organisation API API plans

Embed AI Chat

Authentication flow

Initialise — email check & OTP

Request body

Responses

Verify OTP

Request body

Success response 200

Chat

Headers

Request body

Success response 200

Conversations

Success response 200

AI Configuration (training)

Request body

Knowledge Base

Request body

File Upload

Request body (multipart/form-data)

Errors

Best practices

Success response `200`

Success response `200`

Success response `200`