API reference

Knowledge

Knowledge bases hold the pages, documents and text an assistant answers from. Sources are revised, approved and published as immutable publications, then attached to assistants.

POST/api/knowledgeCreate a knowledge base
GET/api/knowledgeList knowledge bases
GET/api/knowledge/{id}Get a knowledge base
PATCH/api/knowledge/{id}Update a knowledge base
POST/api/knowledge/{id}/sourcesAdd or revise a source
POST/api/knowledge/{id}/discoverFind a site's pages from its sitemap
POST/api/knowledge/{id}/grants/{userId}Grant a member access
DELETE/api/knowledge/{id}/grants/{userId}Remove a member's access
POST/api/knowledge/{id}/publicationsBuild a publication
POST/api/knowledge/{id}/publications/{publicationId}/publishPublish a ready publication
POST/api/knowledge/{id}/publications/{publicationId}/retryRetry a failed publication
POST/api/knowledge/{id}/publications/{publicationId}/testTry a publication in test chats
GET/api/knowledge/{id}/revisions/{revisionId}Preview a revision's extracted text
POST/api/knowledge/{id}/revisions/{revisionId}/approveApprove a revision
POST/api/knowledge/{id}/searchSearch a knowledge base
DELETE/api/knowledge/{id}/sources/{sourceId}Revoke a source
DELETE/api/knowledge/{id}/test-publicationStop trying a publication
POST/api/knowledge/{id}/test-publication/promoteMake the tested publication live

Create a knowledge base

POST/api/knowledge

An empty knowledge base. Add sources, approve them and publish before any assistant can answer from it. Needs an org-wide API key: project keys cannot use organization knowledge.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Request body

namestringrequiredup to 200 characters
Trimmed; 1 to 200 characters.
descriptionstringup to 2000 characters
Default ""

Returns

201 Created

Response attributes

dataKnowledgeBaserequired
12 attributes
- idstringrequired
  kb_...
- org_idstringrequired
- namestringrequired
- descriptionstringrequired
- enabledbooleanrequired
- active_publication_idstring | nullrequired
  The live publication, or null before the first publish.
- versionintegerrequired
  The content counter: bumped when sources change and when name, description or enabled is updated. Approvals, publishing, test picks and retrieval_mode leave it as it is.
- retrieval_modestringrequired
  One of vector_store hybrid
- test_publication_idstring | null
  The publication test chats search instead of the live one, or null.
- test_base_publication_idstring | null
  The live publication when the test one was picked; promoting is refused once live has moved on.
- created_atstringISO 8601 timestamp
- updated_atstringISO 8601 timestamp

400 invalid_knowledge_payload
401 Missing or invalid API key (unauthorized)
403 knowledge_owner_required: a project-scoped key, or a member who is not the organization owner
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

POST /api/knowledge

curl -X POST "https://api.myleadsfactory.tech/api/knowledge" \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Travel policies"
}'

Response 201

