Knowledge Base API Guide | XY Developer Platform

What you are creating

Agent, installation, source, execution.

A Knowledge Base is not a Planner prompt and not a global document bucket. It is one installation of the entitled knowledge-base-answering agent.

1

Agent

Discover the published version and its live setup, input, output, and source schemas.

2

Installation

Set its name, behavior prompt, description, and one to ten initial sources.

3

Sources

Index bounded websites or uploaded files; add up to 100 sources per installation.

4

Execution

Ask a question asynchronously and poll for an answered or no_context result.

Install

Start with bounded, authoritative sources.

Only agent versions published and entitled to your organization appear in the catalog. Read the live agent detail before installation instead of hard-coding an old schema.

Create an installation with a URL source

curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Idempotency-Key: policy-kb-v1" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/agents/knowledge-base-answering/installations" \
  --data '{
    "name": "Operations policy knowledge base",
    "description": "Approved operating policies and procedures.",
    "system_prompt": "Answer only from indexed sources. Say when the sources do not establish an answer.",
    "initial_sources": [
      {
        "type": "url",
        "url": "https://docs.example.com/policies/",
        "crawl_limit": 50
      }
    ]
  }'

URL source

Must use HTTP or HTTPS.
Performs a bounded whole-site crawl from the supplied URL.
crawl_limit accepts 1–500 pages and defaults to 50.
Indexing starts durably after source creation.

File source

Maximum file size is 50 MB.
Supports PDF, JSON, CSV, Markdown/text, common Office formats, and GIF/JPEG/PNG/WebP images.
Uploads go directly to a short-lived signed URL.
Indexing starts only after the completion call.

Upload

Create, upload, complete.

File ingestion is a three-step handshake so the API never proxies large document bytes through the Marketplace service.

Add a PDF source

# 1. Create a file source and receive a short-lived signed PUT action.
curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Idempotency-Key: policy-pdf-v1" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/installations/${INSTALLATION_ID}/sources" \
  --data '{
    "type": "file",
    "file_name": "policy-manual.pdf",
    "content_type": "application/pdf"
  }'

# 2. Use the returned upload URL with the exact content type and file bytes.
curl --fail-with-body --request PUT \
  --header "Content-Type: application/pdf" \
  --upload-file ./policy-manual.pdf \
  'SIGNED_UPLOAD_URL'

# 3. Tell XY the upload is complete so durable indexing can start.
curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  "${XY_API_BASE}/installations/${INSTALLATION_ID}/sources/${SOURCE_ID}/complete"

Readiness

Ready and degraded can both answer questions.

Source indexing is asynchronous and durable. Poll source or installation state; do not wait on the create connection.

Installation status	Meaning	Can execute?
action_required	At least one initial file still awaits its upload/completion action.	No
indexing	Initial sources are still being crawled or indexed.	No
ready	All initial sources indexed successfully.	Yes
degraded	At least one source indexed and another failed.	Yes, against indexed sources
failed	No initial source indexed successfully.	No

Individual sources move through awaiting_upload,indexing, indexed,failed, deleting, anddeleted. A failed source is visible and does not silently become evidence.

Query

Ask through an execution, not a special chat session.

Questions use the normal Marketplace execution lifecycle. Creation returns asynchronously; poll the public execution ID until it reaches a terminal result.

Create a question execution

curl --fail-with-body --request POST \
  --header "Authorization: Bearer ${XY_API_KEY}" \
  --header "Idempotency-Key: question-1842" \
  --header "Content-Type: application/json" \
  "${XY_API_BASE}/installations/${INSTALLATION_ID}/executions" \
  --data '{
    "input": {
      "question": "When does the escalation policy require human review?",
      "response_instructions": "Answer concisely and identify the supporting source.",
      "max_chunks": 5
    },
    "metadata": {"partner_reference": "question-1842"}
  }'

Stable result shape

{
  "outcome": "answered",
  "answer": "Human review is required when …",
  "confidence": 0.91,
  "reasoning": null,
  "sources": [
    {
      "source_id": "src_REPLACE",
      "name": "policy-manual.pdf",
      "excerpt": "…supporting passage…"
    }
  ]
}

max_chunks accepts 1–20 and defaults to 5.response_instructions can adjust answer format for this execution without changing the installation's long-lived behavior prompt.

Operate

Manage knowledge separately from application code.

Sources remain organization-scoped and can be listed, inspected, added, or deleted after installation. Deletion removes the source from future retrieval.

Trace sources

Persist source IDs alongside your own document registry so updates and deletions are deliberate.

Use partner references

Attach your question ID in execution metadata and reconcile the asynchronous response to your system.

Measure outcomes

Read the agent or installation's approved metrics through the governed metrics endpoints.

Review the agent resource model Open live Knowledge Base schemas