Your AI Connector Docs

Knowledge Base API

Your knowledge base is what the AI reads from. It has two parts, and this page covers both:

  • Knowledge sources (/kb-sources) — the web pages and uploaded documents you feed the platform. Each one is read, split into sections, and turned into FAQs your AI can answer from.
  • Knowledge groups (/kb-groups) — named bundles of FAQs you can apply to an Agent or a campaign in a single call, so a body of knowledge you have already curated can be reused on the next Agent you create.

The FAQs a source produces land in the same library as the ones you write by hand, so once an import finishes you read, edit and link them with the FAQs API.

All endpoints below are relative to the base URL https://api.youraiconnector.com/v1. Every request must be authenticated — see API Access and Authentication. API access is a paid feature; without it, requests are rejected with a 403.

Importing costs credits. Reading a page or document and writing FAQs from it consumes credits, roughly in proportion to how much content there is. Use Estimate an import before committing to a large crawl.

How an import works

Importing is a background job, not something that finishes while you wait. Every import endpoint answers immediately with a source_id, and you poll that source until it is done:

  1. Start the import — POST /kb-sources/url (one page), POST /kb-sources/file (an uploaded document), or POST /kb-sources/bulk-import (up to 100 pages). You get back a source ID and status: "queued".
  2. Poll — GET /kb-sources/{sourceId} until status is no longer queued or processing.
  3. Read the FAQs — when the status is ready, the entries it produced are in your FAQ library: GET /faqs.

Every source reports one of these statuses:

Status What it means
queued Waiting to be read. Nothing has been charged yet.
processing Being read and turned into FAQs right now.
ready Finished. Its FAQs are in your library.
failed Could not be imported. error_message says why.
cancelled Stopped before it was read (see Stop an import).
paused Stopped because your own AI key failed mid-import (see Resume a paused import).
deleting A bulk removal is working through it.
unknown The record carries no status. Treat it as not ready.

Attach as you import. Pass autoLinkToAgentId on any import endpoint and the source — plus every FAQ it produces — lands on that Agent’s knowledge in the same call, with no follow-up linking step. autoLinkToCampaignId does the same for a classic campaign. Linking is best effort: an ID that does not exist, or belongs to another account, is skipped silently and the import still runs, so confirm the link by reading the Agent back.

Import a web page

POST /kb-sources/url

Adds one web page to your knowledge base.

Request fields

Field Required Description
url Yes Full http or https address of the page.
autoLinkToAgentId No ID of an AI Agent to attach the imported source to.
autoLinkToCampaignId No Legacy. ID of a campaign to attach the imported source to.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/url?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/url", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/pricing",
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { source_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://example.com/pricing",
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
source_id = res.json().get("source_id")

Response — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued",
  "batch_id": "batch_9f2a"
}

Poll source_id with Check a source until the status is ready or failed.

If the same page is already in your knowledge base, nothing new is queued and you get a 200 instead — and if you asked for an auto-link, the existing source is linked for you anyway:

{
  "success": true,
  "status": "exists",
  "skipped_duplicate": 1
}

A missing url, or one that is not a valid http/https address, returns 400.

Import an uploaded document

POST /kb-sources/file

Adds a document that is already in your account’s file storage as a knowledge source. Supported types: PDF, DOCX, TXT, MD, CSV and XLSX.

This endpoint does not carry the file. There is no multipart upload, no base64 body and no download-from-a-URL: you send the storage location of a file that already exists, and it must live under your own uploads folder (storage_path has to begin with users/{your user id}/uploads/) or the request is refused with 403. The dashboard puts files there when you drag them in. If you have no way to place a file there, import a web page with Import a web page instead.

Request fields

Field Required Description
storage_path Yes Where the uploaded file lives. Must start with users/{your user id}/uploads/.
filename Yes Original file name including its extension — this is how the file type is detected.
mime_type Yes MIME type of the file, for example application/pdf.
autoLinkToAgentId No ID of an AI Agent to attach the document to.
autoLinkToCampaignId No Legacy. ID of a campaign to attach the document to.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/file?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storage_path": "users/abc123uid/uploads/handbook.pdf",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

