DocsModelsGuidesReferenceLearn
Api

Knowledge

Get conversion statistics

GET
/projects/{projectId}/knowledge/analytics/conversions

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Query Parameters

rule_id*string

Rule ID

segment?string

Optional segment key filter

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/analytics/conversions?rule_id=string"
{
  "$schema": "/api/v1/schemas/KbGetConversionStatsOutputBody.json",
  "conversions": [
    {
      "avg_days_to_convert": 0.1,
      "computed_at": "2019-08-24T14:15:22Z",
      "conversion_count": 0,
      "conversion_rate": 0.1,
      "project_id": "string",
      "rule_id": "string",
      "segment_key": "string",
      "shown_count": 0,
      "target_type": "string",
      "top_features": {
        "property1": null,
        "property2": null
      },
      "total_leads": 0
    }
  ],
  "total": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Record recommendation feedback

POST
/projects/{projectId}/knowledge/analytics/feedback

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/analytics/feedback" \  -H "Content-Type: application/json" \  -d '{    "converted": true,    "rule_id": "string",    "score_at_time": 0.1,    "source_node_id": "string",    "target_node_id": "string"  }'
{
  "$schema": "/api/v1/schemas/KbRecordFeedbackOutputBody.json",
  "status": "string"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get trend rankings

GET
/projects/{projectId}/knowledge/analytics/rankings

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Query Parameters

rule_id*string

Rule ID

type*string

Ranking type

window*string

Time window

limit?integer

Max results

Default10
Formatint64
Range1 <= value <= 100

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/analytics/rankings?rule_id=string&type=string&window=string"
{
  "$schema": "/api/v1/schemas/KbGetTrendRankingsOutputBody.json",
  "rankings": [
    {
      "computed_at": "2019-08-24T14:15:22Z",
      "node_id": "string",
      "node_label": "string",
      "project_id": "string",
      "rank": 0,
      "ranking_type": "string",
      "rule_id": "string",
      "value": 0.1,
      "window": "string"
    }
  ],
  "total": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get knowledge base recommendations

GET
/projects/{projectId}/knowledge/analytics/recommendations

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Query Parameters

source_id*string

Source node ID

rule_id*string

Rule ID

limit?integer

Max results

Default10
Formatint64
Range1 <= value <= 100

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/analytics/recommendations?source_id=string&rule_id=string"
{
  "$schema": "/api/v1/schemas/KbGetRecommendationsOutputBody.json",
  "recommendations": [
    {
      "computed_at": "2019-08-24T14:15:22Z",
      "project_id": "string",
      "reasoning": {
        "property1": null,
        "property2": null
      },
      "rule_id": "string",
      "score": 0.1,
      "source_node_id": "string",
      "target_label": "string",
      "target_node_id": "string",
      "target_type": "string"
    }
  ],
  "total": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

List analytics rules

GET
/projects/{projectId}/knowledge/analytics/rules

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/analytics/rules"
{
  "$schema": "/api/v1/schemas/KbListAnalyticsRulesOutputBody.json",
  "rules": [
    {
      "$schema": "/api/v1/schemas/KBAnalyticsRule.json",
      "config": null,
      "created_at": "2019-08-24T14:15:22Z",
      "enabled": true,
      "last_run_at": "2019-08-24T14:15:22Z",
      "last_run_duration_ms": 0,
      "last_run_status": "string",
      "name": "string",
      "project_id": "string",
      "rule_id": "string",
      "rule_type": "string",
      "schedule": "string",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "total": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Create an analytics rule

POST
/projects/{projectId}/knowledge/analytics/rules

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/analytics/rules" \  -H "Content-Type: application/json" \  -d '{    "config": null,    "enabled": true,    "name": "string",    "rule_type": "string"  }'
{
  "$schema": "/api/v1/schemas/KBAnalyticsRule.json",
  "config": null,
  "created_at": "2019-08-24T14:15:22Z",
  "enabled": true,
  "last_run_at": "2019-08-24T14:15:22Z",
  "last_run_duration_ms": 0,
  "last_run_status": "string",
  "name": "string",
  "project_id": "string",
  "rule_id": "string",
  "rule_type": "string",
  "schedule": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get an analytics rule

GET
/projects/{projectId}/knowledge/analytics/rules/{ruleId}

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

ruleId*string

Rule UUID

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/analytics/rules/string"
{
  "$schema": "/api/v1/schemas/KBAnalyticsRule.json",
  "config": null,
  "created_at": "2019-08-24T14:15:22Z",
  "enabled": true,
  "last_run_at": "2019-08-24T14:15:22Z",
  "last_run_duration_ms": 0,
  "last_run_status": "string",
  "name": "string",
  "project_id": "string",
  "rule_id": "string",
  "rule_type": "string",
  "schedule": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Delete an analytics rule

DELETE
/projects/{projectId}/knowledge/analytics/rules/{ruleId}

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

ruleId*string

Rule UUID

Response Body

application/problem+json

curl -X DELETE "https://loading/api/v1/projects/string/knowledge/analytics/rules/string"
Empty
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Update an analytics rule

PUT
/projects/{projectId}/knowledge/analytics/rules/{ruleId}

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

ruleId*string

Rule UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X PUT "https://loading/api/v1/projects/string/knowledge/analytics/rules/string" \  -H "Content-Type: application/json" \  -d '{    "enabled": true  }'
{
  "$schema": "/api/v1/schemas/KBAnalyticsRule.json",
  "config": null,
  "created_at": "2019-08-24T14:15:22Z",
  "enabled": true,
  "last_run_at": "2019-08-24T14:15:22Z",
  "last_run_duration_ms": 0,
  "last_run_status": "string",
  "name": "string",
  "project_id": "string",
  "rule_id": "string",
  "rule_type": "string",
  "schedule": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Manually trigger an analytics rule

POST
/projects/{projectId}/knowledge/analytics/rules/{ruleId}/run

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

ruleId*string

Rule UUID

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/analytics/rules/string/run"
{
  "$schema": "/api/v1/schemas/KbRunAnalyticsRuleOutputBody.json",
  "message": "string",
  "rule_id": "string",
  "status": "string"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}
GET
/projects/{projectId}/knowledge/analytics/trends

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Query Parameters

node_id*string

Node ID to get trends for

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/analytics/trends?node_id=string"
{
  "$schema": "/api/v1/schemas/KbGetTrendsOutputBody.json",
  "total": 0,
  "trends": [
    {
      "computed_at": "2019-08-24T14:15:22Z",
      "max_value": 0.1,
      "metric_name": "string",
      "min_value": 0.1,
      "node_id": "string",
      "project_id": "string",
      "sample_count": 0,
      "value": 0.1,
      "window": "string"
    }
  ]
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Bulk update node properties

PATCH
/projects/{projectId}/knowledge/bulk-update

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X PATCH "https://loading/api/v1/projects/string/knowledge/bulk-update" \  -H "Content-Type: application/json" \  -d '{    "updates": [      {        "entity_type": "string",        "label": "string",        "properties": {          "property1": null,          "property2": null        }      }    ]  }'
{
  "$schema": "/api/v1/schemas/KbBulkUpdateOutputBody.json",
  "count": 0,
  "created": 0,
  "not_found": 0,
  "processed": 0,
  "status": "string",
  "updated": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Compare a property across entities via a shared relation

POST
/projects/{projectId}/knowledge/compare

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/compare" \  -H "Content-Type: application/json" \  -d '{    "entities": [      {        "key": {          "property1": null,          "property2": null        },        "type": "string"      }    ],    "property_path": "string",    "target_entity": {      "key": {        "property1": null,        "property2": null      },      "type": "string"    },    "via_relation": "string"  }'
{
  "$schema": "/api/v1/schemas/KbCompareOutputBody.json",
  "rows": [
    {
      "entity": {
        "key": {
          "property1": null,
          "property2": null
        },
        "type": "string"
      },
      "fact": {
        "created_at": "2019-08-24T14:15:22Z",
        "effective_date": "2019-08-24T14:15:22Z",
        "extraction_confidence": 0.1,
        "fact_id": "string",
        "from_node_id": "string",
        "is_active": true,
        "properties": {
          "property1": null,
          "property2": null
        },
        "relation_type": "string",
        "source_document_id": "string",
        "source_page": 0,
        "source_snippet": "string",
        "to_node_id": "string",
        "version": 0
      },
      "missing": true,
      "missing_reason": "string",
      "value": null
    }
  ]
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

List knowledge base documents

GET
/projects/{projectId}/knowledge/documents

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Query Parameters

limit?integer

Max documents to return

Default50
Formatint64
Range1 <= value <= 1000

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/documents"
{
  "$schema": "/api/v1/schemas/KbListDocumentsOutputBody.json",
  "documents": [
    {
      "$schema": "/api/v1/schemas/KBDocument.json",
      "checksum": "string",
      "classification_candidates_json": "string",
      "classification_confidence": 0.1,
      "classification_status": "string",
      "content_type": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "doc_type": "string",
      "document_id": "string",
      "edge_count": 0,
      "effective_date": "2019-08-24T14:15:22Z",
      "error_msg": "string",
      "extraction_tokens": 0,
      "file_name": "string",
      "file_size": 0,
      "gcs_path": "string",
      "node_count": 0,
      "project_id": "string",
      "root_entity_key": "string",
      "root_entity_node_id": "string",
      "root_entity_type": "string",
      "schema_version_used": 0,
      "status": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "uploaded_by": "string"
    }
  ],
  "total": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Upload a document for knowledge extraction

POST
/projects/{projectId}/knowledge/documents

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Query Parameters

force_replace?boolean

If true, replace existing document with identical content

Defaultfalse

Request Body

multipart/form-data

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/documents"
{
  "$schema": "/api/v1/schemas/KbUploadDocumentOutputBody.json",
  "checksum": "string",
  "document_id": "string",
  "file_name": "string",
  "file_size": 0,
  "gcs_path": "string",
  "status": "string"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get a single document

GET
/projects/{projectId}/knowledge/documents/{docId}

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

docId*string

Document UUID

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/documents/string"
{
  "$schema": "/api/v1/schemas/KBDocument.json",
  "checksum": "string",
  "classification_candidates_json": "string",
  "classification_confidence": 0.1,
  "classification_status": "string",
  "content_type": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "doc_type": "string",
  "document_id": "string",
  "edge_count": 0,
  "effective_date": "2019-08-24T14:15:22Z",
  "error_msg": "string",
  "extraction_tokens": 0,
  "file_name": "string",
  "file_size": 0,
  "gcs_path": "string",
  "node_count": 0,
  "project_id": "string",
  "root_entity_key": "string",
  "root_entity_node_id": "string",
  "root_entity_type": "string",
  "schema_version_used": 0,
  "status": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "uploaded_by": "string"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Delete a document

DELETE
/projects/{projectId}/knowledge/documents/{docId}

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

docId*string

Document UUID

Response Body

application/problem+json

curl -X DELETE "https://loading/api/v1/projects/string/knowledge/documents/string"
Empty
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Resolve a needs_classification document

PATCH
/projects/{projectId}/knowledge/documents/{documentId}/classification

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

documentId*string

Document UUID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X PATCH "https://loading/api/v1/projects/string/knowledge/documents/string/classification" \  -H "Content-Type: application/json" \  -d '{    "root_entity": {      "key": {        "property1": null,        "property2": null      },      "type": "string"    }  }'
{
  "$schema": "/api/v1/schemas/KbPatchClassificationOutputBody.json",
  "document_id": "string",
  "status": "string"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Per-document billed cost breakdown

GET
/projects/{projectId}/knowledge/documents/{documentId}/cost

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

documentId*string

Document UUID.

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/documents/string/cost"
{
  "$schema": "/api/v1/schemas/KbDocCostOutputBody.json",
  "document_ai_rows": [
    {
      "cost_usd": 0.1,
      "model": "string",
      "operation": "string",
      "pages": 0
    }
  ],
  "document_id": "string",
  "llm_rows": [
    {
      "cost_usd": 0.1,
      "model": "string",
      "operation": "string",
      "pages": 0
    }
  ],
  "total_cost_usd": 0.1
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Re-ingest a previously uploaded document

POST
/projects/{projectId}/knowledge/documents/{documentId}/reingest

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

documentId*string

Document UUID.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/documents/string/reingest"
{
  "$schema": "/api/v1/schemas/KbReingestOutputBody.json",
  "document_id": "string",
  "mode": "string",
  "status": "string"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Direct entity lookup by (type, key)

GET
/projects/{projectId}/knowledge/entities/{entityType}/{entityKey}

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

entityType*string

Entity type (e.g. 'hospital').

entityKey*string

URL-encoded JSON of the entity's key fields (e.g. '%7B%22name%22%3A%22Mt+Elizabeth%22%7D').

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/entities/string/string"
{
  "$schema": "/api/v1/schemas/KbGetEntityOutputBody.json",
  "entity_key": {
    "property1": null,
    "property2": null
  },
  "entity_node_id": "string",
  "entity_type": "string",
  "incoming_facts": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "effective_date": "2019-08-24T14:15:22Z",
      "extraction_confidence": 0.1,
      "fact_id": "string",
      "from_node_id": "string",
      "is_active": true,
      "properties": {
        "property1": null,
        "property2": null
      },
      "relation_type": "string",
      "source_document_id": "string",
      "source_page": 0,
      "source_snippet": "string",
      "to_node_id": "string",
      "version": 0
    }
  ],
  "outgoing_facts": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "effective_date": "2019-08-24T14:15:22Z",
      "extraction_confidence": 0.1,
      "fact_id": "string",
      "from_node_id": "string",
      "is_active": true,
      "properties": {
        "property1": null,
        "property2": null
      },
      "relation_type": "string",
      "source_document_id": "string",
      "source_page": 0,
      "source_snippet": "string",
      "to_node_id": "string",
      "version": 0
    }
  ]
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

List active KB facts for a project

GET
/projects/{projectId}/knowledge/facts

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

Query Parameters

limit?integer

Max facts to return (default 50, max 500).

Formatint64
page_token?string

Opaque pagination cursor returned by the previous response.

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/facts"
{
  "$schema": "/api/v1/schemas/KbListFactsOutputBody.json",
  "facts": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "effective_date": "2019-08-24T14:15:22Z",
      "extraction_confidence": 0.1,
      "fact_id": "string",
      "from_node_id": "string",
      "is_active": true,
      "properties": {
        "property1": null,
        "property2": null
      },
      "relation_type": "string",
      "source_document_id": "string",
      "source_page": 0,
      "source_snippet": "string",
      "to_node_id": "string",
      "version": 0
    }
  ],
  "next_page_token": "string"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Insert facts into the knowledge base

POST
/projects/{projectId}/knowledge/facts

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/facts" \  -H "Content-Type: application/json" \  -d '{    "facts": [      {        "entity_type": "string",        "label": "string",        "properties": {          "property1": null,          "property2": null        }      }    ]  }'
{
  "$schema": "/api/v1/schemas/KbInsertFactsOutputBody.json",
  "created": 0,
  "details": [
    {
      "action": "string",
      "label": "string",
      "node_id": "string",
      "type": "string",
      "version": 0
    }
  ],
  "edges": [
    {
      "edge_id": "string",
      "from_node": "string",
      "relation": "string",
      "to_node": "string"
    }
  ],
  "processed": 0,
  "updated": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get the active KB fact for a (from, to, relation) tuple

GET
/projects/{projectId}/knowledge/facts/active

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

Query Parameters

from_node_id?string

Fact tuple component.

to_node_id?string

Fact tuple component.

relation_type?string

Fact tuple component.

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/facts/active"
{
  "$schema": "/api/v1/schemas/KbGetFactOutputBody.json",
  "fact": {
    "created_at": "2019-08-24T14:15:22Z",
    "effective_date": "2019-08-24T14:15:22Z",
    "extraction_confidence": 0.1,
    "fact_id": "string",
    "from_node_id": "string",
    "is_active": true,
    "properties": {
      "property1": null,
      "property2": null
    },
    "relation_type": "string",
    "source_document_id": "string",
    "source_page": 0,
    "source_snippet": "string",
    "to_node_id": "string",
    "version": 0
  }
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get the version chain for a KB fact tuple

GET
/projects/{projectId}/knowledge/facts/history

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

Query Parameters

from_node_id?string

Fact tuple component.

to_node_id?string

Fact tuple component.

relation_type?string

Fact tuple component.

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/facts/history"
{
  "$schema": "/api/v1/schemas/KbGetFactHistoryOutputBody.json",
  "versions": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "effective_date": "2019-08-24T14:15:22Z",
      "extraction_confidence": 0.1,
      "fact_id": "string",
      "from_node_id": "string",
      "is_active": true,
      "properties": {
        "property1": null,
        "property2": null
      },
      "relation_type": "string",
      "source_document_id": "string",
      "source_page": 0,
      "source_snippet": "string",
      "to_node_id": "string",
      "version": 0
    }
  ]
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

List multimodal KB schema versions for a project

GET
/projects/{projectId}/knowledge/multimodal-schemas

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/multimodal-schemas"
{
  "$schema": "/api/v1/schemas/KbMultimodalSchemaListOutputBody.json",
  "schemas": [
    {
      "$schema": "/api/v1/schemas/KBSchema.json",
      "config": {
        "abstain_below_confidence": 0.1,
        "classify_auto_threshold": 0.1,
        "classify_model": "string",
        "extract_min_provenance_confidence": 0.1,
        "extract_model": "string",
        "ingestion_verifier_model": "string",
        "schema_propose_model": "string",
        "use_document_ai_preprocessor": true
      },
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": "string",
      "doc_types": [
        {
          "expected_relationships": [
            "string"
          ],
          "root_entity_type": "string",
          "type": "string"
        }
      ],
      "entity_types": [
        {
          "aliases_field": "string",
          "is_root_candidate": true,
          "key_fields": [
            "string"
          ],
          "properties": [
            {
              "description": "string",
              "name": "string",
              "required": true,
              "type": "string"
            }
          ],
          "type": "string"
        }
      ],
      "project_id": "string",
      "relationship_types": [
        {
          "from": "string",
          "properties": [
            {
              "description": "string",
              "name": "string",
              "required": true,
              "type": "string"
            }
          ],
          "supersession_identity": [
            "string"
          ],
          "to": "string",
          "type": "string"
        }
      ],
      "schema_version": 0,
      "status": "string",
      "template_lineage": "string",
      "vertical_template": "string"
    }
  ]
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Create a new multimodal KB schema version

POST
/projects/{projectId}/knowledge/multimodal-schemas

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/multimodal-schemas" \  -H "Content-Type: application/json" \  -d '{    "config": {},    "created_at": "2019-08-24T14:15:22Z",    "doc_types": [      {        "root_entity_type": "string",        "type": "string"      }    ],    "entity_types": [      {        "is_root_candidate": true,        "key_fields": [          "string"        ],        "type": "string"      }    ],    "project_id": "string",    "relationship_types": [      {        "from": "string",        "supersession_identity": [          "string"        ],        "to": "string",        "type": "string"      }    ],    "schema_version": 0,    "status": "string"  }'
{
  "$schema": "/api/v1/schemas/KbMultimodalSchemaCreateOutputBody.json",
  "schema": {
    "$schema": "/api/v1/schemas/KBSchema.json",
    "config": {
      "abstain_below_confidence": 0.1,
      "classify_auto_threshold": 0.1,
      "classify_model": "string",
      "extract_min_provenance_confidence": 0.1,
      "extract_model": "string",
      "ingestion_verifier_model": "string",
      "schema_propose_model": "string",
      "use_document_ai_preprocessor": true
    },
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": "string",
    "doc_types": [
      {
        "expected_relationships": [
          "string"
        ],
        "root_entity_type": "string",
        "type": "string"
      }
    ],
    "entity_types": [
      {
        "aliases_field": "string",
        "is_root_candidate": true,
        "key_fields": [
          "string"
        ],
        "properties": [
          {
            "description": "string",
            "name": "string",
            "required": true,
            "type": "string"
          }
        ],
        "type": "string"
      }
    ],
    "project_id": "string",
    "relationship_types": [
      {
        "from": "string",
        "properties": [
          {
            "description": "string",
            "name": "string",
            "required": true,
            "type": "string"
          }
        ],
        "supersession_identity": [
          "string"
        ],
        "to": "string",
        "type": "string"
      }
    ],
    "schema_version": 0,
    "status": "string",
    "template_lineage": "string",
    "vertical_template": "string"
  }
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Activate a draft multimodal schema version

POST
/projects/{projectId}/knowledge/multimodal-schemas/{version}/activate

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

version*integer

Schema version to activate.

Formatint64

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/multimodal-schemas/0/activate"
{
  "$schema": "/api/v1/schemas/KbMultimodalSchemaActivateOutputBody.json",
  "active_version": 0,
  "status": "string"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

List knowledge base nodes

GET
/projects/{projectId}/knowledge/nodes

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Query Parameters

type?string

Filter by node type

limit?integer

Max results in single response

Default100
Formatint64
Range1 <= value <= 10000
sort_by?string

Sort field (label, node_type, created_at, updated_at, version, or properties.*)

sort_order?string

Sort direction: asc or desc

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/nodes"
{
  "$schema": "/api/v1/schemas/KbListNodesOutputBody.json",
  "has_more": true,
  "nodes": [
    {
      "$schema": "/api/v1/schemas/KBNode.json",
      "confidence": 0.1,
      "created_at": "2019-08-24T14:15:22Z",
      "is_active": true,
      "label": "string",
      "node_id": "string",
      "node_type": "string",
      "norm_label": "string",
      "project_id": "string",
      "properties": {
        "property1": null,
        "property2": null
      },
      "property_sources": {
        "property1": {
          "doc_id": "string",
          "eff_date": "2019-08-24T14:15:22Z",
          "source": "string"
        },
        "property2": {
          "doc_id": "string",
          "eff_date": "2019-08-24T14:15:22Z",
          "source": "string"
        }
      },
      "scope_id": "string",
      "source_docs": [
        "string"
      ],
      "source_type": "string",
      "tenant_id": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "version": 0
    }
  ]
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Agent: create a knowledge base node

POST
/projects/{projectId}/knowledge/nodes

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Header Parameters

X-Agent-Id?string

ID of the agent making the call (stamped onto PropertySource.Source)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/nodes" \  -H "Content-Type: application/json" \  -d '{    "label": "string",    "node_type": "string",    "properties": {      "property1": null,      "property2": null    }  }'
{
  "$schema": "/api/v1/schemas/KbAgentCreateNodeOutputBody.json",
  "node": {
    "$schema": "/api/v1/schemas/KBNode.json",
    "confidence": 0.1,
    "created_at": "2019-08-24T14:15:22Z",
    "is_active": true,
    "label": "string",
    "node_id": "string",
    "node_type": "string",
    "norm_label": "string",
    "project_id": "string",
    "properties": {
      "property1": null,
      "property2": null
    },
    "property_sources": {
      "property1": {
        "doc_id": "string",
        "eff_date": "2019-08-24T14:15:22Z",
        "source": "string"
      },
      "property2": {
        "doc_id": "string",
        "eff_date": "2019-08-24T14:15:22Z",
        "source": "string"
      }
    },
    "scope_id": "string",
    "source_docs": [
      "string"
    ],
    "source_type": "string",
    "tenant_id": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "version": 0
  }
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get a knowledge base node with edges

GET
/projects/{projectId}/knowledge/nodes/{nodeId}

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

nodeId*string

Node UUID

Query Parameters

history?string

Set to 'true' to include version history

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/nodes/string"
{
  "$schema": "/api/v1/schemas/KbGetNodeOutputBody.json",
  "history": [
    {
      "change_type": "string",
      "changed_at": "2019-08-24T14:15:22Z",
      "changed_by": "string",
      "node_id": "string",
      "project_id": "string",
      "properties": {
        "property1": null,
        "property2": null
      },
      "version": 0
    }
  ],
  "incoming": [
    {
      "confidence": 0.1,
      "created_at": "2019-08-24T14:15:22Z",
      "edge_id": "string",
      "edge_type": "string",
      "from_node_id": "string",
      "label": "string",
      "project_id": "string",
      "properties": {
        "property1": null,
        "property2": null
      },
      "scope_id": "string",
      "source_doc": "string",
      "tenant_id": "string",
      "to_node_id": "string",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "node": {
    "$schema": "/api/v1/schemas/KBNode.json",
    "confidence": 0.1,
    "created_at": "2019-08-24T14:15:22Z",
    "is_active": true,
    "label": "string",
    "node_id": "string",
    "node_type": "string",
    "norm_label": "string",
    "project_id": "string",
    "properties": {
      "property1": null,
      "property2": null
    },
    "property_sources": {
      "property1": {
        "doc_id": "string",
        "eff_date": "2019-08-24T14:15:22Z",
        "source": "string"
      },
      "property2": {
        "doc_id": "string",
        "eff_date": "2019-08-24T14:15:22Z",
        "source": "string"
      }
    },
    "scope_id": "string",
    "source_docs": [
      "string"
    ],
    "source_type": "string",
    "tenant_id": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "version": 0
  },
  "outgoing": [
    {
      "confidence": 0.1,
      "created_at": "2019-08-24T14:15:22Z",
      "edge_id": "string",
      "edge_type": "string",
      "from_node_id": "string",
      "label": "string",
      "project_id": "string",
      "properties": {
        "property1": null,
        "property2": null
      },
      "scope_id": "string",
      "source_doc": "string",
      "tenant_id": "string",
      "to_node_id": "string",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Agent: update a knowledge base node with per-property CAS

PATCH
/projects/{projectId}/knowledge/nodes/{nodeId}

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

nodeId*string

Node UUID

Header Parameters

X-Agent-Id?string

ID of the agent making the call (stamped onto PropertySource.Source on each changed property)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X PATCH "https://loading/api/v1/projects/string/knowledge/nodes/string" \  -H "Content-Type: application/json" \  -d '{    "properties": {      "property1": {        "current": null,        "new": null      },      "property2": {        "current": null,        "new": null      }    }  }'
{
  "$schema": "/api/v1/schemas/KbAgentUpdateNodeOutputBody.json",
  "node": {
    "$schema": "/api/v1/schemas/KBNode.json",
    "confidence": 0.1,
    "created_at": "2019-08-24T14:15:22Z",
    "is_active": true,
    "label": "string",
    "node_id": "string",
    "node_type": "string",
    "norm_label": "string",
    "project_id": "string",
    "properties": {
      "property1": null,
      "property2": null
    },
    "property_sources": {
      "property1": {
        "doc_id": "string",
        "eff_date": "2019-08-24T14:15:22Z",
        "source": "string"
      },
      "property2": {
        "doc_id": "string",
        "eff_date": "2019-08-24T14:15:22Z",
        "source": "string"
      }
    },
    "scope_id": "string",
    "source_docs": [
      "string"
    ],
    "source_type": "string",
    "tenant_id": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "version": 0
  }
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Delete a knowledge base node

DELETE
/projects/{projectId}/knowledge/nodes/{nodeId}

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

nodeId*string

Node UUID

Response Body

application/problem+json

curl -X DELETE "https://loading/api/v1/projects/string/knowledge/nodes/string"
Empty
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Agent: soft-delete a knowledge base node with label CAS

POST
/projects/{projectId}/knowledge/nodes/{nodeId}/agent-delete

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

nodeId*string

Node UUID

Header Parameters

X-Agent-Id?string

ID of the agent making the call (logged for audit)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/nodes/string/agent-delete" \  -H "Content-Type: application/json" \  -d '{    "expected_label": "string"  }'
{
  "$schema": "/api/v1/schemas/KbAgentDeleteNodeOutputBody.json",
  "ok": true
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get node version history

GET
/projects/{projectId}/knowledge/nodes/{nodeId}/history

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

nodeId*string

Node UUID

Query Parameters

limit?integer

Max history entries

Default50
Formatint64
Range1 <= value <= 200

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/nodes/string/history"
{
  "$schema": "/api/v1/schemas/KbGetNodeHistoryOutputBody.json",
  "history": [
    {
      "change_type": "string",
      "changed_at": "2019-08-24T14:15:22Z",
      "changed_by": "string",
      "node_id": "string",
      "project_id": "string",
      "properties": {
        "property1": null,
        "property2": null
      },
      "version": 0
    }
  ],
  "total": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Promote a project-scoped node to the organization-global scope

POST
/projects/{projectId}/knowledge/nodes/{nodeId}/promote-to-org

Path Parameters

projectId*string

Project UUID that currently owns the node

nodeId*string

Node UUID to promote

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tenant_id*string

Target tenant; server rejects if it does not match the authenticated tenant.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/nodes/string/promote-to-org" \  -H "Content-Type: application/json" \  -d '{    "tenant_id": "string"  }'
{
  "$schema": "/api/v1/schemas/KBNodeWithScope.json",
  "confidence": 0.1,
  "created_at": "2019-08-24T14:15:22Z",
  "is_active": true,
  "label": "string",
  "node_id": "string",
  "node_type": "string",
  "norm_label": "string",
  "project_id": "string",
  "properties": {
    "property1": null,
    "property2": null
  },
  "property_sources": {
    "property1": {
      "doc_id": "string",
      "eff_date": "2019-08-24T14:15:22Z",
      "source": "string"
    },
    "property2": {
      "doc_id": "string",
      "eff_date": "2019-08-24T14:15:22Z",
      "source": "string"
    }
  },
  "relevance": 0.1,
  "scope_id": "string",
  "scope_type": "string",
  "source_docs": [
    "string"
  ],
  "source_type": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

List entity schemas

GET
/projects/{projectId}/knowledge/schemas

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/schemas"
{
  "$schema": "/api/v1/schemas/KbListSchemasOutputBody.json",
  "schemas": [
    {
      "$schema": "/api/v1/schemas/KBEntitySchema.json",
      "created_at": "2019-08-24T14:15:22Z",
      "description": "string",
      "display_name": "string",
      "entity_type": "string",
      "fields": [
        {
          "description": "string",
          "enum_values": [
            "string"
          ],
          "indexed": true,
          "name": "string",
          "required": true,
          "type": "string"
        }
      ],
      "project_id": "string",
      "schema_id": "string",
      "similarity_config": {
        "enabled": true,
        "field_weights": {
          "property1": 0.1,
          "property2": 0.1
        },
        "max_edges_per_node": 0,
        "threshold": 0.1
      },
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "total": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Create an entity schema

POST
/projects/{projectId}/knowledge/schemas

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/schemas" \  -H "Content-Type: application/json" \  -d '{    "entity_type": "string",    "fields": [      {        "name": "string",        "required": true,        "type": "string"      }    ]  }'
{
  "$schema": "/api/v1/schemas/KBEntitySchema.json",
  "created_at": "2019-08-24T14:15:22Z",
  "description": "string",
  "display_name": "string",
  "entity_type": "string",
  "fields": [
    {
      "description": "string",
      "enum_values": [
        "string"
      ],
      "indexed": true,
      "name": "string",
      "required": true,
      "type": "string"
    }
  ],
  "project_id": "string",
  "schema_id": "string",
  "similarity_config": {
    "enabled": true,
    "field_weights": {
      "property1": 0.1,
      "property2": 0.1
    },
    "max_edges_per_node": 0,
    "threshold": 0.1
  },
  "updated_at": "2019-08-24T14:15:22Z"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Delete an entity schema

DELETE
/projects/{projectId}/knowledge/schemas/{schemaId}

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

schemaId*string

Schema UUID

Response Body

application/problem+json

curl -X DELETE "https://loading/api/v1/projects/string/knowledge/schemas/string"
Empty
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Update an entity schema

PUT
/projects/{projectId}/knowledge/schemas/{schemaId}

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

schemaId*string

Schema UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X PUT "https://loading/api/v1/projects/string/knowledge/schemas/string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "$schema": "/api/v1/schemas/KBEntitySchema.json",
  "created_at": "2019-08-24T14:15:22Z",
  "description": "string",
  "display_name": "string",
  "entity_type": "string",
  "fields": [
    {
      "description": "string",
      "enum_values": [
        "string"
      ],
      "indexed": true,
      "name": "string",
      "required": true,
      "type": "string"
    }
  ],
  "project_id": "string",
  "schema_id": "string",
  "similarity_config": {
    "enabled": true,
    "field_weights": {
      "property1": 0.1,
      "property2": 0.1
    },
    "max_edges_per_node": 0,
    "threshold": 0.1
  },
  "updated_at": "2019-08-24T14:15:22Z"
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Search the knowledge base

GET
/projects/{projectId}/knowledge/search

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Query Parameters

q*string

Search query text

limit?integer

Max results

Default20
Formatint64
Range1 <= value <= 100
depth?integer

Graph traversal depth (1 or 2)

Default1
Formatint64
Range1 <= value <= 2
history?string

Set to 'true' to include version history per result

type?string

Comma-separated entity types to filter

mode?string

Search mode: bm25, semantic, hybrid, or auto

filters?string

JSON object of property filters

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/search?q=string"
{
  "$schema": "/api/v1/schemas/KBSearchResponse.json",
  "query": "string",
  "results": [
    {
      "history": [
        {
          "change_type": "string",
          "changed_at": "2019-08-24T14:15:22Z",
          "changed_by": "string",
          "node_id": "string",
          "project_id": "string",
          "properties": {
            "property1": null,
            "property2": null
          },
          "version": 0
        }
      ],
      "label": "string",
      "node_id": "string",
      "properties": {
        "property1": null,
        "property2": null
      },
      "related": [
        {
          "edge": "string",
          "label": "string",
          "node_id": "string",
          "properties": {
            "property1": null,
            "property2": null
          },
          "type": "string"
        }
      ],
      "score": 0.1,
      "source": "string",
      "type": "string",
      "updated_at": "string",
      "version": 0
    }
  ],
  "total": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Get knowledge base statistics

GET
/projects/{projectId}/knowledge/stats

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/stats"
{
  "$schema": "/api/v1/schemas/KbGetStatsOutputBody.json",
  "documents": {
    "property1": 0,
    "property2": 0
  },
  "edges": 0,
  "extraction_tokens": 0,
  "nodes": {
    "property1": 0,
    "property2": 0
  }
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Graph traversal from a starting entity

GET
/projects/{projectId}/knowledge/traverse

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

projectId*string

Project UUID.

Query Parameters

from_type?string

Starting entity type.

from_key?string

Starting entity key (URL-encoded JSON).

relation_type?string

Relation to traverse.

direction?string

outbound | inbound | both (default outbound).

max_depth?integer

Traversal depth (default 1, max 3).

Formatint64

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/projects/string/knowledge/traverse"
{
  "$schema": "/api/v1/schemas/KbTraverseOutputBody.json",
  "facts": [
    {
      "depth": 0,
      "fact": {
        "created_at": "2019-08-24T14:15:22Z",
        "effective_date": "2019-08-24T14:15:22Z",
        "extraction_confidence": 0.1,
        "fact_id": "string",
        "from_node_id": "string",
        "is_active": true,
        "properties": {
          "property1": null,
          "property2": null
        },
        "relation_type": "string",
        "source_document_id": "string",
        "source_page": 0,
        "source_snippet": "string",
        "to_node_id": "string",
        "version": 0
      }
    }
  ]
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

List nodes in the organization-global KB scope

GET
/tenants/{tenantId}/knowledge/org-nodes

Path Parameters

tenantId*string

Tenant UUID whose organization-global KB scope is listed.

Query Parameters

limit?integer

Max number of nodes to return; 0 = all rows in the partition.

Default200
Formatint64
Range0 <= value <= 2000

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/tenants/string/knowledge/org-nodes"
{
  "$schema": "/api/v1/schemas/KbListOrgNodesOutputBody.json",
  "nodes": [
    {
      "$schema": "/api/v1/schemas/KBNode.json",
      "confidence": 0.1,
      "created_at": "2019-08-24T14:15:22Z",
      "is_active": true,
      "label": "string",
      "node_id": "string",
      "node_type": "string",
      "norm_label": "string",
      "project_id": "string",
      "properties": {
        "property1": null,
        "property2": null
      },
      "property_sources": {
        "property1": {
          "doc_id": "string",
          "eff_date": "2019-08-24T14:15:22Z",
          "source": "string"
        },
        "property2": {
          "doc_id": "string",
          "eff_date": "2019-08-24T14:15:22Z",
          "source": "string"
        }
      },
      "scope_id": "string",
      "source_docs": [
        "string"
      ],
      "source_type": "string",
      "tenant_id": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "version": 0
    }
  ],
  "total": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Create a knowledge-base node in the organization-global scope

POST
/tenants/{tenantId}/knowledge/org-nodes

Path Parameters

tenantId*string

Tenant UUID — scope_id for the write is the empty string so the node lives in the organization-global scope.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/tenants/string/knowledge/org-nodes" \  -H "Content-Type: application/json" \  -d '{    "label": "string",    "node_type": "string"  }'
{
  "$schema": "/api/v1/schemas/KBNode.json",
  "confidence": 0.1,
  "created_at": "2019-08-24T14:15:22Z",
  "is_active": true,
  "label": "string",
  "node_id": "string",
  "node_type": "string",
  "norm_label": "string",
  "project_id": "string",
  "properties": {
    "property1": null,
    "property2": null
  },
  "property_sources": {
    "property1": {
      "doc_id": "string",
      "eff_date": "2019-08-24T14:15:22Z",
      "source": "string"
    },
    "property2": {
      "doc_id": "string",
      "eff_date": "2019-08-24T14:15:22Z",
      "source": "string"
    }
  },
  "scope_id": "string",
  "source_docs": [
    "string"
  ],
  "source_type": "string",
  "tenant_id": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}
{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Inventory

Previous Page

Knowledge Org

Next Page