SONZAI
Api

Memory

Get memory tree nodes for an agent

GET
/agents/{agentId}/memory

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Query Parameters

user_id?string

Optional user ID to scope memory

instance_id?string

Optional instance ID for scoping

parent_id?string

If set, return children of this node

include_contents?string

Set to 'true' to include fact contents per node

scope?string

Optional scope filter (e.g. 'wisdom')

limit?string

Max nodes to return (default 50, max 200)

memory_type?string

Optional filter: only return nodes with this memory_type (e.g. 'factual', 'episodic', 'semantic', 'procedural', 'identity', 'temporal', 'relational'). When user_id is also set, routes to the indexed memory_tree_nodes_by_type table (O(1)); otherwise falls back to post-fetch filter.

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/agents/string/memory"
{
  "$schema": "/api/v1/schemas/MemoryResponse.json",
  "contents": {
    "property1": [
      {
        "$schema": "/api/v1/schemas/AtomicFact.json",
        "agent_framing": "string",
        "agent_id": "string",
        "atomic_text": "string",
        "character_salience": 0.1,
        "chunk_id": "string",
        "cluster_id": "string",
        "confidence": 0.1,
        "created_at": "2019-08-24T14:15:22Z",
        "emotional_intensity": 0.1,
        "entities": [
          "string"
        ],
        "episode_id": "string",
        "event_time": "2019-08-24T14:15:22Z",
        "evidence_message_ids": [
          "string"
        ],
        "fact_id": "string",
        "fact_type": "string",
        "hit_count": 0,
        "importance": 0.1,
        "inferred_entities": [
          "string"
        ],
        "last_confirmed": "2019-08-24T14:15:22Z",
        "last_retrieved_at": "2019-08-24T14:15:22Z",
        "mention_count": 0,
        "metadata": {
          "property1": null,
          "property2": null
        },
        "miss_count": 0,
        "node_id": "string",
        "polarity_group_id": "string",
        "relationship_relevance": 0.1,
        "retention_strength": 0.1,
        "sentiment": "string",
        "session_id": "string",
        "source_id": "string",
        "source_type": "string",
        "supersedes_id": "string",
        "temporal_relevance": "string",
        "time_sensitive_at": "2019-08-24T14:15:22Z",
        "topic_tags": [
          "string"
        ],
        "updated_at": "2019-08-24T14:15:22Z",
        "user_id": "string"
      }
    ],
    "property2": [
      {
        "$schema": "/api/v1/schemas/AtomicFact.json",
        "agent_framing": "string",
        "agent_id": "string",
        "atomic_text": "string",
        "character_salience": 0.1,
        "chunk_id": "string",
        "cluster_id": "string",
        "confidence": 0.1,
        "created_at": "2019-08-24T14:15:22Z",
        "emotional_intensity": 0.1,
        "entities": [
          "string"
        ],
        "episode_id": "string",
        "event_time": "2019-08-24T14:15:22Z",
        "evidence_message_ids": [
          "string"
        ],
        "fact_id": "string",
        "fact_type": "string",
        "hit_count": 0,
        "importance": 0.1,
        "inferred_entities": [
          "string"
        ],
        "last_confirmed": "2019-08-24T14:15:22Z",
        "last_retrieved_at": "2019-08-24T14:15:22Z",
        "mention_count": 0,
        "metadata": {
          "property1": null,
          "property2": null
        },
        "miss_count": 0,
        "node_id": "string",
        "polarity_group_id": "string",
        "relationship_relevance": 0.1,
        "retention_strength": 0.1,
        "sentiment": "string",
        "session_id": "string",
        "source_id": "string",
        "source_type": "string",
        "supersedes_id": "string",
        "temporal_relevance": "string",
        "time_sensitive_at": "2019-08-24T14:15:22Z",
        "topic_tags": [
          "string"
        ],
        "updated_at": "2019-08-24T14:15:22Z",
        "user_id": "string"
      }
    ]
  },
  "nodes": [
    {
      "access_count": 0,
      "agent_id": "string",
      "child_count": 0,
      "content_count": 0,
      "content_refs": [
        "string"
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "cross_refs": [
        "string"
      ],
      "depth": 0,
      "description": "string",
      "importance": 0.1,
      "is_deleted": true,
      "is_prunable": true,
      "last_accessed_at": "2019-08-24T14:15:22Z",
      "memory_type": "string",
      "metadata": {
        "property1": null,
        "property2": null
      },
      "name": "string",
      "node_id": "string",
      "parent_id": "string",
      "path": "string",
      "recency": 0.1,
      "updated_at": "2019-08-24T14:15:22Z",
      "user_id": "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"
}

Reset memory for an agent-user pair

DELETE
/agents/{agentId}/memory

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Query Parameters

user_id*string

User ID whose memory to reset

instance_id?string

Optional instance ID for scoping

Response Body

application/json

application/problem+json

curl -X DELETE "https://loading/api/v1/agents/string/memory?user_id=string"
{
  "$schema": "/api/v1/schemas/ResetMemoryResponse.json",
  "facts_deleted": 0,
  "facts_failed": 0,
  "failed_fact_ids": [
    "string"
  ],
  "failed_node_ids": [
    "string"
  ],
  "nodes_deleted": 0,
  "nodes_failed": 0,
  "status": "string",
  "success": 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"
}

Trigger memory consolidation

POST
/agents/{agentId}/memory/consolidate

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

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/agents/string/memory/consolidate" \  -H "Content-Type: application/json" \  -d '{    "period": "daily",    "user_id": "string"  }'
{
  "$schema": "/api/v1/schemas/TriggerConsolidationOutputBody.json",
  "success": 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 fact supersedes history

GET
/agents/{agentId}/memory/fact/{factId}/history

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

factId*string

Fact identifier

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/agents/string/memory/fact/string/history"
{
  "$schema": "/api/v1/schemas/FactHistoryResponse.json",
  "current": {
    "$schema": "/api/v1/schemas/AtomicFact.json",
    "agent_framing": "string",
    "agent_id": "string",
    "atomic_text": "string",
    "character_salience": 0.1,
    "chunk_id": "string",
    "cluster_id": "string",
    "confidence": 0.1,
    "created_at": "2019-08-24T14:15:22Z",
    "emotional_intensity": 0.1,
    "entities": [
      "string"
    ],
    "episode_id": "string",
    "event_time": "2019-08-24T14:15:22Z",
    "evidence_message_ids": [
      "string"
    ],
    "fact_id": "string",
    "fact_type": "string",
    "hit_count": 0,
    "importance": 0.1,
    "inferred_entities": [
      "string"
    ],
    "last_confirmed": "2019-08-24T14:15:22Z",
    "last_retrieved_at": "2019-08-24T14:15:22Z",
    "mention_count": 0,
    "metadata": {
      "property1": null,
      "property2": null
    },
    "miss_count": 0,
    "node_id": "string",
    "polarity_group_id": "string",
    "relationship_relevance": 0.1,
    "retention_strength": 0.1,
    "sentiment": "string",
    "session_id": "string",
    "source_id": "string",
    "source_type": "string",
    "supersedes_id": "string",
    "temporal_relevance": "string",
    "time_sensitive_at": "2019-08-24T14:15:22Z",
    "topic_tags": [
      "string"
    ],
    "updated_at": "2019-08-24T14:15:22Z",
    "user_id": "string"
  },
  "previous_versions": [
    {
      "$schema": "/api/v1/schemas/AtomicFact.json",
      "agent_framing": "string",
      "agent_id": "string",
      "atomic_text": "string",
      "character_salience": 0.1,
      "chunk_id": "string",
      "cluster_id": "string",
      "confidence": 0.1,
      "created_at": "2019-08-24T14:15:22Z",
      "emotional_intensity": 0.1,
      "entities": [
        "string"
      ],
      "episode_id": "string",
      "event_time": "2019-08-24T14:15:22Z",
      "evidence_message_ids": [
        "string"
      ],
      "fact_id": "string",
      "fact_type": "string",
      "hit_count": 0,
      "importance": 0.1,
      "inferred_entities": [
        "string"
      ],
      "last_confirmed": "2019-08-24T14:15:22Z",
      "last_retrieved_at": "2019-08-24T14:15:22Z",
      "mention_count": 0,
      "metadata": {
        "property1": null,
        "property2": null
      },
      "miss_count": 0,
      "node_id": "string",
      "polarity_group_id": "string",
      "relationship_relevance": 0.1,
      "retention_strength": 0.1,
      "sentiment": "string",
      "session_id": "string",
      "source_id": "string",
      "source_type": "string",
      "supersedes_id": "string",
      "temporal_relevance": "string",
      "time_sensitive_at": "2019-08-24T14:15:22Z",
      "topic_tags": [
        "string"
      ],
      "updated_at": "2019-08-24T14:15:22Z",
      "user_id": "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 facts for an agent

GET
/agents/{agentId}/memory/facts

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Query Parameters

user_id?string

Optional user ID to scope facts

instance_id?string

Optional instance ID for scoping

fact_type?string

Optional fact type filter

limit?integer

Max facts per page (default 50, max 500)

Default50
Formatint64
Range1 <= value <= 500
page_token?string

Opaque cursor from a prior response's next_page_token. Empty = first page.

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/agents/string/memory/facts"
{
  "$schema": "/api/v1/schemas/ListFactsResponse.json",
  "facts": [
    {
      "confidence": 0.1,
      "content": "string",
      "created_at": "string",
      "entity": "string",
      "fact_id": "string",
      "fact_type": "string",
      "importance": 0.1,
      "mention_count": 0,
      "metadata": {
        "property1": null,
        "property2": null
      },
      "session_id": "string",
      "source_id": "string",
      "source_type": "string",
      "updated_at": "string"
    }
  ],
  "next_page_token": "string",
  "total_count": 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 new fact for an agent

POST
/agents/{agentId}/memory/facts

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Query Parameters

instance_id?string

Optional instance ID for scoping

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/agents/string/memory/facts" \  -H "Content-Type: application/json" \  -d '{    "content": "string"  }'
{
  "$schema": "/api/v1/schemas/AtomicFact.json",
  "agent_framing": "string",
  "agent_id": "string",
  "atomic_text": "string",
  "character_salience": 0.1,
  "chunk_id": "string",
  "cluster_id": "string",
  "confidence": 0.1,
  "created_at": "2019-08-24T14:15:22Z",
  "emotional_intensity": 0.1,
  "entities": [
    "string"
  ],
  "episode_id": "string",
  "event_time": "2019-08-24T14:15:22Z",
  "evidence_message_ids": [
    "string"
  ],
  "fact_id": "string",
  "fact_type": "string",
  "hit_count": 0,
  "importance": 0.1,
  "inferred_entities": [
    "string"
  ],
  "last_confirmed": "2019-08-24T14:15:22Z",
  "last_retrieved_at": "2019-08-24T14:15:22Z",
  "mention_count": 0,
  "metadata": {
    "property1": null,
    "property2": null
  },
  "miss_count": 0,
  "node_id": "string",
  "polarity_group_id": "string",
  "relationship_relevance": 0.1,
  "retention_strength": 0.1,
  "sentiment": "string",
  "session_id": "string",
  "source_id": "string",
  "source_type": "string",
  "supersedes_id": "string",
  "temporal_relevance": "string",
  "time_sensitive_at": "2019-08-24T14:15:22Z",
  "topic_tags": [
    "string"
  ],
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "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 create facts for an agent

POST
/agents/{agentId}/memory/facts/bulk

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Query Parameters

instance_id?string

Optional instance ID for scoping

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/agents/string/memory/facts/bulk" \  -H "Content-Type: application/json" \  -d '{    "facts": [      {        "content": "string"      }    ]  }'
{
  "$schema": "/api/v1/schemas/BulkCreateFactsOutputBody.json",
  "facts": [
    {
      "$schema": "/api/v1/schemas/AtomicFact.json",
      "agent_framing": "string",
      "agent_id": "string",
      "atomic_text": "string",
      "character_salience": 0.1,
      "chunk_id": "string",
      "cluster_id": "string",
      "confidence": 0.1,
      "created_at": "2019-08-24T14:15:22Z",
      "emotional_intensity": 0.1,
      "entities": [
        "string"
      ],
      "episode_id": "string",
      "event_time": "2019-08-24T14:15:22Z",
      "evidence_message_ids": [
        "string"
      ],
      "fact_id": "string",
      "fact_type": "string",
      "hit_count": 0,
      "importance": 0.1,
      "inferred_entities": [
        "string"
      ],
      "last_confirmed": "2019-08-24T14:15:22Z",
      "last_retrieved_at": "2019-08-24T14:15:22Z",
      "mention_count": 0,
      "metadata": {
        "property1": null,
        "property2": null
      },
      "miss_count": 0,
      "node_id": "string",
      "polarity_group_id": "string",
      "relationship_relevance": 0.1,
      "retention_strength": 0.1,
      "sentiment": "string",
      "session_id": "string",
      "source_id": "string",
      "source_type": "string",
      "supersedes_id": "string",
      "temporal_relevance": "string",
      "time_sensitive_at": "2019-08-24T14:15:22Z",
      "topic_tags": [
        "string"
      ],
      "updated_at": "2019-08-24T14:15:22Z",
      "user_id": "string"
    }
  ],
  "facts_created": 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 fact

DELETE
/agents/{agentId}/memory/facts/{factId}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

factId*string

Fact identifier

Response Body

application/problem+json

curl -X DELETE "https://loading/api/v1/agents/string/memory/facts/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 existing fact

PUT
/agents/{agentId}/memory/facts/{factId}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

factId*string

Fact identifier

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/agents/string/memory/facts/string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "$schema": "/api/v1/schemas/AtomicFact.json",
  "agent_framing": "string",
  "agent_id": "string",
  "atomic_text": "string",
  "character_salience": 0.1,
  "chunk_id": "string",
  "cluster_id": "string",
  "confidence": 0.1,
  "created_at": "2019-08-24T14:15:22Z",
  "emotional_intensity": 0.1,
  "entities": [
    "string"
  ],
  "episode_id": "string",
  "event_time": "2019-08-24T14:15:22Z",
  "evidence_message_ids": [
    "string"
  ],
  "fact_id": "string",
  "fact_type": "string",
  "hit_count": 0,
  "importance": 0.1,
  "inferred_entities": [
    "string"
  ],
  "last_confirmed": "2019-08-24T14:15:22Z",
  "last_retrieved_at": "2019-08-24T14:15:22Z",
  "mention_count": 0,
  "metadata": {
    "property1": null,
    "property2": null
  },
  "miss_count": 0,
  "node_id": "string",
  "polarity_group_id": "string",
  "relationship_relevance": 0.1,
  "retention_strength": 0.1,
  "sentiment": "string",
  "session_id": "string",
  "source_id": "string",
  "source_type": "string",
  "supersedes_id": "string",
  "temporal_relevance": "string",
  "time_sensitive_at": "2019-08-24T14:15:22Z",
  "topic_tags": [
    "string"
  ],
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "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"
}

Search agent memories (semantic or BM25)

GET
/agents/{agentId}/memory/search

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Query Parameters

q*string

Search query text

user_id?string

Optional user ID. When set and a vector index is available, search uses cosine similarity over fact embeddings; otherwise falls back to BM25.

instance_id?string

Optional instance ID for scoping

mode?string

Retrieval mode: 'semantic' (requires user_id), 'bm25', or 'auto' (default). 'auto' picks semantic when user_id is set and a vector index is wired.

limit?string

Max results to return (default 20, max 100)

include_verbatim?string

Default 'true'. Set to 'false' to skip the SP4 per-turn verbatim KNN merge and return compressed fact hits only.

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/agents/string/memory/search?q=string"
{
  "$schema": "/api/v1/schemas/SearchResponse.json",
  "results": [
    {
      "content": "string",
      "fact_id": "string",
      "fact_type": "string",
      "score": 0.1,
      "session_id": "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 memory consolidation summaries

GET
/agents/{agentId}/memory/summaries

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Query Parameters

period?string

Filter by consolidation stage: 'daily' or 'weekly'

Value in"daily" | "weekly" | ""
limit?integer

Max summaries to return (1-100)

Default20
Formatint64

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/agents/string/memory/summaries"
{
  "$schema": "/api/v1/schemas/SummariesResponse.json",
  "summaries": [
    {
      "agent_id": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "period_end": "2019-08-24T14:15:22Z",
      "period_start": "2019-08-24T14:15:22Z",
      "session_id": "string",
      "stage": "string",
      "summary": "string",
      "summary_id": "string",
      "topics": [
        "string"
      ],
      "user_id": "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 memory timeline grouped by session

GET
/agents/{agentId}/memory/timeline

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Query Parameters

user_id?string

Optional user ID to scope timeline

instance_id?string

Optional instance ID for scoping

start?string

Start date in YYYY-MM-DD format (default: 30 days ago)

end?string

End date in YYYY-MM-DD format (default: today)

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/agents/string/memory/timeline"
{
  "$schema": "/api/v1/schemas/TimelineResponse.json",
  "sessions": [
    {
      "fact_count": 0,
      "facts": [
        {
          "$schema": "/api/v1/schemas/AtomicFact.json",
          "agent_framing": "string",
          "agent_id": "string",
          "atomic_text": "string",
          "character_salience": 0.1,
          "chunk_id": "string",
          "cluster_id": "string",
          "confidence": 0.1,
          "created_at": "2019-08-24T14:15:22Z",
          "emotional_intensity": 0.1,
          "entities": [
            "string"
          ],
          "episode_id": "string",
          "event_time": "2019-08-24T14:15:22Z",
          "evidence_message_ids": [
            "string"
          ],
          "fact_id": "string",
          "fact_type": "string",
          "hit_count": 0,
          "importance": 0.1,
          "inferred_entities": [
            "string"
          ],
          "last_confirmed": "2019-08-24T14:15:22Z",
          "last_retrieved_at": "2019-08-24T14:15:22Z",
          "mention_count": 0,
          "metadata": {
            "property1": null,
            "property2": null
          },
          "miss_count": 0,
          "node_id": "string",
          "polarity_group_id": "string",
          "relationship_relevance": 0.1,
          "retention_strength": 0.1,
          "sentiment": "string",
          "session_id": "string",
          "source_id": "string",
          "source_type": "string",
          "supersedes_id": "string",
          "temporal_relevance": "string",
          "time_sensitive_at": "2019-08-24T14:15:22Z",
          "topic_tags": [
            "string"
          ],
          "updated_at": "2019-08-24T14:15:22Z",
          "user_id": "string"
        }
      ],
      "first_fact_at": "string",
      "last_fact_at": "string",
      "session_id": "string"
    }
  ],
  "total_facts": 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 wisdom fact audit trail

GET
/agents/{agentId}/memory/wisdom/audit/{factId}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

factId*string

Wisdom fact identifier

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/agents/string/memory/wisdom/audit/string"
{
  "$schema": "/api/v1/schemas/WisdomAuditResponse.json",
  "content": "string",
  "derived_from_hashes": [
    "string"
  ],
  "fact_id": "string",
  "promoted_at": "string",
  "promotion_confidence": 0.1,
  "source_user_count": 0,
  "target_path": "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 wisdom fact

DELETE
/agents/{agentId}/memory/wisdom/{factId}

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

factId*string

Wisdom fact identifier

Response Body

application/json

application/problem+json

curl -X DELETE "https://loading/api/v1/agents/string/memory/wisdom/string"
{
  "$schema": "/api/v1/schemas/DeleteWisdomResponse.json",
  "fact_id": "string",
  "success": 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"
}

List all active facts for a specific user

GET
/agents/{agentId}/users/{userId}/facts

Authorization

AuthorizationBearer <token>

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

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

userId*string

User identifier

Query Parameters

instance_id?string

Optional instance ID for scoping

limit?string

Max facts to return (default 1000, max 5000)

has_metadata?string

Set to 'true' to only return facts with metadata

metadata.item_type?string

Filter by metadata.item_type value

Response Body

application/json

application/problem+json

curl -X GET "https://loading/api/v1/agents/string/users/string/facts"
{
  "$schema": "/api/v1/schemas/ListAllFactsResponse.json",
  "facts": [
    {
      "confidence": 0.1,
      "content": "string",
      "created_at": "string",
      "entity": "string",
      "fact_id": "string",
      "fact_type": "string",
      "importance": 0.1,
      "mention_count": 0,
      "metadata": {
        "property1": null,
        "property2": null
      },
      "session_id": "string",
      "source_id": "string",
      "source_type": "string",
      "updated_at": "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"
}

M C P

Previous Page

Models

Next Page