Response — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}
Status When
400 A required field is missing, or the file is not a type we can read.
403 storage_path is outside your own uploads folder.

Check a source

GET /kb-sources/{sourceId}

The poll that follows every import and refresh. Repeat it until the status is ready or failed.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const source = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
source = res.json()

Response

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "ready",
  "faq_count": 24,
  "section_count": 31,
  "error_message": null
}
Field Type Description
status string Where the source is in the pipeline (see the status table).
faq_count integer How many FAQs have been generated from this source so far.
section_count integer How many content sections the source was split into.
error_message string | null Why the import failed, when the status is failed. null otherwise.

Delete a source

DELETE /kb-sources/{sourceId}

Removes one knowledge source. By default the FAQs it produced are kept — add delete_faqs=true to remove those as well.

Query parameters

Parameter Required Description
delete_faqs No Set to true to also delete every FAQ this source produced. Defaults to false.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123?delete_faqs=true&apiKey=YOUR_API_KEY"

Response

{
  "success": true,
  "faqs_deleted": 24
}

faqs_deleted is 0 unless you asked for delete_faqs=true.

Import many pages at once

POST /kb-sources/bulk-import

Adds up to 100 web pages in one call — the usual follow-up to Discover pages on a website or Find new pages on a website. Pages already in your knowledge base are skipped rather than duplicated (and are still linked to the Agent when you asked for that).

Request fields

Field Required Description
urls Yes Addresses to import. At least 1, at most 100 per call.
autoLinkToAgentId No ID of an AI Agent to attach every imported page to.
autoLinkToCampaignId No Legacy. ID of a campaign to attach every imported page to.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing", "https://example.com/faq"],
    "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-sources/bulk-import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: ["https://example.com/pricing", "https://example.com/faq"],
    autoLinkToAgentId: "ag7HkQ2ZpLxR3mNb",
  }),
});
const { queued_source_ids } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-sources/bulk-import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "urls": ["https://example.com/pricing", "https://example.com/faq"],
        "autoLinkToAgentId": "ag7HkQ2ZpLxR3mNb",
    },
)
queued_source_ids = res.json()["queued_source_ids"]

Response — 202 Accepted

{
  "success": true,
  "batch_id": "batch_9f2a",
  "queued": 2,
  "skipped_duplicate": 0,
  "queued_source_ids": ["kb_src_abc123", "kb_src_def456"]
}

Poll each ID in queued_source_ids with Check a source. Sending an empty urls array, a non-string entry, or more than 100 entries returns 400.

Delete many sources at once

POST /kb-sources/bulk-delete

Removes up to 2,000 knowledge sources in one call. The removal runs in the background and you get an email when it finishes.

Bulk delete always removes the FAQs too. Unlike Delete a source, which keeps them unless you ask otherwise, this endpoint deletes each source together with the FAQs it produced. There is no option to keep them.

Request fields

Field Required Description
sourceIds Yes IDs of the sources to remove. At least 1, at most 2,000 per call.
domainLabel No A friendly name for this clean-up. Used only in the completion email.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIds": ["kb_src_abc123", "kb_src_def456"],
    "domainLabel": "example.com"
  }'

Response — 202 Accepted

{
  "success": true,
  "batch_id": "del_batch_31a",
  "queued": 2
}

Discover pages on a website

POST /kb-sources/discover-pages

Explores a website from one starting address and lists the pages found on the same domain, each with an opinion on whether it is worth importing. Nothing is imported and nothing is selected for you — this is the “what is on this site” step you run before deciding what to send to Import many pages at once.

Request fields

Field Required Description
url Yes Address to start exploring from, usually the site’s home page.
maxPages No Upper bound on how many pages to return.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/discover-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "maxPages": 100 }'

Response