{
  "data": {
    "id": "kb_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "description": "string",
    "enabled": true,
    "active_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "version": 1,
    "retrieval_mode": "vector_store",
    "test_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "test_base_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

List knowledge bases

GET/api/knowledge

Every knowledge base in the organization, newest first. Needs an org-wide API key: project keys cannot use organization knowledge. A project key gets an empty list.

Secret API key, org-wide (not pinned to a project). How it works

Returns

200 OK

Response attributes

dataarray of KnowledgeBaserequired
12 attributes
- idstringrequired
  kb_...
- org_idstringrequired
- namestringrequired
- descriptionstringrequired
- enabledbooleanrequired
- active_publication_idstring | nullrequired
  The live publication, or null before the first publish.
- versionintegerrequired
  The content counter: bumped when sources change and when name, description or enabled is updated. Approvals, publishing, test picks and retrieval_mode leave it as it is.
- retrieval_modestringrequired
  One of vector_store hybrid
- test_publication_idstring | null
  The publication test chats search instead of the live one, or null.
- test_base_publication_idstring | null
  The live publication when the test one was picked; promoting is refused once live has moved on.
- created_atstringISO 8601 timestamp
- updated_atstringISO 8601 timestamp

401 Missing or invalid API key (unauthorized)
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

GET /api/knowledge

curl "https://api.myleadsfactory.tech/api/knowledge" \
  -H "Authorization: Bearer $MLF_API_KEY"

Response 200

{
  "data": [
    {
      "id": "kb_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "name": "Front desk",
      "description": "string",
      "enabled": true,
      "active_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "version": 1,
      "retrieval_mode": "vector_store",
      "test_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "test_base_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "created_at": "2026-10-28T09:30:00.000Z",
      "updated_at": "2026-10-28T09:30:00.000Z"
    }
  ]
}

The base with every source (and its latest revision), publications, the assistants answering from it (attachments), what open assistant drafts would change (pending) and member grants. Poll this after starting a publication until its status is ready.

Secret API key, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....

Returns

200 OK

Response attributes

dataKnowledgeBaseDetailrequired
20 attributes
- idstringrequired
  kb_...
- org_idstringrequired
- namestringrequired
- descriptionstringrequired
- enabledbooleanrequired
- active_publication_idstring | nullrequired
  The live publication, or null before the first publish.
- versionintegerrequired
  The content counter: bumped when sources change and when name, description or enabled is updated. Approvals, publishing, test picks and retrieval_mode leave it as it is.
- retrieval_modestringrequired
  One of vector_store hybrid
- test_publication_idstring | null
  The publication test chats search instead of the live one, or null.
- test_base_publication_idstring | null
  The live publication when the test one was picked; promoting is refused once live has moved on.
- created_atstringISO 8601 timestamp
- updated_atstringISO 8601 timestamp
- permissionstringrequired
  What the caller may do. API keys are publisher.
  One of viewer editor publisher
- can_manage_accessboolean
- configuredboolean
  Whether this deployment can index and search knowledge.
- sourcesarray of KnowledgeSourcerequired
  8 attributes
  - idstringrequired
    ksrc_...
  - titlestringrequired
  - kindstringrequired
    One of text url file
  - urlstring | null
  - audiencestringrequired
    One of public private
  - revoked_atstring | nullISO 8601 timestamp
  - expires_atstring | nullISO 8601 timestamp
  - revisionobject | nullrequired
    The latest revision.
    5 attributes
    idstringrequired
    krev_...
    approvedbooleanrequired
    charactersintegerrequired
    content_hashstringrequired
    created_atstringrequiredISO 8601 timestamp
- publicationsarray of KnowledgePublicationrequired
  8 attributes
  - idstringrequired
    kpub_...
  - statusstringrequired
    One of queued indexing ready failed
  - errorstring | null
  - retryingboolean
    True while a failed publication will be retried automatically: a provider indexing failure (indexing_failed, indexing_timeout or provider_file_missing), fewer than five attempts so far, and no source change since it was built. Keep polling while it is true; otherwise retry it yourself, or build again after a change.
  - hybrid_statusstring | null
    The hybrid search index for this publication, or null when it has none.
    One of queued indexing ready failed
  - base_versionintegerrequired
    The base version it was built from.
  - created_atstringrequiredISO 8601 timestamp
  - published_atstring | nullISO 8601 timestamp
- attachmentsarray of objectrequired
  5 attributes
  - assistant_idstringrequired
  - namestringrequired
  - chatbooleanrequired
  - voicebooleanrequired
  - priorityintegerrequired
- pendingarray of objectrequired
  What publishing each open assistant draft would change for this base.
  6 attributes
  - assistant_idstringrequired
  - namestringrequired
  - changestringrequired
    One of attach update detach
  - chatbooleanrequired
  - voicebooleanrequired
  - priorityintegerrequired
- grantsarray of objectrequired
  2 attributes
  - user_idstringrequired
  - rolestringrequired
    One of viewer editor publisher

401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

GET /api/knowledge/{id}

curl "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID" \
  -H "Authorization: Bearer $MLF_API_KEY"

Response 200

{
  "data": {
    "id": "kb_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "description": "string",
    "enabled": true,
    "active_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "version": 1,
    "retrieval_mode": "vector_store",
    "test_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "test_base_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z",
    "permission": "viewer",
    "can_manage_access": true,
    "configured": true,
    "sources": [
      {
        "id": "ksrc_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "title": "Front desk",
        "kind": "text",
        "url": "https://example.com/hook",
        "audience": "public",
        "revoked_at": "2026-10-28T09:30:00.000Z",
        "expires_at": "2026-10-28T09:30:00.000Z",
        "revision": {
          "id": "ksrc_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
          "approved": true,
          "characters": 1,
          "content_hash": "string",
          "created_at": "2026-10-28T09:30:00.000Z"
        }
      }
    ],
    "publications": [
      {
        "id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "status": "queued",
        "error": "string",
        "retrying": true,
        "hybrid_status": "queued",
        "base_version": 1,
        "created_at": "2026-10-28T09:30:00.000Z",
        "published_at": "2026-10-28T09:30:00.000Z"
      }
    ],
    "attachments": [
      {
        "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "chat": true,
        "voice": true,
        "priority": 1
      }
    ],
    "pending": [
      {
        "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "name": "Front desk",
        "change": "attach",
        "chat": true,
        "voice": true,
        "priority": 1
      }
    ],
    "grants": [
      {
        "user_id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "role": "viewer"
      }
    ]
  }
}

Update a knowledge base

PATCH/api/knowledge/{id}

Rename it, change its description, turn it off (enabled: false stops every attached assistant using it at once, without deleting anything), or choose how it is searched.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....

Request body

namestringup to 200 characters
Trimmed; 1 to 200 characters.
descriptionstringup to 2000 characters
enabledboolean
retrieval_modestring
How assistants search it. New bases use hybrid, which takes effect once the live publication's hybrid index is ready; until then search uses the vector store.
One of vector_store hybrid

Returns

200 OK

Response attributes

dataKnowledgeBaserequired
12 attributes
- idstringrequired
  kb_...
- org_idstringrequired
- namestringrequired
- descriptionstringrequired
- enabledbooleanrequired
- active_publication_idstring | nullrequired
  The live publication, or null before the first publish.
- versionintegerrequired
  The content counter: bumped when sources change and when name, description or enabled is updated. Approvals, publishing, test picks and retrieval_mode leave it as it is.
- retrieval_modestringrequired
  One of vector_store hybrid
- test_publication_idstring | null
  The publication test chats search instead of the live one, or null.
- test_base_publication_idstring | null
  The live publication when the test one was picked; promoting is refused once live has moved on.
- created_atstringISO 8601 timestamp
- updated_atstringISO 8601 timestamp

400 invalid_knowledge_payload
401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

PATCH /api/knowledge/{id}

curl -X PATCH "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID" \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Front desk",
  "description": "string"
}'

Response 200

{
  "data": {
    "id": "kb_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "name": "Front desk",
    "description": "string",
    "enabled": true,
    "active_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "version": 1,
    "retrieval_mode": "vector_store",
    "test_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "test_base_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

Add or revise a source

POST/api/knowledge/{id}/sources

Adds text, a web page (url) or a file (filename and base64: txt, md, html, docx or pdf up to 5 MB) and extracts its text as a new revision awaiting approval. Pass an existing source id to revise it. Only public sources are ever published; audience defaults to private and cannot change later. URL sources must be public HTTPS pages that robots.txt allows, without query or fragment.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....

Request body

idstring
An existing source to revise. Omit to add a new one.
kindstringrequired
One of text url file
titlestringrequiredup to 200 characters
Trimmed; 1 to 200 characters.
audiencestring
Fixed when the source is created.
One of public private
Default "private"
textstringup to 200000 characters
text sources: the content.
urlstringup to 2048 characters
url sources: the page to fetch.
filenamestringup to 200 characters
file sources: the name, whose extension picks the parser.
base64stringup to 7000000 characters
file sources: the file bytes, base64-encoded.
expires_atstring | nullISO 8601 timestamp
Stop using the source after this time.

Returns

201 Created; data.id is the source id, ksrc_...

Response attributes

dataobjectrequired
1 attribute
- idstringrequired

400 invalid_knowledge_payload (including text over 200,000 characters), source_text_required_or_too_large (empty text), invalid_source_id, or a URL or file code: invalid_source_url, public_https_url_required, source_path_not_allowed, source_disallowed_by_robots, source_address_not_public, source_redirect_not_allowed, source_too_large, source_needs_review_no_text, website_content_type_not_supported, unsupported_document_type, pdf_page_limit_reached, document_expansion_too_large
401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found, or source_not_found when revising
409 source_identity_is_immutable (a revision changed the kind, URL or audience: add a new source instead) or source_limit_reached (100 active sources)
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 source_fetch_failed (the page did not answer 200) or knowledge_operation_failed
503 knowledge_storage_not_configured: this deployment cannot store sources

POST /api/knowledge/{id}/sources

curl -X POST "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/sources" \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "url",
  "title": "Refund policy",
  "audience": "public",
  "url": "https://www.acmetravel.com/refunds"
}'

Response 201

{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Find a site's pages from its sitemap

POST/api/knowledge/{id}/discover

Reads the site's sitemap and returns up to 100 page URLs on the same origin that robots.txt allows, without importing anything. Add the ones you want as url sources.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....

Request body

urlstringrequiredup to 2048 characters
Any page on the site; its origin's /sitemap.xml is read.

Returns

200 Page URLs

Response attributes

dataarray of stringrequiredup to 100 items

400 invalid_knowledge_payload or a URL code such as public_https_url_required, source_disallowed_by_robots or source_address_not_public
401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

POST /api/knowledge/{id}/discover

curl -X POST "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/discover" \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/hook"
}'

Response 200

{
  "data": [
    "https://example.com/hook"
  ]
}

Grant a member access

POST/api/knowledge/{id}/grants/{userId}

Gives one organization member a role on this knowledge base: viewer reads, editor adds sources and attaches assistants, publisher also approves and publishes. Calling again changes the role. Requires an organization owner; an API key counts as one.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....
userIdstringrequired
The member's user id.

Request body

rolestringrequired
One of viewer editor publisher

Returns

200 Granted; data.id is the user id

Response attributes

dataobjectrequired
1 attribute
- idstringrequired

400 invalid_knowledge_payload
401 Missing or invalid API key (unauthorized)
403 knowledge_owner_required, or organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found or member_not_found
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

POST /api/knowledge/{id}/grants/{userId}

curl -X POST "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/grants/USER_ID" \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "viewer"
}'

Response 200

{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Remove a member's access

DELETE/api/knowledge/{id}/grants/{userId}

The member loses their role on this knowledge base. Requires an organization owner; an API key counts as one.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....
userIdstringrequired
The member's user id.

Returns

200 Removed

Response attributes

dataobjectrequired
1 attribute
- idstringrequired

401 Missing or invalid API key (unauthorized)
403 knowledge_owner_required, or organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found or member_not_found
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

DELETE /api/knowledge/{id}/grants/{userId}

curl -X DELETE "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/grants/USER_ID" \
  -H "Authorization: Bearer $MLF_API_KEY"

Response 200

{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Build a publication

POST/api/knowledge/{id}/publications

Snapshots every approved public source into a new immutable publication and indexes it in the background (202). Poll the knowledge base until the publication is ready, then publish it. Returns the pending build instead when one is already queued. No request body.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....

Returns

202 Queued; data.id is the publication id, kpub_...

Response attributes

dataobjectrequired
1 attribute
- idstringrequired

400 no_public_sources
401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found
409 review_all_public_sources_first or publication_limit_reached
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry
503 knowledge_not_configured, knowledge_storage_not_configured or knowledge_provider_not_configured

POST /api/knowledge/{id}/publications

curl -X POST "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/publications" \
  -H "Authorization: Bearer $MLF_API_KEY"

Response 202

{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Publish a ready publication

POST/api/knowledge/{id}/publications/{publicationId}/publish

Makes a ready publication the live one, atomically; publishing an older ready publication rolls back to it. 409 publication_not_ready, or sources_changed_rebuild_publication when sources changed since it was built.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....
publicationIdstringrequired
Publication id, kpub_....

Returns

200 Published

Response attributes

dataobjectrequired
1 attribute
- idstringrequired

401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found
409 publication_not_ready (also for an unknown publication id) or sources_changed_rebuild_publication
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

POST /api/knowledge/{id}/publications/{publicationId}/publish

curl -X POST "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/publications/PUBLICATION_ID/publish" \
  -H "Authorization: Bearer $MLF_API_KEY"

Response 200

{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Retry a failed publication

POST/api/knowledge/{id}/publications/{publicationId}/retry

Queues a failed publication for indexing again, from the files it already stored. A publication already queued, indexing or ready returns its id unchanged.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....
publicationIdstringrequired
Publication id, kpub_....

Returns

200 Queued again

Response attributes

dataobjectrequired
1 attribute
- idstringrequired

401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found, or failed_publication_not_found (no failed publication with that id)
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

POST /api/knowledge/{id}/publications/{publicationId}/retry

curl -X POST "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/publications/PUBLICATION_ID/retry" \
  -H "Authorization: Bearer $MLF_API_KEY"

Response 200

{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Try a publication in test chats

POST/api/knowledge/{id}/publications/{publicationId}/test

Test chats (on a test publishable key, or the console's test chat) search this ready publication instead of the live one, so new content can be tried before it goes live. Live chats are unchanged. Make it live with POST /knowledge/{id}/test-publication/promote. Requires publisher access.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....
publicationIdstringrequired
Publication id, kpub_....

Returns

200 Test chats now search it

Response attributes

dataobjectrequired
1 attribute
- idstringrequired

401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found
409 publication_not_ready (also for an unknown publication id) or sources_changed_rebuild_publication
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

POST /api/knowledge/{id}/publications/{publicationId}/test

curl -X POST "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/publications/PUBLICATION_ID/test" \
  -H "Authorization: Bearer $MLF_API_KEY"

Response 200

{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Preview a revision's extracted text

GET/api/knowledge/{id}/revisions/{revisionId}

The text extracted from a source revision, to check before approving it.

Secret API key, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....
revisionIdstringrequired
Revision id, krev_..., from the source's revision.id.

Returns

200 OK

Response attributes

dataKnowledgeRevisionPreviewrequired
4 attributes
- revision_idstringrequired
- titlestringrequired
- textstringrequired
- urlstring | null

401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found or revision_not_found
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry
503 knowledge_storage_not_configured

GET /api/knowledge/{id}/revisions/{revisionId}

curl "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/revisions/REVISION_ID" \
  -H "Authorization: Bearer $MLF_API_KEY"

Response 200

{
  "data": {
    "revision_id": "krev_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "title": "Front desk",
    "text": "Hi, can I book a trip to Lisbon in May?",
    "url": "https://example.com/hook"
  }
}

Approve a revision

POST/api/knowledge/{id}/revisions/{revisionId}/approve

Marks the extracted text as fit to publish. Every public source's latest revision must be approved before a publication can be built. Requires publisher access. No request body.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....
revisionIdstringrequired
Revision id, krev_....

Returns

200 Approved

Response attributes

dataobjectrequired
1 attribute
- idstringrequired

401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found or revision_not_found
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

POST /api/knowledge/{id}/revisions/{revisionId}/approve

curl -X POST "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/revisions/REVISION_ID/approve" \
  -H "Authorization: Bearer $MLF_API_KEY"

Response 200

{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Search a knowledge base

POST/api/knowledge/{id}/search

Runs a question against the live publication (or, with publication: test, the one test chats search) and returns the passages an assistant would get, for checking coverage. It only reads, so a read-only key may call it although it is a POST.

Secret API key, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....

Request body

querystringrequiredup to 2000 characters
publicationstring
test searches the publication test chats use.
One of live test
Default "live"

Returns

200 OK

Response attributes

dataKnowledgeSearchResultrequired
3 attributes
- statusstringrequired
  empty: nothing matched or nothing is published. unavailable: search failed this time.
  One of unattached skipped ok empty unavailable
- evidencearray of objectrequired
  8 attributes
  - knowledge_base_idstringrequired
  - publication_idstringrequired
  - source_idstringrequired
  - revision_idstringrequired
  - titlestringrequired
  - urlstring | nullrequired
  - textstringrequired
  - scorenumberrequired
    Similarity, for ordering only; not a confidence.
- elapsed_msintegerrequired

400 invalid_knowledge_payload
401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

POST /api/knowledge/{id}/search

curl -X POST "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/search" \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "Can I get a refund if my flight is cancelled?"
}'

Response 200

{
  "data": {
    "status": "unattached",
    "evidence": [
      {
        "knowledge_base_id": "kb_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "source_id": "ksrc_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "revision_id": "krev_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
        "title": "Front desk",
        "url": "https://example.com/hook",
        "text": "Hi, can I book a trip to Lisbon in May?",
        "score": 1
      }
    ],
    "elapsed_ms": 640
  }
}

Revoke a source

DELETE/api/knowledge/{id}/sources/{sourceId}

Answers stop using the source at once, even from the live publication; the next publication leaves it out.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....
sourceIdstringrequired
Source id, ksrc_....

Returns

200 Revoked; data is the source row with revoked_at set

Response attributes

dataobjectrequired
1 attribute
- idstringrequired

401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found or source_not_found
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

DELETE /api/knowledge/{id}/sources/{sourceId}

curl -X DELETE "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/sources/SOURCE_ID" \
  -H "Authorization: Bearer $MLF_API_KEY"

Response 200

{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Stop trying a publication

DELETE/api/knowledge/{id}/test-publication

Test chats go back to searching the live publication. Requires publisher access.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....

Returns

200 Cleared; data.id is the knowledge base id

Response attributes

dataobjectrequired
1 attribute
- idstringrequired

401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

DELETE /api/knowledge/{id}/test-publication

curl -X DELETE "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/test-publication" \
  -H "Authorization: Bearer $MLF_API_KEY"

Response 200

{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}

Make the tested publication live

POST/api/knowledge/{id}/test-publication/promote

Makes the publication test chats are searching the live one, then clears the test pick. Send expected_publication_id to be sure it is the one you tested. Refused when another publication went live after it was picked, since it may lack what that one added: try the publication again, or build a new one. Requires publisher access.

Secret API key, not read-only, org-wide (not pinned to a project). How it works

Path parameters

idstringrequired
Knowledge base id, kb_....

Request body

expected_publication_idstringnot empty
The publication you tested, kpub_...; 409 test_publication_changed when the test pick is another one.

Returns

200 Live; data.id is the publication id

Response attributes

dataobjectrequired
1 attribute
- idstringrequired

400 invalid_knowledge_payload
401 Missing or invalid API key (unauthorized)
403 organization_knowledge_access_required (a project-scoped key) or knowledge_forbidden (no grant, or too low a role)
404 knowledge_not_found
409 no_test_publication, test_publication_changed, test_publication_stale (another publication went live after this one was picked), publication_not_ready or sources_changed_rebuild_publication
429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
502 knowledge_operation_failed: an unexpected failure; retry

POST /api/knowledge/{id}/test-publication/promote

curl -X POST "https://api.myleadsfactory.tech/api/knowledge/KNOWLEDGE_ID/test-publication/promote" \
  -H "Authorization: Bearer $MLF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expected_publication_id": "kpub_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
}'

Response 200

{
  "data": {
    "id": "id_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f"
  }
}