Knowledge, FAQ, and training API

Use these 86 endpoints to manage knowledge content, FAQ sources, scenarios, training availability, and customer-facing shop memory. Paths below are relative to the Public API base URL.

Send X-Api-Key on every request and Content-Type: application/json when sending a body. Your key determines the store; do not send a shop ID. For example:

curl -s 'https://app.chatty.net/v1/knowledge/entries?type=qna&page=1&limit=20' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Each row is one endpoint. The request column shows a JSON body, a query-string example, or “No body”. Replace path parameters such as :id with IDs from the matching read/create endpoint. Numeric examples such as 12345 are placeholders. Response examples are excerpts showing the envelope and relevant fields; records may contain additional metadata. Empty-list examples are valid empty results, not the only possible response. All routes can return the shared errors at the end, plus the group-specific errors described in each section.

A successful write does not always mean its content is indexed or its job is finished. Read the returned status and poll the matching status endpoint. Retrying a creation after a timeout can duplicate work; check the saved records before retrying.

Knowledge entries

GET /knowledge/entries uses page (default 1) and limit (default 20), not a Chat API cursor. Optional filters: search, comma-separated type, source, topic, status, state, issue, and dateFrom/dateTo. Types are qna, url, shopify_page, file; a url filter also includes Shopify pages. Issues are conflict, index_error, too_short, too_long, stale. A locale filter currently returns no entries. The list returns data, count, total, and pagination at the top level.

For creation, type defaults to qna; Q&A requires question and answer. URL entries use url; file content uses content and optional filename; page text can use mdContent. Optional title, status, topics (string array), and scope (array of support/sales) accompany the content. Status values are active, draft, and inactive. A requested draft is stored as status: "inactive" with isDraft: true. Omitting status also defaults to draft. Screening can reject content or flag it for review, so read the returned status instead of assuming it is live. allowDuplicate: true permits an independent identical-content copy; it does not bypass all screening.

PATCH accepts answer, question, scope, status, title, topics, and url. Other body fields are ignored. Content edits go through ingestion; a scope-only edit does not rerun content screening. Bulk create and bulk status accept 1–100 entries/IDs. Bulk create returns an outcome per item, including failures even with HTTP 201. Bulk status validates the whole ID selection first but is not an all-or-nothing transaction. Bulk delete requires 1–100 IDs and confirm: true; it deletes only those IDs, not the whole knowledge base.

Group errors: VALIDATION_FAILED, NOT_FOUND, CONFIRM_REQUIRED, DUPLICATE_ENTRY, INGESTION_REVIEW, CONFLICT_PENDING, and SCREEN_*. Duplicate errors may include error.existingId. Read all bulk outcomes before retrying.

Import, export, and revisions

Export accepts format=json (default) or format=csv and returns a downloadable knowledge.json or knowledge.csv, not a data envelope. JSON contains entries; CSV uses the Q&A export representation.

Import accepts format (json or csv), content through text, content, or entries (in that priority), and/or fileIds. Non-string content is JSON-encoded; strings are trimmed. At least content or file IDs are required. This is an asynchronous knowledge import, not the FAQ-source import. Poll the returned jobId: status is queued, importing, applied, partial, or failed. report.applied, report.failed, and report.items report outcomes; HTTP 202 alone does not mean the content is available. Only the latest import job for the shop is exposed; an older job ID may return 404.

Revision reads show a pending revision, publishing applies it to the existing live entry, and deleting discards the pending revision without deleting the live entry. These routes do not create a revision. Missing revisions return NOT_FOUND; import/export input errors use VALIDATION_FAILED. Publishing may also encounter the knowledge ingestion errors listed above.

Health and operations

All GETs here have no body. Summary combines status counts and active counts by source type. Coverage returns counts for conflicting, failed-index, long, short, and stale content. Its unresolvedQuestionsPath is an admin path; use /knowledge/unresolved for the API.

