Resolve a citation link (lazy)

curl --request GET \
  --url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId}/source_url \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId}/source_url', 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}/documents/{documentId}/source_url"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "object": "document.source_url",
  "document_id": "vsf_550e8400-e29b-41d4-a716-446655440000",
  "source_type": "uploaded_file",
  "url": "https://api.studio.prisme.ai/v2/files/wsp_acme/nf_8GkX2p9QwLmZ4rTv1bCdE.report.pdf?token=temp_hmac",
  "expires_at": 1717000300
}

Documents

Resolve a citation link (lazy)

Citation resolver. Authorization is on the VECTOR STORE (reader+), not on the underlying file: a caller who can search the store already reads the content as chunks, so the source follows the store’s ACL. For uploaded_file, the storage workspace (privileged) mints a short-lived native share URL (~5 min) and returns it with expires_at; callers re-resolve on expiry. For other source types, returns source_url as-is; a document with no stored source_url, or an uploaded_file whose native file is owned by another workspace, resolves to 404 SOURCE_UNAVAILABLE.

Frontends should call this lazily - when the user clicks a citation - never eagerly for every search hit.

GET

/

v1

/

knowledge_bases

/

{knowledgeBaseId}

/

documents

/

{documentId}

/

source_url

Resolve a citation link (lazy)

curl --request GET \
  --url https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId}/source_url \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://{host}/v2/workspaces/slug:storage/webhooks/v1/knowledge_bases/{knowledgeBaseId}/documents/{documentId}/source_url', 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}/documents/{documentId}/source_url"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "object": "document.source_url",
  "document_id": "vsf_550e8400-e29b-41d4-a716-446655440000",
  "source_type": "uploaded_file",
  "url": "https://api.studio.prisme.ai/v2/files/wsp_acme/nf_8GkX2p9QwLmZ4rTv1bCdE.report.pdf?token=temp_hmac",
  "expires_at": 1717000300
}

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-]+$

documentId

string

required

Document id. Legacy physical prefix vsf_ (the doc_ rename is deferred).

Maximum string length: 128

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

Response

Resolved URL.

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.

object

enum<string>

required

Available options:

document.source_url

document_id

string

required

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

source_type

enum<string>

required

Available options:

uploaded_file,

remote_file,

web_page,

connector_document

url

string<uri>

required

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.