API reference

Manage knowledge bases, content, flows and gaps from your own systems. Everything the console does goes through this API.

Authentication

Send your tenant API key in the X-API-Key header on every request. The key is tied to one tenant and every call is scoped to it.

HTTP

X-API-Key: YOUR_API_KEY

Base URL: https://avatar-api.syntiva.tech. Requests and responses are JSON unless an endpoint takes a file upload. Endpoints that work inside one knowledge base take knowledge_base_id as a query parameter or in the path.

Errors

Errors return a non-2xx status with a JSON body such as {"error": "Missing knowledge_base_id"}. Some endpoints also return error_ar with an Arabic message. 401 means the key is missing or invalid, 403 that the resource belongs to another tenant, and 429 that you hit a rate limit.

Tenants

Your account and its usage.

Get the current tenant, including its plan and limits.

GET/tenants/me

curl "https://avatar-api.syntiva.tech/tenants/me" \
  -H "X-API-Key: YOUR_API_KEY"

Response (abbreviated)

{
  "id": "tnt_…",
  "name": "Example Authority",
  "subscription_tier": "pro"
}

Get usage counts for the current tenant.

GET/tenants/me/usage

curl "https://avatar-api.syntiva.tech/tenants/me/usage" \
  -H "X-API-Key: YOUR_API_KEY"

Knowledge bases

Each knowledge base has its own content, search index, widget settings and widget key.

List the tenant's knowledge bases.

GET/knowledge-bases

curl "https://avatar-api.syntiva.tech/knowledge-bases" \
  -H "X-API-Key: YOUR_API_KEY"

Create a knowledge base.

POST/knowledge-bases

namerequiredstringbody: Display name.
descriptionstringbody: Optional description.
languagear | enbody: Main language of the content.

Parameters
Name	Type	Description
`name`required	stringbody	Display name.
`description`	stringbody	Optional description.
`language`	ar \| enbody	Main language of the content.

curl -X POST "https://avatar-api.syntiva.tech/knowledge-bases" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer service",
    "language": "ar"
  }'

Get one knowledge base.

GET/knowledge-bases/{id}

idrequiredstringpath: Knowledge base ID.

Parameters
Name	Type	Description
`id`required	stringpath	Knowledge base ID.

curl "https://avatar-api.syntiva.tech/knowledge-bases/{id}" \
  -H "X-API-Key: YOUR_API_KEY"

PATCH/knowledge-bases/{id}/widget

idrequiredstringpath: Knowledge base ID.
widgetrequiredobjectbody: Settings to save. allowed_domains must be an array and enabled a boolean.

Parameters
Name	Type	Description
`id`required	stringpath	Knowledge base ID.
`widget`required	objectbody	Settings to save. allowed_domains must be an array and enabled a boolean.

curl -X PATCH "https://avatar-api.syntiva.tech/knowledge-bases/{id}/widget" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "widget": {
      "enabled": true,
      "allowed_domains": [
        "www.example.com",
        "*.example.com"
      ]
    }
  }'

POST/knowledge-bases/{id}/widget-key

idrequiredstringpath: Knowledge base ID.

Parameters
Name	Type	Description
`id`required	stringpath	Knowledge base ID.

curl -X POST "https://avatar-api.syntiva.tech/knowledge-bases/{id}/widget-key" \
  -H "X-API-Key: YOUR_API_KEY"

Response (abbreviated)

{
  "widget_key": "wk_…"
}

Delete a knowledge base and everything in it.

DELETE/knowledge-bases/{id}

idrequiredstringpath: Knowledge base ID.

Parameters
Name	Type	Description
`id`required	stringpath	Knowledge base ID.

curl -X DELETE "https://avatar-api.syntiva.tech/knowledge-bases/{id}" \
  -H "X-API-Key: YOUR_API_KEY"

Documents

Source files for a knowledge base. Uploading starts text extraction and Q&A generation.

List documents in a knowledge base.

GET/documents

knowledge_base_idrequiredstringquery: The knowledge base to act on.

Parameters
Name	Type	Description
`knowledge_base_id`required	stringquery	The knowledge base to act on.