{
  "success": true,
  "source_type": "sitemap",
  "pages": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing",
      "depth": 1,
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ]
}
Field Type Description
source_type string How the pages were found — sitemap (the site’s own sitemap) or link_discovery (by following links).
url string Full address of the page.
title string | null Page title, when one could be read.
depth integer How many links away from the starting page this page was found.
score integer How useful the page looks as knowledge, from 0 to 100.
recommendation string add (clearly worth importing, score 90 or above), maybe (borderline), or skip (content that rarely helps an assistant — changelogs, legal pages, duplicate translations).
reason_key string A stable, machine-readable reason behind the recommendation, for example core_page, changelog_history, legal_page or locale_duplicate.

Exploration is best effort. If the site cannot be read the response is still 200, with success: false, an empty pages list and an error message. Check success before reading pages.

A missing url returns 400.

Estimate what an import will cost

POST /kb-sources/estimate-cost

Works out how many credits a proposed import would consume, before you commit to it. Pages are fetched and documents are read to measure their size, but nothing is imported and the estimate itself does not spend credits.

Request fields

Field Required Description
urls No Page addresses you are considering importing.
files No Already-uploaded files you are considering. Each entry needs storage_path, filename and mime_type.
tier No The AI quality tier the import will run on, so the estimate matches what you will actually be charged. Leave it out for the standard rate.

Send urls, files, or both.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/estimate-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/pricing"] }'

Response

{
  "success": true,
  "estimates": [
    { "ref": "https://example.com/pricing", "chunks": 7, "credits": 7 }
  ],
  "total_chunks": 7,
  "total_credits": 7
}

Each row echoes back the URL or storage path in ref so you can match it to your input. A page or file that could not be read still gets a row, counted as one chunk, with an error on it.

Stop an import

POST /kb-sources/cancel-import

Stops pages that are still waiting in the import queue — the “stop import” button for a crawl that turned out bigger than you expected. Cancelling a waiting page costs nothing, because it has not been read yet.

Pages already being processed are not stopped: their work is under way and is charged either way, so they finish. The response reports how many those were.

Request fields

Field Required Description
host No Only stop waiting pages on this website (for example docs.example.com). Leave it out to stop every waiting import on the account.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/cancel-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "host": "docs.example.com" }'

Response

{
  "success": true,
  "cancelled": 412,
  "in_flight": 3
}

Resume a paused import

POST /kb-sources/resume-import

Restarts an import that was paused because your own AI key stopped working.

Calling this is your consent to finish the import on whichever key is live now — which may mean spending platform credits if your own key is still down.

Request fields

Field Required Description
host No Only resume paused pages on this website. Leave it out to resume everything paused.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/resume-import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "success": true,
  "resumed": 58
}

Find new pages on a website

POST /kb-sources/refresh-domain

Explores a website you have already imported from and reports only the pages that are not in your knowledge base yet, each with the same recommendation as page discovery. Nothing is imported and nothing is changed.

The two follow-ups are deliberately separate calls, so walking away from this one costs nothing:

Request fields

Field Required Description
baseUrl Yes Any address on the website, or just the host.
maxPages No Upper bound on how many pages to explore.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Response

{
  "success": true,
  "source_type": "sitemap",
  "discovered": 249,
  "new_pages": [
    {
      "url": "https://example.com/new-guide",
      "score": 95,
      "recommendation": "add",
      "reason_key": "core_page"
    }
  ],
  "new_urls_queued": 0,
  "existing_refresh_queued": 249
}
Field Type Description
discovered integer How many pages were found on the site in total.
new_pages array Pages not in your knowledge base yet. Nothing is queued for you — import the ones you want.
new_urls_queued integer Always 0. Kept for backwards compatibility; this endpoint never queues anything.
existing_refresh_queued integer How many pages you already imported from this site were found ready to be re-read. Nothing is queued by this call.
batch_id string Present only when a batch was created.

Like discovery, this fails softly: a site that cannot be read still returns 200, with success: false, an empty new_pages and an error. A missing or empty baseUrl returns 400.

Refresh every page on a website

POST /kb-sources/trigger-domain-refresh

Re-reads every page you have already imported from a website, so its FAQs follow the site’s current content: changed sections are updated, new sections added and removed sections dropped.

This queues work and returns immediately. Follow it with Track a website refresh, and stop it with Stop a website refresh.

Request fields

