API Reference · v1.1

Build against the Personize API v1.1 with endpoint-level detail.

110 public v1.1 routes across memory, prompts, governance, agents, and key management. v1.1 collapses 37+ overlapping v1 routes into ~30 routes organized around three verbs (save, retrieve, manage) plus import for ETL. v1 sunsets 2026-07-15 — see the migration guide.

Quickstart

Base URL: https://agent.personize.ai

curl -X GET "https://agent.personize.ai/api/v1.1/me" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Most routes use `Authorization: Bearer sk_live_...` secret-key auth.

This is the v1.1 reference — v1 sunsets 2026-07-15. See the migration guide.

SDK-backed routes are labeled so you can map each endpoint to the latest client method quickly.

Base URL

https://agent.personize.ai

Authentication

Secret keys for product routes, JWT for admin routes.

Error shape

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Monthly API limit exceeded.",
  "limit": 10000,
  "current": 10000
}

2 endpoints

Identity

Validate your key and inspect the organization, user, and plan attached to the current request context.

GET/api/v1.1/testSecret keySDK

Authentication test

Runs a lightweight auth check and returns the resolved user and organization identifiers.

Usage: Use this first in a quickstart or health check to verify a key before calling billable endpoints.

SDK: client.test()

Response

{
  "success": true,
  "message": "Authentication successful",
  "data": {
    "timestamp": "2026-03-18T12:00:00.000Z",
    "ip": "1.2.3.4",
    "userAgent": "curl/7.88",
    "userId": "user_123",
    "organizationId": "org_123"
  }
}

SDK Example

const result = await client.test();
console.log(result.data.organizationId);

GET/api/v1.1/meSecret keySDK

Current context

Returns the current org, user, active key metadata, and plan limits.

Usage: Use this to confirm key scope and inspect plan limits before you build rate-limit handling.

SDK: client.me()

Response

{
  "success": true,
  "data": {
    "organization": { "id": "org_123" },
    "user": { "id": "user_123" },
    "key": { "id": "key_123", "scope": "admin" },
    "plan": {
      "name": "Free Plan",
      "limits": {
        "maxApiCallsPerMonth": 10000,
        "maxApiCallsPerMinute": 60
      }
    }
  }
}

SDK Example

const result = await client.me();
console.log(result.data.plan.limits);

Returns `429` when the current key has crossed per-minute or monthly limits.

5 endpoints

AI And Async

Run prompt workflows, route messages through semantic guidelines, and poll async jobs when a call completes in the background.

POST/api/v1.1/ai/smart-guidelinesSecret keySDK

Smart guidelines

Semantically selects the most relevant guidelines or sections for a message and returns compiled context.

Usage: Use this before generation when you want policy, tone, or playbook context assembled automatically.

SDK: client.ai.smartGuidelines()

Parameters

Field	Type	Where	Required	Description
message	string	body	Yes	The task or user message to route.
guidelineIds	string[]	body	No	Restrict routing to specific guideline IDs.
guidelineNames	string[]	body	No	Resolve guidelines by name.
tags	string[]	body	No	Only include guidelines carrying these tags.
excludeTags	string[]	body	No	Exclude guidelines with these tags.
mode	string	body	No	Controls routing depth and latency.Default: `auto`Options: `fast`, `deep`, `auto`

Request

{
  "message": "Write a sales sequence for our top enterprise ICPs",
  "tags": ["sales"],
  "mode": "deep"
}

Response

{
  "success": true,
  "mode": "deep",
  "creditsCharged": 1,
  "selection": [
    {
      "guidelineId": "act_123",
      "name": "Sales Playbook",
      "score": 0.92,
      "reason": "High relevance to sales sequence",
      "mode": "section",
      "sections": ["Cold Email", "Enterprise Tone"],
      "availableSections": ["Cold Email", "Enterprise Tone", "Pricing", "Objections"],
      "trimmedSections": ["Pricing", "Objections"],
      "content": "## Sales Playbook: Cold Email\n..."
    }
  ],
  "compiledContext": "SOURCE: Sales Playbook\n...",
  "budgetMetadata": {
    "budgetUsed": 3200,
    "budgetLimit": 10000,
    "demotedCount": 1,
    "demotedGuidelines": [
      {
        "id": "act_456",
        "name": "Compliance Policy",
        "description": "Internal compliance rules for outbound communications...",
        "score": 0.71,
        "sections": ["Email Disclaimers", "Data Handling"]
      }
    ]
  },
  "usage": {
    "durationMs": 340,
    "guidelinesScanned": 12,
    "selectedCount": 3
  }
}

SDK Example

const result = await client.ai.smartGuidelines({
  message: "Write a sales sequence for our top enterprise ICPs",
  tags: ["sales"],
  maxContentTokens: 5000,
});
// Demoted guidelines available for follow-up
for (const g of result.budgetMetadata?.demotedGuidelines || []) {
  console.log(g.name, g.sections);
}

Default maxContentTokens is 10,000 (~3-5 full guidelines). Set lower (e.g. 5,000) for smaller context windows.
Guidelines exceeding ~10K tokens per item are auto-trimmed to relevant sections. The response includes availableSections and trimmedSections so you know what was cut.
Demoted guidelines (over budget) are returned as summaries with id, description, score, and section titles. Use guideline_read(id, { header }) to fetch specific sections on demand.
The mode param controls routing: 'fast' (~200ms, embedding-only), 'deep' (~2-5s, LLM routing), 'auto' (system decides). All modes respect maxContentTokens.

POST/api/v1.1/promptSecret keySDK

Prompt execution

Runs a direct prompt or multi-step instruction chain with optional structured outputs, evaluation, auto-memorize, and attachments.

Usage: Use this for general-purpose generation, extraction, or tool-augmented reasoning from the public API.

SDK: client.ai.prompt() / client.ai.promptStream()

Parameters

Field	Type	Where	Required	Description
prompt	string	body	No	Single-step prompt text.
instructions	Instruction[]	body	No	Ordered instruction blocks for multi-step runs.
stream	boolean	body	No	Set `true` for SSE streaming; `false` returns an async event or sync result.
tier	string	body	No	Quality and pricing tier.Default: `pro`Options: `basic`, `pro`, `ultra`
attachments	Attachment[]	body	No	Images, PDFs, or documents sent with the prompt.
outputs	OutputDefinition[]	body	No	Named structured outputs extracted server-side.

Request

{
  "prompt": "Summarize our Q4 sales strategy in five bullets",
  "tier": "pro",
  "outputs": [{ "name": "summary" }]
}

Response

{
  "success": true,
  "text": "Here is the finished draft.",
  "outputs": { "summary": "..." },
  "metadata": {
    "model": "anthropic/claude-sonnet-4-20250514",
    "provider": "anthropic",
    "tier": "pro",
    "creditsCharged": 1,
    "usage": {
      "promptTokens": 120,
      "completionTokens": 450
    },
    "toolCalls": [],
    "stepsExecuted": 1,
    "instructionsExecuted": 1
  }
}

SDK Example

const result = await client.ai.prompt({
  prompt: "Summarize our Q4 sales strategy in five bullets",
  tier: "pro",
  outputs: [{ name: "summary" }],
});
console.log(result.outputs.summary);

When `stream` is `false`, some requests complete asynchronously and return an event you can poll.
For SSE, use the SDK streaming helper rather than building the parser by hand.

GET/api/v1.1/eventsSecret key

List async events

Lists async events for the current organization.

Usage: Use this to inspect recent prompt, batch memorization, or evaluation jobs.

Parameters

Field	Type	Where	Required	Description
limit	number	query	No	Page size.Default: `20`
nextToken	string	query	No	Cursor from a previous page.

Response

{
  "success": true,
  "data": {
    "events": [
      { "eventId": "evt_123", "status": "processing", "type": "prompt" }
    ],
    "count": 1,
    "nextToken": "eyJ..."
  }
}

GET/api/v1.1/events/:idSecret key

Get async event

Fetches the current state of one async event.

Usage: Use this to poll prompt, batch, or evaluation jobs until they finish.

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The event ID returned by an async endpoint.

Response

{
  "success": true,
  "data": {
    "eventId": "evt_123",
    "status": "completed",
    "responsePayload": { "success": true }
  }
}

GET/api/v1.1/events/:id/detailsSecret key

Get event details

Returns subrecords or detail rows for a large async job.

Usage: Use this when you need item-level detail from a batch process.

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Event ID.
limit	number	query	No	Page size for detail rows.
nextToken	string	query	No	Cursor for more detail rows.

Response

{
  "success": true,
  "data": {
    "eventId": "evt_123",
    "details": [],
    "count": 0
  }
}

2 endpoints

AI Generation

Step-driven AI orchestration and OpenAI-compatible chat completions with built-in governance, memory, and client-executed tools.

POST/api/v1.1/responsesSecret keySDK

Create a response

Execute step-driven AI orchestration with governance, memory, and client-executed tools. The primary generation endpoint.

Usage: Run multi-step AI workflows with fine-grained control over tool access, governance injection, and structured output extraction.

SDK: client.responses.create(options)

Parameters

Field	Type	Where	Required	Description
steps	StepDefinition[]	body	No	Ordered instructions for the AI to execute sequentially. Each step has a prompt, optional tool scope, and max_steps.
messages	ChatMessage[]	body	No	Alternative to steps. Standard message array (system/user/assistant). Converted to a single step internally.
tools	ClientToolSchema[]	body	No	User-defined tools (JSON schema only). When the LLM calls these, the response returns requires_action and the SDK executes them on your server.
tier	string	body	No	Model quality tier when not using BYOK.Default: `basic`Options: `basic`, `pro`, `ultra`
model	string	body	No	Model ID for BYOK mode (e.g., 'claude-sonnet-4-6', 'gpt-4o').
provider	string	body	No	Provider for BYOK mode.Options: `openrouter`, `openai`, `anthropic`, `google`, `deepseek`, `xai`
llm_api_key	string	body	No	Your own LLM provider API key for BYOK mode.
session_id	string	body	No	Group related requests into a session for SmartGuidelines deduplication.
temperature	number	body	No	Sampling temperature (0-2).Range: `0–2`
max_tokens	number	body	No	Maximum tokens for the response.

Request

{
  "tier": "pro",
  "steps": [
    { "prompt": "Research {{company}} and find their tech stack", "tools": ["web_search"] },
    { "prompt": "Draft a personalized outreach email" }
  ],
  "personize": {
    "governance": { "guideline_ids": ["brand-voice"] },
    "memory": { "record_id": "contact-123", "recall": true },
    "outputs": [
      { "key": "email_subject", "type": "string" },
      { "key": "email_body", "type": "string" }
    ]
  }
}

Response

{
  "id": "resp_abc123",
  "status": "completed",
  "session_id": "sess_xyz789",
  "output": [{
    "type": "message",
    "role": "assistant",
    "content": [{ "type": "text", "text": "Here's the drafted email..." }]
  }],
  "outputs": {
    "email_subject": "Quick question about your React stack",
    "email_body": "Hi Sarah, I noticed Acme Corp..."
  },
  "usage": { "prompt_tokens": 2000, "completion_tokens": 800, "total_tokens": 2800 },
  "metadata": { "tier": "pro", "credits_charged": 3.2 }
}

SDK Example

const result = await client.responses.create({
  tier: 'pro',
  steps: [
    { prompt: 'Research {{company}} tech stack', tools: ['web_search'] },
    { prompt: 'Draft a personalized outreach email' }
  ],
  personize: {
    governance: { guideline_ids: ['brand-voice'] },
    memory: { record_id: 'contact-123', recall: true }
  }
});
console.log(result.outputs.email_subject);

If both steps and messages are provided, steps takes priority.
Client-executed tools: define tool schemas in the request. When the LLM calls them, the response returns status: 'requires_action'. Your SDK executes the tool locally and sends the result back.
BYOK mode: provide llm_api_key + model + provider to use your own LLM key. Billed at a flat platform fee instead of per-token.
Session IDs enable SmartGuidelines deduplication across requests in the same session.

POST/api/v1.1/chat/completionsSecret keySDK

Chat completion (OpenAI-compatible)

OpenAI-compatible chat completion endpoint. Drop-in replacement that adds Personize governance, memory, and evaluation on top of standard chat.

Usage: Quick integration for developers migrating from OpenAI. Supports all Personize extensions as optional parameters.

SDK: client.chat.completions.create(options)

Parameters

Field	Type	Where	Required	Description
messages	ChatMessage[]	body	Yes	Standard OpenAI message array (system/user/assistant/tool roles).
tools	ToolSchema[]	body	No	OpenAI-format tool definitions. Client-executed tools work the same as /responses.
tool_choice	string	body	No	Tool selection mode.Options: `auto`, `none`, `required`
tier	string	body	No	Model quality tier.Default: `basic`Options: `basic`, `pro`, `ultra`
model	string	body	No	Model ID for BYOK mode.
provider	string	body	No	Provider for BYOK mode.Options: `openrouter`, `openai`, `anthropic`, `google`, `deepseek`, `xai`
llm_api_key	string	body	No	Your own LLM provider API key.
temperature	number	body	No	Sampling temperature (0-2).Range: `0–2`
max_tokens	number	body	No	Maximum tokens for the response.

Request

{
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Draft a follow-up email for Acme Corp" }
  ],
  "tier": "pro",
  "personize": {
    "governance": { "guideline_ids": ["brand-voice"] },
    "memory": { "record_id": "contact-123", "recall": true }
  }
}

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710892800,
  "model": "google/gemini-2.5-flash-lite-preview-09-2025",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Subject: Following up on our conversation..."
    },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 1200, "completion_tokens": 450, "total_tokens": 1650 },
  "session_id": "sess_xyz789",
  "metadata": { "tier": "pro", "credits_charged": 1.5 }
}