curl "https://avatar-api.syntiva.tech/documents?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Upload a PDF, DOCX, XLSX or TXT file (multipart/form-data).

POST/documents

knowledge_base_idrequiredstringquery: The knowledge base to act on.
filerequiredfileform: The document to upload.

Parameters
Name	Type	Description
`knowledge_base_id`required	stringquery	The knowledge base to act on.
`file`required	fileform	The document to upload.

curl -X POST "https://avatar-api.syntiva.tech/documents?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@./service-guide.pdf"

Delete a document and the Q&A pairs generated from it.

DELETE/documents/{id}

idrequiredstringpath: Document ID.
knowledge_base_idrequiredstringquery: The knowledge base to act on.

Parameters
Name	Type	Description
`id`required	stringpath	Document ID.
`knowledge_base_id`required	stringquery	The knowledge base to act on.

curl -X DELETE "https://avatar-api.syntiva.tech/documents/{id}?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Run Q&A generation again for a document. Returns a workflow ID to poll.

POST/qa-generation/process-document/{documentId}

documentIdrequiredstringpath: Document ID.

Parameters
Name	Type	Description
`documentId`required	stringpath	Document ID.

curl -X POST "https://avatar-api.syntiva.tech/qa-generation/process-document/{documentId}" \
  -H "X-API-Key: YOUR_API_KEY"

Q&A pairs

The answers the persona gives.

List Q&A pairs in a knowledge base.

GET/qa-pairs

knowledge_base_idrequiredstringquery: The knowledge base to act on.

Parameters
Name	Type	Description
`knowledge_base_id`required	stringquery	The knowledge base to act on.

curl "https://avatar-api.syntiva.tech/qa-pairs?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Get one Q&A pair.

GET/qa-pairs/{id}

idrequiredstringpath: Q&A pair ID.
knowledge_base_idrequiredstringquery: The knowledge base to act on.

Parameters
Name	Type	Description
`id`required	stringpath	Q&A pair ID.
`knowledge_base_id`required	stringquery	The knowledge base to act on.

curl "https://avatar-api.syntiva.tech/qa-pairs/{id}?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Create a Q&A pair.

POST/qa-pairs

knowledge_base_idrequiredstringquery: The knowledge base to act on.
questionrequiredstringbody: The question.
answerrequiredstringbody: The answer.
languagear | enbody: Detected automatically if omitted.
typemcq | short | longbody: Answer type.
difficultyeasy | medium | hardbody: Difficulty label.

Parameters
Name	Type	Description
`knowledge_base_id`required	stringquery	The knowledge base to act on.
`question`required	stringbody	The question.
`answer`required	stringbody	The answer.
`language`	ar \| enbody	Detected automatically if omitted.
`type`	mcq \| short \| longbody	Answer type.
`difficulty`	easy \| medium \| hardbody	Difficulty label.

curl -X POST "https://avatar-api.syntiva.tech/qa-pairs?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are your opening hours?",
    "answer": "Sunday to Thursday, 7:30 to 15:00.",
    "language": "en"
  }'

Generate Q&A pairs from pasted text (at least 100 characters).

POST/qa-pairs/generate-from-text

knowledge_base_idrequiredstringquery: The knowledge base to act on.
textrequiredstringbody: Source text.
run_auditbooleanbody: Audit the generated pairs afterwards. Defaults to true.

Parameters
Name	Type	Description
`knowledge_base_id`required	stringquery	The knowledge base to act on.
`text`required	stringbody	Source text.
`run_audit`	booleanbody	Audit the generated pairs afterwards. Defaults to true.

curl -X POST "https://avatar-api.syntiva.tech/qa-pairs/generate-from-text?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Our service centres are open Sunday to Thursday…",
    "run_audit": true
  }'

Query

Ask a knowledge base a question from your own backend.

Find the best answer for a question using semantic and keyword search.

POST/query

knowledge_base_idrequiredstringquery: The knowledge base to act on.
queryrequiredstringbody: The question.
top_knumberbody: How many candidates to consider. Defaults to 5.
include_videobooleanbody: Include answer video URLs. Defaults to true.
session_idstringbody: Keep related questions in one session. Generated if omitted.

