SONZAI
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"
}

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 <= 200

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",
      "content_type": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "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",
      "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

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

body*file
Formatbinary

Response Body

application/json

application/problem+json

curl -X POST "https://loading/api/v1/projects/string/knowledge/documents" \  -H "Content-Type: application/octet-stream" \  -d 'string'
{
  "$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",
  "content_type": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "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",
  "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"
}

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"
}

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

Default100
Formatint64
Range1 <= value <= 500
offset?integer

Pagination offset

Default0
Formatint64
Range0 <= value
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",
  "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"
        },
        "property2": {
          "doc_id": "string",
          "eff_date": "2019-08-24T14:15:22Z"
        }
      },
      "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"
}

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"
      },
      "property2": {
        "doc_id": "string",
        "eff_date": "2019-08-24T14:15:22Z"
      }
    },
    "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"
}

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"
}

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"
    },
    "property2": {
      "doc_id": "string",
      "eff_date": "2019-08-24T14:15:22Z"
    }
  },
  "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"
}

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"
        },
        "property2": {
          "doc_id": "string",
          "eff_date": "2019-08-24T14:15:22Z"
        }
      },
      "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"
    },
    "property2": {
      "doc_id": "string",
      "eff_date": "2019-08-24T14:15:22Z"
    }
  },
  "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