Bulk progress describes the latest queued bulk action. Cancellation sets a request flag only while the matching job is queued or processing; it does not undo completed writes. FAQ audit starts a scan; read it again until state is done before using its report. A successful start is not a completed audit.

Duplicate resolution requires candidateId, decision (create, merge, replace), and entry. create keeps an independent entry; merge joins answers and topics into the candidate; replace applies incoming content to the candidate's ID. Inspect the returned saved, skipped, pendingReview, and report, rather than assuming an HTTP 200 saved content. An invalid decision/body returns VALIDATION_FAILED; a missing duplicate candidate currently surfaces as 500 INTERNAL_ERROR.

Entry resync returns NOT_FOUND for an unknown entry. Store-page resync returns a queued jobId. Monitor page sync through /sync/status; its page counters do not prove completion.

Suggestions and unanswered questions

Suggestion lists accept an optional status (pending, accepted, skipped). The HTTP response wraps another list object inside data: use data.data for items, data.summary for counts, and data.generationStatus for generation state. Generation returns HTTP 202 with queued or in_progress; poll the list for results. A failed enqueue returns 500 GENERATION_FAILED.

Accept optionally takes an edited answer; omit it to use the suggested answer. Skip takes no body. An unknown item, accepting an already accepted item, or skipping an accepted item returns 404 NOT_FOUND. Bulk actions are /knowledge/suggestions/bulk-accept and /knowledge/suggestions/bulk-skip, with a nonempty ids array. For bulk skip, a response can be {"data":{"success":true,"skipped":1}}. Their returned count may be smaller than the requested selection. Invalid IDs-body input returns VALIDATION_FAILED; an unknown bulk action returns NOT_FOUND.

Unresolved lists contain only open questions. Optional query parameters: reason, limit (default 20), after/before (record IDs), and hasCount=true. Use data.data and data.pagination; this endpoint does not use the knowledge list's page number. Resolve requires answer, with optional status, and creates a knowledge Q&A from the stored question before marking it resolved. The same validation, screening, and duplicate errors as entry creation apply. Delete dismisses the question by marking it deleted, rather than deleting a knowledge entry.

FAQ source categories, questions, and blocks

These are the FAQ source records shown on your storefront, separate from knowledge entries. Lists return all records without pagination. GET and DELETE have no body. A category's display title is named question, not name; creation requires it. Optional category fields include published, featured, icon, and position (omitted means append). Deleting a category moves its questions to the default category and updates affected FAQ blocks; deleting the default category is rejected.

Question creation requires question, answer, and an existing categoryId from your store. published defaults to true; featured is optional. PATCH merges with existing values and validates the destination category, so moving a question requires a valid categoryId. Keep image content as URLs rather than inline base64. Block bodies use blockName, heading, subHeading, display, categorizeFaqs, and a faqs array referencing source questions (questionId, categoryId, question, answer, published). Placement options include showOnProductPages, productPagesMode (all, specific, collections, tags), products, collections, tags, showOnHomepage, showOnCollectionPages, showOnCartPage, showOnBlogPages, showOnSpecificPages, showCustomUrls, and customUrls (one storefront path per line). Read an existing block before changing its layout. PATCH replaces supplied fields, including whole arrays. Block creation returns an id, question creation a questionId, and category creation a categoryId plus position.

Run the FAQ audit before syncing ready FAQ content into knowledge. POST /faq/sync-to-knowledge takes no body and queues the ready selection. Poll GET on the same path; read state, phase, processed, total, progress, and any error. HTTP 202 is only acceptance. Group errors are 400 VALIDATION_FAILED, 404 NOT_FOUND, and 500 INTERNAL_ERROR for other failures. FAQ import, export and delete-all are below.

Import, export, and delete all FAQs

Export. format is csv (default) or json. status is all (default) or published, which keeps questions that are published in a published category. All rows come in one response. CSV starts with a byte order mark and has the columns Question, Answer, Category, Published question, Featured question, Published category and Featured category. JSON returns the question flags only. A question in several categories appears once per category.

