Resolve citation links in a batch

curl --request POST \
  --url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/source_urls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_ids": [
    "<string>"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({document_ids: ['<string>']})
};

fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/source_urls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/source_urls"

payload = { "document_ids": ["<string>"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "list",
  "data": [
    {
      "object": "document.source_url",
      "document_id": "<string>",
      "url": "<string>",
      "expires_at": 123
    }
  ]
}

Documents

Resolve citation links in a batch

Batch form of the single-doc citation resolver - the N+1 replacement for calling GET /documents/{document_id}/source_url once per search hit. Resolves up to 50 documents in one round-trip. Authorization is on the KNOWLEDGE BASE (reader+), the same boundary as /search and the single-doc resolver: a caller who can search the store already reads its chunks, so a source URL follows the store ACL.

Per-item failures are returned INLINE - a document not in this knowledge base, a dangling native file, or a transient mint failure never fails the whole batch, which always returns 200. Each data entry is either a resolved document.source_url object or a { document_id, error } item; a failed item carries no object field, so detect it by the presence of error. Technical item failures (error.technical: true, e.g. MINT_FAILED / RESOLVE_FAILED) are retryable; business ones (NOT_FOUND, SOURCE_UNAVAILABLE) are terminal.

POST

knowledge_bases

{knowledgeBaseId}

source_urls

Resolve citation links in a batch

curl --request POST \
  --url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/source_urls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "document_ids": [
    "<string>"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({document_ids: ['<string>']})
};

fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/source_urls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/source_urls"

payload = { "document_ids": ["<string>"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "object": "list",
  "data": [
    {
      "object": "document.source_url",
      "document_id": "<string>",
      "url": "<string>",
      "expires_at": 123
    }
  ]
}

Authorizations

Authorization

string

header

required

User session JWT or instance API key (iak_*). Send as Authorization: Bearer <token>.

Path Parameters

knowledgeBaseId

string

required

Knowledge base id. Legacy physical prefix vs_ (the kb_ rename is deferred).

Maximum string length: 128

Pattern: ^vs_[A-Za-z0-9-]+$

Body

application/json

document_ids

string[]

required

Document ids to resolve (1-50 per request). Bounded strings, deliberately NOT pattern-constrained to ^vsf_ so legacy or backfilled ids still resolve.

Required array length: 1 - 50 elements

Required string length: 1 - 128

knowledge_base_id

string

Optional override of the path parameter (body wins).

Maximum string length: 128

agent_id

string

Agent context for trusted-workspace authorization, used when a trusted product resolves citations on an end user's behalf.

Maximum string length: 128

Response

One entry per requested document (order not guaranteed). Always 200, even when every item failed - inspect each entry.

Batch citation-resolution response. data holds one entry per requested document, in no guaranteed order; each entry is either a resolved document.source_url object or a per-item error object. Even a fully-failed batch returns 200 - inspect every item.

object

enum<string>

required

Available options:

list

data

object[]

required

Result of the lazy citation resolver. For uploaded_file, the URL is a short-lived native share URL minted BY THE STORAGE WORKSPACE (not the user - a knowledge-base reader may have no rights on the underlying file; chunk text is already readable through search, so the source follows the knowledge base's ACL). For all other source types, url is the document's source_url as-is and expires_at is null.

Option 1
Option 2

Hide child attributes

data.object

enum<string>

required

Available options:

document.source_url

data.document_id

string

required

Pattern: ^vsf_[A-Za-z0-9-]+$

data.source_type

enum<string>

required

Available options:

uploaded_file,

remote_file,

web_page,

connector_document

data.url

string<uri>

required

data.expires_at

integer | null

Unix seconds. Populated for minted short-lived URLs (uploaded_file) and null for every other source type. For a minted URL it is always set: if the file service's own expiry is missing or unparseable, a conservative request-time-plus-TTL estimate is returned rather than null, so callers always have a refresh signal. Re-resolve on expiry.

Resolve a citation link (lazy)List crawl seeds

⌘I

Introduction

Platform API

Agent Creator API

LLM Gateway API

Governance API

Knowledges API

Resolve citation links in a batch

Authorizations

Path Parameters

Body

Response