SDK Example

const chat = await client.chat.completions.create({
  messages: [
    { role: 'user', content: 'Draft a follow-up email for Acme Corp' }
  ],
  personize: {
    governance: { guideline_ids: ['brand-voice'] },
    memory: { record_id: 'contact-123', recall: true }
  }
});
console.log(chat.choices[0].message.content);

Response format matches the OpenAI Chat Completions API exactly.
Personize extensions (governance, memory) are optional. Without them, this behaves like a standard chat completion.
Internally converts messages to a single-step orchestration call.

13 endpoints

Memory

Store, recall, filter, and summarize customer memory across structured fields and free-form context.

POST/api/v1.1/memory/saveSecret keySDK

Save memory (shape: shortform | document)

Single-record AI-powered write. The `shape` discriminator selects between extraction-driven `shortform` (default) and typed `document` storage. Subsumes v1's `/memorize`, `/memorize_pro`, `/memorize_context`, `/upsert`, and `/context/save`.

Usage: The one write endpoint for AI-powered single saves. `shape='shortform'` runs extraction to produce atoms + properties. `shape='document'` stores typed guidelines/playbooks/references with optional metadata enrich.

SDK: client.v1_1.memory.save()

Parameters

Field	Type	Where	Required	Description
content	string	body	Yes	The source content to store. Primary for both shapes.
shape	string	body	No	What data shape is being sent. Defaults to `shortform`. Use `document` for typed knowledge docs.Default: `shortform`Options: `shortform`, `document`
type	string	body	No	Required when `shape='document'`. Registry value from `/context/manage/doc-types` (e.g. `guideline`, `playbook`, `reference`, `template`, `brief`, or org-defined).
recordId	string	body	No	Present = record-scoped write. Absent = org-scoped.
properties	object	body	No	Seed/hints for `shortform` (LLM may extract both atoms + properties); metadata for `document`.
options	object	body	No	Per-write controls: `mode` (sync/async/bulk), `tier`, `upsert`, `enrich`, `aiGenerated`, `collectionIds`.

Request

{
  "shape": "shortform",
  "content": "Meeting notes: John prefers email and is evaluating in Q2.",
  "properties": { "email": "john@example.com" },
  "options": { "tier": "pro" },
  "collectionGraph": true,
  "smartGraph": true,
  "relations": [
    { "relationType": "works_at",
      "toIdentity": { "kind": "websiteUrl", "value": "acme.com" },
      "toEntityType": "company" }
  ]
}

Response

{
  "shape": "shortform",
  "recordId": "rec_xyz",
  "memories": [...],
  "properties": {...},
  "destination": "fast-sf",
  "reason": "fast-eligible",
  "jobId": "evt_...",
  "estimatedCompletionMs": 12000,
  "cost": { "credits": 3, "tier": "pro" },
  "warnings": [],
  "deduplication": { "skipped": 0, "merged": 0 }
}

SDK Example

const result = await client.v1_1.memory.save({
  content: "John prefers email and is evaluating in Q2.",
  properties: { email: "john@example.com" },
  // shape defaults to 'shortform' — extracts both atoms + properties
});

// Document shape — stores a typed guideline
const doc = await client.v1_1.memory.save({
  shape: "document",
  type: "guideline",
  content: "## Sales Playbook\n...",
  options: { enrich: true },
});

Three credit tiers: full extraction / metadata enrich / direct write. Tier billed is surfaced in response.cost.tier.
`recordId` carries scope: present = record-scoped, absent = org-scoped.
Aliases: `/memorize`, `/memorize_pro`, `/upsert`, `/context/save` are accepted but deprecated and emit RFC 8594 Deprecation headers.

POST/api/v1.1/memory/save/batchSecret keySDK

Save memory batch (per-item shape)

N independent saves in one call. Per-item `shape`. Loop-dispatch handler (MAX_BATCH_SIZE=100). Returns 207 Multi-Status on partial failures.

Usage: Use when you have a small heterogeneous set of saves that should run together but may have different shapes per item. For homogeneous, schema-driven imports use `/memory/import` instead.

SDK: client.v1_1.memory.saveBatch()

Parameters

Field	Type	Where	Required	Description
items	object[]	body	Yes	Array of per-item save payloads. Each item follows the `/memory/save` body shape. Max 100 items per call.
options	object	body	No	Top-level defaults applied to each item (overridable per item). `mode` must be `async` or `bulk` for batches — sync not allowed.

Request

{
  "items": [
    { "shape": "shortform", "content": "...", "recordId": "rec_1" },
    { "shape": "document", "type": "guideline", "content": "..." }
  ],
  "options": { "mode": "async", "tier": "pro" }
}

Response

{
  "results": [
    { "ok": true, "shape": "shortform", "recordId": "rec_1", "jobId": "evt_1" },
    { "ok": false, "error": "schema_violation", "message": "missing required type for shape=document" }
  ],
  "summary": { "total": 2, "succeeded": 1, "failed": 1 }
}

Returns 207 Multi-Status when any item fails; 200 when all succeed.
Per-item `options` override top-level `options` for that item only.
Server routes individual items to `fast-sf` (<25 records) or `bulk-sf` (≥25, batch-capable provider).

POST/api/v1.1/memory/importSecret keySDK

Import memory (ETL with per-property extract)

Bulk ETL ingestion: mapping + rows with per-property `extract` flag. Public promotion of the internal CRM-sync `batch-memorize-import` path — same payload schema, same per-field AI-routing.

Usage: Use for CRM/warehouse/spreadsheet imports where each property has known direct-write vs. LLM-extract handling. The per-property `extract: true` flag opts a field into AI extraction; default `false` writes directly.

SDK: client.v1_1.memory.import()

Parameters

Field	Type	Where	Required	Description
source	string	body	Yes	Origin label.Options: `hubspot`, `salesforce`, `apollo`, `nango`, `api-custom`
mapping	object	body	Yes	`{ entityType, propertyMappings: [{ source, target, extract, aiGenerated, direction }] }`.
rows	object[]	body	Yes	Raw tabular rows keyed by provider field names.
options	object	body	No	`{ mode: 'async'\|'bulk', tier, dryRun, chunkSize }`.

Request

{
  "source": "hubspot",
  "mapping": {
    "entityType": "contact",
    "propertyMappings": [
      { "source": "firstname", "target": { "propertyName": "first_name" }, "extract": false, "direction": "both" },
      { "source": "notes", "target": { "propertyName": "notes" }, "extract": true, "direction": "in" }
    ]
  },
  "rows": [
    { "firstname": "John", "notes": "Long transcript..." }
  ],
  "options": { "mode": "async", "tier": "pro" }
}

Response

{
  "jobId": "evt_...",
  "destination": "bulk-sf",
  "enqueuedRows": 1500,
  "chunks": 15,
  "estimatedCompletionMs": 45000,
  "cost": {
    "estimatedCredits": 450,
    "tier": "pro",
    "perPropertyEstimate": {
      "notes": { "credits": 450, "extract": true },
      "firstname": { "credits": 0, "extract": false }
    }
  }
}

Per-property `extract: true` runs LLM extraction on that field; `extract: false` (default) writes the value directly.
`direction: 'in' | 'out' | 'both'` controls sync semantics.
Use `options.dryRun: true` for a no-op validation pass with cost estimate.

POST/api/v1.1/memory/retrieveSecret keySDK

Retrieve memory (5 modes)

Unified retrieve with 5 modes: `scout` (default, multi-source no-LLM), `brief` (LLM synthesis), `expand` (paginate), `filter` (17 operators), `fetch` (by IDs). Zero schema change from v1 `/retrieve`, `/smart-recall*`, `/recall*`, `/search`, `/smart-memory-digest`, `/similar`, `/filter-by-property`.

Usage: The single retrieve endpoint. Pick a `mode` based on intent: scout for fast recall, brief for synth, expand for pagination, filter for structured property queries, fetch for known-ID lookups.

SDK: client.v1_1.memory.retrieve()

Parameters

Field	Type	Where	Required	Description
message	string	body	No	Natural language query. Required for `scout`, `brief`, `expand`.
mode	string	body	No	Retrieval mode.Default: `scout`Options: `scout`, `brief`, `expand`, `filter`, `fetch`
identifiers	object	body	No	`{ emails?, websites?, record_ids? }` — scope retrieval to known entities.
filters	object	body	No	Required for `mode='filter'`. Structured property filters with 17 operators.
ids	string[]	body	No	Required for `mode='fetch'`. Direct memory/record IDs to load.
limit	number	body	No	Max results.Default: `10`Range: `1–5000`
token_budget	number	body	No	Token budget for `brief` mode compiled context.Default: `4000`
session_id	string	body	No	Session ID for follow-up queries.
output_format	string	body	No	Response shape.Default: `structured`Options: `structured`, `narrative`

Request

{
  "mode": "scout",
  "message": "What is John's budget and timeline?",
  "identifiers": { "emails": ["john@example.com"] }
}

Response

{
  "success": true,
  "mode": "scout",
  "data": {
    "results": [
      { "text": "John's budget is $50k, evaluating in Q2.", "score": 0.91, "record_id": "rec_456" }
    ],
    "creditsCharged": 1
  }
}

SDK Example

// Scout — fast no-LLM recall
const scout = await client.v1_1.memory.retrieve({
  mode: "scout",
  message: "AI automation buyers",
});

// Brief — LLM-synthesized answer
const brief = await client.v1_1.memory.retrieve({
  mode: "brief",
  message: "What is John's budget?",
  identifiers: { emails: ["john@example.com"] },
  token_budget: 2000,
});

// Filter — structured property query
const filter = await client.v1_1.memory.retrieve({
  mode: "filter",
  filters: { ARR: { gt: 10000 }, "Renewal Date": { exists: true } },
});

Replaces v1's `/smart-recall`, `/smart-recall-unified`, `/recall`, `/recall_pro`, `/search`, `/smart-memory-digest`, `/similar`, `/memory/filter-by-property`, `/memory/query-properties`.
`scout` ~ 1 credit. `brief` ~ 2 credits. `expand`/`filter`/`fetch` cheap (≤1 credit) when no LLM is in the loop.

POST/api/v1.1/memorizeSecret keySDK

Memorize content

Stores raw content and runs extraction so Personize can create structured properties and free-form memory.

Usage: Use this to turn notes, calls, forms, or documents into searchable customer memory.

SDK: client.memory.memorize()

Parameters

Field	Type	Where	Required	Description
content	string	body	Yes	The source content to store and analyze.
email	string	body	No	Contact identity.
website_url	string	body	No	Company identity.
record_id	string	body	No	Direct record identifier.
type	string	body	No	Entity type such as `Contact` or `Company`.
tier	string	body	No	Memorization tier.Default: `pro`Options: `basic`, `pro`, `pro_fast`, `ultra`
collectionIds	string[]	body	No	Restrict extraction to specific collections.

Request

{
  "content": "Meeting notes: John prefers email contact and is evaluating in Q2.",
  "email": "john@example.com",
  "type": "Contact"
}

Response

{
  "success": true,
  "message": "Memorization started",
  "data": {
    "eventId": "evt_mem_123",
    "trackingId": "trk_abc",
    "status": "processing",
    "receivedAt": "2026-03-18T12:00:00.000Z",
    "organizationId": "org_123",
    "recordId": "rec_456",
    "type": "Contact",
    "identity": { "email": "john@example.com" }
  }
}

SDK Example

const result = await client.memory.memorize({
  content: "Meeting notes: John prefers email contact and is evaluating in Q2.",
  email: "john@example.com",
  type: "Contact",
});
console.log(result.data.eventId);

Returns 202. Completes asynchronously — poll with the events endpoint.

POST/api/v1.1/smart-recallSecret keySDK

Smart recall

Runs RAG-style retrieval with reflection and answer assembly.

Usage: Use this when you want the best coverage for open-ended customer questions.

SDK: client.memory.smartRecall()

Parameters

Field	Type	Where	Required	Description
query	string	body	Yes	Natural-language retrieval question.
mode	string	body	No	Retrieval mode. Fast skips reflection (~500ms, 1 credit). Deep enables reflection + answer generation (~10-20s, 2 credits).Default: `deep`Options: `fast`, `deep`
recordId	string	body	No	Scope recall to one record.
email	string	body	No	Scope recall to one contact.
websiteUrl	string	body	No	Scope recall to one company.
phoneNumber	string	body	No	Scope recall by phone number.
postalCode	string	body	No	Scope recall by postal code.
deviceId	string	body	No	Scope recall by device ID.
contentId	string	body	No	Scope recall by content ID.
customKeyName	string	body	No	Custom CRM key field name.
customKeyValue	string	body	No	Custom CRM key field value.
limit	number	body	No	How many memories to return.Default: `10`Range: `1–5000`
type	string	body	No	Entity type filter.Options: `contact`, `company`, `user`

Request

{
  "query": "AI automation decision makers in SaaS",
  "mode": "fast",
  "groupByRecord": true,
  "limit": 20
}

Response

