Clomni

Scopes and endpoints: AI agents, knowledge base, help center

Last updated: 11 November 2026 · 13 min read

Scopes for reading, training and publishing AI agents, getting answers from them, the knowledge base and the help center. Changing an AI agent takes two steps: ai_agents:write prepares the draft and ai_agents:publish makes it live.

Steps

  1. 1

    How to read this article

    • Paths follow https://api.clomni.ai/v1: GET /v1/agents means https://api.clomni.ai/v1/agents. Paths have no workspace ID, because a token belongs to one workspace.
    • Every request carries the Authorization: Bearer clomni_pat_xxx header. How to get a token: Tokens and authentication in the Developer API.
    • Risk: low (no personal data), medium (reads customer data or changes internal data), high (sends to customers, deletes, bulk exports, changes live settings).
    • Every scope goes through review, in public apps too. More: Review: checking scopes and rejection reasons.
    • "Also grants": write and manage grant the read of the same resource. send, delete, publish, assign and run grant nothing.
    • When an endpoint lists several scopes, any one of them is enough. Without the scope the API answers 403 insufficient_scope with required_scopes in the body.
    • Every POST takes an Idempotency-Key header, so a repeated request is not run twice.
  2. 2

    Read AI agents (ai_agents:read)

    Reads AI agents: settings, instructions, draft, versions, FAQs ("Q&A" in the dashboard), scenarios ("Situations" in the dashboard), test questions and runs, the agent's tools and the inboxes it answers in.

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/ai_agent_faqs: List FAQ entries
    • GET /v1/ai_agent_faqs/{faq_id}: Get a FAQ entry
    • GET /v1/ai_agent_tools: List AI agent tools
    • GET /v1/ai_agent_tools/{ai_agent_tool_id}: Get an AI agent tool
    • GET /v1/ai_agents: List AI agents
    • GET /v1/ai_agents/tools: List tools an AI agent can use
    • GET /v1/ai_agents/{ai_agent_id}: Get an AI agent
    • GET /v1/ai_agents/{ai_agent_id}/draft: Get an AI agent's draft
    • GET /v1/ai_agents/{ai_agent_id}/inboxes: List the inboxes an AI agent answers in
    • GET /v1/ai_agents/{ai_agent_id}/scenarios: List scenarios
    • GET /v1/ai_agents/{ai_agent_id}/scenarios/{scenario_id}: Get a scenario
    • GET /v1/ai_agents/{ai_agent_id}/test_questions: List test questions
    • GET /v1/ai_agents/{ai_agent_id}/test_runs/{test_run_id}: Get a test run
    • GET /v1/ai_agents/{ai_agent_id}/versions: List an AI agent's versions

    Example:

    curl "https://api.clomni.ai/v1/ai_agents" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/ai_agent_faqs" \
  -H "Authorization: Bearer clomni_pat_xxx"
  3. 3

    Edit AI agent drafts (ai_agents:write)

    Creates AI agents, edits the draft's settings, saves and deletes scenarios in the draft. It does not touch the live agent: ai_agents:publish makes the draft live.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: ai_agents:read.

    Endpoints:

    • POST /v1/ai_agents: Create an AI agent
    • PATCH /v1/ai_agents/{ai_agent_id}/draft: Update an AI agent's draft
    • POST /v1/ai_agents/{ai_agent_id}/draft/scenarios: Save a scenario in the draft
    • DELETE /v1/ai_agents/{ai_agent_id}/draft/scenarios/{scenario_id}: Delete a scenario from the draft

    Example:

    curl -X POST "https://api.clomni.ai/v1/ai_agents" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales assistant", "description": "Answers order and delivery questions", "config": {"product_name": "Demo Store"}}'
  4. 4

    Train AI agents (ai_agents:train)

    Trains AI agents: adds, changes and deletes FAQs, scenarios and test questions, imports test questions, starts test runs, marks results, rebuilds what the agent searches. Test runs and rebuilding use AI credit.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: nothing else.

    Endpoints:

    • POST /v1/ai_agent_faqs: Create a FAQ entry
    • PATCH /v1/ai_agent_faqs/{faq_id}: Update a FAQ entry
    • DELETE /v1/ai_agent_faqs/{faq_id}: Delete a FAQ entry
    • POST /v1/ai_agents/{ai_agent_id}/scenarios: Create a scenario
    • PATCH /v1/ai_agents/{ai_agent_id}/scenarios/{scenario_id}: Update a scenario
    • DELETE /v1/ai_agents/{ai_agent_id}/scenarios/{scenario_id}: Delete a scenario
    • POST /v1/ai_agents/{ai_agent_id}/test_questions: Create a test question
    • POST /v1/ai_agents/{ai_agent_id}/test_questions/import: Import test questions
    • PATCH /v1/ai_agents/{ai_agent_id}/test_questions/{test_question_id}: Update a test question
    • DELETE /v1/ai_agents/{ai_agent_id}/test_questions/{test_question_id}: Delete a test question
    • PATCH /v1/ai_agents/{ai_agent_id}/test_results/{test_result_id}: Mark a test result
    • POST /v1/ai_agents/{ai_agent_id}/test_runs: Start a test run
    • POST /v1/ai_agents/{ai_agent_id}/train: Retrain an AI agent

    Example:

    curl -X POST "https://api.clomni.ai/v1/ai_agent_faqs" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"question": "How long does delivery take?", "answer": "1 working day in Baku, 2-3 working days to the regions.", "assistant_id": 4}'
  5. 5

    Publish AI agents (ai_agents:publish)

    Changes the live agent: publishes the draft, restores an older version, changes settings at once with PATCH /v1/ai_agents/{ai_agent_id}, connects the agent to an inbox and disconnects it, changes how it works in an inbox, deletes the agent. The answers customers get change, so it is high risk.

    • Risk: high.
    • Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days.
    • Also grants: nothing else.

    Endpoints:

    • PATCH /v1/ai_agents/{ai_agent_id}: Update a live AI agent
    • DELETE /v1/ai_agents/{ai_agent_id}: Delete an AI agent
    • POST /v1/ai_agents/{ai_agent_id}/draft/publish: Publish an AI agent's draft
    • POST /v1/ai_agents/{ai_agent_id}/inboxes: Connect an AI agent to an inbox
    • PATCH /v1/ai_agents/{ai_agent_id}/inboxes/{inbox_id}: Change how an AI agent works in an inbox
    • DELETE /v1/ai_agents/{ai_agent_id}/inboxes/{inbox_id}: Disconnect an AI agent from an inbox
    • POST /v1/ai_agents/{ai_agent_id}/versions/{version}/restore: Restore an AI agent version

    Example:

    curl -X POST "https://api.clomni.ai/v1/ai_agents/4/draft/publish" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl -X POST "https://api.clomni.ai/v1/ai_agents/4/inboxes" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"inbox": {"inbox_id": 5}}'
  6. 6

    Ask an AI agent (ai_agents:ask)

    Gets answers from an AI agent on your own platform, the way the agent's test panel answers. Nothing is written to any conversation. Every answer is charged to the AI credit; when it runs out you get 402 ai_credit_spent. With handoff: true, pass the question to a person.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: nothing else.

    Endpoints:

    • POST /v1/ai_agents/{ai_agent_id}/ask: Ask an AI agent

    Example:

    curl -X POST "https://api.clomni.ai/v1/ai_agents/4/ask" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"question": "And to the regions?", "history": [{"role": "user", "content": "How long does delivery take?"}, {"role": "assistant", "content": "1 working day in Baku."}]}'
  7. 7

    Read the knowledge base (knowledge:read)

    Reads the knowledge base documents and links and whether they have been read (status, sync_status).

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/knowledge: List knowledge base documents
    • GET /v1/knowledge/{document_id}: Get a knowledge base document

    Example:

    curl "https://api.clomni.ai/v1/knowledge?assistant_id=4" \
  -H "Authorization: Bearer clomni_pat_xxx"
  8. 8

    Edit the knowledge base (knowledge:write)

    Adds a web page by link or a file and deletes documents. A document is read in the background; status shows when it is ready. There is no separate update endpoint: when a page changes, delete the old document and add it again.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: knowledge:read.

    Endpoints:

    • POST /v1/knowledge: Add a document or link
    • DELETE /v1/knowledge/{document_id}: Delete a knowledge base document

    Example:

    curl -X POST "https://api.clomni.ai/v1/knowledge" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"document": {"name": "Delivery rules", "external_link": "https://demo-store.example/delivery", "assistant_id": 4}}'
  9. 9

    Read AI logs (ai_logs:read)

    Reads the AI log: questions the agent could not answer, answer reviews and the agent's results.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/ai_agents/{ai_agent_id}/gaps: List questions an AI agent could not answer
    • GET /v1/ai_agents/{ai_agent_id}/results: Get an AI agent's results
    • GET /v1/ai_agents/{ai_agent_id}/reviews: List AI answer reviews
    • GET /v1/ai_agents/{ai_agent_id}/reviews/{review_id}: Get an AI answer review

    Example:

    curl "https://api.clomni.ai/v1/ai_agents/4/gaps" \
  -H "Authorization: Bearer clomni_pat_xxx"
  10. 10

    Read the help center (help_center:read)

    Reads help center portals, categories and articles, and searches articles.

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/portals: List help center portals
    • GET /v1/portals/{portal_id}: Get a help center portal
    • GET /v1/portals/{portal_id}/articles: List articles
    • GET /v1/portals/{portal_id}/articles/{article_id}: Get an article
    • GET /v1/portals/{portal_id}/categories: List categories
    • GET /v1/portals/{portal_id}/categories/{category_id}: Get a category
    • GET /v1/search/articles: Search help center articles

    Example:

    curl "https://api.clomni.ai/v1/portals" \
  -H "Authorization: Bearer clomni_pat_xxx"
  11. 11

    Edit the help center (help_center:write)

    Writes, edits, publishes and deletes articles, creates categories, changes the order and the portal settings.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: help_center:read.

    Endpoints:

    • PATCH /v1/portals/{portal_id}: Update a help center portal
    • POST /v1/portals/{portal_id}/articles: Create an article
    • POST /v1/portals/{portal_id}/articles/reorder: Reorder articles
    • PATCH /v1/portals/{portal_id}/articles/{article_id}: Update an article
    • DELETE /v1/portals/{portal_id}/articles/{article_id}: Delete an article
    • POST /v1/portals/{portal_id}/categories: Create a category
    • POST /v1/portals/{portal_id}/categories/reorder: Reorder categories
    • PATCH /v1/portals/{portal_id}/categories/{category_id}: Update a category
    • DELETE /v1/portals/{portal_id}/categories/{category_id}: Delete a category

    Example:

    curl -X POST "https://api.clomni.ai/v1/portals/demo-store/articles" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "How do I track my order?", "content": "Find your order number under My orders.", "category_id": 11, "status": "published", "locale": "en"}'
  12. 12

    About the help center

    The customer help site (portal, categories, articles) is not in any Clomni package since 5 November 2026 and is not shown in the dashboard. The help_center:* scopes and endpoints stay in the catalogue, but do not build new integrations on them. To answer customers automatically, use the AI agent's knowledge base (knowledge:write) and FAQs (ai_agents:train).

  13. 13

    Related articles

Document

Developer platform: guide v1.0 · 41 pages Open Download