Parameters
Name	Type	Description
`knowledge_base_id`required	stringquery	The knowledge base to act on.
`query`required	stringbody	The question.
`top_k`	numberbody	How many candidates to consider. Defaults to 5.
`include_video`	booleanbody	Include answer video URLs. Defaults to true.
`session_id`	stringbody	Keep related questions in one session. Generated if omitted.

curl -X POST "https://avatar-api.syntiva.tech/query?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are your opening hours?"
  }'

Response (abbreviated)

{
  "answer": {
    "id": "qa_…",
    "question": "What are your opening hours?",
    "answer": "Sunday to Thursday…"
  },
  "candidates": [
    "…"
  ]
}

Intent responses

Greetings, fallbacks and other responses that aren't answers to questions.

List intent responses for a knowledge base.

GET/intent-responses

knowledge_base_idrequiredstringquery: The knowledge base to act on.

Parameters
Name	Type	Description
`knowledge_base_id`required	stringquery	The knowledge base to act on.

curl "https://avatar-api.syntiva.tech/intent-responses?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Update an intent response's text.

PATCH/intent-responses/{id}

idrequiredstringpath: Intent response ID.
response_textstringbody: What the persona says.
follow_up_textstringbody: Optional follow-up line.

Parameters
Name	Type	Description
`id`required	stringpath	Intent response ID.
`response_text`	stringbody	What the persona says.
`follow_up_text`	stringbody	Optional follow-up line.

curl -X PATCH "https://avatar-api.syntiva.tech/intent-responses/{id}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "response_text": "Hello! How can I help you today?"
  }'

Delete one intent response.

DELETE/intent-responses/{id}

idrequiredstringpath: Intent response ID.

Parameters
Name	Type	Description
`id`required	stringpath	Intent response ID.

curl -X DELETE "https://avatar-api.syntiva.tech/intent-responses/{id}" \
  -H "X-API-Key: YOUR_API_KEY"

Delete all intent responses for a knowledge base.

DELETE/intent-responses

knowledge_base_idrequiredstringquery: The knowledge base to act on.

Parameters
Name	Type	Description
`knowledge_base_id`required	stringquery	The knowledge base to act on.

curl -X DELETE "https://avatar-api.syntiva.tech/intent-responses?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Avatars

The persona's face and voice.

List avatars.

GET/avatars

curl "https://avatar-api.syntiva.tech/avatars" \
  -H "X-API-Key: YOUR_API_KEY"

Create an avatar from a portrait image (multipart/form-data).

POST/avatars

namerequiredstringform: Avatar name.
imagerequiredfileform: Portrait image.
descriptionstringform: Optional description.
gendermale | femaleform: Used for voice and gender-correct Arabic. Defaults to male.
voice_idstringform: Voice to use for this avatar.
dialectstringform: msa (default), emirati, saudi, qatari, kuwaiti, bahraini, omani, egyptian or levantine.
is_defaultbooleanform: Make this the tenant's default avatar.

Parameters
Name	Type	Description
`name`required	stringform	Avatar name.
`image`required	fileform	Portrait image.
`description`	stringform	Optional description.
`gender`	male \| femaleform	Used for voice and gender-correct Arabic. Defaults to male.
`voice_id`	stringform	Voice to use for this avatar.
`dialect`	stringform	msa (default), emirati, saudi, qatari, kuwaiti, bahraini, omani, egyptian or levantine.
`is_default`	booleanform	Make this the tenant's default avatar.

curl -X POST "https://avatar-api.syntiva.tech/avatars" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "name=Noor" \
  -F "image=@./noor.jpg" \
  -F "dialect=emirati" \
  -F "gender=female"

Get one avatar.

GET/avatars/{id}

idrequiredstringpath: Avatar ID.

Parameters
Name	Type	Description
`id`required	stringpath	Avatar ID.

curl "https://avatar-api.syntiva.tech/avatars/{id}" \
  -H "X-API-Key: YOUR_API_KEY"

Background jobs

Long-running work such as rendering and indexing. Each call returns a workflow ID you can poll.

Render an avatar's idle loop.

POST/workflows/avatar-idle