{
  "success": true,
  "data": {
    "results": [
      { "id": "mem_1", "text": "Evaluating AI tools...", "score": 0.91, "record_id": "REC#abc" }
    ],
    "total_retrieved": 15,
    "recordGroups": [
      {
        "recordId": "REC#abc",
        "type": "contact",
        "topScore": 0.91,
        "matchCount": 5,
        "topMatches": [
          { "id": "mem_1", "text": "Evaluating AI tools...", "score": 0.91 },
          { "id": "mem_2", "text": "CTO leading automation...", "score": 0.84 },
          { "id": "mem_3", "text": "Budget approved Q2...", "score": 0.79 }
        ]
      }
    ]
  }
}

SDK Example

const result = await client.memory.smartRecall({
  query: "AI automation decision makers in SaaS",
  mode: "fast",
  groupByRecord: true,
});
// Flat results
console.log(result.data.results);
// Grouped by record
console.log(result.data.recordGroups);

mode: "fast" costs 1 credit, mode: "deep" costs 2 credits per call.
Individual flags (enable_reflection, generate_answer, fast_mode) are accepted for backward compatibility but mode takes precedence.

POST/api/v1.1/searchSecret keySDK

Search records (deprecated alias)

Filters or searches records by conditions and optionally returns property values or memories.

Usage: Use `POST /memory/retrieve` mode=`scout` for v1.1 equivalent. Alias still accepted with deprecation headers through sunset date.

SDK: client.memory.search()

Parameters

Field	Type	Where	Required	Description
query	string	body	No	Natural-language search phrase.
groups	object[]	body	No	Condition groups: `[{ conditions: [{ property, operator, value?, collectionId? }] }]`.
type	string	body	No	Entity type filter.
page	number	body	No	Page number (1-based).Default: `1`
pageSize	number	body	No	Results per page.Default: `50`Range: `1–200`

Request

{
  "groups": [
    {
      "conditions": [
        { "property": "Lifecycle Stage", "operator": "equals", "value": "SQL" }
      ]
    }
  ],
  "pageSize": 20
}

Response

{
  "success": true,
  "data": {
    "recordIds": ["contact_123"],
    "totalMatched": 1,
    "page": 1,
    "pageSize": 20,
    "totalPages": 1,
    "records": [
      {
        "recordId": "contact_123",
        "mainProperties": { "Lifecycle Stage": "SQL" }
      }
    ]
  }
}

SDK Example

const result = await client.memory.search({
  groups: [
    { conditions: [{ property: "Lifecycle Stage", operator: "equals", value: "SQL" }] }
  ],
  pageSize: 20,
});
console.log(result.data.records);

POST/api/v1.1/recallSecret keySDK

Direct recall (deprecated alias)

Fetches memories directly without the deeper reflection flow used by smart recall.

Usage: Use this when you want lower-latency retrieval with more predictable payloads.

SDK: client.memory.recall()

Parameters

Field	Type	Where	Required	Description
query	string	body	Yes	Retrieval question or phrase.
recordId	string	body	No	Direct record scope.
email	string	body	No	Contact scope.
websiteUrl	string	body	No	Company scope.
limit	number	body	No	How many memories to return.Default: `10`
type	string	body	No	Entity type filter.Options: `contact`, `company`, `user`

Request

{
  "query": "What product objections has Jane mentioned?",
  "email": "jane@example.com"
}

Response

{
  "success": true,
  "data": [
    {
      "text": "Jane needs SOC 2 documentation before procurement.",
      "score": 0.89,
      "recordId": "contact_jane",
      "createdAt": "2026-03-15T10:00:00.000Z"
    }
  ]
}

SDK Example

const result = await client.memory.recall({
  query: "What product objections has Jane mentioned?",
  email: "jane@example.com",
  limit: 10,
});
console.log(result.data);

POST/api/v1.1/batch-memorizeSecret keySDK

Batch memorize (deprecated alias)

Processes a batch of records with field mapping and per-property extraction rules.

Usage: Use `POST /memory/import` for v1.1 — identical payload (`source`, `mapping`, `rows`).

SDK: client.memory.memorizeBatch()

Parameters

Field	Type	Where	Required	Description
source	string	body	No	Human-readable import source label.
mapping	object	body	No	Mapping: `{ entityType, email?, website?, customKeyName?, customKey?, properties }`.
rows	object[]	body	No	Tabular payload rows to import.
records	object[]	body	No	Pre-shaped records for SDK compatibility.

Request

{
  "source": "hubspot-sync",
  "mapping": {
    "entityType": "Contact",
    "properties": {
      "first_name": "First Name",
      "last_name": "Last Name"
    }
  },
  "rows": [
    { "first_name": "Ava", "last_name": "Stone", "email": "ava@example.com" }
  ]
}

Response

{
  "success": true,
  "data": {
    "eventId": "evt_batch_123",
    "trackingId": "trk_batch_abc",
    "status": "processing",
    "receivedAt": "2026-03-18T12:00:00.000Z"
  }
}

SDK Example

const result = await client.memory.memorizeBatch({
  source: "hubspot-sync",
  mapping: {
    entityType: "Contact",
    properties: { first_name: "First Name", last_name: "Last Name" },
  },
  rows: [
    { first_name: "Ava", last_name: "Stone", email: "ava@example.com" },
  ],
});
console.log(result.data.eventId);

POST/api/v1.1/smart-memory-digestSecret keySDK

Smart memory digest — RETIRED in v1.1

Builds a compact context bundle for one entity, including properties, free-form memories, and summarization.

Usage: Migrated to `POST /memory/retrieve` mode=`brief`. Identical compiled-context output.

SDK: client.memory.smartDigest()

Parameters

Field	Type	Where	Required	Description
recordId	string	body	No	Direct record scope.
email	string	body	No	Contact scope.
websiteUrl	string	body	No	Company scope.
type	string	body	No	Entity type.Options: `contact`, `company`, `user`

Request

{
  "recordId": "contact_123",
  "type": "Contact"
}

Response

{
  "success": true,
  "data": {
    "recordId": "contact_123",
    "type": "Contact",
    "properties": {
      "Lifecycle Stage": "SQL",
      "Renewal Date": "2026-06-30"
    },
    "memories": [
      {
        "text": "Prefers email communication",
        "createdAt": "2026-03-10T08:00:00.000Z"
      }
    ],
    "compiledContext": "## Contact: contact_123\n\n### Properties\n- Lifecycle Stage: SQL\n...",
    "tokenEstimate": 340,
    "tokenBudget": 4000
  }
}

SDK Example

const result = await client.memory.smartDigest({
  recordId: "contact_123",
  type: "Contact",
});
console.log(result.data.compiledContext);

POST/api/v1.1/propertiesSecret keySDK

Get record properties (deprecated alias)

Fetches property values for a record, joined with collection schema descriptions and the update flag that indicates whether properties can be overwritten or are append-only.

Usage: Use `GET /memory/manage/:id` for v1.1.

SDK: client.memory.properties()

Parameters

Field	Type	Where	Required	Description
email	string	body	No	Contact email.
websiteUrl	string	body	No	Company website URL.
recordId	string	body	No	Direct record ID.
type	string	body	No	Entity type.Options: `contact`, `company`, `user`
propertyNames	string[]	body	No	Filter to specific properties. Omit for all.
includeDescriptions	boolean	body	No	Join with collection schema descriptions.Default: `true`
nonEmpty	boolean	body	No	Exclude properties with null/empty values.Default: `false`

Request

{
  "email": "john@acme.com",
  "propertyNames": ["Tasks", "Lifecycle Stage"],
  "nonEmpty": true
}

Response

{
  "success": true,
  "data": {
    "recordId": "rec_456",
    "type": "Contact",
    "properties": [
      {
        "name": "Tasks",
        "value": [{ "id": "t1", "title": "Follow up", "status": "pending" }],
        "type": "json",
        "description": "Array of task objects { id, title, status, assignee, due }.",
        "update": false,
        "collectionName": "Contact Properties"
      },
      {
        "name": "Lifecycle Stage",
        "value": "SQL",
        "type": "text",
        "description": "Current funnel position.",
        "update": true,
        "collectionName": "Contact Properties"
      }
    ]
  }
}

SDK Example

const result = await client.memory.properties({
  email: "john@acme.com",
  propertyNames: ["Tasks", "Lifecycle Stage"],
  nonEmpty: true,
});
for (const prop of result.data.properties) {
  console.log(prop.name, prop.value, "update:", prop.update);
}

Properties with update: true can be overwritten. Properties with update: false are append-only — new values are pushed, not replaced.

POST/api/v1.1/similarSecret keySDK

Find Similar Records (deprecated alias)

Find records similar to a seed record across properties, memories, or shared connections. Uses parallel multi-vector search for high accuracy.

Usage: Use `GET /memory/manage/:id/similar` for v1.1.

SDK: client.memory.similar()

Parameters

Field	Type	Where	Required	Description
seed	object	body	Yes	Seed record identifier: { email?, recordId?, websiteUrl?, customKeyName?, customKeyValue? }
topK	number	body	No	Max results per page.Default: `25`
dimensions	string	body	No	What drives similarity.Default: `hybrid`Options: `properties`, `memories`, `hybrid`, `connections`

Request

{
  "seed": { "email": "john@acme.com" },
  "topK": 10,
  "dimensions": "hybrid"
}

Response

{
  "success": true,
  "seed": { "recordId": "REC#abc", "type": "contact", "label": "john@acme.com", "vectorsUsed": 16 },
  "results": [
    { "recordId": "REC#def", "score": 0.87, "tier": "very_similar", "matchBreakdown": { "propertiesScore": 0.91, "memoriesScore": 0.82 } }
  ],
  "tiers": { "very_similar": ["REC#def"], "similar": ["REC#ghi"], "somewhat_similar": [] },
  "totalMatches": 2,
  "usage": { "credits": 1 }
}

SDK Example

const result = await client.memory.similar({
  seed: { email: "john@acme.com" },
  topK: 10,
});
console.log(result.data.results);

1 credit per request
Connections dimension is Phase 2
Uses seed record's stored vectors for high accuracy (0.98+ top scores). Latency depends on seed vector count.

POST/api/v1.1/segmentSecret keySDK

Segment Audience — RETIRED in v1.1

Bucket all records into similarity tiers relative to a seed record or text.

Usage: Migration: build similar audience flows via `POST /memory/retrieve` mode=`filter` with property thresholds, or `mode=fetch` for ID-driven tiering.

SDK: client.memory.segment()

Parameters

Field	Type	Where	Required	Description
seed	object	body	Yes	Seed: { email?, recordId?, websiteUrl?, text? }. Text creates a text-based seed.
maxPerTier	number	body	No	RecordIds per tier page.Default: `50`
dimensions	string	body	No	What drives similarity.Default: `hybrid`Options: `properties`, `memories`, `hybrid`

Request

{
  "seed": { "text": "Enterprise SaaS CTO interested in AI" },
  "maxPerTier": 10
}

Response

{
  "success": true,
  "seed": { "recordId": null, "type": "contact", "label": "Enterprise SaaS CTO...", "vectorsUsed": 1 },
  "tiers": {
    "very_similar": { "count": 5, "recordIds": ["REC#1"], "hasMore": false },
    "similar": { "count": 12, "recordIds": ["REC#6"], "hasMore": true },
    "somewhat_similar": { "count": 34, "recordIds": ["REC#20"], "hasMore": true },
    "not_similar": { "count": 890, "recordIds": [], "approximate": true }
  },
  "totalRecords": 941,
  "usage": { "credits": 2 }
}

SDK Example

const result = await client.memory.segment({
  seed: { text: "Enterprise SaaS CTO interested in AI" },
  maxPerTier: 10,
});
console.log(result.data.tiers.very_similar.recordIds);

2 credits per request
not_similar count is approximate
Record seeds use parallel multi-vector search (high accuracy). Text seeds use query expansion -- the description is decomposed into 4-6 focused CRM property-value phrases, each embedded separately for better matching.
Text seeds work best with descriptive phrases matching CRM data format (e.g., 'Healthcare compliance officer at 500-person hospital using Epic for HIPAA audit automation')

21 endpoints

Memory Manage (REST verbs)

Deterministic CRUD on records, properties, and memories — no LLM, low cost. v1.1 collapses v1's action-named POSTs (`/memory/update`, `/memory/delete-record`, `/memory/property-history`, `/similar`) into REST verbs under `/memory/manage/*`.

GET/api/v1.1/memory/manageSecret keySDK

List records

Paginated list of records with optional filters (type, collection, owner, updatedAt range).

Usage: Browse all records in an org. For ad-hoc structured queries use `POST /memory/retrieve` mode=`filter`.

SDK: client.v1_1.memory.manage.list()

Parameters

Field	Type	Where	Required	Description
type	string	query	No	Filter by entity type.
collectionId	string	query	No	Filter by collection.
limit	number	query	No	Page size.Default: `50`
nextToken	string	query	No	Cursor from previous page.

Response

{
  "data": { "records": [{ "recordId": "rec_1", "type": "contact", ... }], "nextToken": null }
}

GET/api/v1.1/memory/manage/:idSecret keySDK

Get one record

Returns one record with its properties, schema descriptions, and recent memories. Replaces v1's `POST /properties` and `POST /memory/query-properties`.

Usage: Fetch a record by ID with full property + memory detail.

SDK: client.v1_1.memory.manage.get(id)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Record ID.
includeMemories	boolean	query	No	Include recent memories array.Default: `true`
propertyNames	string	query	No	Comma-separated property names to filter.

PATCH/api/v1.1/memory/manage/:idSecret keySDK

Update record properties

Direct property write — deterministic, no LLM, 0 credits. Replaces v1's `POST /memory/update`.

Usage: Use this for known property writes when you don't need extraction.