Import. Send either CSV with Content-Type: text/csv, or JSON: an array of rows, or {"rows":[...],"overwrite":false,"publish":false}. Both take 1–500 rows.

• JSON rows need question (up to 10,000 characters), answer (up to 100,000), category (up to 1,000), published and featured. Any invalid row rejects the whole request with 400 VALIDATION_FAILED.
• CSV must include the headers Question, Answer, Category, Published question and Featured question; extra columns, such as the category columns from an export, are ignored. A CSV file is at most 5 MB, or the route returns 413 PAYLOAD_TOO_LARGE. In CSV, a row with an empty value, a flag other than true/false, or an inline base64 image is counted in fail and skipped; the other rows still import. fail.detail lists the 1-based row numbers per problem.
• Categories are matched by exact name. A missing category is created, published only when publish is true.
• A question with the same text in the same category counts as duplicate and is skipped, unless overwrite is true; then the existing question is updated. overwrite and publish default to false and can also be sent as query parameters.
• success counts imported or updated rows, countQuestionNew the new questions, and categories the categories used. Chatty also emails the result to the store's email address.

Delete all. This permanently deletes every FAQ question and category, and clears them from FAQ blocks and translations. It needs the exact body {"confirm":"DELETE ALL FAQS"}. The job runs in the background, about 100 questions per second. Poll GET /faq/delete-all until state is done or error; it returns {"data":null} if no deletion has ever run. While a deletion is queued or running, another start returns 409 ALREADY_RUNNING. A job with no progress for 30 minutes is treated as stopped, and a new one can start.

Product FAQs

Use the Shopify product ID for productId (a numeric ID or URL-encoded Shopify GID). PUT accepts a nonempty faqs array; each item requires question and answer, and an id updates that FAQ. The response is an array of saved IDs, not FAQ records. GET is scoped to the product and store. DELETE requires the FAQ to belong to that product/store. Errors: VALIDATION_FAILED for invalid FAQ input, NOT_FOUND for a missing target, and DUPLICATE_ENTRY for an identical product question.

Scenarios

Create a custom scenario with required name and instruction. Optional intents and exampleMessages default to empty arrays; exampleMessages must contain strings. Optional scope is an array of support/sales that controls retrieval scope. status accepts active, draft, inactive and defaults to draft. Supported intents: product_search, cart, order_tracking, discount, after_sale, human_transfer, loyalty, sizing, general, other, ask_related_product, ask_complementary, shipping_delivery, payment, store_info, product_compare, availability, gift, subscription, order_change.

PATCH can edit custom scenario content and linked training data (linkedItems with type/id, or linkedDocumentIds). Immutable identity fields and keyword are ignored. Default scenarios accept only status and their own settings fields; an unsupported field returns FIELD_NOT_PERMITTED. Default scenarios cannot be deleted. Creation also checks the plan's custom-scenario limit; at present LIMIT_REACHED is returned with HTTP 500, not 403. Use the status endpoint for a status-only change.

The linkable-training-data picker requires type: url, shopify_page, file, qna, in-app, product, collection, or discount. Optional search, status, page (default 1), limit (default 50, maximum 100), and sort (default updatedAt_desc) are accepted; filters vary by source. Results expose id, type, label, and optional subtitle/updatedAt, plus top-level pagination.hasNext. An unsupported type is HTTP 400 with a string error, not the usual coded error object.

Revision routes review an existing pending revision. Publishing updates the same live scenario ID; deleting a revision does not delete the scenario. Missing scenarios or revisions return NOT_FOUND. Input errors return VALIDATION_FAILED. Lists include quality and observability; observability.available: false means no measured usage is available, not zero matches.

Size guides

Create requires name and readable size-chart markdown. Optional measurementFields overrides the parsed fields. matchType defaults to automatic, matchLogic defaults to {"collectionIds":[],"collections":[]}, and status defaults to draft (active/draft/inactive are accepted). PUT updates supplied fields; including markdown reparses the chart and preserves explicitly supplied measurementFields. Reads do not parse the chart.

