Skip to documentation
Weavers Docs

Pages and endpoints

Tab to navigate · Enter to openEsc to close
Back to Weavers
Menu

POST /api/knowledge-assistant/messages

Account required · HTTP API reference

All endpoints · Authentication and retries · Download OpenAPI

  • Requires a signed-in account and permission to access this resource. Use identifiers returned by your own account's earlier requests.
  • Protected writes require an allowed Origin, the CSRF cookie and matching X-CSRF-Token header.

Request

ParameterLocationType and requirement
x-idempotency-keyheaderstring · required

Pattern: ^[A-Za-z0-9_-]{8,128}$

Originheaderstring · required

An origin allowed by this deployment.

X-CSRF-Tokenheaderstring · required

Must match the CSRF cookie issued to this browser.

Body · application/json

conversationId required · string
message required · string
responseMode required · "answer" | "document_draft"

Example

Examples use fictional data. Replace identifiers with resources you can access. For account requests, cookies.txt must contain your own session; set CSRF_TOKEN to the matching CSRF cookie value where required.

Save as request.json
{
  "conversationId": "1",
  "message": "Explain the data used in this research.",
  "responseMode": "answer"
}
cURL (POSIX shell)
curl --include \
  --request POST \
  'https://api.weavers.app/api/knowledge-assistant/messages' \
  --cookie cookies.txt --cookie-jar cookies.txt \
  --header 'x-idempotency-key: example-request-0001' \
  --header 'Origin: https://weavers.app' \
  --header "X-CSRF-Token: ${CSRF_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

Responses

200 · Successful response.

application/json

200 example · synthetic data
{
  "model": "example",
  "answer": "example",
  "responseMode": "answer",
  "retrievalPlanHash": "example",
  "sources": [],
  "conversationId": "1",
  "userMessage": {
    "id": "1",
    "conversationId": "1",
    "role": "user",
    "content": "Explain the data used in this research.",
    "toolName": null,
    "toolCallId": null,
    "metadata": {},
    "promptTokens": 1,
    "completionTokens": 1,
    "totalTokens": 1,
    "latencyMs": null,
    "errorCode": null,
    "createdAt": "2025-01-01T00:00:00.000Z"
  },
  "assistantMessage": {
    "id": "1",
    "conversationId": "1",
    "role": "user",
    "content": "Explain the data used in this research.",
    "toolName": null,
    "toolCallId": null,
    "metadata": {},
    "promptTokens": 1,
    "completionTokens": 1,
    "totalTokens": 1,
    "latencyMs": null,
    "errorCode": null,
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}
View response model
model required · string
answer required · string
responseMode required · "answer" | "document_draft"
retrievalPlanHash required · string
sources required · array of object
View sources model

Array items:

citation required · number
title required · string
documentKey required · null | string
View documentKey model
Variant 1: null

null

Variant 2: string

string

revisionId required · null | string
View revisionId model
Variant 1: null

null

Variant 2: string

string

scopeKey required · string
sourceProvider required · string
evidenceKinds required · array of string
View evidenceKinds model

Array items:

string

authority required · string
sensitivity required · string
excerpt required · string
provenance required · object
View provenance model

Additional fields: JSON value.

Additional fields: JSON values.

conversationId required · string
userMessage required · object
View userMessage model
id required · string
conversationId required · string
role required · "user" | "assistant" | "system" | "tool"
content required · string
toolName required · null | string
View toolName model
Variant 1: null

null

Variant 2: string

string

toolCallId required · null | string
View toolCallId model
Variant 1: null

null

Variant 2: string

string

metadata required · object
View metadata model

Additional fields: JSON value.

promptTokens required · number
completionTokens required · number
totalTokens required · number
latencyMs required · null | number
View latencyMs model
Variant 1: null

null

Variant 2: number

number

errorCode required · null | string
View errorCode model
Variant 1: null

null

Variant 2: string

string

createdAt required · string

Additional fields: JSON values.

assistantMessage required · object
View assistantMessage model
id required · string
conversationId required · string
role required · "user" | "assistant" | "system" | "tool"
content required · string
toolName required · null | string
View toolName model
Variant 1: null

null

Variant 2: string

string

toolCallId required · null | string
View toolCallId model
Variant 1: null

null

Variant 2: string

string

metadata required · object
View metadata model

Additional fields: JSON value.

promptTokens required · number
completionTokens required · number
totalTokens required · number
latencyMs required · null | number
View latencyMs model
Variant 1: null

null

Variant 2: number

number

errorCode required · null | string
View errorCode model
Variant 1: null

null

Variant 2: string

string

createdAt required · string

Additional fields: JSON values.

Additional fields: JSON values.

400 · Invalid request.

application/json

400 example · synthetic data
{
  "error": "example",
  "code": "example"
}
View response model
error required · string
code required · string

Additional fields: JSON values.

401 · Authentication is missing or invalid.

application/json

401 example · synthetic data
{}
View response model

Error envelopes can include resource-specific details. Check the status before reading these fields.

error optional · string
code optional · string
message optional · string

Additional fields: JSON values.

403 · Permission, origin or CSRF check failed.

application/json

403 example · synthetic data
{}
View response model

Error envelopes can include resource-specific details. Check the status before reading these fields.

error optional · string
code optional · string
message optional · string

Additional fields: JSON values.

429 · Rate limit reached; honor Retry-After when supplied.

application/json

429 example · synthetic data
{}
View response model

Error envelopes can include resource-specific details. Check the status before reading these fields.

error optional · string
code optional · string
message optional · string

Additional fields: JSON values.

500 · Server failure.

application/json

500 example · synthetic data
{}
View response model

Error envelopes can include resource-specific details. Check the status before reading these fields.

error optional · string
code optional · string
message optional · string

Additional fields: JSON values.

default · Operation-specific error. Inspect error/code before deciding whether to retry.

application/json

default example · synthetic data
{
  "error": "example",
  "code": "conversation_busy",
  "retryable": false
}
View response model
error required · string
code required · "conversation_busy" | "knowledge_assistant_disabled" | "knowledge_assistant_forbidden" | "knowledge_release_unavailable" | "retrieval_plan_invalid" | "retrieval_no_sources" | "request_conflict" | "rag_timeout" | "nvidia_unavailable" | "rag_invalid_response" | "conversation_not_found" | "proposal_not_found" | "proposal_forbidden"
retryable required · boolean

Additional fields: JSON values.