SDK: client.v1_1.memory.manage.update(id, ...)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Record ID.
properties	object	body	Yes	Property name → value map.
options	object	body	No	`{ versionGuard, arrayOp: 'append'\|'replace'\|'remove' }`.

Request

{
  "properties": { "Lifecycle Stage": "SQL", "ARR": 50000 }
}

PATCH/api/v1.1/memory/manageSecret keySDK

Bulk update records

Update properties on N records in one call. Replaces v1's `POST /memory/bulk-update`.

Usage: Use for batched direct writes.

SDK: client.v1_1.memory.manage.bulkUpdate()

DELETE/api/v1.1/memory/manage/:idSecret keySDK

Delete record (soft)

Soft-deletes a record. Sets pendingDeletion + 30-day TTL on the snapshot. Replaces v1's `POST /memory/delete-record`.

Usage: Use this instead of v1's POST action.

SDK: client.v1_1.memory.manage.delete(id)

POST/api/v1.1/memory/manage/:id/restoreSecret keySDK

Restore a pending-deletion record

Cancels pending deletion. Replaces v1's `POST /memory/cancel-deletion`.

Usage: Available during the 30-day grace window.

SDK: client.v1_1.memory.manage.restore(id)

GET/api/v1.1/memory/manage/:id/similarSecret keySDK

Find similar to seed record

Lookalike search seeded by a record's stored vectors. Replaces v1's `POST /similar` and `POST /memory/manage/similar`.

Usage: Lookalike prospecting and relationship mapping. REST verb on the seed record.

SDK: client.v1_1.memory.manage.similar(id)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Seed record ID.
topK	number	query	No	Number of neighbors.Default: `25`
dimensions	string	query	No	What drives similarity.Default: `hybrid`Options: `properties`, `memories`, `hybrid`

GET/api/v1.1/memory/manage/:id/property-historySecret keySDK

Property change history

Audit log of all property changes for one record. Replaces v1's `POST /memory/property-history`.

Usage: Compliance, sync conflict diagnosis, drift detection.

SDK: client.v1_1.memory.manage.propertyHistory(id)

GET/api/v1.1/memory/manage/pending-deletionsSecret keySDK

List pending-deletion records

Returns records currently in the soft-delete grace window with their `deletionTTL` timestamps.

Usage: Admin/compliance UI for managing pending deletions before TTL fires.

SDK: client.v1_1.memory.manage.pendingDeletions()

GET/api/v1.1/memory/manage/keysSecret keySDK

List CRM keys

List all CRM key types and values registered for the org. Replaces v1's `POST /list-keys`.

Usage: Inspect what identifier types (email, websiteUrl, recordId, custom) have been used.

SDK: client.v1_1.memory.manage.keys.list()

PATCH/api/v1.1/memory/manage/keysSecret keySDK

Bulk update CRM keys

Replaces v1's `POST /update-keys-batch`.

Usage: Bulk remap CRM keys (e.g., migrating identifier strategy).

SDK: client.v1_1.memory.manage.keys.bulkUpdate()

PATCH/api/v1.1/memory/manage/keys/:keyNameSecret keySDK

Update one CRM key

Replaces v1's `POST /update-keys`.

Usage: Update a single CRM key value.

SDK: client.v1_1.memory.manage.keys.update(keyName, ...)

DELETE/api/v1.1/memory/manage/keys/:keyNameSecret keySDK

Delete CRM key

Replaces v1's `POST /delete-keys`.

Usage: Remove a CRM key value.

SDK: client.v1_1.memory.manage.keys.delete(keyName)

POST/api/v1.1/memory/updateSecret keySDK

Single update (deprecated alias)

Updates one property or free-form memory with optional version checks and array operations.

Usage: Use this for targeted edits from admin tools, user workflows, or correction jobs.

SDK: client.memory.update()

Parameters

Field	Type	Where	Required	Description
recordId	string	body	Yes	Target record ID.
propertyName	string	body	No	Property to update.
propertyValue	unknown	body	No	New value for the property.

Request

{
  "recordId": "contact_123",
  "propertyName": "Lifecycle Stage",
  "propertyValue": "SQL"
}

Response

{
  "success": true,
  "data": {
    "previousValue": "Lead",
    "newValue": "SQL",
    "version": 4,
    "stores": {
      "snapshot": true,
      "lancedb": true,
      "freeform": false
    }
  }
}

SDK Example

const result = await client.memory.update({
  recordId: "contact_123",
  propertyName: "Lifecycle Stage",
  propertyValue: "SQL",
});
console.log(result.data.version);

POST/api/v1.1/memory/bulk-updateSecret keySDK

Bulk property update (deprecated alias)

Updates multiple properties on one record in a single request.

Usage: Use `PATCH /memory/manage` for v1.1.

SDK: client.memory.bulkUpdate()

Parameters

Field	Type	Where	Required	Description
recordId	string	body	Yes	Target record ID.
updates	object[]	body	Yes	Property updates: `[{ propertyName, propertyValue, collectionId?, confidence? }]`.

Request

{
  "recordId": "contact_123",
  "updates": [
    { "propertyName": "Lifecycle Stage", "propertyValue": "SQL" },
    { "propertyName": "Owner", "propertyValue": "Alex" }
  ]
}

Response

{
  "success": true,
  "data": {
    "results": [
      {
        "propertyName": "Lifecycle Stage",
        "previousValue": "Lead",
        "newValue": "SQL",
        "status": "updated"
      },
      {
        "propertyName": "Owner",
        "previousValue": null,
        "newValue": "Alex",
        "status": "created"
      }
    ],
    "version": 9
  }
}

SDK Example

const result = await client.memory.bulkUpdate({
  recordId: "contact_123",
  updates: [
    { propertyName: "Lifecycle Stage", propertyValue: "SQL" },
    { propertyName: "Owner", propertyValue: "Alex" },
  ],
});
console.log(result.data.version);

POST/api/v1.1/memory/deleteSecret keySDK

Delete memories (deprecated alias)

Soft-deletes specific memories or memories older than a date.

Usage: v1.1: scoped deletes use `DELETE /memory/manage/:id/memories/:memoryId`.

SDK: client.memory.delete()

Parameters

Field	Type	Where	Required	Description
ids	string[]	body	No	Specific memory IDs to delete.
crmKeys	object	body	No	Delete by record, email, or website scope.
olderThan	string	body	No	Delete memories older than this ISO timestamp.

Request

{
  "ids": ["mem_123", "mem_456"]
}

Response

{
  "success": true,
  "data": {
    "deletedCount": 2,
    "hardDeleteAt": "2026-04-17T12:00:00.000Z"
  }
}

SDK Example

const result = await client.memory.delete({
  ids: ["mem_123", "mem_456"],
});
console.log(result.data.deletedCount);

POST/api/v1.1/memory/delete-recordSecret keySDK

Delete a record (deprecated alias)

Soft-deletes all memories for one record across memory stores.

Usage: Use `DELETE /memory/manage/:id` for v1.1.

SDK: client.memory.deleteRecord()

Parameters

Field	Type	Where	Required	Description
recordId	string	body	Yes	Target record ID.
type	string	body	Yes	Entity type.
reason	string	body	No	Why the record is being deleted.

Request

{
  "recordId": "contact_123",
  "type": "Contact",
  "reason": "GDPR erasure request"
}

Response

{
  "success": true,
  "data": {
    "deletedCount": 12,
    "hardDeleteAt": "2026-04-17T12:00:00.000Z"
  }
}

SDK Example

const result = await client.memory.deleteRecord({
  recordId: "contact_123",
  type: "Contact",
  reason: "GDPR erasure request",
});
console.log(result.data.deletedCount);

POST/api/v1.1/memory/cancel-deletionSecret keySDK

Cancel deletion (deprecated alias)

Restores a soft-deleted record within the recovery window.

Usage: Use `POST /memory/manage/:id/restore` for v1.1.

SDK: client.memory.cancelDeletion()

Parameters

Field	Type	Where	Required	Description
recordId	string	body	Yes	Record to restore.
type	string	body	No	Entity type.

Request

{
  "recordId": "contact_123",
  "type": "Contact"
}

Response

{
  "success": true,
  "data": {
    "restoredCounts": {
      "snapshot": 8,
      "freeform": 4,
      "lancedb": 12
    },
    "warning": null
  }
}

SDK Example

const result = await client.memory.cancelDeletion({
  recordId: "contact_123",
  type: "Contact",
});
console.log(result.data.restoredCounts);

POST/api/v1.1/memory/property-historySecret keySDK

Property history (deprecated alias)

Fetches a paginated history of property changes for one record.

Usage: Use `GET /memory/manage/:id/property-history` for v1.1.

SDK: client.memory.propertyHistory()

Parameters

Field	Type	Where	Required	Description
recordId	string	body	Yes	Target record ID.
propertyName	string	body	No	Optional single-property filter.
from	string	body	No	Lower time bound (ISO).
to	string	body	No	Upper time bound (ISO).
limit	number	body	No	Page size.Default: `20`
nextToken	string	body	No	Cursor for the next page.

Request

{
  "recordId": "contact_123",
  "propertyName": "Lifecycle Stage",
  "limit": 20
}

Response

{
  "success": true,
  "data": {
    "entries": [
      {
        "entryId": "hist_123",
        "propertyName": "Lifecycle Stage",
        "propertyValue": "SQL",
        "collectionId": "col_contact",
        "updatedBy": "system",
        "createdAt": "2026-03-18T12:00:00.000Z"
      }
    ],
    "nextToken": null
  }
}

SDK Example

const result = await client.memory.propertyHistory({
  recordId: "contact_123",
  propertyName: "Lifecycle Stage",
  limit: 20,
});
console.log(result.data.entries);

POST/api/v1.1/memory/query-propertiesSecret keySDK

Natural-language property query (deprecated alias)

Searches one property across records using natural-language matching.

Usage: Use `POST /memory/retrieve` mode=`scout` for v1.1.

SDK: client.memory.queryProperties()

Parameters

Field	Type	Where	Required	Description
propertyName	string	body	Yes	Property to search.
query	string	body	Yes	Natural-language search phrase.
recordId	string	body	No	Optional single-record scope.
type	string	body	No	Entity filter.

Request

{
  "propertyName": "Pain Points",
  "query": "mentions security review delays"
}

Response

{
  "success": true,
  "data": {
    "matches": [
      {
        "recordId": "company_123",
        "propertyValue": "Security review is blocking rollout.",
        "matchReason": "Semantic match on security-related delays"
      }
    ],
    "processedCount": 150,
    "totalAvailable": 1200,
    "truncated": true,
    "capMessage": "Processed 150 of 1200 records"
  }
}

SDK Example

const result = await client.memory.queryProperties({
  propertyName: "Pain Points",
  query: "mentions security review delays",
});
console.log(result.data.matches);

POST/api/v1.1/memory/filter-by-propertySecret keySDK

Deterministic property filter (deprecated alias)

Filters records with explicit property operators and pagination.

Usage: Use `POST /memory/retrieve` mode=`filter` for v1.1.

SDK: client.memory.filterByProperty()

Parameters

Field	Type	Where	Required	Description
conditions	object[]	body	Yes	Property filters such as `equals`, `contains`, `gt`, or `exists`.
logic	string	body	No	How conditions are combined.Default: `AND`Options: `AND`, `OR`
type	string	body	No	Entity filter.Options: `contact`, `company`, `user`
limit	number	body	No	Page size.Default: `50`
nextToken	string	body	No	Cursor for additional results.

Request

{
  "conditions": [
    { "propertyName": "ARR", "operator": "gt", "value": 10000 },
    { "propertyName": "Renewal Date", "operator": "exists" }
  ],
  "logic": "AND"
}

Response

{
  "success": true,
  "data": {
    "records": [
      {
        "recordId": "company_123",
        "type": "Company",
        "matchedProperties": { "ARR": 50000 },
        "lastUpdatedAt": "2026-03-18T12:00:00.000Z"
      }
    ],
    "totalMatched": 1,
    "nextToken": null
  }
}

SDK Example

const result = await client.memory.filterByProperty({
  conditions: [
    { propertyName: "ARR", operator: "gt", value: 10000 },
    { propertyName: "Renewal Date", operator: "exists" },
  ],
  logic: "AND",
});
console.log(result.data.records);

18 endpoints

Governance And Schema

Manage guidelines, entity types, and schema collections that shape retrieval, extraction, and agent behavior.

GET/api/v1.1/guidelinesSecret keySDK

List guidelines

Lists guidelines with pagination and tag-based filters.

Usage: Use this to build governance pickers, admin tables, or sync flows.

SDK: client.guidelines.list()

Parameters

Field	Type	Where	Required	Description
limit	number	query	No	Page size.Default: `20`
nextToken	string	query	No	Cursor from a previous page.
tags	string \| string[]	query	No	Only include these tags.
excludeTags	string \| string[]	query	No	Exclude these tags.
summary	boolean	query	No	Omit the full `value` payload.

Response

{
  "success": true,
  "data": {
    "actions": [
      {
        "id": "act_123",
        "type": "variables",
        "payload": {
          "name": "ICP",
          "description": "Ideal customer profile",
          "tags": ["sales"]
        }
      }
    ],
    "count": 1,
    "nextToken": "eyJ..."
  }
}

SDK Example

const result = await client.guidelines.list({
  tags: ["sales"],
  limit: 10,
});
console.log(result.data.actions);

POST/api/v1.1/guidelinesSecret keySDK

Create a guideline

Creates a new guideline or governance variable.

Usage: Use this to seed policy, tone, or playbook content programmatically.