List filters: status, sort (default updatedAt_desc), limit (default 20), after/before record IDs, and hasCount=true. Its page lives inside data, like unresolved questions. Writes also check the current Pro-or-above size-guide entitlement and may return 403 PLAN_REQUIRED. Other errors: VALIDATION_FAILED, NOT_FOUND, chart_unreadable, not_a_size_chart, chart_service_unavailable. The last one is HTTP 503; the two chart-input errors are HTTP 400.

Training catalog

These lists return data.data and data.pagination; preserve the outer data wrapper when parsing. Product lists accept search, page (default 1), limit (default 10, maximum 50), sort (default title_asc), and status (active, inactive, not-added, all; default active). Optional selection filters include vendors, tags, metaTags, productIds, collectionIds (or collectionId), collections (titles), and restrictProductIds. Repeat query keys for multiple values. isSmartRecommendation without product/collection conditions returns an empty result with an error message.

Discount lists accept search, status (active, inactive, expiring), page (default 1), limit (default 20), and sort using updatedAt, createdAt, or title with _asc/_desc. expiring selects active discounts ending within seven days. Collection lists accept search, status, sort (default updatedAt_desc), page (default 1), limit (default 20, maximum 100), and hasCount=true.

Status writes require the matching ID array and a boolean enabled. Product IDs are Shopify IDs; collection IDs come from the synced collection list. Enabling products can hit the product allowance while returning HTTP 200: inspect limitReached, toEnableIds, toDisableIds, and the returned success flag before treating every requested product as trained. Collection status writes return 400 INVALID_VALUE with missing collectionIds when collections have not synced yet; run product sync first. Other input errors use VALIDATION_FAILED. Unknown shops use NOT_FOUND; an invalid discount sort currently surfaces as 500 INTERNAL_ERROR.

Shop memory and synchronization

Shop memory is knowledge for the customer-facing agent, not a merchant-assistant memory store. Profile and skill reads carry audience: "customer-facing-agent". The profile can be null, and skills can be empty. Skill IDs are numeric strings; deleting an unknown or foreign skill returns 404 NOT_FOUND.

Training accepts an optional force boolean, family (deepseek or anthropic), and quality (quality-pair, cheap-only, agentic). Unrecognized family/quality values fall back to the service defaults. It returns HTTP 202 with jobId; poll /shop-memory/jobs/:id on the Public API. Do not follow the returned legacy statusUrl under /agent-api/. Jobs progress from queued to running, then applied, failed, or skipped. Another active job currently returns 500 JOB_IN_FLIGHT; wait for that job instead of repeatedly queuing work. Missing or cross-shop jobs return 404 NOT_FOUND or 404 SHOP_SCOPE_MISMATCH.

Clearing requires confirm: true and removes both the shop profile and skills; without it, the response is 400 VALIDATION_FAILED. This does not clear customer memory or ordinary knowledge entries.

Sync supports exactly products, discounts, and pages. POST takes no body and returns 202 with a jobId, but that ID is an acknowledgement, not a durable per-job status handle. Read /sync/status for current shop progress. Product/discount done requires numeric synced/total counters and no error. Missing counters do not mean completion; pages.done remains false because the page source has no matching counter pair. An unknown sync resource returns 404 NOT_FOUND.

Errors

Except for the linkable-training-data type error noted above, failures use {"error":{"code":"…","message":"…"}}. Some include details, reason, or existingId. Do not infer success from a bulk HTTP status alone.

Example rejected creation:

{"error":{"code":"DUPLICATE_ENTRY","message":"DEDUPE_CONTENT_HASH","existingId":"entry_123"}}

Read Authentication and Errors and rate limits for shared key, version, and rate-limit behavior. The MCP tools reference describes grouped tools that call these routes; their availability still depends on authentication and scopes.