Field Required Description
baseUrl Yes Any address on the website, or just the host.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/trigger-domain-refresh?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "baseUrl": "https://example.com" }'

Response

{
  "success": true,
  "queued": 249
}

Track a website refresh

GET /kb-sources/domain-refresh-status

How far along a website refresh is, so you can show progress like “221 of 249”.

Query parameters

Parameter Required Description
baseUrl Yes Any address on the website, or just the host.

cURL

curl "https://api.youraiconnector.com/v1/kb-sources/domain-refresh-status?baseUrl=https://example.com&apiKey=YOUR_API_KEY"

Response

{
  "success": true,
  "job": {
    "domainBatchId": "job_7c1e",
    "host": "example.com",
    "total": 249,
    "pending": 28,
    "succeeded": 219,
    "failed": 2,
    "skippedDuplicate": 0,
    "status": "refreshing",
    "startedAtIso": "2026-06-15T09:00:00.000Z"
  }
}

job is null when no refresh is running for that website. Pages finished so far is total minus pending. The job status is one of refreshing (still working through pages), deduplicating (the clean-up pass at the end), or the final completed, failed and cancelled. Keep domainBatchId — it is what you pass to the cancel endpoint.

A missing or empty baseUrl returns 400.

Stop a website refresh

POST /kb-sources/refresh-domain/cancel

Stops a website refresh that is still working through its pages. Pages already finished keep their updated content; pages not started are dropped, and pages that were being re-read go back to their previous state.

Request fields

Field Required Description
jobId Yes The domainBatchId returned by Track a website refresh.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/refresh-domain/cancel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "job_7c1e" }'

Response

{
  "success": true,
  "status": "cancelled",
  "cancelled_units": 28,
  "sources_reset": 3,
  "sources_cancelled": 25
}
Field Type Description
status string State of the refresh after this call: cancelled, deduplicating, completed or failed.
cancelled_units integer How much work was still outstanding when the cancel landed. 0 on a repeat cancel.
sources_reset integer Pages taken back out of processing and returned to ready.
sources_cancelled integer Brand-new pages of this refresh that were still queued and are now cancelled.

Cancelling twice is harmless — the second call reports the same final state. Once the refresh has moved on to its clean-up pass it can no longer be stopped, and the response comes back with success: false and reason: "already_finalizing". A missing jobId returns 400, and a job that is not in your account returns 404.

Refresh a single source

POST /kb-sources/{sourceId}/refresh

Re-reads one web page you have already imported and brings its FAQs back in line with the page’s current content: changed sections are updated, new ones added, removed ones dropped.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/kb_src_abc123/refresh?apiKey=YOUR_API_KEY"

Response — 202 Accepted

{
  "success": true,
  "source_id": "kb_src_abc123",
  "status": "queued"
}

Poll the source until its status leaves queued and processing. A source ID that is not in your account returns 404.

Pick the most relevant pages

POST /kb-sources/select-relevant-pages

Asks the AI to pick the five pages, out of a list of candidates, that best describe a business — used when generating a campaign playbook from a website. This consumes credits.

Request fields

Field Required Description
urls Yes Candidate page addresses to choose from, usually from page discovery.
homeUrl Yes The site’s home page, used as context for the choice.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-sources/select-relevant-pages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "homeUrl": "https://example.com",
    "urls": ["https://example.com/about", "https://example.com/pricing"]
  }'

Response

{
  "success": true,
  "pages": [
    { "url": "https://example.com/pricing", "title": "Pricing", "type": "pricing" }
  ]
}

This is a helper, not a resource: on failure it still answers 200, with success: false, an empty pages list and an error message.

Knowledge groups

A knowledge group is a named bundle of FAQs — “Shipping and returns”, “Onboarding” — that you can apply to an Agent or a campaign in one call. The group holds references, not copies: the FAQs themselves stay in your single library, so editing one with the FAQs API updates it everywhere it is used.

Applying a group only ever adds what is missing, so applying the same group twice is harmless and added_count comes back as 0 the second time.

Create a knowledge group

POST /kb-groups