SDK: client.guidelines.create()

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	Guideline name.
value	string	body	No	Full markdown or text content.
description	string	body	No	Short summary.
tags	string[]	body	No	Tags for filtering and routing.
secure	boolean	body	No	Marks the value as sensitive.
slug	string	body	No	SDK compatibility alias.

Request

{
  "name": "Brand Voice",
  "description": "How our outbound voice should sound",
  "value": "# Tone\nConfident, direct, and specific.",
  "tags": ["marketing"]
}

Response

{
  "success": true,
  "data": {
    "id": "act_123",
    "type": "variables"
  }
}

SDK Example

const result = await client.guidelines.create({
  name: "Brand Voice",
  description: "How our outbound voice should sound",
  value: "# Tone\nConfident, direct, and specific.",
  tags: ["marketing"],
});
console.log(result.data.id);

GET/api/v1.1/guidelines/:id/structureSecret keySDK

Guideline heading structure

Returns the extracted markdown headings for one guideline.

Usage: Use this when you want section-aware editing or selective retrieval.

SDK: client.guidelines.getStructure()

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Guideline ID.

Response

{
  "success": true,
  "data": {
    "headings": ["Tone", "Do", "Do Not"]
  }
}

SDK Example

const result = await client.guidelines.getStructure("act_123");
console.log(result.data.headings);

GET/api/v1.1/guidelines/:id/sectionSecret keySDK

Guideline section content

Returns the content under a specific heading inside a guideline.

Usage: Use this for focused reads instead of fetching the full guideline value.

SDK: client.guidelines.getSection()

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Guideline ID.
header	string	query	Yes	Heading to extract.

Response

{
  "success": true,
  "data": {
    "header": "Tone",
    "content": "Confident, direct, and specific."
  }
}

SDK Example

const result = await client.guidelines.getSection("act_123", {
  header: "Tone",
});
console.log(result.data.content);

PATCH/api/v1.1/guidelines/:idSecret keySDK

Update a guideline

Partially updates guideline metadata or content.

Usage: Use this to replace content, append sections, or patch one heading in place.

SDK: client.guidelines.update()

Parameters

Field	Type	Where	Required	Description
name	string	body	No	Rename the guideline.
value	string	body	No	Replacement or appended content.
description	string	body	No	Updated summary.
tags	string[]	body	No	Updated tags.
secure	boolean	body	No	Updated security flag.
updateMode	string	body	No	Patch mode.Default: `replace`Options: `replace`, `append`, `section`, `appendToSection`
sectionHeader	string	body	No	Target heading for section updates.
separator	string	body	No	Separator inserted during append operations.
historyNote	string	body	No	Human-readable change note.

Request

{
  "updateMode": "section",
  "sectionHeader": "Tone",
  "value": "Confident, direct, and helpful.",
  "historyNote": "Refined messaging voice"
}

Response

{
  "success": true,
  "data": {
    "id": "act_123",
    "updated": true
  }
}

SDK Example

const result = await client.guidelines.update("act_123", {
  updateMode: "section",
  sectionHeader: "Tone",
  value: "Confident, direct, and helpful.",
});
console.log(result.data.updated);

DELETE/api/v1.1/guidelines/:idSecret keySDK

Delete a guideline

Deletes a guideline by ID.

Usage: Use this to remove governance content that should no longer route into Smart Guidelines or agents.

SDK: client.guidelines.delete()

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Guideline ID.

Response

{
  "success": true,
  "message": "Guideline deleted"
}

SDK Example

await client.guidelines.delete("act_123");

POST/api/v1.1/smart-updateSecret keySDK

Smart Update

AI-powered governance and schema evolution. Analyzes instruction + raw material against existing guidelines or collections and returns (or applies) a structured change plan.

Usage: Use when you have unstructured material (policy docs, meeting notes, feedback, competitor analysis, CRM exports) that should become structured governance or schema. The AI figures out what to create, update, or flag as conflicting.

SDK: client.guidelines.smartUpdate()

Parameters

Field	Type	Where	Required	Description
type	string	body	Yes	What to update.Options: `guideline`, `collection`
instruction	string	body	Yes	What to do with the material. Be specific about the goal.
material	string	body	Yes	Raw content: text, notes, JSON, meeting notes, policy docs, etc. Max 50K chars.
strategy	string	body	No	Execution strategy.Default: `suggest`Options: `suggest`, `safe`, `force`

Request

{
  "type": "guideline",
  "instruction": "Update our sales guidelines with this new enterprise discount tier",
  "material": "Enterprise customers (500+ seats) can now get 15% discount with VP approval. Standard pricing remains $49/seat.",
  "strategy": "suggest"
}

Response

{
  "success": true,
  "data": {
    "status": "planned",
    "creditsUsed": 3,
    "items": [
      {
        "itemId": "item_1",
        "action": "update_section",
        "target": "sales-playbook",
        "targetId": "act_123",
        "sectionHeader": "## Pricing",
        "reasoning": "Material contains new enterprise discount tier",
        "detail": "Updates pricing section with enterprise tier",
        "preview": {
          "before": "Standard: $49/seat/month.",
          "after": "Standard: $49/seat/month.\nEnterprise (500+ seats): 15% volume discount. Requires VP approval."
        },
        "hasConflict": false,
        "applied": false
      }
    ],
    "summary": "Added enterprise discount tier to sales playbook pricing section."
  }
}

SDK Example

// Suggest mode (plan only, no writes)
const plan = await client.guidelines.smartUpdate({
  type: "guideline",
  instruction: "Update sales guidelines with new enterprise pricing",
  material: "Enterprise customers (500+ seats) can now get 15% discount...",
  strategy: "suggest",
});

// Review the plan
for (const item of plan.data.items) {
  console.log(`${item.action} on ${item.target}: ${item.detail}`);
}

// Apply non-conflicting changes
const applied = await client.guidelines.smartUpdate({
  type: "guideline",
  instruction: "Update sales guidelines with new enterprise pricing",
  material: "Enterprise customers (500+ seats) can now get 15% discount...",
  strategy: "safe",
});

3 credits per call
Material trimmed at 50K characters with warning
Use strategy='suggest' first to review plan before applying

GET/api/v1.1/guidelines/{id}/attachmentsSecret keySDK

List Guideline Attachments

List all file attachments for a specific guideline. Returns metadata for each attachment including name, type, description, usage, audit status, and fetch analytics.

Usage: Discover what resources (scripts, templates, configs, data files, prompts, images) are attached to a guideline before accessing their content.

SDK: client.guidelines.listAttachments(guidelineId)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Guideline ID

Request

GET /api/v1.1/guidelines/guide-abc123/attachments

Response

{ "success": true, "data": [{ "id": "att_a1b2c3", "name": "compliance-check.py", "type": "script", "description": "GDPR compliance validator", "usage": "Run before sending emails with PII", "language": "python", "sizeBytes": 2340, "audit": { "status": "clean", "findings": [] } }] }

SDK Example

const attachments = await client.guidelines.listAttachments("guide-abc123");

0 credits
Returns metadata only -- use Get Attachment Content for file data

POST/api/v1.1/guidelines/{id}/attachmentsSecret key

Upload Guideline Attachment

Upload a file attachment to a guideline. Supports scripts, templates, references, configs, data files, schemas, prompts, and images. Files are automatically audited for quality and security by an LLM.

Usage: Attach actionable resources to guidelines so AI agents can access scripts, templates, and reference files alongside governance policies.

SDK: client.guidelines.uploadAttachment(guidelineId, options)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Guideline ID
file	file	body	Yes	File to upload (multipart/form-data)
metadata.type	string	body	Yes	Attachment type: script, template, reference, config, data, schema, prompt, image
metadata.description	string	body	Yes	What this file is (used for SmartContext routing)
metadata.usage	string	body	Yes	When and how agents should use this file
metadata.language	string	body	No	Programming language for scripts: python, javascript, typescript, bash, sql, etc.

Request

POST /api/v1.1/guidelines/guide-abc123/attachments
Content-Type: multipart/form-data

file: <binary>
metadata: { "type": "script", "description": "GDPR compliance validator", "usage": "Run before sending emails with PII", "language": "python" }

Response

{ "success": true, "data": { "id": "att_a1b2c3", "name": "compliance-check.py", "type": "script", "sizeBytes": 2340, "audit": { "status": "pending" } } }

SDK Example

const att = await client.guidelines.uploadAttachment("guide-abc123", {
  file: fs.readFileSync("./compliance-check.py"),
  type: "script",
  description: "GDPR compliance validator",
  usage: "Run before sending emails with PII",
  language: "python",
});

0 credits
Max 5 MB per file
Max 10 attachments per guideline
LLM audit runs automatically after upload

GET/api/v1.1/guidelines/{id}/attachments/{attachmentId}/contentSecret keySDK

Get Attachment Content

Download the full content of an attachment. Returns the raw file with appropriate Content-Type header.

Usage: Fetch actual file content for execution, rendering, or analysis. Each download is tracked for usage analytics.

SDK: client.guidelines.getAttachmentContent(guidelineId, attachmentId)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Guideline ID
attachmentId	string	path	Yes	Attachment ID

Request

GET /api/v1.1/guidelines/guide-abc123/attachments/att_a1b2c3/content

Response

Raw file content with Content-Type header matching the file MIME type

SDK Example

const content = await client.guidelines.getAttachmentContent("guide-abc123", "att_a1b2c3");

0 credits
Increments fetch count on the attachment for analytics

DELETE/api/v1.1/guidelines/{id}/attachments/{attachmentId}Secret keySDK

Delete Attachment

Permanently delete an attachment from a guideline. Removes both the file from storage and the metadata record.

Usage: Remove outdated, incorrect, or unnecessary attachments from guidelines.

SDK: client.guidelines.deleteAttachment(guidelineId, attachmentId)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Guideline ID
attachmentId	string	path	Yes	Attachment ID

Request

DELETE /api/v1.1/guidelines/guide-abc123/attachments/att_a1b2c3

Response

{ "success": true }

SDK Example

await client.guidelines.deleteAttachment("guide-abc123", "att_a1b2c3");

0 credits
Irreversible

GET/api/v1.1/entitiesSecret key

List entity types

Lists entity types available to the current organization.

Usage: Use this to inspect or seed the entity model that collections and memory records rely on.

Parameters

Field	Type	Where	Required	Description
limit	number	query	No	Page size.Default: `20`
nextToken	string	query	No	Cursor from a previous page.

Response

{
  "success": true,
  "data": {
    "entities": [
      { "id": "ent_contact", "name": "Contact", "status": "Active" }
    ],
    "count": 1
  }
}

These routes are server-only today and are not wrapped by the SDK.

POST/api/v1.1/entitiesSecret key

Create an entity type

Creates a new entity type for your organization.

Usage: Use this when your product needs memory records outside the default Contact and Company models.

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	Entity display name.
slug	string	body	No	URL-safe identifier.
properties	object[]	body	No	Initial property definitions.
identifierColumn	string	body	No	Primary identifier field name.

Request

{
  "name": "Partner",
  "identifierColumn": "Partner ID"
}

Response

{
  "success": true,
  "data": {
    "id": "ent_partner",
    "name": "Partner"
  }
}

GET/api/v1.1/collectionsSecret keySDK

List collections

Lists property collections with pagination and tag filters.

Usage: Use this to discover schemas available for extraction or record management.

SDK: client.collections.list()

Parameters

Field	Type	Where	Required	Description
limit	number	query	No	Page size.Default: `20`
nextToken	string	query	No	Cursor from a previous page.
tags	string \| string[]	query	No	Only include these tags.
excludeTags	string \| string[]	query	No	Exclude these tags.
summary	boolean	query	No	Return lighter-weight collection payloads.

Response

{
  "success": true,
  "data": {
    "collections": [
      { "id": "col_contact", "collectionName": "Contact Properties" }
    ],
    "count": 1
  }
}

SDK Example

const result = await client.collections.list({
  tags: ["sales"],
  limit: 10,
});
console.log(result.data.collections);

POST/api/v1.1/collectionsSecret keySDK

Create a collection

Creates a collection and optionally seeds its property schema. Each property defines a field that the AI extraction pipeline will populate when content is memorized.

Usage: Use this to define extraction-ready schemas for contacts, companies, or custom entity types.

SDK: client.collections.create()

Parameters

Field	Type	Where	Required	Description
collectionName	string	body	Yes	Display name (e.g., 'Contact Properties', 'Deal Tracker').
entityType	string	body	No	Entity type: 'Contact', 'Company', 'Deal', 'Employee', or any custom type.
definition	string	body	No	Description or extraction instructions for the whole collection. Helps AI understand the collection's purpose.
properties	PropertyDefinition[]	body	No	Initial property definitions. Can be added later via PATCH. Each property accepts: `propertyName` (required), `systemName` (auto-generated if omitted, immutable), `type` ('text' default, 'number', 'boolean', 'array', 'date', 'options'), `description` (extraction instructions for AI), `update` (true=replaceable, false=append-only), `options` (example values or comma-separated list), `tags` (string[] for extraction boosting), `status` ('Active' or 'Deleted').
name	string	body	No	SDK alias for `collectionName`.
collectionId	string	body	No	Optional custom ID. Auto-generated (UUID) if omitted.

Request

{
  "collectionName": "Contact Properties",
  "entityType": "Contact",
  "definition": "Customer profile fields for GTM workflows",
  "properties": [
    {
      "propertyName": "Lifecycle Stage",
      "type": "options",
      "options": "Lead, MQL, SQL, Customer, Churned",
      "description": "Current funnel stage",
      "update": true
    },
    {
      "propertyName": "Meeting Notes",
      "type": "array",
      "description": "Chronological log of meeting summaries and action items",
      "update": false,
      "tags": ["interaction"]
    }
  ]
}