avatar_idrequiredstringbody: Avatar ID.

Parameters
Name	Type	Description
`avatar_id`required	stringbody	Avatar ID.

curl -X POST "https://avatar-api.syntiva.tech/workflows/avatar-idle" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_id": "av_…"
  }'

Render the answer video for one Q&A pair.

POST/workflows/single-video

knowledge_base_idrequiredstringquery: The knowledge base to act on.
qa_pair_idrequiredstringbody: Q&A pair ID.
avatar_idstringbody: Defaults to the knowledge base's avatar.

Parameters
Name	Type	Description
`knowledge_base_id`required	stringquery	The knowledge base to act on.
`qa_pair_id`required	stringbody	Q&A pair ID.
`avatar_id`	stringbody	Defaults to the knowledge base's avatar.

curl -X POST "https://avatar-api.syntiva.tech/workflows/single-video?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qa_pair_id": "qa_…"
  }'

Render answer videos for many Q&A pairs.

POST/workflows/batch-videos

knowledge_base_idrequiredstringquery: The knowledge base to act on.
avatar_idstringbody: Defaults to the knowledge base's avatar.
concurrencynumberbody: Parallel renders.
document_idstringbody: Only pairs from this document.
status_filterpending | failed | needs_tts_regenbody: Only pairs in this state.

Parameters
Name	Type	Description
`knowledge_base_id`required	stringquery	The knowledge base to act on.
`avatar_id`	stringbody	Defaults to the knowledge base's avatar.
`concurrency`	numberbody	Parallel renders.
`document_id`	stringbody	Only pairs from this document.
`status_filter`	pending \| failed \| needs_tts_regenbody	Only pairs in this state.

curl -X POST "https://avatar-api.syntiva.tech/workflows/batch-videos?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status_filter": "pending"
  }'

Index all of a knowledge base's Q&A pairs for search.

POST/workflows/vectorize-sync

knowledge_base_idrequiredstringquery: The knowledge base to act on.
batch_sizenumberbody: Defaults to 50.

Parameters
Name	Type	Description
`knowledge_base_id`required	stringquery	The knowledge base to act on.
`batch_size`	numberbody	Defaults to 50.

curl -X POST "https://avatar-api.syntiva.tech/workflows/vectorize-sync?knowledge_base_id=KB_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Get a background job's status.

GET/workflows/{id}/status

idrequiredstringpath: Workflow ID.

Parameters
Name	Type	Description
`id`required	stringpath	Workflow ID.

curl "https://avatar-api.syntiva.tech/workflows/{id}/status" \
  -H "X-API-Key: YOUR_API_KEY"

Flows

E-services built in the workflow designer, and their submissions.

List flows.

GET/flows

curl "https://avatar-api.syntiva.tech/flows" \
  -H "X-API-Key: YOUR_API_KEY"

Get a flow with its steps, conditions and connections.

GET/flows/{id}

idrequiredstringpath: Flow ID.

Parameters
Name	Type	Description
`id`required	stringpath	Flow ID.

curl "https://avatar-api.syntiva.tech/flows/{id}" \
  -H "X-API-Key: YOUR_API_KEY"

Check whether a message should start this flow, using its trigger keywords.

POST/flows/{id}/trigger

idrequiredstringpath: Flow ID.
messagerequiredstringbody: The user's message.

Parameters
Name	Type	Description
`id`required	stringpath	Flow ID.
`message`required	stringbody	The user's message.

curl -X POST "https://avatar-api.syntiva.tech/flows/{id}/trigger" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I want to renew my licence"
  }'

Start a submission. Set webhook_url to receive the result.

POST/flows/{id}/submissions

idrequiredstringpath: Flow ID.
session_idstringbody: The conversation's session ID.
webhook_urlstringbody: HTTPS URL that receives flow.completed or flow.abandoned.

Parameters
Name	Type	Description
`id`required	stringpath	Flow ID.
`session_id`	stringbody	The conversation's session ID.
`webhook_url`	stringbody	HTTPS URL that receives flow.completed or flow.abandoned.