Creates a group. It starts empty — add FAQs to it with Add a FAQ to a group.

Request fields

Field Required Description
name Yes Name of the group.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping and returns" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/kb-groups", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Shipping and returns" }),
});
const { group_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Shipping and returns"},
)
group_id = res.json()["group_id"]

Response — 201 Created

{
  "success": true,
  "group_id": "kbg_abc123"
}

Rename a knowledge group

PUT /kb-groups/{groupId}

Changes a group’s name. Its FAQs are untouched.

Request fields

Field Required Description
name Yes New name for the group.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Shipping, returns and refunds" }'

Response

{
  "success": true,
  "group_id": "kbg_abc123",
  "name": "Shipping, returns and refunds"
}

Delete a knowledge group

DELETE /kb-groups/{groupId}

Deletes the group. Only the bundle is removed — the FAQs in it stay in your library, and anything the group was already applied to keeps those FAQs.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123?apiKey=YOUR_API_KEY"

Response

{
  "success": true
}

Add a FAQ to a group

POST /kb-groups/{groupId}/faqs

Puts an existing FAQ into a group. This only changes the bundle — it does not attach the FAQ to any Agent by itself; apply the group for that.

Request fields

Field Required Description
faq_id Yes ID of the FAQ to add.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_id": "aBcD1234eFgH5678" }'

Response

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Remove a FAQ from a group

DELETE /kb-groups/{groupId}/faqs/{faqId}

Takes a FAQ out of a group. The FAQ itself is not deleted, and Agents the group was already applied to keep it.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

Response

{
  "success": true,
  "group_id": "kbg_abc123",
  "faq_id": "aBcD1234eFgH5678"
}

Apply a group to an Agent

POST /kb-groups/{groupId}/apply-to-agent

Adds every FAQ in the group to an AI Agent’s knowledge in one call — the fast way to give a new Agent a body of knowledge you have already curated.

Request fields

Field Required Description
agent_id Yes ID of the AI Agent to apply the group to.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "ag7HkQ2ZpLxR3mNb" }),
  }
);
const { added_count } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agent_id": "ag7HkQ2ZpLxR3mNb"},
)
added_count = res.json()["added_count"]

Response

{
  "success": true,
  "group_id": "kbg_abc123",
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "added_count": 12
}

added_count is how many FAQs were actually added — 0 when the group is empty or already applied.

Apply a group to a campaign

POST /kb-groups/{groupId}/apply-to-campaign

The classic-campaign version of the call above. On an Agent-based account use Apply a group to an Agent instead.

Request fields

Field Required Description
campaign_id Yes ID of the campaign to apply the group to.

cURL

curl -X POST "https://api.youraiconnector.com/v1/kb-groups/kbg_abc123/apply-to-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign123" }'

Response

{
  "success": true,
  "group_id": "kbg_abc123",
  "campaign_id": "campaign123",
  "added_count": 12
}

Knowledge Base API errors

These endpoints return the standard error envelope:

{
  "success": false,
  "error": "Knowledge base source not found."
}
Status When it happens on a knowledge base endpoint
400 A required field is missing or invalid — an empty url, a missing baseUrl or jobId, more than 100 URLs in a bulk import, more than 2,000 IDs in a bulk delete, or a file type we cannot read.
402 Not enough credits to run the import. Top up and try again.
403 A storage_path outside your own uploads folder — or your plan does not include API access.
404 The source, group, FAQ, Agent, campaign or refresh job was not found — either it does not exist or it belongs to another account.

Soft failures are not errors. Discovery (discover-pages, refresh-domain) and the page-picking helper answer 200 with success: false and an error message when the website cannot be read, rather than failing the request. Always check success before reading the data.

The shared codes every endpoint can return — 401, 403 (your plan does not include API access), 429 (rate limit) and 500 — are listed with retry guidance in Errors & Pagination.

  • FAQs API — read, edit and link the FAQs your sources produce.
  • Managing FAQs — the same knowledge base in the dashboard.
  • AI Agents — the Agents you attach sources and groups to.
  • API Access — generate your API key.
  • Authentication — all the ways to pass your key.