Response

{
  "success": true,
  "data": {
    "id": "col_contact",
    "collectionName": "Contact Properties"
  }
}

SDK Example

const result = await client.collections.create({
  collectionName: "Contact Properties",
  entityType: "Contact",
  properties: [
    { propertyName: "Lifecycle Stage", type: "options", options: "Lead, MQL, SQL, Customer", update: true },
    { propertyName: "Meeting Notes", type: "array", description: "Chronological meeting log", update: false, tags: ["interaction"] },
  ],
});
console.log(result.data.id);

PATCH/api/v1.1/collections/:idSecret keySDK

Update a collection

Updates collection metadata or adds/modifies property definitions. **Incremental**: send only the properties you want to add or change -- existing properties not included in the request are preserved unchanged.

Usage: Use this to add new properties to an existing collection, modify property definitions, rename the collection, or soft-delete properties. You do NOT need to send the full property list.

SDK: client.collections.update()

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Collection ID.
collectionName	string	body	No	Updated display name (only if renaming).
definition	string	body	No	Updated description or extraction instructions.
properties	PropertyDefinition[]	body	No	Properties to add or modify. Send only new or changed properties -- existing ones are preserved. Each property accepts: `propertyName` (required), `systemName`, `type`, `description`, `update`, `options`, `tags`, `status`. See Create endpoint for full field reference.
historyNote	string	body	No	Human-readable change note for the audit trail.

Request

{
  "properties": [
    {
      "propertyName": "Location",
      "type": "text",
      "description": "City or region where the contact is based (e.g., 'San Francisco', 'London')",
      "update": true,
      "tags": ["identity"]
    },
    {
      "propertyName": "Budget Range",
      "type": "options",
      "options": "<50K, 50K-200K, 200K-1M, >1M",
      "description": "Estimated annual budget for our product category",
      "update": true,
      "tags": ["qualification"]
    }
  ],
  "historyNote": "Added Location and Budget Range properties for lead scoring"
}

Response

{
  "success": true,
  "data": {
    "id": "col_contact",
    "updated": true
  }
}

SDK Example

// Add a single property to an existing collection
const result = await client.collections.update("col_contact", {
  properties: [
    { propertyName: "Location", type: "text", description: "City or region", update: true, tags: ["identity"] },
  ],
  historyNote: "Added Location property",
});

// Add multiple properties at once
await client.collections.update("col_contact", {
  properties: [
    { propertyName: "Budget Range", type: "options", options: "<50K, 50K-200K, 200K-1M, >1M", update: true },
    { propertyName: "Decision Timeline", type: "text", description: "When they plan to buy", update: true },
    { propertyName: "Objections Log", type: "array", description: "Sales objections raised", update: false },
  ],
  historyNote: "Added qualification properties for lead scoring",
});

// Soft-delete a property
await client.collections.update("col_contact", {
  properties: [
    { propertyName: "Old Field", systemName: "old_field", status: "Deleted" },
  ],
  historyNote: "Retired Old Field property",
});

**Incremental updates**: Only send properties you want to add or change. Existing properties not in the request are preserved.
**Adding properties**: Include the new property in the `properties` array. Future memorize calls will automatically extract values for it.
**Soft-deleting properties**: Set `status: 'Deleted'` on a property to remove it from extraction without deleting stored values.
**Modifying properties**: Send the property with its existing `systemName` and the fields you want to change. `systemName` is immutable and identifies which property to update.
**Retroactive extraction**: Existing records are NOT retroactively updated when you add a property. Re-memorize content to populate new properties on existing records.

DELETE/api/v1.1/collections/:idSecret keySDK

Delete a collection

Deletes a collection by ID.

Usage: Use this to remove obsolete schemas.

SDK: client.collections.delete()

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Collection ID.

Response

{
  "success": true,
  "message": "Collection deleted"
}

SDK Example

await client.collections.delete("col_contact");

System collections cannot be deleted.

GET/api/v1.1/collections/:id/historySecret keySDK

Collection history

Returns historical versions for a collection, including optional diff mode.

Usage: Use this to audit schema changes or power version history views.

SDK: client.collections.history()

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Collection ID.
mode	string	query	No	History mode.Default: `full`Options: `full`, `diff`
limit	number	query	No	Page size.Default: `20`

Response

{
  "success": true,
  "data": {
    "actionId": "act_col123",
    "mode": "diff",
    "versions": [
      {
        "timestamp": "2026-03-18T12:00:00.000Z",
        "historyNote": "Added budget property",
        "changes": {
          "propertiesAdded": [],
          "propertiesRemoved": [],
          "propertiesModified": []
        }
      }
    ]
  }
}

SDK Example

const result = await client.collections.history("col_contact", {
  mode: "diff",
});
console.log(result.data.versions);

14 endpoints

Context

Knowledge layer for agent-readable documents. v1.1 introduces (1) the `shape='document'` path on `/memory/save` for single-doc writes, (2) a PG-backed doc-type registry under `/context/manage/doc-types/*`, and (3) async bulk-save under `/context/save/batch/*` (1-24h SLA via provider batch APIs). Legacy `/api/v1/agentdocs/*` paths are retired in v1.1.

GET/api/v1.1/context/manage/doc-typesSecret keySDK

List doc-types

List built-in + org-defined document subtypes from the PG-backed `context_doc_types` registry.

Usage: Discover what `type` values can be passed to `POST /memory/save` with `shape='document'`. Built-ins: `guideline`, `playbook`, `reference`, `template`, `brief`.

SDK: client.v1_1.context.docTypes.list()

Response

{
  "data": {
    "docTypes": [
      { "name": "guideline", "scope": "builtin", "displayName": "Guideline" },
      { "name": "playbook", "scope": "builtin", "displayName": "Playbook" },
      { "name": "icp_brief", "scope": "org", "displayName": "ICP Brief", "createdBy": "user_..." }
    ]
  }
}

POST/api/v1.1/context/manage/doc-typesJWTSDK

Create doc-type (admin)

Create an org-defined document subtype. Admin scope required.

Usage: Extend the doc-type registry with org-specific document categories (e.g. `icp_brief`, `pricing_sheet`, `objection_playbook`).

SDK: client.v1_1.context.docTypes.create()

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	Type identifier (slug). Lowercase, alphanumeric + underscores.
displayName	string	body	Yes	Human-readable name.
description	string	body	No	What this type is used for.

PATCH/api/v1.1/context/manage/doc-types/:nameJWTSDK

Update doc-type (admin)

Update an org-defined doc-type's metadata. Built-ins are immutable.

Usage: Edit display name / description without renaming.

SDK: client.v1_1.context.docTypes.update(name)

DELETE/api/v1.1/context/manage/doc-types/:nameJWTSDK

Delete doc-type (admin)

Soft-delete a doc-type. Use `?force=orphan` to reassign existing docs to `reference`. Built-ins cannot be deleted.

Usage: Retire an org-defined doc-type.

SDK: client.v1_1.context.docTypes.delete(name)

Parameters

Field	Type	Where	Required	Description
force	string	query	No	Set to `orphan` to reassign existing docs to `reference` and proceed with deletion.Options: `orphan`

POST/api/v1.1/context/manage/doc-types/:name/renameJWTSDK

Rename doc-type (admin)

Rename with alias forwarding — old name continues to resolve for backwards compatibility.

Usage: Evolve type taxonomy without breaking existing references.

SDK: client.v1_1.context.docTypes.rename(name)

Parameters

Field	Type	Where	Required	Description
newName	string	body	Yes	New slug.

GET/api/v1.1/context/manage/doc-types/:name/historySecret keySDK

Doc-type audit log

Returns the change history for a doc-type (create/update/rename/delete events).

Usage: Audit who changed what and when.

SDK: client.v1_1.context.docTypes.history(name)

POST/api/v1.1/context/save/batchSecret keySDK

Async bulk doc save (1-24h SLA)

Document-specific async bulk save via provider batch APIs (Anthropic Message Batches / OpenAI Batches / Bedrock CreateModelInvocationJob). 1-24h SLA. Returns `eventId` immediately. Tier-dependent max: basic 50 / pro 250 / enterprise 1000 docs.

Usage: Use for large knowledge migrations where 1-24h latency is acceptable in exchange for ~50% cost reduction. Webhook `context.batch-save.completed` is the preferred completion signal.

SDK: client.v1_1.context.save.batch()

Parameters

Field	Type	Where	Required	Description
items	object[]	body	Yes	Array of doc-save payloads (same shape as `POST /memory/save` with `shape='document'`).
options	object	body	No	`{ tier, callbackUrl }`. Provider auto-selected by org BYOK config.

Response

{
  "eventId": "evt_batch_...",
  "status": "queued",
  "estimatedCompletionMs": 7200000,
  "itemCount": 150,
  "cost": { "estimatedCredits": 1800, "tier": "pro", "savingsVsSync": "~50%" }
}

Tier-dependent max: basic 50 / pro 250 / enterprise 1000 documents per call.
Webhook `context.batch-save.completed` fires when the batch reaches terminal state.
Use `/context/save/batch/validate` (free) for pre-flight validation and cost estimate.

POST/api/v1.1/context/save/batch/validateSecret keySDK

Validate bulk doc save (no charge)

Pre-flight validation — returns `{ valid, itemCount, estimatedCredits }` or per-item errors. No credits charged.

Usage: Validate payload + estimate cost before committing to a billable batch run.

SDK: client.v1_1.context.save.batchValidate()

GET/api/v1.1/context/save/batch/:eventId/statusSecret keySDK

Poll bulk doc save status

Returns batch status and per-item results once terminal. Prefer the `context.batch-save.completed` webhook over polling.

Usage: Status check fallback when webhooks aren't wired.

SDK: client.v1_1.context.save.batchStatus(eventId)

GET/api/v1.1/contextSecret keySDK

List Context Docs

Lists all agent-readable documents with optional type and tag filtering.

Usage: Use this to list all context docs or filter by type (guideline, playbook, reference, template, brief). Old path /api/v1.1/agentdocs is RETIRED in v1.1 (returns 410 Gone).

SDK: client.context.list()

Parameters

Field	Type	Where	Required	Description
type	string	query	No	Filter by AgentDoc type.Options: `guideline`, `playbook`, `reference`, `template`, `brief`
tags	string \| string[]	query	No	Only include these tags.
excludeTags	string \| string[]	query	No	Exclude these tags.
recordId	string	query	No	Filter/boost docs linked to this record.
limit	number	query	No	Page size.Default: `20`
nextToken	string	query	No	Cursor from a previous page.
summary	boolean	query	No	Omit full content from response.

Response

{
  "success": true,
  "data": {
    "actions": [
      {
        "id": "act_123",
        "type": "variables",
        "payload": {
          "name": "Sales Qualification SOP",
          "agentDocType": "playbook",
          "description": "Step-by-step qualification process",
          "tags": ["sales", "qualification"]
        }
      }
    ],
    "count": 1
  }
}

SDK Example

const docs = await client.context.list({ type: 'playbook', tags: ['sales'] });

POST/api/v1.1/contextSecret keySDK

Create Context Doc

Creates a new agent-readable document. Set type to control how agents treat it.

Usage: Create guidelines (enforceable rules), playbooks (step-by-step processes), references (background info), templates (output formats), or briefs (account context). Old path /api/v1.1/agentdocs remains as a stable alias.

SDK: client.context.create()

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	Document name.
type	string	body	No	AgentDoc type.Default: `reference`Options: `guideline`, `playbook`, `reference`, `template`, `brief`
value	string	body	No	Markdown content.
description	string	body	No	Short description for search/routing.
tags	string[]	body	No	Categorization tags.
recordIds	string[]	body	No	Associated record IDs.

Request

{
  "name": "Sales Qualification SOP",
  "type": "playbook",
  "value": "## Step 1: Initial Contact\n...",
  "description": "Step-by-step sales qualification process",
  "tags": ["sales", "qualification"]
}

Response

{
  "success": true,
  "data": { "id": "act_456", "type": "variables", ... }
}

SDK Example

const doc = await client.context.create({
  name: 'Sales Qualification SOP',
  type: 'playbook',
  value: '## Step 1\n...',
  tags: ['sales'],
});

POST/api/v1.1/context/retrieveSecret keySDK

Retrieve Context Docs (canonical v1.1)

Canonical route for AI-powered doc routing. Semantically selects relevant context docs for a task with optional type filtering. Identical behavior to POST /ai/smart-docs.

Usage: Use this canonical path for new integrations. POST /ai/smart-docs and POST /api/v1.1/agentdocs/retrieve remain as stable aliases.

SDK: client.context.retrieve()

Parameters

Field	Type	Where	Required	Description
message	string	body	Yes	Task description with rich keywords.
types	string[]	body	No	Filter by types.Options: `guideline`, `playbook`, `reference`, `template`, `brief`
mode	string	body	No	Routing mode.Default: `auto`Options: `fast`, `deep`, `auto`
tags	string[]	body	No	Include only docs with these tags.
maxContentTokens	number	body	No	Token budget limit.Default: `10000`

Request

{
  "message": "Writing cold outreach to VP Sales at healthcare company",
  "types": ["guideline", "template"],
  "mode": "fast"
}

Response