curl -X POST "https://avatar-api.syntiva.tech/flows/{id}/submissions" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "4f0d…",
    "webhook_url": "https://example.com/hooks/servly"
  }'

Get a submission and its collected data.

GET/flows/{id}/submissions/{submissionId}

idrequiredstringpath: Flow ID.
submissionIdrequiredstringpath: Submission ID.

Parameters
Name	Type	Description
`id`required	stringpath	Flow ID.
`submissionId`required	stringpath	Submission ID.

curl "https://avatar-api.syntiva.tech/flows/{id}/submissions/{submissionId}" \
  -H "X-API-Key: YOUR_API_KEY"

Save collected data or change status. Completing or abandoning sends the webhook.

PATCH/flows/{id}/submissions/{submissionId}

idrequiredstringpath: Flow ID.
submissionIdrequiredstringpath: Submission ID.
collected_dataobjectbody: Answers keyed by step and field.
statusin_progress | completed | abandonedbody: New status.

Parameters
Name	Type	Description
`id`required	stringpath	Flow ID.
`submissionId`required	stringpath	Submission ID.
`collected_data`	objectbody	Answers keyed by step and field.
`status`	in_progress \| completed \| abandonedbody	New status.

curl -X PATCH "https://avatar-api.syntiva.tech/flows/{id}/submissions/{submissionId}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed"
  }'

List submissions across all flows.

GET/flows/submissions/all

curl "https://avatar-api.syntiva.tech/flows/submissions/all" \
  -H "X-API-Key: YOUR_API_KEY"

One-time passcodes

Verify a phone number or email inside a flow. See Workflows for limits and delivery.

Create a 6-digit code for an identifier.

POST/otp/send

identifierrequiredstringbody: Phone number or email. phone or email are accepted as aliases.
channelsms | emailbody: Inferred from the identifier if omitted.

Parameters
Name	Type	Description
`identifier`required	stringbody	Phone number or email. phone or email are accepted as aliases.
`channel`	sms \| emailbody	Inferred from the identifier if omitted.

curl -X POST "https://avatar-api.syntiva.tech/otp/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "+971501234567"
  }'

Response (abbreviated)

{
  "ok": true,
  "expires_in_seconds": 300,
  "channel": "sms",
  "identifier": "+971501234567"
}

Check a code. Each code works once.

POST/otp/verify

identifierrequiredstringbody: The same identifier used to send.
coderequiredstringbody: The code the person entered.

Parameters
Name	Type	Description
`identifier`required	stringbody	The same identifier used to send.
`code`required	stringbody	The code the person entered.

curl -X POST "https://avatar-api.syntiva.tech/otp/verify" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "+971501234567",
    "code": "482913"
  }'

Response (abbreviated)

{
  "ok": true,
  "valid": true
}

Knowledge gaps

Questions the persona couldn't answer, and the actions that close them.

List gaps for a knowledge base.

GET/knowledge-gaps/{knowledgeBaseId}

knowledgeBaseIdrequiredstringpath: Knowledge base ID.
statusstringquery: pending, suggested, reviewed, addressed or dismissed.
sort_bystringquery: occurrence_count (default), first_seen_at or last_seen_at.
limitnumberquery: Up to 100. Defaults to 50.
offsetnumberquery: For paging.

Parameters
Name	Type	Description
`knowledgeBaseId`required	stringpath	Knowledge base ID.
`status`	stringquery	pending, suggested, reviewed, addressed or dismissed.
`sort_by`	stringquery	occurrence_count (default), first_seen_at or last_seen_at.
`limit`	numberquery	Up to 100. Defaults to 50.
`offset`	numberquery	For paging.

curl "https://avatar-api.syntiva.tech/knowledge-gaps/{knowledgeBaseId}" \
  -H "X-API-Key: YOUR_API_KEY"

Get one gap.

GET/knowledge-gaps/{knowledgeBaseId}/{gapId}

curl "https://avatar-api.syntiva.tech/knowledge-gaps/{knowledgeBaseId}/{gapId}" \
  -H "X-API-Key: YOUR_API_KEY"

Draft an answer in Arabic and English into the Suggested Q&A queue.

POST/knowledge-gaps/{knowledgeBaseId}/{gapId}/generate-suggestion