{
  "success": true,
  "data": {
    "selection": [
      { "name": "Email Compliance Rules", "priority": "critical", "content": "..." }
    ],
    "compiledContext": "[GUIDELINE] SOURCE: Email Compliance Rules\n..."
  }
}

Canonical path added in v1.1. POST /ai/smart-docs and POST /api/v1.1/agentdocs/retrieve remain as stable aliases.

POST/api/v1.1/context/saveSecret keySDK

Save Context Doc with AI (canonical v1.1)

Save content as a context doc. AI-powered (default) or direct storage (aiExtraction=false). Supports per-token billing, pipeline presets, and multi-file upload.

Usage: Use this canonical path for new integrations. POST /smart-update and POST /api/v1.1/agentdocs/save remain as stable aliases.

SDK: client.context.save()

Parameters

Field	Type	Where	Required	Description
type	string	body	No	Target AgentDoc type.Options: `guideline`, `playbook`, `reference`, `template`, `brief`
instruction	string	body	Yes	What to do with the material, or document title for direct storage.
material	string	body	No	Content to save (up to 800K chars).
strategy	string	body	No	Execution strategy.Default: `suggest`Options: `suggest`, `safe`, `force`
aiExtraction	boolean	body	No	Set false to store content without AI. 0 credits. Default: true.
tier	string	body	No	Pricing tier.Options: `basic`, `pro`, `ultra`
pipelinePreset	string	body	No	Pipeline preset for accuracy/cost tradeoff.Options: `fast`, `standard`, `thorough`

Request

// AI-powered (default)
{
  "type": "guideline",
  "instruction": "Update our cold email policy with these new compliance rules",
  "material": "New regulations require...",
  "strategy": "suggest"
}

// Direct storage (no AI, 0 credits)
{
  "instruction": "Q2 Meeting Notes",
  "material": "## Decisions\nApproved budget...",
  "aiExtraction": false
}

Response

{
  "success": true,
  "data": {
    "plan": [
      { "action": "update", "guidelineId": "act_123", "name": "Cold Email Policy", "changes": "..." }
    ]
  }
}

Canonical path added in v1.1. POST /smart-update and POST /api/v1.1/agentdocs/save remain as stable aliases.

POST/api/v1.1/ai/smart-docsSecret keySDK

Smart Docs

AI-powered semantic routing that finds relevant AgentDocs for a task. Supports type filtering, record boosting, and session deduplication. Guidelines are prioritized in scoring.

Usage: Use instead of smart-guidelines when you need all types of agent-readable documents, not just enforceable rules.

SDK: client.ai.smartDocs()

Parameters

Field	Type	Where	Required	Description
message	string	body	Yes	Task description with rich keywords.
types	string[]	body	No	Filter by types.Options: `guideline`, `playbook`, `reference`, `template`, `brief`
agentdocIds	string[]	body	No	Filter to specific IDs.
agentdocNames	string[]	body	No	Filter by name.
tags	string[]	body	No	Include only docs with these tags.
excludeTags	string[]	body	No	Exclude docs with these tags.
recordId	string	body	No	Boost docs linked to this record.
mode	string	body	No	Routing mode.Default: `auto`Options: `fast`, `deep`, `auto`
sessionId	string	body	No	For session-based deduplication.
maxContentTokens	number	body	No	Token budget limit.Default: `10000`

Request

{
  "message": "Writing cold outreach to VP Sales at healthcare company",
  "types": ["guideline", "template"],
  "mode": "fast"
}

Response

{
  "success": true,
  "data": {
    "selection": [
      { "name": "Email Compliance Rules", "priority": "critical", "content": "..." },
      { "name": "Cold Email Template", "priority": "critical", "content": "..." }
    ],
    "compiledContext": "[GUIDELINE] SOURCE: Email Compliance Rules\n...",
    "usage": { "durationMs": 180, "selectedCount": 2 }
  }
}

SDK Example

const docs = await client.ai.smartDocs({
  message: 'Writing cold outreach to VP Sales',
  types: ['guideline', 'template'],
});

Guidelines are prioritized in scoring — they rank higher than other types at equal relevance.
Session deduplication works across smart-docs and smart-guidelines when using the same sessionId.
Compiled context uses type-aware headers: [GUIDELINE], [PLAYBOOK], [REFERENCE], etc.

4 endpoints

Agents And Evaluation

List prompt-action agents, inspect their expected inputs, run them, and evaluate memorization quality against a schema.

GET/api/v1.1/agentsSecret keySDK

List agents

Lists available agents for the current organization.

Usage: Use this to populate agent pickers or sync agent catalogs into your product.

SDK: client.agents.list()

Parameters

Field	Type	Where	Required	Description
limit	number	query	No	Page size.Default: `20`
nextToken	string	query	No	Cursor from a previous page.
summary	boolean	query	No	Return lighter agent payloads.Default: `false`
tags	string \| string[]	query	No	Include tag filter.
excludeTags	string \| string[]	query	No	Exclude tag filter.

Response

{
  "success": true,
  "data": {
    "actions": [
      {
        "id": "act_agent123",
        "type": "promptaction",
        "payload": { "name": "Lead Qualifier" }
      }
    ],
    "count": 1
  }
}

SDK Example

const result = await client.agents.list({ limit: 10 });
console.log(result.data.actions);

GET/api/v1.1/agents/:idSecret keySDK

Get agent details

Returns the full agent config and expected inputs inferred from template variables.

Usage: Use this when you need to render a runtime form before executing an agent.

SDK: client.agents.get()

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Agent ID.

Response

{
  "success": true,
  "data": {
    "id": "act_agent123",
    "payload": {
      "name": "Lead Qualifier",
      "instructions": [
        { "prompt": "Research {{companyName}} in {{industry}}", "order": 1 }
      ]
    },
    "expectedInputs": ["companyName", "industry"]
  }
}

SDK Example

const result = await client.agents.get("act_agent123");
console.log(result.data.expectedInputs);

POST/api/v1.1/agents/:id/runSecret keySDK

Run an agent

Executes an agent by ID and optionally streams its output.

Usage: Use this to operationalize prompt-action agents from your own app or workflow runner.

SDK: client.agents.run()

Parameters

Field	Type	Where	Required	Description
inputs	object	body	No	Values for agent template variables.
stream	boolean	body	No	Enable streaming mode.
email	string	body	No	Contact scope.
websiteUrl	string	body	No	Company scope.
recordId	string	body	No	Record scope.

Request

{
  "inputs": {
    "companyName": "Acme",
    "industry": "Manufacturing"
  },
  "recordId": "company_acme"
}

Response

{
  "success": true,
  "text": "Based on my analysis...",
  "metadata": {
    "model": "google/gemini-2.5-flash-lite-preview-09-2025",
    "toolCalls": [],
    "stepsExecuted": 3
  }
}

SDK Example

const result = await client.agents.run("act_agent123", {
  inputs: { companyName: "Acme", industry: "Manufacturing" },
  recordId: "company_acme",
});
console.log(result.text);

The SDK exposes `attachments` and `mcpTools`, but current server wiring primarily reads `inputs`, `stream`, `email`, `websiteUrl`, and `recordId`.

POST/api/v1.1/evaluate/memorization-accuracySecret keySDK

Memorization accuracy evaluation

Runs extraction, analysis, and schema-optimization phases against a collection.

Usage: Use this to test whether your schema captures the right information from real-world text.

SDK: client.evaluate.memorizationAccuracy()

Parameters

Field	Type	Where	Required	Description
collectionId	string	body	Yes	Collection under test.
input	string	body	Yes	Text to evaluate.

Request

{
  "collectionId": "col_contact",
  "input": "Jane is the VP of Sales at Acme and needs SOC 2 docs before buying.",
  "skipStorage": true
}

Response

{
  "success": true,
  "data": {
    "success": true,
    "phases": [
      { "phase": "extraction", "collectionName": "Contact Properties" },
      { "phase": "analysis" },
      { "phase": "schema" }
    ],
    "summary": {
      "totalDuration": 4400,
      "propertiesOptimized": 1
    }
  }
}

SDK Example

const result = await client.evaluate.memorizationAccuracy({
  collectionId: "col_contact",
  input: "Jane is the VP of Sales at Acme and needs SOC 2 docs before buying.",
  skipStorage: true,
});
console.log(result.data.summary);

7 endpoints

Usage And Key Management

Inspect usage and manage API keys. These routes are intended for authenticated application or dashboard contexts.

GET/api/v1.1/usage/currentJWT

Current month usage

Returns usage for the current month for one organization.

Usage: Use this to power billing dashboards, usage alerts, or internal admin views.

Parameters

Field	Type	Where	Required	Description
organizationId	string	query	Yes	Organization to inspect.

Response

{
  "success": true,
  "data": {
    "organizationId": "org_123",
    "month": "202603",
    "usage": {
      "apiCalls": 128,
      "credits": 42
    }
  }
}

POST/api/v1.1/keysJWT

Create an API key

Creates a new secret key for an organization.

Usage: Use this from your dashboard or internal tooling when you need to provision integration credentials.

Parameters

Field	Type	Where	Required	Description
organizationId	string	body	Yes	Owning organization ID.
description	string	body	Yes	Human-readable label.
scope	string	body	No	Key scope.Default: `admin`Options: `admin`, `member-only`, `read-only`
expiresIn	number \| 'never'	body	No	Expiry in days or `never`.Default: `never`

Request

{
  "organizationId": "org_123",
  "description": "Production CRM sync",
  "scope": "admin",
  "expiresIn": 90
}

Response

{
  "success": true,
  "data": {
    "id": "key_123",
    "apiKey": "sk_live_...",
    "scope": "admin",
    "organizationId": "org_123"
  },
  "warning": "Save this key now. It cannot be retrieved again."
}

GET/api/v1.1/keysJWT

List API keys

Lists redacted API keys for an organization.

Usage: Use this to render key inventories, rotation reminders, or governance dashboards.

Parameters

Field	Type	Where	Required	Description
organizationId	string	query	Yes	Organization to inspect.

Response

{
  "success": true,
  "data": {
    "keys": [
      {
        "id": "key_123",
        "description": "Production CRM sync",
        "scope": "admin",
        "keyPrefix": "sk_live_abcd"
      }
    ]
  }
}

GET/api/v1.1/keys/:idJWT

Get one API key

Returns the decrypted key plus owner metadata for one key ID.

Usage: Use this sparingly for internal admin flows that need to reveal or verify one key record.

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Key ID.
organizationId	string	query	Yes	Owning organization ID.

Response

{
  "success": true,
  "data": {
    "id": "key_123",
    "apiKey": "sk_live_...",
    "organizationId": "org_123",
    "userId": "user_123",
    "scope": "admin"
  }
}

POST/api/v1.1/keys/:id/regenerateJWT

Regenerate a key

Rotates an existing key and returns the new plain-text secret once.

Usage: Use this for key rotation workflows or incident response.

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Key ID.
organizationId	string	body	Yes	Owning organization ID.

Request

{
  "organizationId": "org_123"
}

Response

{
  "success": true,
  "data": {
    "newApiKey": "sk_live_new_...",
    "oldRevokedAt": "2026-03-18T12:00:00.000Z"
  },
  "warning": "Save this key now. It cannot be retrieved again."
}

DELETE/api/v1.1/keys/:idJWT

Revoke a key

Revokes an API key immediately.

Usage: Use this when a key is no longer needed or should be invalidated after a security event.

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Key ID.
organizationId	string	query	Yes	Owning organization ID.

Response

{
  "success": true,
  "message": "API key revoked"
}

GET / POST/api/v1.1/keys/validateNone

Validate a secret key

Resolves a secret key to its organization, user, key ID, and scope. No prior authentication required.

Usage: Use this to verify a secret key from external systems without requiring JWT auth.

Parameters

Field	Type	Where	Required	Description
Authorization	Bearer sk_live_...	header	No	Preferred way to send the key.
apiKey	string	body	No	POST fallback for sending the key in the body.

Response

{
  "success": true,
  "data": {
    "organizationId": "org_123",
    "userId": "user_123",
    "keyId": "key_123",
    "scope": "admin"
  }
}

This is the only public endpoint that requires no prior authentication.

7 endpoints

Organizations & Members

Manage your organization and team members. API keys are strictly scoped to one organization.

GET/api/v1.1/organizationsSecret keySDK

Get current organization

Returns the organization associated with the calling API key. Each key is scoped to exactly one org.

Usage: Use this to verify which org your API key is connected to and check org metadata.

SDK: client.organizations.get()

Response

{
  "id": "org_abc123",
  "name": "Acme Corp",
  "owner": "user_xyz",
  "numberOfMembers": 3,
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-03-20T14:30:00Z"
}

Free -- no credit cost.

POST/api/v1.1/organizationsSecret keySDK

Create organization

Creates a new organization with the calling user as owner. Auto-generates an admin API key for the new org, returned in the response (shown only once).

Usage: Use this for programmatic org provisioning. The new key is scoped to the new org only.

SDK: client.organizations.create({ name })

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	Organization name (1-100 characters).

Request

{ "name": "Acme Corp" }

Response

{
  "organization": {
    "id": "org_new123",
    "name": "Acme Corp",
    "owner": "user_xyz",
    "numberOfMembers": 1,
    "createdAt": "2026-04-06T10:00:00Z"
  },
  "apiKey": {
    "id": "key_abc",
    "key": "sk_live_xxxx...",
    "scope": "admin",
    "organizationId": "org_new123",
    "note": "Store securely. This key is shown only once."
  }
}

Free. Rate limited to 5 creates per hour per API key.

PATCH/api/v1.1/organizationsSecret keySDK

Update organization

Updates the organization name. Caller must be the organization owner.

Usage: Use this to rename your organization.

SDK: client.organizations.update({ name })

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	New organization name (1-100 characters).

Request

{ "name": "Acme Corp Updated" }

Response

{
  "id": "org_abc123",
  "name": "Acme Corp Updated",
  "owner": "user_xyz",
  "numberOfMembers": 3,
  "updatedAt": "2026-04-06T12:00:00Z"
}

Free. Owner only.

GET/api/v1.1/membersSecret keySDK

List members

Lists all members of the API key's organization with their roles and join dates.

Usage: Use this to see who has access to the organization.

SDK: client.members.list()

Parameters

Field	Type	Where	Required	Description
limit	number	query	No	Max results per page.Default: `25`
nextToken	string	query	No	Pagination cursor.

Response

{
  "members": [
    { "userId": "user_xyz", "email": "alice@acme.com", "role": "OWNER", "joinedAt": "2026-01-15T10:00:00Z" }
  ],
  "total": 3,
  "nextToken": null
}

Free.

POST/api/v1.1/members/inviteSecret keySDK

Invite members

Invites users by email (max 10 per call). Existing users get an in-app invitation. Non-users get an external invitation claimed on signup.

Usage: Use this to programmatically add team members to your organization.

SDK: client.members.invite({ emails })

Parameters

Field	Type	Where	Required	Description
emails	string[]	body	Yes	Email addresses to invite (1-10).
suppressEmail	boolean	body	No	Skip sending invitation email.Default: `false`

Request

{ "emails": ["alice@acme.com", "bob@acme.com"] }

Response

{
  "invited": [{ "email": "alice@acme.com", "userId": "user_123", "invitationId": "inv_456" }],
  "invitedExternal": [{ "email": "bob@acme.com", "invitationId": "inv_789" }],
  "alreadyMembers": [],
  "alreadyInvited": []
}

Free. Admin scope required.

DELETE/api/v1.1/members/:userIdSecret keySDK

Remove member

Removes a member from the organization. Owner can remove any non-owner. Non-owner can only remove themselves (leave). Cannot target the owner.

Usage: Use this to remove team members or leave an organization.

SDK: client.members.remove(userId)

Parameters

Field	Type	Where	Required	Description
userId	string	path	Yes	User ID to remove.

Free. Cannot target the organization owner -- returns 403.

PATCH/api/v1.1/members/:userId/roleSecret keySDK

Update member role

Changes a member's role between ADMIN and MEMBER. Owner only. Cannot change the owner's role.

Usage: Use this to promote or demote team members.

SDK: client.members.updateRole(userId, { role })

Parameters

Field	Type	Where	Required	Description
userId	string	path	Yes	User ID to update.
role	string	body	Yes	New role.Options: `ADMIN`, `MEMBER`

Request

{ "role": "ADMIN" }

Free. Owner only. Cannot change the owner's role.

8 endpoints

Platform Configuration

Manage entity types, MCP servers, and webhook destinations.

GET/api/v1.1/entities/:idSecret keySDK

Get entity type

Returns a single entity type by ID with its full schema definition.

Usage: Use this to inspect an entity type's configuration.

SDK: client.entityTypes.get(id)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Entity type ID.

Response

{
  "id": "act_abc123",
  "name": "Contact",
  "slug": "contact",
  "primaryKeyField": "email",
  "isSystem": true,
  "status": "Active",
  "schemaVersion": 1
}

Free.

PATCH/api/v1.1/entities/:idSecret keySDK

Update entity type

Updates entity type fields. Cannot change slug or isSystem. System entity types cannot be archived.

Usage: Use this to modify entity type metadata like name, icon, or color.

SDK: client.entityTypes.update(id, { name, description })

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Entity type ID.
name	string	body	No	Display name.
description	string	body	No	Description (max 500 chars).
status	string	body	No	Active or Archived.Options: `Active`, `Archived`

Free. Admin scope required.

DELETE/api/v1.1/entities/:idSecret keySDK

Archive entity type

Archives an entity type (does not destroy). Records of that type still exist. Reversible via PATCH with status: Active. System types cannot be archived.

Usage: Use this to retire entity types you no longer need.

SDK: client.entityTypes.archive(id)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Entity type ID.

Free. Admin scope required. System types (Contact, Company) are protected.

GET/api/v1.1/mcpsSecret keySDK

List MCP servers

Lists all registered MCP server connections (simple MCPs only, not OAuth).

Usage: Use this to see which MCP servers are connected to your organization.

SDK: client.mcps.list()

Response

{
  "items": [{
    "id": "mcp_abc",
    "name": "My Internal Tools",
    "serverUrl": "https://mcp.acme.com/sse?key=***",
    "transportType": "streamable-http",
    "authType": "bearer",
    "status": "active",
    "tools": [{ "name": "search_docs", "description": "Search internal docs" }],
    "disabledTools": []
  }],
  "total": 1
}

Free. OAuth MCPs (Google, Microsoft, HubSpot) are excluded.

POST/api/v1.1/mcps/testSecret keySDK

Test MCP connection

Tests a connection to an MCP server without creating a record. Returns discovered tools.

Usage: Use this to validate an MCP server URL before registering it.

SDK: client.mcps.test({ serverUrl, transportType, authType })

Parameters

Field	Type	Where	Required	Description
serverUrl	string	body	Yes	MCP server URL (max 2048 chars). SSRF-protected.
transportType	string	body	Yes	Transport type.Options: `sse`, `http`, `streamable-http`
authType	string	body	Yes	Authentication type.Options: `bearer`, `api_key`, `none`
apiKey	string	body	No	API key (required when authType is not none).

Response

{
  "connected": true,
  "tools": [{ "name": "search_docs", "description": "Search internal docs" }],
  "toolsCount": 1
}

Free. 10 second timeout. Private/internal URLs are blocked (SSRF protection).

POST/api/v1.1/mcpsSecret keySDK

Create MCP server

Registers a new MCP server connection with KMS-encrypted credentials.

Usage: Use this to connect an external MCP server to your organization.

SDK: client.mcps.create({ name, serverUrl, transportType, authType })

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	Display name (1-100 chars).
serverUrl	string	body	Yes	MCP server URL.
transportType	string	body	Yes	Transport type.Options: `sse`, `http`, `streamable-http`
authType	string	body	Yes	Auth type.Options: `bearer`, `api_key`, `none`
apiKey	string	body	No	API key (required when authType is not none).
description	string	body	No	Optional description.

Free. Admin scope required. Server URLs redacted in responses.

GET/api/v1.1/destinationsSecret keySDK

List destinations

Lists all webhook and S3 destinations for the organization.

Usage: Use this to see where events are being delivered.

SDK: client.destinations.list()

Response

{
  "success": true,
  "data": [{
    "id": "dest_abc",
    "name": "My Webhook",
    "type": "webhook",
    "config": { "url": "https://hooks.acme.com/personize", "method": "POST", "secret": "********" },
    "events": ["prompt.completed"],
    "isActive": true,
    "retryPolicy": { "maxRetries": 3, "backoffMs": 1000 }
  }]
}

Free. Max 25 destinations per org.

POST/api/v1.1/destinationsSecret keySDK

Create destination

Creates a webhook or S3 destination. Signing secret auto-generated for webhooks (returned only in create response).

Usage: Use this to set up event delivery to external systems.

SDK: client.destinations.create({ name, type, config, events })

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	Display name.
type	string	body	Yes	Destination type.Options: `webhook`, `s3`
config	object	body	Yes	Type-specific config (url/method/headers for webhook, bucketName/region/prefix for s3).
events	string[]	body	Yes	Events to subscribe to (e.g., prompt.completed).

Free. Admin scope required. SSRF protection on webhook URLs. Signing secret shown only once.

4 endpoints

Analytics

Read-only metrics for monitoring org health, memory performance, and credit usage.

GET/api/v1.1/analytics/overviewSecret keySDK

Organization overview

High-level snapshot of organization health: record counts, memory counts, active destinations and MCPs.

Usage: Use this for AI agent self-monitoring -- quick health check of the org.

SDK: client.analytics.overview()

Response

{
  "records": { "total": 12450 },
  "memories": { "total": 87320 },
  "properties": { "total": 62100, "avgPerRecord": 5.0 },
  "activeDestinations": 3,
  "activeMcps": 2
}

0.1 credits. 5 min cache.

GET/api/v1.1/analytics/memorySecret keySDK

Memory performance

Memorize and recall performance metrics for a time window.

Usage: Use this to monitor memory system health and performance trends.

SDK: client.analytics.memory({ window: '24h' })

Parameters

Field	Type	Where	Required	Description
window	string	query	No	Time window.Default: `24h`Options: `1h`, `24h`, `7d`, `30d`

Response

{
  "window": "24h",
  "memorize": { "totalCalls": 1240, "successRate": 0.98, "avgLatencyMs": 320 },
  "recall": { "totalCalls": 890, "successRate": 0.99, "avgLatencyMs": 210 }
}

0.1 credits. 5 min cache.

GET/api/v1.1/analytics/creditsSecret keySDK

Credit balance

Current credit balance, usage breakdown, and subscription details.

Usage: Use this to monitor credit consumption. Always free so agents can check without spending credits.

SDK: client.analytics.credits()

Response

{
  "balance": 48500,
  "included": 100000,
  "used": 51500,
  "purchased": 0,
  "monthly": 100000
}

Always free -- no credit cost.

GET/api/v1.1/analytics/operationsSecret keySDK

Operation counts

Operation volume and token usage for a time window.

Usage: Use this to track API usage patterns and token consumption.

SDK: client.analytics.operations({ window: '7d' })

Parameters

Field	Type	Where	Required	Description
window	string	query	No	Time window.Default: `24h`Options: `1h`, `24h`, `7d`, `30d`

Response

{
  "window": "7d",
  "operations": { "memorizes": 8700, "recalls": 6230 },
  "tokens": { "input": 2400000, "output": 890000, "total": 3290000 },
  "credits": { "used": 51500 }
}

0.1 credits. 5 min cache.

5 endpoints

Notifications

Send actionable notifications to organization members with link, callback, and dismiss buttons.

POST/api/v1.1/notificationsSecret keySDK

Send notification

Sends notifications to specific users with optional actionable buttons. Supports link, callback (webhook), and dismiss actions.

Usage: Use this for AI agents to surface decisions, alerts, or approvals to humans.

SDK: client.notifications.send({ recipients, title, body, actions })

Parameters

Field	Type	Where	Required	Description
recipients	string[]	body	Yes	User IDs to notify (max 50).
title	string	body	Yes	Notification title (max 200 chars).
body	string	body	Yes	Notification body (max 2000 chars).
priority	string	body	No	Priority level.Default: `normal`Options: `normal`, `urgent`
actions	Action[]	body	No	Actionable buttons (max 5). Types: link, callback, dismiss.

Request

{
  "recipients": ["userId1"],
  "title": "3 new leads matched your ICP",
  "body": "Found via overnight enrichment pipeline",
  "priority": "normal",
  "actions": [
    { "type": "link", "label": "Review", "url": "/records?filter=new" },
    { "type": "callback", "label": "Approve", "callbackUrl": "https://agent.acme.com/approve", "callbackPayload": { "batchId": "42" } },
    { "type": "dismiss", "label": "Dismiss" }
  ]
}

Response

{
  "success": true,
  "notificationIds": ["notif_abc123"],
  "recipientCount": 1
}

0.5 credits per recipient. Rate limited: 50 per org per hour. Callback URLs are SSRF-protected.

POST/api/v1.1/notifications/broadcastSecret keySDK

Broadcast notification

Sends a notification to all members matching a role group (all, admins, or owners).

Usage: Use this for org-wide announcements from AI agents.

SDK: client.notifications.broadcast({ recipientGroup, title, body })

Parameters

Field	Type	Where	Required	Description
recipientGroup	string	body	Yes	Target group.Options: `all`, `admins`, `owners`
title	string	body	Yes	Notification title (max 200 chars).
body	string	body	Yes	Notification body (max 2000 chars).
priority	string	body	No	Priority level.Default: `normal`Options: `normal`, `urgent`
actions	Action[]	body	No	Actionable buttons (max 5).

0.5 credits per recipient. Rate limited: 50 per org per hour. Max 100 recipients per broadcast.

GET/api/v1.1/notificationsSecret keySDK

List notifications

Lists notifications for the API key's user, newest first. Excludes dismissed notifications.

Usage: Use this to display a notification inbox or check for pending actions.

SDK: client.notifications.list()

Parameters

Field	Type	Where	Required	Description
limit	number	query	No	Max results.Default: `25`
nextToken	string	query	No	Pagination cursor.

Free.

GET/api/v1.1/notifications/unread-countSecret keySDK

Unread count

Returns the number of unread notifications for the API key's user.

Usage: Use this for badge counts in the dashboard.

SDK: client.notifications.unreadCount()

Response

{ "unreadCount": 5 }

Free.

POST/api/v1.1/notifications/:id/actionSecret keySDK

Execute callback action

Executes a callback action on a notification. Fires a signed webhook (HMAC-SHA256) to the callbackUrl with the callbackPayload. Callbacks expire after 7 days.

Usage: Use this to trigger human-in-the-loop approvals from the dashboard.

SDK: client.notifications.executeAction(id, actionId)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Notification ID.
actionId	string	body	Yes	Action ID from the notification's actions array.

Response

{ "status": "delivered" }

Free. Returns 410 if callback expired. Webhook signed with HMAC-SHA256.