curl -X POST "https://avatar-api.syntiva.tech/knowledge-gaps/{knowledgeBaseId}/{gapId}/generate-suggestion" \
  -H "X-API-Key: YOUR_API_KEY"

Write the answer yourself. It's added to the Suggested Q&A queue for approval.

POST/knowledge-gaps/{knowledgeBaseId}/{gapId}/manual-answer

answersrequiredobject[]body: One entry per language: language, question, answer and optional alternative_questions.

Parameters
Name	Type	Description
`answers`required	object[]body	One entry per language: language, question, answer and optional alternative_questions.

curl -X POST "https://avatar-api.syntiva.tech/knowledge-gaps/{knowledgeBaseId}/{gapId}/manual-answer" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": [
      {
        "language": "en",
        "question": "Can I transfer my permit?",
        "answer": "Yes. Submit a transfer request…"
      }
    ]
  }'

Change a gap's status or add notes.

PATCH/knowledge-gaps/{knowledgeBaseId}/{gapId}

statusstringbody: New status.
notesstringbody: Internal notes.

Parameters
Name	Type	Description
`status`	stringbody	New status.
`notes`	stringbody	Internal notes.

curl -X PATCH "https://avatar-api.syntiva.tech/knowledge-gaps/{knowledgeBaseId}/{gapId}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "reviewed"
  }'

Dismiss a gap.

DELETE/knowledge-gaps/{knowledgeBaseId}/{gapId}

curl -X DELETE "https://avatar-api.syntiva.tech/knowledge-gaps/{knowledgeBaseId}/{gapId}" \
  -H "X-API-Key: YOUR_API_KEY"

Restore a dismissed gap.

POST/knowledge-gaps/{knowledgeBaseId}/{gapId}/restore

curl -X POST "https://avatar-api.syntiva.tech/knowledge-gaps/{knowledgeBaseId}/{gapId}/restore" \
  -H "X-API-Key: YOUR_API_KEY"

Suggested Q&A

Drafted answers waiting for review. Approving one creates the Q&A pair and indexes it.

List suggestions for a knowledge base.

GET/suggested-qa/{knowledgeBaseId}

curl "https://avatar-api.syntiva.tech/suggested-qa/{knowledgeBaseId}" \
  -H "X-API-Key: YOUR_API_KEY"

Approve a suggestion, optionally editing it first.

POST/suggested-qa/{knowledgeBaseId}/{suggestionId}/approve

questionstringbody: Edited question.
answerstringbody: Edited answer.
languagear | enbody: Language of the pair.

Parameters
Name	Type	Description
`question`	stringbody	Edited question.
`answer`	stringbody	Edited answer.
`language`	ar \| enbody	Language of the pair.

curl -X POST "https://avatar-api.syntiva.tech/suggested-qa/{knowledgeBaseId}/{suggestionId}/approve" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Reject a suggestion.

POST/suggested-qa/{knowledgeBaseId}/{suggestionId}/reject

reasonstringbody: Optional reason, kept for your records.

Parameters
Name	Type	Description
`reason`	stringbody	Optional reason, kept for your records.

curl -X POST "https://avatar-api.syntiva.tech/suggested-qa/{knowledgeBaseId}/{suggestionId}/reject" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Covered by an existing answer"
  }'

Approve several suggestions at once.

POST/suggested-qa/{knowledgeBaseId}/batch-approve

suggestion_idsrequiredstring[]body: Suggestions to approve.

Parameters
Name	Type	Description
`suggestion_ids`required	string[]body	Suggestions to approve.

curl -X POST "https://avatar-api.syntiva.tech/suggested-qa/{knowledgeBaseId}/batch-approve" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "suggestion_ids": [
      "sug_…",
      "sug_…"
    ]
  }'

Authentication#

Errors#

Tenants#

Get the current tenant, including its plan and limits.#

Get usage counts for the current tenant.#

Knowledge bases#

List the tenant's knowledge bases.#

Create a knowledge base.#

Get one knowledge base.#

Update the widget settings: enabled, allowed domains, customization and features.#

Get the knowledge base's public widget key, creating it if it doesn't exist yet.#

Delete a knowledge base and everything in it.#

Documents#

List documents in a knowledge base.#

Upload a PDF, DOCX, XLSX or TXT file (multipart/form-data).#

Delete a document and the Q&A pairs generated from it.#

Run Q&A generation again for a document. Returns a workflow ID to poll.#

Q&A pairs#

List Q&A pairs in a knowledge base.#

Get one Q&A pair.#

Create a Q&A pair.#

Generate Q&A pairs from pasted text (at least 100 characters).#

Query#

Find the best answer for a question using semantic and keyword search.#

Intent responses#

List intent responses for a knowledge base.#

Update an intent response's text.#

Delete one intent response.#

Delete all intent responses for a knowledge base.#

Avatars#

List avatars.#

Create an avatar from a portrait image (multipart/form-data).#

Get one avatar.#

Background jobs#

Render an avatar's idle loop.#

Render the answer video for one Q&A pair.#

Render answer videos for many Q&A pairs.#

Index all of a knowledge base's Q&A pairs for search.#

Get a background job's status.#

Flows#

List flows.#

Get a flow with its steps, conditions and connections.#

Check whether a message should start this flow, using its trigger keywords.#

Start a submission. Set webhook_url to receive the result.#

Get a submission and its collected data.#

Save collected data or change status. Completing or abandoning sends the webhook.#

List submissions across all flows.#

One-time passcodes#

Create a 6-digit code for an identifier.#

Check a code. Each code works once.#

Knowledge gaps#

List gaps for a knowledge base.#

Get one gap.#

Draft an answer in Arabic and English into the Suggested Q&A queue.#

Write the answer yourself. It's added to the Suggested Q&A queue for approval.#

Change a gap's status or add notes.#

Dismiss a gap.#

Restore a dismissed gap.#

Suggested Q&A#

List suggestions for a knowledge base.#

Approve a suggestion, optionally editing it first.#

Reject a suggestion.#

Approve several suggestions at once.#

Authentication

Errors

Tenants

Get the current tenant, including its plan and limits.

Get usage counts for the current tenant.

Knowledge bases

List the tenant's knowledge bases.

Create a knowledge base.

Get one knowledge base.

Update the widget settings: enabled, allowed domains, customization and features.

Get the knowledge base's public widget key, creating it if it doesn't exist yet.

Delete a knowledge base and everything in it.

Documents

List documents in a knowledge base.

Upload a PDF, DOCX, XLSX or TXT file (multipart/form-data).

Delete a document and the Q&A pairs generated from it.

Run Q&A generation again for a document. Returns a workflow ID to poll.

Q&A pairs

List Q&A pairs in a knowledge base.

Get one Q&A pair.

Create a Q&A pair.

Generate Q&A pairs from pasted text (at least 100 characters).

Query

Find the best answer for a question using semantic and keyword search.

Intent responses

List intent responses for a knowledge base.

Update an intent response's text.

Delete one intent response.

Delete all intent responses for a knowledge base.

Avatars

List avatars.

Create an avatar from a portrait image (multipart/form-data).

Get one avatar.

Background jobs

Render an avatar's idle loop.

Render the answer video for one Q&A pair.

Render answer videos for many Q&A pairs.

Index all of a knowledge base's Q&A pairs for search.

Get a background job's status.

Flows

List flows.

Get a flow with its steps, conditions and connections.

Check whether a message should start this flow, using its trigger keywords.

Start a submission. Set webhook_url to receive the result.

Get a submission and its collected data.

Save collected data or change status. Completing or abandoning sends the webhook.

List submissions across all flows.

One-time passcodes

Create a 6-digit code for an identifier.

Check a code. Each code works once.

Knowledge gaps

List gaps for a knowledge base.

Get one gap.

Draft an answer in Arabic and English into the Suggested Q&A queue.

Write the answer yourself. It's added to the Suggested Q&A queue for approval.

Change a gap's status or add notes.

Dismiss a gap.

Restore a dismissed gap.

Suggested Q&A

List suggestions for a knowledge base.

Approve a suggestion, optionally editing it first.

Reject a suggestion.

Approve several suggestions at once.