API Reference · v1.1

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

177 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 is deprecated and still supported; 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, the version to build against for all new integrations. v1 is deprecated but still works for existing integrations; it is documented separately at /docs/api/v1 (API v1 Reference (Deprecated)). No retirement date has been set yet.

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/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.

GET/api/v1.1/me/entitlementsSecret keySDK

Plan entitlements

Returns the resolved plan entitlements for the current organization: limits, feature flags, BYOK policy, and per-operation tier availability.

Usage: Use this to drive client-side feature gating (for example, hiding BYOK config UI when `byok` is `disabled`) without hardcoding plan names.

SDK: client.entitlements()

Response

{
  "success": true,
  "data": {
    "planName": "Free Plan",
    "limits": {
      "maxOrganizations": 1,
      "maxAiAutomations": 2,
      "maxRecordsSyncIn": 1000,
      "maxRecordsSyncOut": 1000,
      "maxApiCallsPerMonth": 20000,
      "maxApiCallsPerMinute": 160,
      "maxActiveSchedules": 5,
      "maxSchedulesPerRecord": 2,
      "maxRetrievesPerMonth": 50000,
      "maxPromptsPerMonth": 2000
    },
    "features": ["basic_analytics", "standard_support"],
    "byok": "optional",
    "operationTiers": {
      "memorize": ["basic", "pro", "pro_fast", "ultra"],
      "generate": ["basic", "pro", "ultra"],
      "retrieval": ["fast", "deep"]
    }
  }
}

SDK Example

const result = await client.entitlements();
console.log(result.data.byok, result.data.operationTiers);

No extra DB call -- the plan is already resolved by the API key auth middleware.
`byok` is `disabled` | `optional` | `required`; values shown above reflect the Free Plan and vary by plan.

4 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/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.

7 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 (shapes: text, property, document, identifiers, items[])

The one write endpoint. The `shape` field selects what is being saved: `text` (free text, AI extraction), `property` (direct property writes, no AI), `document` (typed knowledge documents), `identifiers` (add record identifiers), or send `items[]` to save several independent items in one call. Address the target record with `record` or `about: 'self'`.

Usage: Use `shape: 'text'` to extract memories and properties from free text, `shape: 'property'` for exact values, `shape: 'document'` for guidelines, playbooks and references, and `items[]` for up to 100 mixed saves. Writes are queued: the response carries a `jobId` and a `statusUrl` to poll.

SDK: client.memory.save()

Parameters

Field	Type	Where	Required	Description
shape	string	body	No	What is being sent. An omitted `shape` defaults to `shortform`, which runs memorizePro and extracts both memories and properties. `shape: 'text'` maps to the same path, or to a memories-only path (no property extraction) when `extractProperties` is `false`. `identifiers` is selected only by sending `shape: 'identifiers'`.Default: `shortform`Options: `text`, `property`, `document`, `identifiers`
content	string	body	No	The source content to store. Required for `text` and `document`.
extractProperties	boolean	body	No	Top-level switch, valid only with `shape: 'text'`. `false` stores memories without extracting properties.Default: `true`
record	object	body	No	Canonical record address, for example `{ id }` or `{ email }` plus an entity type. Mutually exclusive with `about`.
about	string	body	No	Set to `'self'` to target the caller's own record. Mutually exclusive with `record`.Options: `self`
recordId	string	body	No	Flat record identity. Present = record-scoped write. Absent = org-scoped.
type	string	body	No	Entity type. For `shape: 'document'` this is the document type (e.g. `guideline`, `playbook`, `reference`, `template`, `brief`, or org-defined).
properties	object	body	No	Seed/hints for `text`; the values to write for `property`; metadata for `document`.
add	object[]	body	No	For `shape: 'identifiers'`: the identifiers to add, as `[{ name, value }]`. Needs a record identity (`record`, `about: 'self'`, `recordId`, an email, or similar). Single record only: `identifiers` inside `items[]` is rejected with 400.
items	object[]	body	No	Batch mode: up to 100 independent save items, each with its own `shape`. `identifiers` is not accepted as an item shape. Returns 207 Multi-Status on partial failures.
idempotencyKey	string	body	No	Body spelling of the `Idempotency-Key` header, 8 to 200 characters. A retry with the same key does not save twice. Not accepted with `shape: 'identifiers'`.
relations	DeclaredRelation[]	body	No	Caller-declared graph edges, written synchronously and free of additional charge. Each item: `{ relationType, toRecordId \| toIdentity{kind,value} + toEntityType, confidence? }`. `toIdentity.kind` is a standard kind (email, websiteUrl, linkedinHandle, phoneNumber, salesforceId, crmDealId, name) or the org's own primary identifier for `toEntityType`; an unknown kind is rejected with 400 `INVALID_IDENTITY_KIND`.
visibility	string	body	No	Visibility of the saved document or memory. Passed through for `document` saves.
options	object	body	No	Per-write controls: `mode` (sync/async/bulk), `tier`, `upsert`, `enrich`, `aiGenerated`, `collectionIds`.

Request

{
  "shape": "text",
  "content": "Meeting notes: Jane prefers email and is evaluating in Q2.",
  "record": { "email": "jane@example.com", "type": "contact" },
  "idempotencyKey": "notes-2026-10-26-001",
  "options": { "tier": "pro" },
  "collectionGraph": true,
  "smartGraph": true,
  "relations": [
    { "relationType": "works_at",
      "toIdentity": { "kind": "websiteUrl", "value": "acme.com" },
      "toEntityType": "company" }
  ]
}

Response

{
  "recordId": "rec_xyz",
  "jobId": "evt_...",
  "statusUrl": "/api/v1.1/memory/jobs/evt_...",
  "estimatedCompletionMs": 12000,
  "cost": { "credits": 3, "tier": "pro" },
  "warnings": []
}

SDK Example

// Text: extracts memories and properties
const result = await client.memory.save({
  shape: "text",
  content: "Jane prefers email and is evaluating in Q2.",
  record: { email: "jane@example.com", type: "contact" },
});

// Property: direct write, no AI
await client.memory.save({
  shape: "property",
  record: { email: "jane@example.com", type: "contact" },
  properties: { deal_stage: "Proposal" },
});

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

// Poll the job
const status = await client.memory.getJob(result.jobId);

An omitted `shape` defaults to `shortform`: it runs memorizePro and extracts both memories and properties. `shape: 'text'` takes the same path, or a memories-only path when top-level `extractProperties` is `false`.
Top-level `extractProperties` is valid only with `shape: 'text'`. It is distinct from `options.extractProperties`, which applies to `document` saves.
`items[]` accepts `shortform`, `freeform` and `document` items, up to 100 per call. Do not mix top-level content with `items[]`.
`shape: 'identifiers'` is single record only. It needs a record identity (`record`, `about: 'self'`, `recordId`, an email, or similar) and is rejected with 400 inside `items[]`. It does not accept `mode`, `options` or `idempotencyKey`.
Every save is queued. The response returns a `jobId` and a `statusUrl`; poll `GET /api/v1.1/memory/jobs/:jobId` for the result. Non-fatal issues are listed in `warnings[]`.
Tier billed is surfaced in `response.cost.tier`. `recordId` or `record` carries scope: present = record-scoped, absent = org-scoped.
Looking for the old endpoint names? See [/docs/api/migration](/docs/api/migration).

GET/api/v1.1/memory/jobs/:jobIdSecret keySDK

Get job status

One uniform status for an async save, batch save or import job. Use the `jobId` (or the `statusUrl`) returned by a save.

Usage: Poll until `state` is terminal (`succeeded`, `failed` or `partial`) to know when a save has finished.

SDK: client.memory.getJob(jobId)

Parameters

Field	Type	Where	Required	Description
jobId	string	path	Yes	Job ID returned by `POST /api/v1.1/memory/save` or `POST /api/v1.1/memory/import`.

Response

{
  "jobId": "evt_...",
  "kind": "memorize",
  "state": "running",
  "warnings": []
}

SDK Example

const job = await client.memory.getJob("evt_...");
if (job.state === "succeeded") {
  // done
}

`kind` is `memorize`, `save-batch` or `import`.
`state` is one of `queued`, `running`, `succeeded`, `failed`, `partial`.
A job owned by another organization returns 404 `not_found`. Import jobs are visible to organization admins only.

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

Delete (record, memory, document, edge, property, attachment, identifier)

The one delete endpoint. `type` selects what is deleted. A `record` delete is soft by default and restorable for 30 days; send `hard: true` to delete permanently.

Usage: Delete records, memories, documents, graph edges, properties, attachments or identifiers with one call shape.

SDK: client.memory.delete()

Parameters

Field	Type	Where	Required	Description
type	string	body	Yes	What to delete.Options: `record`, `memory`, `document`, `edge`, `property`, `attachment`, `identifier`
record	object	body	No	Record address. A soft record delete needs `record.id` and `record.entityType`. A hard record delete takes `record.id` or `ids`.
ids	string[]	body	No	IDs to delete (memories, documents, edges, attachments, or records for a hard delete). Either `ids` or `record` is required.
hard	boolean	body	No	Permanent delete. For `type: 'record'` this skips the soft-delete grace window. A hard batch needs `confirm: true`.Default: `false`
propertyNames	string[]	body	No	Property names to remove. Used by `property` and `identifier`.
reason	string	body	No	Optional audit reason.
guidelineId	string	body	No	Used by `attachment`: the document that owns the attachment.

Request

{
  "type": "record",
  "record": { "id": "rec_abc123", "entityType": "contact" },
  "reason": "Customer request"
}

Response

{
  "success": true,
  "soft": true,
  "warnings": []
}

SDK Example

// Soft delete (default for records, restorable for 30 days)
await client.memory.delete({
  type: "record",
  record: { id: "rec_abc123", entityType: "contact" },
});

// Permanent delete
await client.memory.delete({
  type: "record",
  record: { id: "rec_abc123" },
  hard: true,
});

`record` deletes are soft unless `hard: true`. Restore a soft delete with `POST /api/v1.1/memory/manage/:id/restore`.
Fields that the chosen `type` does not use are not an error; they are named in `warnings[]`.
Validation failures return 400 `VALIDATION_ERROR`.

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, with the 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 (6 modes)

Unified retrieve with 6 modes: `scout` (default, multi-source no-LLM), `brief` (LLM synthesis), `expand` (paginate), `filter` (structured property and document filters), `fetch` (by IDs) and `similar` (records or text similar to a seed).

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

SDK: client.memory.retrieve()

Parameters

Field	Type	Where	Required	Description
message	string	body	No	Natural language query. Required for `scout`, `brief`, `expand`. With `sources.documents` or `sources.properties` set to true, a message alone runs an org-wide scout (no record anchor needed).
mode	string	body	No	Retrieval mode.Default: `scout`Options: `scout`, `brief`, `expand`, `filter`, `fetch`, `similar`
identifiers	object	body	No	`{ emails?, websites?, record_ids? }`: scope retrieval to known entities.
filters	object	body	No	Required for `mode='filter'`. Structured property filters: `groups`, `groupLogic`, `crmFilter`, `collectionIds`, and `documents`.
filters.groups[].conditions[].operator	string	body	No	Filter operator. Canonical list: EQ, NEQ, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH, GT, GTE, LT, LTE, BETWEEN, NOT_BETWEEN, IN, NOT_IN, IS_SET, IS_NOT_SET, IS_EMPTY, EXISTS, NOT_EXISTS. Common aliases such as `equals` are normalized.Options: `EQ`, `NEQ`, `CONTAINS`, `NOT_CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `GT`, `GTE`, `LT`, `LTE`, `BETWEEN`, `NOT_BETWEEN`, `IN`, `NOT_IN`, `IS_SET`, `IS_NOT_SET`, `IS_EMPTY`, `EXISTS`, `NOT_EXISTS`
filters.groups[].logic	string	body	No	How the conditions inside one group combine.Default: `AND`Options: `AND`, `OR`
filters.groupLogic	string	body	No	How groups combine with each other. Anything other than `AND` joins with `OR`.Default: `OR`Options: `AND`, `OR`
filters.documents	object	body	No	Document listing, `mode='filter'` only. Stands alone: cannot be combined with `groups`, `crmFilter`, `collectionIds` or `listAll`. Fields: `docType`, `tags`, `status`, `recordId`, `limit` (max 200), `cursor`.
ids	string[]	body	No	Required for `mode='fetch'`. Direct memory/record IDs to load. Fetch also accepts the document and record additions described in the notes.
seed	object	body	No	Required for `mode='similar'`. Send exactly one of `seed.record` (a record address) or `seed.text` (1 to 2000 characters, embedded once). `seed.entityType` only labels the response for text seeds.
cursor	string	body	No	Opaque page token for `mode='similar'`. Take it from `nextCursor` in the previous response. Cursors are bound to the query: reuse them only with the same request.
topK	number	body	No	Alias of `limit` for `mode='similar'` only. `limit` wins when both are sent.
limit	number	body	No	Max results. For `mode='similar'` this is the page size.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.memory.retrieve({
  mode: "scout",
  message: "AI automation buyers",
});

// Brief: LLM-synthesized answer
const brief = await client.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.memory.retrieve({
  mode: "filter",
  filters: {
    groups: [{ logic: "AND", conditions: [
      { property: "ARR", operator: "GT", value: 10000 },
      { property: "Renewal Date", operator: "EXISTS" },
    ] }],
  },
});

// Similar: nearest neighbours of a seed, paged with an opaque cursor
const similar = await client.memory.retrieve({
  mode: "similar",
  seed: { text: "AI automation buyers" },
  limit: 10,
});
const next = await client.memory.retrieve({
  mode: "similar",
  seed: { text: "AI automation buyers" },
  limit: 10,
  cursor: similar.nextCursor,
});

`mode='similar'` takes `seed.record` or `seed.text` (exactly one), `limit` (1 to 100, default 10) with `topK` as an alias (`limit` wins), and `cursor`. The response carries `nextCursor`; cursors are opaque and bound to the query.
`mode='fetch'` also loads documents and records by ID. `mode='filter'` accepts `filters.documents` for document listing.
A `message` with `sources.documents` or `sources.properties` set to true runs an org-wide scout with no record anchor. Other sources return empty without a record.
`filters.groups[].logic` defaults to `AND`. `filters.groupLogic` defaults to `OR`: anything other than `AND` joins groups with `OR`.
Looking for the old endpoint names? See [/docs/api/migration](/docs/api/migration).
`scout` ~ 1 credit. `brief` ~ 2 credits. `expand`/`filter`/`fetch` cheap (≤1 credit) when no LLM is in the loop.
Retrieved documents default to `status='active'` (widen via `statuses`). Each returned document carries `updatedAt` (ISO 8601 last-update) and `status` (`active`/`draft`/`retired`/`archived`) so agents can weigh staleness.

POST/api/v1.1/memory/retrieve/feedbackSecret keySDK

Record retrieve feedback

Records a thumbs-up/down (and optional notes) on a previous `POST /retrieve` call, keyed by its `retrievalId`.

Usage: Use this to capture end-user feedback on retrieve answers so you can track answer quality over time.

SDK: client.retrieveFeedback({ retrievalId, rating, notes })

Parameters

Field	Type	Where	Required	Description
retrievalId	string	body	Yes	The `retrievalId` returned by the earlier `POST /retrieve` call.
rating	number	body	Yes	1 = thumbs up, 0 = neutral, -1 = thumbs down.Options: `-1`, `0`, `1`
notes	string	body	No	Optional free-text notes, up to 2000 characters.

Request

{
  "retrievalId": "5f2c1e9a-0b1f-4a3d-9c2e-1a2b3c4d5e6f",
  "rating": 1,
  "notes": "Answer correctly cited the renewal date."
}

Response

{
  "feedbackId": "fb_...",
  "retrievalId": "5f2c1e9a-0b1f-4a3d-9c2e-1a2b3c4d5e6f"
}

Returns 404 for organizations that do not have unified retrieve (`POST /retrieve`) enabled -- feedback capture shares that endpoint's rollout gate.

GET/api/v1.1/memory/retrieve/:retrievalId/synthesisSecret keySDK

Poll deferred retrieve synthesis

Polls for the result of a deferred LLM synthesis started by a `POST /retrieve` call, when the synthesis was not returned inline.

Usage: Use this after a `POST /retrieve` response indicates a deferred synthesis, polling until `status` moves from `pending` to `ok` or `error`.

SDK: client.getSynthesis(retrievalId)

Parameters

Field	Type	Where	Required	Description
retrievalId	string	path	Yes	The `retrievalId` returned by the earlier `POST /retrieve` call. Must be a UUID.

Response

{
  "retrievalId": "5f2c1e9a-0b1f-4a3d-9c2e-1a2b3c4d5e6f",
  "orgId": "org_123",
  "status": "ok",
  "answer": "John's budget is $50k, evaluating in Q2.",
  "confidence": "high",
  "sourcesUsed": ["rec_456"],
  "durationMs": 1840,
  "totalTokens": 612,
  "createdAt": 1771200000000,
  "completedAt": 1771200001840
}

`status` is `pending` (poll again), `ok` (answer/confidence/sourcesUsed populated), or `error` (`errorMessage` populated).
Returns 404 with `error: 'synthesis_not_found'` when no deferred synthesis row exists for that `retrievalId`, and 404 with `error: 'not_found'` for organizations without unified retrieve enabled.

2 endpoints

Memory: restore and pending deletions

Restore a soft-deleted record and list records in the deletion grace window. For the old endpoint names see [/docs/api/migration](/docs/api/migration).

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

Restore a pending-deletion record

Cancels a pending soft-deletion within the 30-day grace window, restoring the record. A soft delete comes from `POST /api/v1.1/memory/delete`.

Usage: Undo an accidental or premature soft delete before the hard-delete TTL fires.

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

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Record ID segment. Not read by the current handler -- see notes.
recordId	string	body	Yes	Record to restore. Set this to the same value as the `:id` in the URL (see notes).
type	string	body	No	Entity type.Default: `contact`

Request

{
  "recordId": "rec_abc123",
  "type": "contact"
}

Response

{
  "success": true,
  "data": {
    "success": true,
    "restoredCounts": { "snapshot": "restored", "freeform": "restored", "lancedb": "restored" }
  }
}

The `:id` path segment scopes the call. If you also send `recordId` in the body it takes precedence, which keeps older v1-style callers working unchanged.
Returns 409 (`DELETION_FINALIZED`) if the 30-day grace window already elapsed and the hard delete has run.

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 reviewing or reversing pending deletions before the TTL fires.

SDK: client.v1_1.memory.manage.getPendingDeletions(params)

Parameters

Field	Type	Where	Required	Description
type	string	body	No	Filter to one entity type.
limit	number	body	No	Page size.Default: `50`
nextToken	string	body	No	Cursor from a previous page.

Response

{
  "success": true,
  "data": {
    "records": [
      { "recordId": "rec_abc123", "type": "contact", "pendingDeletion": true, "pendingDeletionAt": "2026-08-01T00:00:00.000Z", "deletionTTL": 1785000000, "hardDeleteAtEstimated": "2026-08-31T00:00:00.000Z", "email": "jane@example.com" }
    ],
    "nextToken": null
  }
}

Filters (`type`, `limit`, `nextToken`) are read from the JSON request body, not the query string, even though this is a GET route.

16 endpoints

Graph & Relation Types

Configure the property-to-edge inference graph used by memory saves: the relation type taxonomy (the vocabulary of edge kinds), per-org rules that map an entity property to an inferred edge, and org-level graph settings. Canonical at the v1.1 path `/api/v1.1/memory/manage/graph/*`. Relation types are one set of operations, not three separate features, despite appearing under both the graph and memory taxonomies. On the v1.1 mount, every WRITE route (create, batch create, update, delete) additionally requires `admin` scope on the API key, matching the rest of the `/memory/manage` taxonomy; reads are not admin-gated on either mount.

GET/api/v1.1/memory/manage/graph/configSecret keySDK

Get graph config bundle

Returns a full snapshot of the org's graph configuration: relation types, rules, and settings, in one call.

Usage: Use this to render a graph-configuration screen without three separate list calls.

SDK: client.v1_1.memory.graph.getConfig()

Response

{
  "success": true,
  "data": {
    "relationTypes": [
      { "typeName": "works_at", "displayLabel": "Works At", "category": "role", "isBuiltin": true, "isSingleValued": true, "isSymmetric": false, "inverseType": "employs", "defaultWeight": 1, "allowedFromTypes": ["contact"], "allowedToTypes": ["company"], "examples": [], "isActive": true, "scope": "system" }
    ],
    "rules": [
      { "ruleId": "rule_abc", "sourceEntityType": "contact", "propertyName": "company", "relationType": "works_at", "targetEntityType": "company", "valueShape": "scalar", "resolveBy": ["websiteUrl", "name"], "normalize": "companyHint", "allowStub": true, "allowSelfType": false, "inverse": false, "confidence": 0.9, "isBuiltin": true, "isActive": true, "scope": "system", "overridesSystem": false }
    ],
    "settings": { "inheritSystemRules": true }
  }
}

Empty/un-activated orgs (no kit installed yet) omit system built-ins from `relationTypes` and `rules`, so the response shows no phantom graph schema.

PUT/api/v1.1/memory/manage/graph/configSecret keySDK

Replace graph config bundle

Atomic bundle upsert: creates or updates relation types, then rules, then settings, in that order, from one payload.

Usage: Use this to provision a full graph schema (relation types + rules + settings) for an org in one call, for example from a setup kit.

SDK: client.v1_1.memory.graph.putConfig(body)

Parameters

Field	Type	Where	Required	Description
relationTypes	object[]	body	No	Relation types to create. Same shape as the create-relation-type body. Max 100.
rules	object[]	body	No	Rules to create. Same shape as the create-rule body. Max 200.
settings	object	body	No	`{ inheritSystemRules: boolean }`.

Response

{
  "success": true,
  "data": {
    "relationTypes": [ { "typeName": "works_at" } ],
    "rules": [ { "ruleId": "rule_abc" } ],
    "settings": { "inheritSystemRules": true }
  },
  "notice": "Graph rule saved. Synchronous edge writes and Fargate workers pick it up within ~5s (cache-invalidation log); the async inference Lambda within ~60s (cache TTL)."
}

All three sections are optional; omit a section to leave it unchanged.
Requires `admin` scope.

GET/api/v1.1/memory/manage/graph/rulesSecret keySDK

List graph rules

Lists the effective graph rules for the org: system built-ins plus per-org rules and overrides.

Usage: Use this to inspect which property-to-edge inference rules are active before writing a save that relies on Channel B (`collectionGraph`).

SDK: client.v1_1.memory.graph.listRules(opts)

Parameters

Field	Type	Where	Required	Description
includeInactive	boolean	query	No	Include disabled/tombstoned rules.Default: `false`
sourceEntityType	string	query	No	Filter to rules whose sourceEntityType matches.
includeSystem	boolean	query	No	Set to `false` to exclude system built-in rules.Default: `true`

Response

{
  "success": true,
  "data": {
    "items": [
      { "ruleId": "rule_abc", "sourceEntityType": "contact", "propertyName": "company", "relationType": "works_at", "targetEntityType": "company", "valueShape": "scalar", "resolveBy": ["websiteUrl", "name"], "normalize": "companyHint", "allowStub": true, "allowSelfType": false, "inverse": false, "confidence": 0.9, "isBuiltin": true, "isActive": true, "scope": "system", "overridesSystem": false }
    ],
    "counts": { "system": 12, "org": 2, "tombstoned": 0 },
    "inheritSystemRules": true
  }
}

System built-in rules are hidden for an un-activated org (no kit installed yet), the same way `graph/config` hides them.

POST/api/v1.1/memory/manage/graph/rulesSecret keySDK

Create a graph rule

Creates a per-org rule mapping one source entity property to an inferred edge. `relationType` must already exist in the relation-types registry.

Usage: Use this to teach Channel B (`collectionGraph` on memory saves) to infer an edge whenever a given property is written.

SDK: client.v1_1.memory.graph.createRule(body)

Parameters

Field	Type	Where	Required	Description
sourceEntityType	string	body	Yes	Entity type the property lives on. Must match `^[a-z][a-z0-9_]{0,40}$`.
propertyName	string	body	Yes	Property name that triggers the rule. 3-60 chars, alphanumeric/underscore/hyphen.
relationType	string	body	Yes	Existing relation type name this rule infers. Must match `^[a-z][a-z0-9_]{2,40}$`.
targetEntityType	string	body	Yes	Entity type the edge points to.
resolveBy	string[]	body	Yes	Identity kinds tried in order to resolve the edge target, strongest first.Options: `email`, `websiteUrl`, `linkedinHandle`, `phoneNumber`, `salesforceId`, `crmDealId`, `name`
valueShape	string	body	No	Whether the property holds one value or an array.Options: `scalar`, `array`
normalize	string	body	No	Normalizer applied to the property value before identity resolution.Options: `email`, `domain`, `linkedinHandle`, `phone`, `lowercase`, `companyHint`, `identity`
allowStub	boolean	body	No	Allow creating a stub target record when no match resolves. Not permitted when the strongest `resolveBy` kind is `name`.
allowSelfType	boolean	body	No	Required `true` when `sourceEntityType` equals `targetEntityType`, otherwise the rule is rejected as a no-op.
inverse	boolean	body	No	Whether to also write the inverse edge.
confidence	number	body	No	Confidence score for the inferred edge.Default: `0.9`Range: `0–1`
disabled	boolean	body	No	Create the rule inactive. Useful to tombstone an inherited system rule of the same (sourceEntityType, propertyName).

Request

{
  "sourceEntityType": "contact",
  "propertyName": "referred_by_email",
  "relationType": "referred_by",
  "targetEntityType": "contact",
  "resolveBy": ["email"],
  "normalize": "email",
  "confidence": 0.85
}

Response

{
  "success": true,
  "data": { "ruleId": "rule_xyz", "sourceEntityType": "contact", "propertyName": "referred_by_email", "relationType": "referred_by", "targetEntityType": "contact", "valueShape": "scalar", "resolveBy": ["email"], "normalize": "email", "allowStub": false, "allowSelfType": true, "inverse": false, "confidence": 0.85, "isBuiltin": false, "isActive": true, "scope": "org", "overridesSystem": false },
  "notice": "Graph rule saved. Synchronous edge writes and Fargate workers pick it up within ~5s (cache-invalidation log); the async inference Lambda within ~60s (cache TTL)."
}

Returns 409 (`rule_conflict`) if a rule already exists for the same (sourceEntityType, propertyName) -- use PATCH to update it instead.
Requires `admin` scope.

POST/api/v1.1/memory/manage/graph/rules/batchSecret keySDK

Batch create graph rules

Creates up to 25 graph rules in one transaction. Same per-rule shape as the single-create endpoint.

Usage: Use this to provision several inference rules at once, for example when installing a setup kit.

SDK: client.v1_1.memory.graph.batchCreateRules(items)

Parameters

Field	Type	Where	Required	Description
items	object[]	body	Yes	Array of rule payloads, each shaped like the create-rule body. 1-25 items.

Response

{
  "success": true,
  "data": { "items": [ { "ruleId": "rule_1", "sourceEntityType": "contact", "propertyName": "company" } ], "count": 1 },
  "notice": "Graph rule saved. Synchronous edge writes and Fargate workers pick it up within ~5s (cache-invalidation log); the async inference Lambda within ~60s (cache TTL)."
}

Rejects the whole batch with 400 on a duplicate (sourceEntityType, propertyName) within the batch, and with 409 if any item already exists in the org.
Requires `admin` scope.

GET/api/v1.1/memory/manage/graph/rules/:ruleIdSecret keySDK

Get a graph rule

Fetches one graph rule by ID.

Usage: Use this to inspect a specific rule before patching or deleting it.

SDK: client.v1_1.memory.graph.getRule(ruleId)

Parameters

Field	Type	Where	Required	Description
ruleId	string	path	Yes	Rule ID.

Response

{
  "success": true,
  "data": { "ruleId": "rule_abc", "sourceEntityType": "contact", "propertyName": "company", "relationType": "works_at", "targetEntityType": "company", "isActive": true, "scope": "org" }
}

Returns 404 (`not_found`) if the rule does not exist in this org.

PATCH/api/v1.1/memory/manage/graph/rules/:ruleIdSecret keySDK

Update a graph rule

Partial update of a graph rule. `sourceEntityType` and `propertyName` are immutable.

Usage: Use this to change what a rule infers, or to flip `isActive` to disable it.

SDK: client.v1_1.memory.graph.updateRule(ruleId, body)

Parameters

Field	Type	Where	Required	Description
ruleId	string	path	Yes	Rule ID.
relationType	string	body	No	New relation type this rule infers.
targetEntityType	string	body	No	New target entity type.
valueShape	string	body	No	Update the value shape.Options: `scalar`, `array`
resolveBy	string[]	body	No	Replace the identity-kind resolution order.
normalize	string	body	No	Update the normalizer.
allowStub	boolean	body	No	Update the stub-creation flag.
allowSelfType	boolean	body	No	Update the self-type flag.
inverse	boolean	body	No	Update whether the inverse edge is also written.
confidence	number	body	No	Update the confidence score.Range: `0–1`
isActive	boolean	body	No	Enable or disable the rule.

Response

{
  "success": true,
  "data": { "ruleId": "rule_abc", "isActive": false },
  "notice": "Graph rule saved. Synchronous edge writes and Fargate workers pick it up within ~5s (cache-invalidation log); the async inference Lambda within ~60s (cache TTL)."
}

Returns 403 (`system_rule_immutable`) if `ruleId` is a built-in system rule -- create an org rule with the same (sourceEntityType, propertyName) to override it instead.
Requires `admin` scope.

DELETE/api/v1.1/memory/manage/graph/rules/:ruleIdSecret keySDK

Delete a graph rule

Soft-deletes a per-org graph rule by setting it inactive.

Usage: Use this to remove an inference rule you no longer want firing.

SDK: client.v1_1.memory.graph.deleteRule(ruleId)

Parameters

Field	Type	Where	Required	Description
ruleId	string	path	Yes	Rule ID.

Response

{
  "success": true,
  "data": { "ruleId": "rule_abc", "sourceEntityType": "contact", "propertyName": "company", "isActive": false, "scope": "org" },
  "notice": "Graph rule saved. Synchronous edge writes and Fargate workers pick it up within ~5s (cache-invalidation log); the async inference Lambda within ~60s (cache TTL)."
}

Returns 403 (`system_rule_immutable`) for built-in system rules -- they cannot be deleted, only overridden with a disabled org rule of the same key.
Requires `admin` scope.

GET/api/v1.1/memory/manage/graph/settingsSecret keySDK

Get graph settings

Returns the org's `inheritSystemRules` flag.

Usage: Use this to check whether the org currently inherits the platform's built-in graph rules.

SDK: client.v1_1.memory.graph.getSettings()

Response

{
  "success": true,
  "data": { "inheritSystemRules": true }
}

PATCH/api/v1.1/memory/manage/graph/settingsSecret keySDK

Update graph settings

Sets the org's `inheritSystemRules` flag.

Usage: Use this to opt an org out of the platform's built-in graph rules and rely entirely on org-defined rules.

SDK: client.v1_1.memory.graph.updateSettings(body)

Parameters

Field	Type	Where	Required	Description
inheritSystemRules	boolean	body	Yes	Whether system built-in rules apply on top of org rules.

Request

{ "inheritSystemRules": false }

Response

{
  "success": true,
  "data": { "inheritSystemRules": false },
  "notice": "Graph rule saved. Synchronous edge writes and Fargate workers pick it up within ~5s (cache-invalidation log); the async inference Lambda within ~60s (cache TTL)."
}

Requires `admin` scope.

GET/api/v1.1/memory/manage/relation-typesSecret keySDK

List relation types

Lists the relation type taxonomy for the org: system built-ins plus per-org types.

Usage: Use this to see which edge kinds (`works_at`, `referred_by`, etc.) are available before referencing one in a graph rule or a `relations[]` declared edge on a memory save.

SDK: client.v1_1.memory.listRelationTypes(opts)

Parameters

Field	Type	Where	Required	Description
includeInactive	boolean	query	No	Include disabled types.Default: `false`
includeSystem	boolean	query	No	Set to `false` to exclude system built-in types.Default: `true`

Response

{
  "success": true,
  "data": {
    "items": [
      { "typeName": "works_at", "displayLabel": "Works At", "description": null, "category": "role", "isBuiltin": true, "isSingleValued": true, "isSymmetric": false, "inverseType": "employs", "defaultWeight": 1, "allowedFromTypes": ["contact"], "allowedToTypes": ["company"], "examples": [], "isActive": true, "scope": "system", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }
    ],
    "counts": { "system": 18, "org": 3 }
  }
}

System built-in types are hidden for an un-activated org (no kit installed yet).

POST/api/v1.1/memory/manage/relation-typesSecret keySDK

Create a relation type

Creates a per-org relation type.

Usage: Use this to define a new edge kind before referencing it in graph rules or declared `relations[]` on a memory save.

SDK: client.v1_1.memory.createRelationType(body)

Parameters

Field	Type	Where	Required	Description
typeName	string	body	Yes	Unique relation type name. Must match `^[a-z][a-z0-9_]{2,40}$`.
displayLabel	string	body	No	Human-readable label (1-120 chars).
description	string	body	No	Description (max 2000 chars).
category	string	body	No	Classification.Options: `biographical`, `role`, `activity`, `mention`, `generic`
isSingleValued	boolean	body	No	Whether a source record can only hold one edge of this type.
isSymmetric	boolean	body	No	Whether the edge reads the same in both directions.
inverseType	string	body	No	Relation type name to use for the inverse edge.
defaultWeight	number	body	No	Default edge weight.Default: `1.0`Range: `0–1`
allowedFromTypes	string[]	body	No	Entity types allowed as the edge source. Omit to allow any.
allowedToTypes	string[]	body	No	Entity types allowed as the edge target. Omit to allow any.
examples	string[]	body	No	Example sentences illustrating the relation. Max 10 entries, 240 chars each.

Request

{
  "typeName": "referred_by",
  "displayLabel": "Referred By",
  "category": "role",
  "isSingleValued": true,
  "allowedFromTypes": ["contact"],
  "allowedToTypes": ["contact"]
}

Response

{
  "success": true,
  "data": { "typeName": "referred_by", "displayLabel": "Referred By", "description": null, "category": "role", "isBuiltin": false, "isSingleValued": true, "isSymmetric": false, "inverseType": null, "defaultWeight": 1, "allowedFromTypes": ["contact"], "allowedToTypes": ["contact"], "examples": [], "isActive": true, "scope": "org", "createdAt": "2026-09-01T00:00:00.000Z", "updatedAt": "2026-09-01T00:00:00.000Z" },
  "notice": "Graph rule saved. Synchronous edge writes and Fargate workers pick it up within ~5s (cache-invalidation log); the async inference Lambda within ~60s (cache TTL)."
}

Returns 400 (`validation_failed`) if `inverseType` references a type that does not exist or is inactive in this org.
Requires `admin` scope.

POST/api/v1.1/memory/manage/relation-types/batchSecret keySDK

Batch create relation types

Creates up to 25 relation types in one transaction.

Usage: Use this to provision a full relation-type vocabulary at once, for example when installing a setup kit.

SDK: client.v1_1.memory.batchCreateRelationTypes(items)

Parameters

Field	Type	Where	Required	Description
items	object[]	body	Yes	Array of relation type payloads, each shaped like the create body. 1-25 items.

Response

{
  "success": true,
  "data": { "items": [ { "typeName": "referred_by", "scope": "org" } ], "count": 1 },
  "notice": "Graph rule saved. Synchronous edge writes and Fargate workers pick it up within ~5s (cache-invalidation log); the async inference Lambda within ~60s (cache TTL)."
}

Requires `admin` scope.

GET/api/v1.1/memory/manage/relation-types/:typeNameSecret keySDK

Get a relation type

Fetches one relation type by name.

Usage: Use this to inspect a relation type's allowed from/to types before referencing it in a graph rule.

SDK: client.v1_1.memory.getRelationType(typeName)

Parameters

Field	Type	Where	Required	Description
typeName	string	path	Yes	Relation type name.

Response

{
  "success": true,
  "data": { "typeName": "works_at", "displayLabel": "Works At", "category": "role", "isBuiltin": true, "scope": "system" }
}

Returns 404 (`not_found`) if the type does not exist in this org.

PATCH/api/v1.1/memory/manage/relation-types/:typeNameSecret keySDK

Update a relation type

Partial update of a per-org relation type. `typeName` is immutable. `null` on a nullable field clears it.

Usage: Use this to adjust a relation type's metadata, symmetry, weight, or allowed entity types.

SDK: client.v1_1.memory.updateRelationType(typeName, body)

Parameters

Field	Type	Where	Required	Description
typeName	string	path	Yes	Relation type name.
displayLabel	string	body	No	New label. `null` clears it.
description	string	body	No	New description. `null` clears it.
category	string	body	No	New classification.Options: `biographical`, `role`, `activity`, `mention`, `generic`
isSingleValued	boolean	body	No	Update single-valued flag.
isSymmetric	boolean	body	No	Update symmetric flag.
inverseType	string	body	No	New inverse type name. `null` clears it.
defaultWeight	number	body	No	New default weight.Range: `0–1`
allowedFromTypes	string[]	body	No	New allowed source entity types. `null` clears the restriction.
allowedToTypes	string[]	body	No	New allowed target entity types. `null` clears the restriction.
examples	string[]	body	No	New example sentences. `null` clears them.

Response

{
  "success": true,
  "data": { "typeName": "referred_by", "isSymmetric": true },
  "notice": "Graph rule saved. Synchronous edge writes and Fargate workers pick it up within ~5s (cache-invalidation log); the async inference Lambda within ~60s (cache TTL)."
}

Requires `admin` scope.

DELETE/api/v1.1/memory/manage/relation-types/:typeNameSecret keySDK

Delete a relation type

Soft-deletes a per-org relation type by setting it inactive.

Usage: Use this to remove a relation type you no longer use.

SDK: client.v1_1.memory.deleteRelationType(typeName)

Parameters

Field	Type	Where	Required	Description
typeName	string	path	Yes	Relation type name.

Response

{
  "success": true,
  "data": { "typeName": "referred_by", "isActive": false, "scope": "org" },
  "notice": "Graph rule saved. Synchronous edge writes and Fargate workers pick it up within ~5s (cache-invalidation log); the async inference Lambda within ~60s (cache TTL)."
}

Built-in system types cannot be deleted.
Requires `admin` scope.

20 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.

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

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.

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

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.

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

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.

Parameters

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

Response

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

GET/api/v1.1/guidelines/downloadSecret key

Download guidelines as a zip

Builds (or serves a cached) zip of the org's guideline-type context docs, including their attachments, and returns a presigned S3 download URL. Same underlying handler as the documents download route, but this path pre-filters to `type: 'guideline'` documents only.

Usage: Export governance content -- guidelines plus their attachments -- as a portable zip archive, for example for backup or handoff to another system.

Parameters

Field	Type	Where	Required	Description
scope	string	query	No	Set to `platform` to download the pre-built, publicly-hosted platform guideline pack instead of the org's own guidelines.Options: `platform`

Response

{
  "success": true,
  "url": "https://...presigned-s3-url...",
  "scope": "org",
  "type": "guideline",
  "count": 12,
  "cached": false
}

`?scope=platform` requires NO authentication and skips the type filter entirely -- it returns a pre-built platform-wide zip (`note: "Pre-built at last seed. Re-run seed script to update."`), not the caller's org guidelines.
Without `?scope=platform`, results are cached per org+type for a TTL; `cached: true` on a cache hit.
The zip includes each doc's content, a `meta.json`, and its attachments, plus a top-level `manifest.json`.
Unlike the documents download route, this route always injects `type: 'guideline'` server-side -- there is no way to widen it back to all doc types on this path.

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.

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

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.

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Guideline ID

Request

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

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": [] } }] }

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.

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

/api/v1.1/guidelines/guide-abc123/attachments (POST)
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" } } }

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.

Parameters

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

Request

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

Response

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

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.

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 }

0 credits
Irreversible

POST/api/v1.1/guidelines/{id}/attachments/batchSecret keySDK

Batch Upload Guideline Attachments

Uploads multiple file attachments to a guideline in one multipart request, each with its own metadata. Same validation, storage, and LLM audit pipeline as the single-file upload.

Usage: Attach several resources (scripts, templates, configs) to a guideline in one call instead of one request per file.

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Guideline ID
files	file[]	body	Yes	Up to 10 files (multipart/form-data field name `files`).
manifest	object[]	body	Yes	JSON array of per-file metadata, same index order as `files`. Each entry: `{ type, description, usage, name?, language?, sectionHeader? }` (same shape as single-upload `metadata`).

Request

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

files: <binary>, <binary>
manifest: [{ "type": "script", "description": "...", "usage": "..." }, { "type": "reference", "description": "...", "usage": "..." }]

Response

{ "success": true, "data": { "uploaded": [{ "id": "att_a1b2c3", "name": "..." }, { "id": "att_d4e5f6", "name": "..." }], "warnings": [] } }

Returns 201 on success.
Max 10 files per batch call. A single invalid manifest entry (e.g. bad `type`) rejects the entire batch (400, `batch rejected`) -- no partial upload.
The identical operation exists scoped to a context document instead of a guideline -- see the document attachments batch upload in the Documents category. Both mount the same underlying route factory.

GET/api/v1.1/attachments/statsSecret keySDK

Org-wide attachment stats

Returns total attachment count, total storage bytes, and a per-type breakdown across every attachment in the org -- guideline-scoped and context-doc-scoped combined.

Usage: Monitor storage usage against the org's attachment storage quota before it's exceeded.

SDK: client.attachments.stats()

Response

{
  "success": true,
  "data": {
    "totalCount": 42,
    "totalSizeBytes": 1048576,
    "countByType": { "script": 10, "reference": 32 }
  }
}

SDK Example

const stats = await client.attachments.stats();
console.log(stats.data.totalSizeBytes);

Counts every attachment in the org regardless of which guideline or context document it's scoped to.
The same-looking path under a scoped mount (a guideline or document attachments mount followed by `/stats`) is NOT a separate stats endpoint -- those routers have no `/stats` route, so it falls through to "get attachment by id" with id=`stats` and returns 404 (`not_found`) unless an attachment happens to be literally named that. Use this org-level endpoint for stats instead.

GET/api/v1.1/attachmentsSecret key

List all org attachments

Lists attachments across the whole org (both guideline- and context-doc-scoped), with optional type/search filtering and pagination.

Usage: Browse or search every attachment in the org without knowing in advance which guideline or context doc it's attached to.

Parameters

Field	Type	Where	Required	Description
type	string	query	No	Filter by attachment type.Options: `script`, `template`, `reference`, `config`, `data`, `schema`, `prompt`, `image`
search	string	query	No	Case-insensitive match against attachment name or description.
limit	number	query	No	Page size.
nextToken	string	query	No	Pagination cursor from a previous page.

Response

{
  "success": true,
  "data": [
    { "id": "att_a1b2c3", "name": "compliance-check.py", "type": "script", "sizeBytes": 2340 }
  ],
  "nextToken": null
}

No SDK wrapper yet -- call this path directly.
There is no org-level batch-upload or single-upload route; uploads must go through a scoped mount (a guideline or document attachments mount, or its `/batch` equivalent).

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);

23 endpoints

Documents

Knowledge layer for agent-readable documents. Write documents with `save` `shape='document'`, read them with `retrieve` (`mode='filter'` to list, `mode='fetch'` to get, `scout` or `brief` to search) and remove them with `delete` `type='document'` or `type='attachment'`. Also covers (1) a PG-backed doc-type registry under `/context/manage/doc-types/*` and (2) async bulk document save under `/context/save/batch/*` (1-24h SLA via provider batch APIs). The `/api/v1.1/agentdocs/*` paths return 410 Gone.

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.listDocTypes()

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-typesSecret keySDK

Create doc-type (admin)

Creates an org-defined document subtype (a per-org row; system built-ins are never touched).

Usage: Extend the doc-type registry with org-specific document categories (e.g. `icp_brief`, `pricing_sheet`, `objection_playbook`) for use as `type` on `POST /memory/save` with `shape='document'`.

SDK: client.v1_1.context.createDocType(body)

Parameters

Field	Type	Where	Required	Description
type_name	string	body	Yes	Slug identifier. Must match `^[a-z][a-z0-9_]{2,40}$` (lowercase snake_case; kebab-case is rejected).
label	string	body	Yes	Display label, 1-80 chars.
description	string	body	No	What this type is used for, max 500 chars.
constraint_level	string	body	No	How strictly retrieval treats documents of this type.Options: `hard`, `soft`, `reference`
scoring_boost	number	body	No	Retrieval ranking boost/penalty.Range: `-1–1`
always_on_eligible	boolean	body	No	Whether docs of this type can be included unconditionally in context assembly.
intent_boosts	object	body	No	Map of intent name to boost value (-1 to 1).
require_rfc2119	boolean	body	No	Require RFC 2119 keywords (MUST/SHOULD/etc.) in docs of this type.
require_examples	boolean	body	No	Require at least one example in docs of this type.
min_words	number	body	No	Minimum word count for docs of this type.
max_words	number	body	No	Maximum word count for docs of this type.
preamble	string	body	No	Text prepended when this type is assembled into context, max 500 chars.
agent_instruction	string	body	No	Instruction shown to the agent for how to use docs of this type, max 2000 chars.
when_to_use	string	body	No	Guidance on when this type applies, max 1000 chars.
routing_keywords	string[]	body	No	Keywords used to route queries toward this type. Max 20 entries, 60 chars each.
output_structure_hint	string	body	No	Hint for how generated docs of this type should be structured, max 2000 chars.
example_titles	string[]	body	No	Example document titles for this type. Max 20 entries, 200 chars each.
sort_order	number	body	No	Display order relative to other types.

Request

{
  "type_name": "icp_brief",
  "label": "ICP Brief",
  "description": "Ideal-customer-profile summaries used in qualification playbooks.",
  "constraint_level": "soft"
}

Response

{
  "type": {
    "org_id": "org_123",
    "type_name": "icp_brief",
    "type_id": "b3f1...",
    "label": "ICP Brief",
    "description": "Ideal-customer-profile summaries used in qualification playbooks.",
    "constraint_level": "soft",
    "scoring_boost": 0,
    "always_on_eligible": false,
    "is_builtin": false
  }
}

Requires `admin` scope on the API key.

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

Update doc-type (admin)

Partial update of an org-defined doc-type's metadata. `type_name` is immutable here (use rename); built-ins always return 404.

Usage: Edit a doc-type's label, description, or scoring behavior without renaming it.

SDK: client.v1_1.context.updateDocType(typeName, body)

Parameters

Field	Type	Where	Required	Description
type_name	string	path	Yes	Doc-type to update.
label	string	body	No	New display label.
description	string	body	No	New description. `null` clears it.
constraint_level	string	body	No	Update retrieval strictness.Options: `hard`, `soft`, `reference`
scoring_boost	number	body	No	Update the retrieval ranking boost.Range: `-1–1`
always_on_eligible	boolean	body	No	Update whether docs of this type can be always-on.
routing_keywords	string[]	body	No	Replace the routing keywords.
sort_order	number	body	No	Update display order.

Request

{
  "label": "ICP Brief (v2)",
  "scoring_boost": 0.2
}

Response

{
  "type": {
    "org_id": "org_123",
    "type_name": "icp_brief",
    "label": "ICP Brief (v2)",
    "scoring_boost": 0.2,
    "is_builtin": false
  }
}

Requires `admin` scope on the API key.
Only per-org rows are editable; a missing type or a system built-in both return 404 (the UPDATE only matches `is_builtin = false` rows).

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

Delete doc-type (admin)

Soft-deletes an org-defined doc-type. Use `?force=orphan` to reassign existing docs to `reference` first. Built-ins cannot be deleted.

Usage: Retire an org-defined doc-type that is no longer needed.

SDK: client.v1_1.context.deleteDocType(typeName)

Parameters

Field	Type	Where	Required	Description
type_name	string	path	Yes	Doc-type to delete.
force	string	query	No	Set to `orphan` to reassign existing docs to `reference` and proceed with deletion.Options: `orphan`

Response

{
  "error": "type_in_use",
  "doc_count": 12,
  "options": ["reassign_to", "merge_via_rename", "orphan_with_default"],
  "hint": "Pass ?force=orphan to reassign all docs to \"reference\" and delete, or use the rename endpoint to merge into another type."
}

Requires `admin` scope on the API key.
204 No Content on success. A missing type, or a system built-in with no per-org override, returns 404.
409 (`type_in_use`, shown above) if docs still reference this type and `?force=orphan` was not passed.

POST/api/v1.1/context/manage/doc-types/:type_name/renameSecret keySDK

Rename doc-type (admin)

Atomic rename with alias forwarding -- the old name becomes a tombstone that continues to resolve to the renamed type for backwards compatibility.

Usage: Evolve the type taxonomy (or merge one org type into another) without breaking existing document references.

SDK: client.v1_1.context.renameDocType(name, { newName })

Parameters

Field	Type	Where	Required	Description
type_name	string	path	Yes	Current doc-type name.
new_name	string	body	Yes	New slug. Must match `^[a-z][a-z0-9_]{2,40}$` and differ from `type_name`.

Request

{ "new_name": "icp_profile" }

Response

{
  "type": {
    "org_id": "org_123",
    "type_name": "icp_profile",
    "label": "ICP Brief",
    "is_builtin": false
  }
}

Requires `admin` scope on the API key.
403 (`builtin_immutable`) if `type_name` is a system built-in, 404 (`not_found`) if there is no per-org row with that name, 409 (`target_name_in_use`) if `new_name` already exists and is active.

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

Doc-type audit log

Returns the append-only change history for a doc-type (create/update/rename/delete events), newest first.

Usage: Audit who changed a doc-type's definition and when.

SDK: client.v1_1.context.getDocTypeHistory(typeName)

Parameters

Field	Type	Where	Required	Description
type_name	string	path	Yes	Doc-type to fetch history for.
limit	number	query	No	Page size.Default: `50`

Response

{
  "entries": [
    { "history_id": "hist_1", "org_id": "org_123", "type_name": "icp_brief", "change_kind": "updated", "change_summary": null, "actor_user_id": "user_123", "diff": { "scoring_boost": [0, 0.2] }, "created_at": "2026-08-20T10:00:00.000Z" }
  ]
}

Read access only requires the API key (no `admin` scope), unlike the mutation routes.

GET/api/v1.1/context/manage/tagsSecret keySDK

List curated tags

Returns the org's curated tag vocabulary: system built-ins merged with per-org overrides. Mirrors the doc-types list pattern.

Usage: Discover what canonical tags exist before tagging a context document, or before building a tag-picker UI.

SDK: client.v1_1.context.listTags(opts)

Parameters

Field	Type	Where	Required	Description
include_ai_legacy	string	query	No	Set to `true` to also surface AI-created legacy tags (`created_by='ai-legacy'`), hidden by default so they can be triaged separately.Options: `true`

Response

{
  "tags": [
    { "org_id": "org_123", "canonical_tag": "sales", "tag_id": "tag_1", "label": "Sales", "description": null, "aliases": ["selling"], "usage_count": 42, "renamed_to": null, "is_builtin": true, "is_active": true, "sort_order": 0, "created_by": null, "created_at": "2026-01-01T00:00:00.000Z", "updated_at": "2026-01-01T00:00:00.000Z" }
  ]
}

System built-ins are omitted for an un-activated org (no kit installed yet), the same way the doc-types list is gated.

GET/api/v1.1/context/manage/tags/:canonical_tag/historySecret keySDK

Tag audit log

Returns the append-only change history for one tag (create/update/rename/delete events), newest first.

Usage: Audit who changed a tag's definition and when.

SDK: client.v1_1.context.getTagHistory(canonicalTag, opts)

Parameters

Field	Type	Where	Required	Description
canonical_tag	string	path	Yes	Tag to fetch history for.
limit	number	query	No	Page size.Default: `50`

Response

{
  "canonical_tag": "sales",
  "history": [
    { "history_id": "hist_1", "org_id": "org_123", "canonical_tag": "sales", "change_kind": "updated", "change_summary": null, "actor_user_id": "user_123", "diff": { "label": ["Sales Team", "Sales"] }, "created_at": "2026-08-20T10:00:00.000Z" }
  ],
  "count": 1
}

POST/api/v1.1/context/manage/tagsSecret keySDK

Create a tag (admin)

Creates (or upserts) a per-org curated tag. Best-effort embedding generation runs after the write so semantic tag-matching ("snap") picks it up from day one.

Usage: Add an org-specific tag to the curated vocabulary used for context-document categorization and snap-matching.

SDK: client.v1_1.context.createTag(body)

Parameters

Field	Type	Where	Required	Description
canonical_tag	string	body	Yes	Slug identifier. Must match `^[a-z][a-z0-9_-]{1,59}$`.
label	string	body	Yes	Display label, 1-80 chars.
description	string	body	No	What this tag means, max 500 chars. Used to generate the matching embedding.
aliases	string[]	body	No	Alternate spellings/synonyms that resolve to this tag. Max 20 entries, same slug format as `canonical_tag`.
sort_order	number	body	No	Display order relative to other tags.

Request

{
  "canonical_tag": "renewal_risk",
  "label": "Renewal Risk",
  "description": "Signals that an account is at risk of not renewing.",
  "aliases": ["churn_risk"]
}

Response

{
  "tag": {
    "org_id": "org_123",
    "canonical_tag": "renewal_risk",
    "tag_id": "tag_9",
    "label": "Renewal Risk",
    "description": "Signals that an account is at risk of not renewing.",
    "aliases": ["churn_risk"],
    "usage_count": 0,
    "renamed_to": null,
    "is_builtin": false,
    "is_active": true,
    "sort_order": 0,
    "created_by": "user_123",
    "created_at": "2026-09-01T00:00:00.000Z",
    "updated_at": "2026-09-01T00:00:00.000Z"
  }
}

Requires `admin` scope on the API key.
The response never includes the `embedding` field, even though it's stored -- it's a large numeric array with no use to API consumers.

PATCH/api/v1.1/context/manage/tags/:canonical_tagSecret keySDK

Update a tag (admin)

Partial update of a per-org tag's label, description, aliases, or sort order. `canonical_tag` is immutable here (use rename); built-ins always return 404. Re-embeds automatically when `description` changes.

Usage: Edit a tag's metadata without renaming it.

SDK: client.v1_1.context.updateTag(canonicalTag, body)

Parameters

Field	Type	Where	Required	Description
canonical_tag	string	path	Yes	Tag to update.
label	string	body	No	New display label, 1-80 chars.
description	string	body	No	New description. `null` clears it and triggers a re-embed.
aliases	string[]	body	No	Replace the alias list. Max 20 entries.
sort_order	number	body	No	Update display order.

Request

{ "label": "Renewal Risk (Q3)", "aliases": ["churn_risk", "at_risk"] }

Response

{
  "tag": {
    "org_id": "org_123",
    "canonical_tag": "renewal_risk",
    "label": "Renewal Risk (Q3)",
    "aliases": ["churn_risk", "at_risk"],
    "is_builtin": false
  }
}

Requires `admin` scope on the API key.
Only per-org rows are editable; a missing tag or a system built-in both return 404.

DELETE/api/v1.1/context/manage/tags/:canonical_tagSecret keySDK

Delete a tag (admin)

Soft-deletes a per-org tag. Built-ins or non-existent rows return 404. Does NOT cascade to context documents -- docs keep the tag in their `tags`/`auto_tags` arrays, they just stop matching this tag in future snap suggestions.

Usage: Retire an org-specific tag that is no longer useful.

SDK: client.v1_1.context.deleteTag(canonicalTag)

Parameters

Field	Type	Where	Required	Description
canonical_tag	string	path	Yes	Tag to delete.

Requires `admin` scope on the API key.
204 No Content on success.

POST/api/v1.1/context/manage/tags/:canonical_tag/renameSecret keySDK

Rename a tag (admin)

Atomic rename: the old name becomes a tombstone alias, the new name carries the preserved `tag_id`. Documents referencing the old name keep working via the alias chain.

Usage: Evolve the tag vocabulary without breaking documents that already carry the old tag.

SDK: client.v1_1.context.renameTag(canonicalTag, { newName })

Parameters

Field	Type	Where	Required	Description
canonical_tag	string	path	Yes	Current tag name.
new_name	string	body	Yes	New slug. Must match `^[a-z][a-z0-9_-]{1,59}$`.

Request

{ "new_name": "churn_risk" }

Response

{
  "tag": {
    "org_id": "org_123",
    "canonical_tag": "churn_risk",
    "tag_id": "tag_9",
    "label": "Renewal Risk",
    "is_builtin": false
  }
}

Requires `admin` scope on the API key.
403 (`builtin_immutable`) for a system built-in, 404 (`not_found`) if there is no per-org row with that name, 409 (`target_name_in_use`) if `new_name` already exists and is active.

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)

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

List documents (retrieve, mode=filter)

Lists documents with `mode: "filter"` and `filters.documents`. This is a plain listing: no LLM and no content. It cannot be combined with `filters.groups`, `filters.crmFilter`, `filters.collectionIds` or `filters.listAll`.

Usage: List all documents, or narrow by document type, tags, status or linked record. The legacy agentdocs routes return 410 Gone.

Parameters

Field	Type	Where	Required	Description
mode	string	body	Yes	Must be `filter` when `filters.documents` is set.Options: `filter`
filters.documents.docType	string[]	body	No	Only these document types (max 50).
filters.documents.tags	string[]	body	No	Only documents with these tags (max 50).
filters.documents.status	string[]	body	No	Lifecycle statuses to include.Options: `active`, `draft`, `retired`, `archived`
filters.documents.recordId	string	body	No	Only documents linked to this record.
filters.documents.limit	number	body	No	Page size, 1 to 200.
filters.documents.cursor	string	body	No	Cursor from a previous page.

Request

{
  "mode": "filter",
  "filters": { "documents": { "docType": ["playbook"], "tags": ["sales"], "limit": 20 } }
}

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

Save a document (save, shape=document)

Creates or updates a document with `shape: "document"`. Set the document type with `docType` to control how agents treat it (guideline, playbook, reference, template or brief, plus any custom doc type).

Usage: Create or update documents, restore an earlier version, and attach files. The legacy agentdocs routes return 410 Gone.

Parameters

Field	Type	Where	Required	Description
shape	string	body	Yes	Must be `document`.Options: `document`
docType	string	body	Yes	Document type (alias of `type`; `docType` wins when both are set).
recordIds	string[]	body	No	Record IDs the document is linked to (max 50).
targetIds	string[]	body	No	Existing document IDs to update instead of creating a new one.
updateMode	string	body	No	How an update is applied when `targetIds` is set.Default: `append`Options: `append`, `replace`, `section`, `appendToSection`
sectionHeader	string	body	No	Section to target for the `section` and `appendToSection` update modes.
restoreVersionId	string	body	No	Restore this earlier version of the target document. Other document fields are ignored.
attachments	object[]	body	No	Files to attach to the document.
status	string	body	No	Lifecycle status of the document.

Request

{
  "shape": "document",
  "docType": "playbook",
  "content": "## Step 1: Initial Contact\n...",
  "tags": ["sales", "qualification"]
}

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

Get documents (retrieve, mode=fetch)

Fetches documents by ID with `mode: "fetch"`. Use `fetch.documentIds` for documents, `fetch.documentHistory` for version history rows and `fetch.attachmentIds` for attachments.

Usage: Read known documents, with the detail level you need, their history, or their attachments.

Parameters

Field	Type	Where	Required	Description
mode	string	body	Yes	Must be `fetch`.Options: `fetch`
fetch.documentIds	string[]	body	No	Document IDs to fetch (max 100).
fetch.include	string	body	No	Document detail level. `section` requires `fetch.sectionIds`.Options: `meta`, `sections`, `section`, `content`
fetch.documentHistory	object[]	body	No	History rows per document: `{ documentId, limit (default 50, max 200), cursor }` (max 20 entries).
fetch.attachmentIds	string[]	body	No	Attachment IDs to fetch (max 100).

Request

{
  "mode": "fetch",
  "fetch": { "documentIds": ["3f9a1c2e-..."], "include": "sections" }
}

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

Search documents (retrieve, scout or brief)

Selects the documents relevant to a task with the `scout` or `brief` depth and `sources.documents`. Options for the documents source go under `intent.perSource.documents`.

Usage: Route agents to the right documents for a message, with type, tag and status filtering.

Parameters

Field	Type	Where	Required	Description
message	string	body	No	Task description with rich keywords.
sources.documents	boolean	body	No	Set `true` to include documents.
intent.perSource.documents.limit	number	body	No	Max documents, 1 to 100.
intent.perSource.documents.types	string[]	body	No	Only these document types.
intent.perSource.documents.tags	string[]	body	No	Only documents with these tags.
intent.perSource.documents.tagMode	string	body	No	How `tags` match: any of them, or all of them.Default: `any`Options: `any`, `all`
intent.perSource.documents.statuses	string[]	body	No	Lifecycle statuses to include. Defaults to `active`.Options: `active`, `draft`, `retired`, `archived`
intent.perSource.documents.include	string	body	No	Detail level for record-attached documents when no message is sent.Options: `meta`, `sections`, `content`

Request

{
  "message": "Writing cold outreach to VP Sales at healthcare company",
  "sources": { "documents": true },
  "intent": { "perSource": { "documents": { "types": ["guideline", "template"], "tags": ["email"], "tagMode": "all" } } }
}

`tagMode` defaults to `any`; use `all` to require every listed tag.

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

Delete documents or attachments (delete)

Deletes documents or attachments with `type: "document"` or `type: "attachment"`.

Usage: Remove documents or their attachments. The legacy agentdocs routes return 410 Gone.

Parameters

Field	Type	Where	Required	Description
type	string	body	Yes	What to delete.Options: `document`, `attachment`
ids	string[]	body	Yes	IDs of the documents or attachments to delete.
guidelineId	string	body	No	Owning document ID. Required when `type` is `attachment`.

Request

{ "type": "attachment", "guidelineId": "guide-abc123", "ids": ["att_a1b2c3"] }

GET/api/v1.1/context/manage/downloadSecret key

Download context docs as a zip

Builds (or serves a cached) zip of the org's context docs, including their attachments, and returns a presigned S3 download URL. Same handler that backs the guidelines download route, but this path applies no type filter by default -- it covers every doc type.

Usage: Export context docs -- content, metadata, and attachments -- as a portable zip archive, for example for backup or migration.

Parameters

Field	Type	Where	Required	Description
type	string	query	No	Restrict the zip to one AgentDoc type.Options: `guideline`, `playbook`, `reference`, `template`, `brief`

Response

{
  "success": true,
  "url": "https://...presigned-s3-url...",
  "scope": "org",
  "type": "all",
  "count": 37,
  "cached": false
}

Results are cached per org+type for a TTL; `cached: true` on a cache hit.
The zip includes each doc's content, a `meta.json`, and its attachments, plus a top-level `manifest.json`.
Returns `url: null, count: 0` (still 200) when the org has no docs, or none matching the `type` filter.

POST/api/v1.1/context/manage/:id/cloneSecret key

Clone a context doc

Creates a duplicate of an existing context document (guideline, playbook, reference, template, or brief) under the caller's organization, copying its payload verbatim.

Usage: Branch off an existing doc as a starting point for a new one without hand-copying its content.

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Context doc ID to clone.

Request

/api/v1.1/context/manage/act_abc123/clone (POST)

Response

{
  "success": true,
  "message": "Action cloned successfully",
  "data": {
    "id": "3f9a1c2e-...-uuid",
    "type": "variables",
    "organizationId": "org_abc123",
    "payload": { "name": "Sales Qualification SOP", "agentDocType": "playbook", "value": "..." },
    "createdAt": "2026-09-01T00:00:00.000Z"
  }
}

The clone's `payload` is copied as-is; the name is NOT suffixed with "(copy)" or similar -- the source and clone share the same displayed name.
The cloned doc gets a fresh raw UUID as its `id`, not the `act_`-prefixed format that document creation generates.
Requires the caller to have clone access to the source doc; returns 403 (`Access Denied`) otherwise, 404 if the source doc doesn't exist.

POST/api/v1.1/context/manage/:id/attachments/batchSecret key

Batch upload context doc attachments

Uploads multiple file attachments to a context document in one multipart request, each with its own metadata. Same validation, storage, and LLM audit pipeline as a single-file upload -- the same route factory used for guideline attachments, scoped to a context doc instead.

Usage: Attach several resources (scripts, templates, configs) to a context document in one call instead of one request per file.

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Context doc ID.
files	file[]	body	Yes	Up to 10 files (multipart/form-data field name `files`).
manifest	object[]	body	Yes	JSON array of per-file metadata, same index order as `files`. Each entry: `{ type, description, usage, name?, language?, sectionHeader? }`.

Request

/api/v1.1/context/manage/act_abc123/attachments/batch (POST)
Content-Type: multipart/form-data

files: <binary>, <binary>
manifest: [{ "type": "reference", "description": "...", "usage": "..." }, { "type": "config", "description": "...", "usage": "..." }]

Response

{ "success": true, "data": { "uploaded": [{ "id": "att_a1b2c3", "name": "..." }], "warnings": [] } }

Returns 201 on success.
Same operation, quota, and validation as the guideline attachments batch upload (see the Governance category), just scoped to a document instead of a guideline.
No SDK wrapper for this scope yet.

1 endpoints

Agents And Evaluation

Evaluate memorization quality against a schema.

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.

12 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.

Response

{ "deleted": true }

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

Response

{
  "userId": "user_abc123",
  "role": "ADMIN",
  "updatedAt": "2026-09-01T00:00:00.000Z"
}

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

GET/api/v1.1/members/invitationsSecret keySDK

List pending invitations

Lists pending invitations for the organization: in-app invitations (for existing users) and external invitations (for people without an account yet, claimed on signup).

Usage: Audit or display outstanding invites before resending or canceling them.

SDK: client.members.listInvitations()

Response

{
  "invitations": [
    { "email": "bob@acme.com", "userId": null, "invitationId": "inv_789", "createdAt": "2026-08-01T00:00:00.000Z" }
  ],
  "count": 1
}

Admin scope required, and the caller must be the organization owner -- 403 (`FORBIDDEN`) otherwise.
The underlying service supports `limit` / `nextToken` pagination, but this route does not pass query params through -- it always returns the first page at the service default page size.

GET/api/v1.1/organizations/embedding-configSecret keySDK

Get BYO embedding model config

Returns the org's configured bring-your-own embedding model (1536-dimension only), or `embeddingConfig: null` if the org still uses the platform default.

Usage: Check whether the org has already locked in a custom embedding model before attempting to set one -- the setter is immutable after first use.

SDK: client.organizations.getEmbeddingConfig()

Response

{
  "success": true,
  "status": "locked",
  "editable": false,
  "embeddingConfig": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "dimensions": 1536,
    "lockedAt": "2026-06-01T00:00:00.000Z"
  }
}

`status` is `"default"` (with `embeddingConfig: null`) until the org sets a model for the first time; it then flips to `"locked"` and `editable` becomes `false`.
Requires a plan that allows custom LLM keys -- 403 (`byok_not_allowed`) otherwise.

GET/api/v1.1/organizations/embedding-modelsSecret keySDK

List 1536d embedding models

Lists the curated catalog of 1536-dimension-capable embedding models available for the org's first-set picker, across all BYO-selectable providers.

Usage: Show which provider/model combos are eligible before calling the setter -- the platform stores all vectors in one fixed 1536d space.

SDK: client.organizations.listEmbeddingModels()

Parameters

Field	Type	Where	Required	Description
includePlatform	boolean	query	No	Include the keyless platform-default provider (Bedrock) in the list.Default: `false`

Response

{
  "success": true,
  "dimensions": 1536,
  "providers": ["openai", "openrouter"],
  "data": [{ "provider": "openai", "model": "text-embedding-3-small" }]
}

Curated list -- providers don't self-report embedding dimensions; the live probe in `PUT /organizations/embedding-config` is the actual hard guard.
Requires a plan that allows custom LLM keys.

GET/api/v1.1/organizations/embedding-models/:providerSecret keySDK

List 1536d embedding models for one provider

Same catalog as the unfiltered list route, scoped to a single provider.

Usage: Fetch just one provider's model options, for example when the UI picker already knows which provider the customer chose.

SDK: client.organizations.listEmbeddingModels(provider)

Parameters

Field	Type	Where	Required	Description
provider	string	path	Yes	Embedding provider.Options: `openai`, `openrouter`, `bedrock`

Response

{
  "success": true,
  "provider": "openai",
  "dimensions": 1536,
  "data": [{ "provider": "openai", "model": "text-embedding-3-small" }]
}

400 (`unsupported_provider`) for a provider outside `openai` / `openrouter` / `bedrock`, with the valid list returned in `supportedProviders`.

PUT/api/v1.1/organizations/embedding-configSecret keySDK

Set BYO embedding model config

Sets the org's bring-your-own embedding model. Immutable after the first successful set for a given org -- the model itself can never change afterward, only the stored API key can be rotated.

Usage: Opt an org into its own embedding-model key instead of the platform default, before any vectors are written under it.

SDK: client.organizations.setEmbeddingConfig({ provider, model, apiKey })

Parameters

Field	Type	Where	Required	Description
provider	string	body	Yes	Embedding provider.Options: `openai`, `openrouter`, `bedrock`
model	string	body	Yes	Model identifier for the chosen provider.
apiKey	string	body	No	Required for `openai` / `openrouter`. Omit for `bedrock`, which uses the platform's AWS credentials.

Request

{ "provider": "openai", "model": "text-embedding-3-small", "apiKey": "sk-..." }

Response

{
  "success": true,
  "dimensions": 1536,
  "embeddingConfig": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "dimensions": 1536,
    "lockedAt": "2026-06-01T00:00:00.000Z"
  }
}

First set for the org live-probes the model and rejects it (400) unless it returns EXACTLY 1536 dimensions.
Immutable lock: calling this again with a DIFFERENT provider/model returns 400 with the currently-locked config in the response -- changing embedding models requires a full re-embed migration, not this endpoint. Calling it again with the SAME provider/model is allowed and only rotates the stored API key.
`POST /organizations/embedding-config` is a same-handler alias of this endpoint, kept so the MCP client (which has no PUT verb) can reach it.
Requires `admin` scope and a plan that allows custom LLM keys (403 `byok_not_allowed` otherwise).

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, 1-100 chars.
pluralLabel	string	body	No	Plural display name, 1-100 chars.
description	string	body	No	Description (max 500 chars).
icon	string	body	No	Icon identifier (max 50 chars).
color	string	body	No	Hex color, e.g. `#4F46E5`.
primaryKeyField	string	body	No	Property name used as the display/primary key (max 100 chars).
identifierColumn	string	body	No	Which standard identifier resolves records of this type.Options: `email`, `websiteUrl`, `phoneNumber`, `postalCode`, `deviceId`, `contentId`
status	string	body	No	Active or Archived. Setting `Archived` on a system type returns 403.Options: `Active`, `Archived`

Request

{
  "name": "Company",
  "color": "#4F46E5",
  "description": "A business account."
}

Response

{
  "success": true,
  "data": {
    "id": "act_abc123",
    "name": "Company",
    "pluralLabel": "Companies",
    "slug": "company",
    "description": "A business account.",
    "icon": "building",
    "color": "#4F46E5",
    "primaryKeyField": "websiteUrl",
    "identifierColumn": "websiteUrl",
    "isSystem": false,
    "status": "Active",
    "schemaVersion": 1,
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-09-01T00:00:00.000Z"
  }
}

Free. Requires `admin` scope on the API key.
`slug` and `isSystem` cannot be changed via this endpoint -- they're stripped from the body before validation even if sent.
At least one field is 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.

Response

{
  "success": true,
  "data": {
    "id": "act_abc123",
    "name": "Company",
    "slug": "company",
    "isSystem": false,
    "status": "Archived",
    "schemaVersion": 1
  },
  "message": "Entity type archived. To restore it, send PATCH /api/v1.1/entities/:id with { \"status\": \"Active\" }."
}

This is a soft-delete (archive), not a hard delete -- existing records of this type and their data are untouched, and the type is reversible via `PATCH /entities/:id` with `{ status: 'Active' }`.
Free. Requires `admin` scope on the API key. System types (Contact, Company) return 403.

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.

14 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.

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

Analytics access and tier

Returns the caller's resolved analytics tier and which analytics features are unlocked, with the credit cost and minimum tier required for each.

Usage: Use this to pre-render locked/unlocked analytics widgets in your UI instead of discovering access via 403s.

SDK: client.analytics.access()

Response

{
  "orgId": "org_123",
  "tier": "free",
  "tierOrder": ["free", "starter", "pro", "personizer"],
  "isSuperAdmin": false,
  "billInternal": false,
  "features": {
    "access": { "allowed": true, "requiredTier": "free", "credits": 0 },
    "overview": { "allowed": true, "requiredTier": "free", "credits": 0 },
    "operations.breakdown": { "allowed": false, "requiredTier": "starter", "credits": 0.1 },
    "retrieve": { "allowed": false, "requiredTier": "pro", "credits": 0.1 }
  }
}

Free discovery endpoint -- no credit charge, no tier requirement. Cached 60s.
Feature keys and their tier/credit values are SSM-tunable (`/personize/{stage}/analytics/access`), so exact numbers can change without a code deploy.

GET/api/v1.1/analytics/memory/historySecret keySDK

Memory metrics history

Returns a time series of a single memory metric (latency, throughput, quality, or cost) at hourly or daily granularity.

Usage: Use this to chart memory system trends over time instead of a single snapshot.

SDK: client.analytics.memoryHistory({ metric: 'throughput', granularity: 'daily', days: 7 })

Parameters

Field	Type	Where	Required	Description
metric	string	query	No	Metric to chart.Default: `throughput`Options: `latency`, `throughput`, `quality`, `cost`
granularity	string	query	No	Bucket size.Default: `daily`Options: `hourly`, `daily`
days	number	query	No	Lookback window in days.Default: `7`Range: `1–90`

Response

{
  "orgId": "org_123",
  "metric": "throughput",
  "granularity": "daily",
  "days": 7,
  "dataPoints": [
    { "timestamp": "2026-08-25T00:00:00.000Z", "value": 1240 }
  ]
}

Requires Pro tier. Default 0.1 credits (SSM-tunable). 5 min cache.

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

Retrieve latency and feedback

Per-mode retrieve latency (p50/p95/p99), token and cache-hit stats, and thumbs-up/down feedback summary for a time window.

Usage: Use this to monitor retrieve quality and latency by mode, and to track feedback trends from `POST /retrieve/feedback`.

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

Parameters

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

Response

{
  "window": "7d",
  "status": "ok",
  "modes": {
    "scout": {
      "calls": 420, "ok": 410, "failed": 5, "partial": 5, "successRate": 0.976,
      "p50Ms": 180, "p95Ms": 640, "p99Ms": 1100,
      "totalTokens": 128000, "cacheReadTokens": 40000, "cacheHitRatio": 0.3125,
      "costUSD": 1.42
    },
    "brief": {
      "calls": 96, "ok": 94, "failed": 1, "partial": 1, "successRate": 0.979,
      "p50Ms": 1400, "p95Ms": 3200, "p99Ms": 4100,
      "totalTokens": 210000, "cacheReadTokens": 90000, "cacheHitRatio": 0.4286,
      "costUSD": 3.05
    }
  },
  "feedback": { "total": 38, "thumbsUp": 31, "thumbsDown": 4, "neutral": 3, "thumbsUpRate": 0.8158 }
}

Requires Pro tier via the shared analytics access gate, but this handler does not currently deduct credits despite the tier's advertised default. 5 min cache.
`status` is `unavailable` (with an `error`) when the underlying PG read fails, or `empty` when the window has no calls.

GET/api/v1.1/analytics/operations/breakdownSecret keySDK

Operation breakdown by type

Grouped, expandable per-type breakdown of operations (calls, credits, tokens, latency) for a time window, rollup-backed.

Usage: Use this to see which specific operation types (not just memorize/retrieve totals) are driving credit spend.

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

Parameters

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

Response

{
  "window": "7d",
  "source": "rollup",
  "asOf": "2026-09-01T00:00:00.000Z",
  "groups": [
    {
      "group": "memory",
      "label": "Memory",
      "count": 8700,
      "credits": 4200.5,
      "children": [
        { "type": "save", "label": "Save", "count": 6200, "credits": 3100.2, "inputTokens": 1800000, "outputTokens": 420000, "ok": 6100, "failed": 100, "p50Ms": 220, "p95Ms": 900 }
      ]
    }
  ],
  "totals": { "credits": 4200.5, "operations": 8700 }
}

Requires Starter tier. Default 0.1 credits (SSM-tunable). 5 min cache.
`costUSD` (internal provider cost) is stripped from this org-scoped response; only `credits` (customer-visible cost) is included.
p50Ms/p95Ms are the max seen across merged rollup buckets, not a true percentile recomputation.

GET/api/v1.1/analytics/operations/historySecret keySDK

Per-request operation history

Keyset-paginated feed of individual operations (not aggregated), with per-row credits, tokens, latency, and optionally the sanitized request/response payloads.

Usage: Use this to drill into individual calls behind an aggregate spike, or to build a live operations log.

SDK: client.analytics.operationHistory({ limit: 50 })

Parameters

Field	Type	Where	Required	Description
limit	number	query	No	Page size.Default: `50`Range: `1–200`
cursor	string	query	No	Opaque cursor from a previous page's `nextCursor`.
opType	string	query	No	Filter to one operation type.
client	string	query	No	Filter by calling client.Options: `ui`, `sdk`, `cli`, `mcp`, `api`, `unknown`
source	string	query	No	Filter by call source.Options: `api`, `agent_tool`, `mcp`, `scheduler`, `batch`
userId	string	query	No	Filter to one user.
withPayloads	boolean	query	No	Include the sanitized request/response body per row. Set `false` for lighter, larger pages.Default: `true`

Response

{
  "orgId": "org_123",
  "items": [
    {
      "opId": "op_abc123", "type": "save", "label": "Save", "group": "memory",
      "createdAt": "2026-09-01T00:00:00.000Z",
      "userId": "user_123", "source": "api", "client": "sdk", "status": "ok",
      "creditsUsed": 1.2, "durationMs": 340,
      "inputTokens": 1800, "outputTokens": 420,
      "llmModel": "gpt-4.1", "llmProvider": "openai", "mode": "shortform",
      "request": { "content": "..." }, "response": { "success": true }
    }
  ],
  "nextCursor": "MjAyNi0wOS0wMVQwMDowMDowMC4wMDBafG9wX2FiYzEyMw==",
  "hasMore": true
}

Requires Pro tier via the shared analytics access gate, but this is a raw read (no aggregation) and is not billed. Never cached -- always live.
`costUSD` (internal provider cost) is stripped from this org-scoped response.
`request`/`response` are `null` for rows recorded before this feature shipped, and for non-HTTP operations with no captured body.

GET/api/v1.1/analytics/operations/totalsSecret keySDK

Grand totals

Rollup-backed grand totals (credits, operations, tokens, cost, success rate) for a time window, or org-lifetime when `window` is omitted, plus a compact per-group breakdown.

Usage: Use this for a single KPI-row summary instead of assembling one from the full breakdown.

SDK: client.analytics.totals({ window: '30d' })

Parameters

Field	Type	Where	Required	Description
window	string	query	No	Time window. Omit for org-lifetime totals.Options: `1h`, `24h`, `7d`, `30d`

Response

{
  "window": "30d",
  "source": "rollup",
  "asOf": "2026-09-01T00:00:00.000Z",
  "totals": {
    "credits": 51500.2, "operations": 14900,
    "tokens": {
      "input": 2400000, "output": 890000, "total": 3290000,
      "cachedInput": 900000, "freshInput": 1500000, "cacheWrite": 60000
    },
    "successRate": 0.987
  },
  "byGroup": [
    { "group": "memory", "label": "Memory", "count": 8700, "credits": 4200.5 }
  ]
}

Free (Free tier, 0 default credits). 5 min cache.
`costUSD` (internal provider cost) is stripped from this org-scoped response; it is present on the Super-Admin `/analytics/admin/totals` surface.

GET/api/v1.1/analytics/operations/timeseriesSecret keySDK

Usage over time

Rollup-backed daily/weekly/monthly time series: overall totals plus a per-group series, for charting usage over time.

Usage: Use this to render a usage-over-time chart, optionally split by operation group.

SDK: client.analytics.timeseries({ window: '30d' })

Parameters

Field	Type	Where	Required	Description
window	string	query	No	Time window, or `all` for full history.Default: `30d`Options: `1h`, `24h`, `7d`, `30d`, `all`
granularity	string	query	No	Bucket size. Defaults to `day` for a windowed range, `month` for `all`.Options: `day`, `week`, `month`

Response

{
  "window": "30d",
  "granularity": "day",
  "source": "rollup",
  "asOf": "2026-09-01T00:00:00.000Z",
  "series": [
    { "day": "2026-08-25", "credits": 1400.2, "operations": 480, "inputTokens": 320000, "outputTokens": 90000, "ok": 470, "failed": 10 }
  ],
  "byGroup": [
    { "group": "memory", "label": "Memory", "series": [ { "day": "2026-08-25", "credits": 700.1, "calls": 240 } ] }
  ]
}

Requires Starter tier. Default 0.1 credits (SSM-tunable). 5 min cache.

GET/api/v1.1/analytics/operations/modelsSecret keySDK

Model and provider cost breakdown

Per-model and per-provider call counts, token usage, and credit cost for a time window.

Usage: Use this to see which models or providers are driving cost, and to spot-check average credits per call.

SDK: client.analytics.models({ window: '30d' })

Parameters

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

Response

{
  "window": "30d",
  "source": "pg",
  "models": [
    { "name": "gpt-4.1", "provider": "openai", "calls": 3200, "credits": 2100.4, "inputTokens": 1400000, "outputTokens": 380000, "tokens": 1780000, "avgCreditsPerCall": 0.66, "creditsPerKToken": 1.1806 }
  ],
  "providers": [
    { "name": "openai", "provider": null, "calls": 3200, "credits": 2100.4, "inputTokens": 1400000, "outputTokens": 380000, "tokens": 1780000, "avgCreditsPerCall": 0.66, "creditsPerKToken": 1.1806 }
  ]
}

Requires Pro tier. Default 0.2 credits (SSM-tunable). 5 min cache.
`costUSD` (internal provider cost) is stripped from this org-scoped response.

GET/api/v1.1/analytics/operations/inventorySecret keySDK

Org entity inventory

Org-wide entity counts: records, saved memories, filled properties, entity types, collections, graph edges, relation types, graph rules, document types, documents, integrations, and API keys.

Usage: Use this for a single-call snapshot of everything provisioned in an org, for a settings/overview page.

SDK: client.analytics.inventory()

Response

{
  "orgId": "org_123",
  "source": "pg",
  "inventory": {
    "records": 12450, "savedMemories": 87320, "filledProperties": 62100,
    "entityTypes": 3, "collections": 6, "declaredProperties": 48,
    "graphEdges": 21000, "relationTypes": 22, "graphRules": 14,
    "documentTypes": 5, "documents": 40,
    "integrations": { "mcps": 2, "destinations": 3 },
    "apiKeys": 4
  }
}

Free (Free tier, 0 default credits). 5 min cache.
Individual inventory fields fall back to `null` (not 0) when their sub-lookup fails, so `null` means "couldn't determine" rather than "zero".

POST/api/v1.1/analytics/operations/refreshSecret keySDK

Refresh operations rollup

Triggers an on-demand recompute of this org's operations rollup, rate-limited to once every 5 minutes per organization.

Usage: Use this when you need the totals/breakdown/timeseries endpoints to reflect very recent activity instead of waiting for the next scheduled rollup.

SDK: client.analytics.refresh()

Response

{
  "refreshed": true,
  "asOf": "2026-09-01T00:05:00.000Z"
}

No request body or query/path parameters -- the refresh is scoped to the caller's organization via the API key, and there is nothing to configure.
Requires Pro tier via the shared analytics access gate, but this handler does not currently deduct credits.
If called again within 5 minutes of the last refresh, returns `{ "refreshed": false, "asOf", "retryAfterSeconds", "message" }` instead of re-running.
Invalidates this org's cached totals/breakdown so the next read reflects the refresh.

5 endpoints

BYOK Configuration

Bring-your-own-key LLM routing: inspect and update per-function/per-tier model config, browse live provider model catalogs, and verify the org's routing actually resolves onto customer keys instead of managed credentials. These routes exist under v1.1 only -- there is no v1 equivalent.

GET/api/v1.1/byok/llm-configSecret keySDK

Get BYOK configuration

Returns the org's BYOK enablement, stored provider keys (masked), and per-function/per-tier model routing config.

Usage: Use this to render the current BYOK configuration before letting a user edit it.

SDK: client.byok.getConfig()

Response

{
  "success": true,
  "byokEnabled": true,
  "providers": [
    { "provider": "openai", "verified": true, "maskedKey": "sk-...ab12", "addedAt": "2026-04-01T00:00:00.000Z" }
  ],
  "functions": {
    "memorize": {
      "basic": { "provider": "openai", "model": "gpt-4o-mini" },
      "pro": { "provider": "openai", "model": "gpt-4.1" },
      "ultra": null
    },
    "recall": null,
    "smartContext": null,
    "smartUpdate": null,
    "generate": null
  }
}

Returns 403 with `code: 'byok_not_allowed'` when the org's plan does not allow custom LLM keys.

PUT/api/v1.1/byok/llm-configSecret keySDK

Save BYOK configuration

Replaces per-function tier model routing. Setting a function to `null` resets it to the platform default; sending a function replaces its entire tier map.

Usage: Use this to point specific functions (memorize, recall, smartContext, smartUpdate, generate) at your own provider keys and models, per tier.

SDK: client.byok.saveConfig({ functions })

Parameters

Field	Type	Where	Required	Description
functions	object	body	Yes	Partial map of function name to per-tier model config or `null`. Keys: `memorize`, `recall`, `smartContext`, `smartUpdate`, `generate`. Each value is `{ basic?, pro?, ultra? }` where each tier is `{ provider, model, reasoning? }` or `null`.

Request

{
  "functions": {
    "memorize": {
      "pro": { "provider": "openai", "model": "gpt-4.1" }
    }
  }
}

Response

{
  "success": true,
  "message": "Configuration saved"
}

Rejected with 400 (`code: 'byok_invalid_provider'`) if a referenced provider has no stored key for the org.
Rejected with 400 (`code: 'invalid_model'`) if a model id is confirmed absent from the provider's live catalog.
Provider keys themselves (add/remove) are not managed by this endpoint -- that stays in the Personize dashboard.

GET/api/v1.1/byok/resolved-modelsSecret keySDK

Get resolved BYOK models

Returns the effective (post-routing) provider and model for every BYOK-eligible function, for one tier or all tiers.

Usage: Use this to confirm what actually resolves at request time, since a saved config can still fall back to the platform default under certain conditions.

SDK: client.byok.resolvedModels({ tier })

Parameters

Field	Type	Where	Required	Description
tier	string	query	No	Tier to resolve.Default: `all`Options: `basic`, `pro`, `ultra`, `all`

Response

{
  "success": true,
  "orgId": "org_123",
  "resolved": {
    "pro": {
      "memorize": { "provider": "openai", "model": "gpt-4.1", "routeReason": "org-byok", "isByok": true },
      "recall": { "provider": "openrouter", "model": "google/gemma-4-31b-it", "routeReason": "platform-tier", "isByok": false }
    }
  }
}

`isByok: false` with `routeReason: 'platform-tier'` means that function is currently running on Personize's managed credentials, not the org's own key.

GET/api/v1.1/byok/llm-config/models/:providerSecret keySDK

Get provider model catalog

Fetches the live model catalog for a provider, decrypting the org's stored key server-side when the provider requires one for catalog access.

Usage: Use this to populate a model picker with the provider's actual available models instead of a hardcoded list.

SDK: client.byok.getModels(provider, { refresh })

Parameters

Field	Type	Where	Required	Description
provider	string	path	Yes	Provider id, for example `openai`, `anthropic`, `openrouter`, `bedrock`.
refresh	boolean	query	No	Bypass the 1-hour catalog cache and refetch live.Default: `false`

Response

{
  "success": true,
  "provider": "openai",
  "data": [
    { "id": "gpt-4.1", "name": "GPT-4.1" }
  ],
  "cached": true
}

Returns 400 (`code: 'no_provider_key'`) if the provider needs a key for catalog access and the org has not stored one.
Catalogs are cached in-memory per org+provider for 1 hour unless `refresh=true`.

GET/api/v1.1/byok/verifySecret keySDK

Verify BYOK configuration

Per-entry health check of the stored config: whether each configured (function, tier) entry has a key present, resolves to a valid catalog model, and actually runs on the customer's key rather than falling back to managed credentials.

Usage: Use this to audit BYOK setup and catch entries that silently fall back to managed credentials.

SDK: client.byok.verify()

Response

{
  "success": true,
  "ok": false,
  "entries": [
    {
      "function": "memorize", "tier": "pro", "provider": "openai", "model": "gpt-4.1",
      "keyPresent": true, "modelValid": true, "isByok": true, "routeReason": "org-byok"
    },
    {
      "function": "recall", "tier": "pro", "provider": "openai", "model": "gpt-4.1",
      "keyPresent": false, "modelValid": true, "isByok": false, "routeReason": "platform-tier",
      "error": "Resolves to Personize managed credentials (isByok=false), provider key missing or undecryptable"
    }
  ]
}

`ok` is `true` only when every entry both resolves onto the org's own key (or `org-byoc`) and has a valid catalog model.

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.

6 endpoints

Schedules

Create recurring or one-time tasks that run a prompt or send a notification, on a cron/rate schedule (recurring) or at a fixed future time (one-time). v1 only -- not mounted on v1.1. Reads (list, get, executions) accept `admin`, `member-only`, or `read-only` key scope; writes (create, update, delete) require `admin` scope.

POST/api/v1.1/schedulesSecret keySDK

Create a schedule

Creates a recurring or one-time schedule. Recurring schedules fire on `pattern`; one-time schedules fire once at `runAt`.

Usage: Use this to automate a recurring prompt (e.g. a daily digest) or a one-time reminder without building your own cron infrastructure.

SDK: client.schedules.create(options)

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	Unique kebab-case name within the org (lowercase letters, digits, hyphens, underscores).
taskType	string	body	Yes	What the schedule runs.Options: `run_prompt`, `send_notification`, `run_sync`, `run_digest`, `run_usage_analytics`
taskPayload	object	body	Yes	Task-specific payload. For `run_prompt`, the same body as `POST /api/v1.1/prompt` (requires `prompt` or `instructions`). For `send_notification`, `{ contentMode: 'static'\|'smart', title/body (static) or topic (smart), recipientEmail or recipientUserId, channels, priority }`.
recurring	boolean	body	No	`true` fires on `pattern`; `false` fires once at `runAt`.Default: `false`
pattern	string	body	No	Cron or rate expression. Required when `recurring` is `true`.
runAt	string	body	No	ISO8601 timestamp to fire once. Required when `recurring` is `false`.
description	string	body	No	Free-text description (max 500 chars).
startDate	string	body	No	ISO8601 timestamp. Recurring schedules do not fire before this.
endDate	string	body	No	ISO8601 timestamp. Recurring schedules stop firing after this.
timezone	string	body	No	IANA timezone the pattern is evaluated in.Default: `UTC`
enabled	boolean	body	No	Whether the schedule is active.Default: `true`
concurrencyPolicy	string	body	No	Behavior when the previous run of this schedule is still in flight at the next fire time.Default: `allow`Options: `allow`, `skip`

Request

{
  "name": "daily-followup-john",
  "taskType": "run_prompt",
  "taskPayload": {
    "prompt": "Draft a 2-line follow-up email for this contact.",
    "memorize": { "recordId": "rec_abc", "type": "Contact" },
    "governedMemory": true,
    "outputs": [{ "name": "email", "required": true }]
  },
  "recurring": true,
  "pattern": "rate(1 day)"
}

Response

{
  "success": true,
  "data": {
    "id": "01J8X8Q1Z6R3N9V6K5Y2W1T4C0",
    "organizationId": "org_123",
    "userId": "user_123",
    "name": "daily-followup-john",
    "description": "",
    "taskType": "run_prompt",
    "taskPayload": { "prompt": "Draft a 2-line follow-up email for this contact.", "memorize": { "recordId": "rec_abc", "type": "Contact" }, "governedMemory": true, "outputs": [{ "name": "email", "required": true }] },
    "recurring": true,
    "pattern": "rate(1 day)",
    "timezone": "UTC",
    "enabled": true,
    "status": "active",
    "concurrencyPolicy": "allow",
    "consecutiveFailures": 0,
    "runCount": 0,
    "errorCount": 0,
    "createdAt": "2026-09-01T00:00:00.000Z",
    "updatedAt": "2026-09-01T00:00:00.000Z"
  }
}

Recurring needs `pattern`; one-time needs `runAt` -- never both, the schema rejects a payload that doesn't match `recurring`.
`pattern` syntax: `rate(N minutes|hours|days|weeks)` for a fixed interval (e.g. `rate(1 day)`), or `cron(MIN HOUR DOM MON DOW YEAR)` (AWS-flavored 6-field cron, e.g. `cron(0 9 ? * MON *)` for Mondays at 9am) for calendar-based firing.
Recurring `rate(...)` schedules with no user-supplied `startDate` get up to ±60s of jitter auto-applied, so many identical 'every N' schedules don't all fire at the same second.
`run_prompt` and `send_notification` payloads are validated against their full schema at creation time. `run_sync`, `run_digest`, and `run_usage_analytics` are internal-only task types (migration/platform use).
Create-only: it never updates an existing schedule. Returns 409 if a schedule with this name already exists that is not deleted (active, paused, completed or error); the body carries `error: "duplicate_name"` and `code: "DUPLICATE_NAME"`. Only a deleted schedule's name can be reused. To change one, use `PATCH /api/v1.1/schedules/:id` (id or name). The SDK throws a `ConflictError` (a `PersonizeError` subclass, `status === 409`, `code === 'DUPLICATE_NAME'`).
Requires `admin` scope.

GET/api/v1.1/schedulesSecret keySDK

List schedules

Lists schedules for the org, optionally filtered by record, contact, company, or task type.

Usage: Use this to see what's currently scheduled, or to find the schedules tied to one record.

SDK: client.schedules.list(options)

Parameters

Field	Type	Where	Required	Description
limit	number	query	No	Page size.Default: `50`
nextToken	string	query	No	Cursor from a previous page.
recordId	string	query	No	Filter to schedules whose taskPayload references this record.
email	string	query	No	Filter to schedules whose taskPayload references this contact email.
websiteUrl	string	query	No	Filter to schedules whose taskPayload references this company website.
taskType	string	query	No	Filter by task type.

Response

{
  "success": true,
  "data": [
    { "id": "01J8...", "name": "daily-followup-john", "taskType": "run_prompt", "recurring": true, "pattern": "rate(1 day)", "status": "active", "enabled": true }
  ],
  "nextToken": null
}

The recordId/email/websiteUrl/taskType filters are applied after the page is fetched, so a filtered page can return fewer than `limit` items even when more matches exist -- keep following `nextToken`. When any filter is set, the response also includes `filtered: true` and `rawCount` (the unfiltered page size).
Requires `admin`, `member-only`, or `read-only` scope.

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

Get a schedule

Fetches one schedule by its ULID id or kebab-case name.

Usage: Use this to inspect a schedule's current config, status, or last-run info.

SDK: client.schedules.get(idOrName)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	ULID id or kebab-case name.

Response

{
  "success": true,
  "data": {
    "id": "01J8X8Q1Z6R3N9V6K5Y2W1T4C0",
    "name": "daily-followup-john",
    "taskType": "run_prompt",
    "recurring": true,
    "pattern": "rate(1 day)",
    "status": "active",
    "enabled": true,
    "lastRunAt": "2026-08-31T00:00:12.000Z",
    "lastRunStatus": "success",
    "runCount": 42,
    "errorCount": 0
  }
}

Returns 404 (`schedule_not_found`) if the id/name doesn't resolve to a schedule in this org, or if it was soft-deleted.
Requires `admin`, `member-only`, or `read-only` scope.

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

Update a schedule

Partial update of a schedule. `name`, `taskType`, `recurring`, and `startDate` are immutable after creation.

Usage: Use this to change a schedule's payload, timing, or enabled state without recreating it.

SDK: client.schedules.update(idOrName, patch)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	ULID id or kebab-case name.
description	string	body	No	New description (max 500 chars).
taskPayload	object	body	No	Replace the task payload.
pattern	string	body	No	New cron/rate expression (recurring schedules).
runAt	string	body	No	New fire time (one-time schedules).
endDate	string	body	No	New end date.
timezone	string	body	No	New IANA timezone.
enabled	boolean	body	No	Enable or disable the schedule.
concurrencyPolicy	string	body	No	New concurrency policy.Options: `allow`, `skip`

Request

{ "pattern": "rate(4 hours)" }

Response

{
  "success": true,
  "data": { "id": "01J8X8Q1Z6R3N9V6K5Y2W1T4C0", "name": "daily-followup-john", "pattern": "rate(4 hours)", "enabled": true }
}

Requires `admin` scope.

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

Delete a schedule

Soft-deletes a schedule (90-day retention). After deletion, GET/PATCH/DELETE and the executions endpoint all 404 for this schedule.

Usage: Use this to stop a schedule from firing and remove it from listings.

SDK: client.schedules.delete(idOrName)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	ULID id or kebab-case name.

Response

{
  "success": true,
  "deleted": "daily-followup-john"
}

Requires `admin` scope.

GET/api/v1.1/schedules/:id/executionsSecret keySDK

List execution history

Lists past executions for one schedule, newest first.

Usage: Use this to audit whether a scheduled task actually ran, and inspect its result or error per firing.

SDK: client.schedules.executions(idOrName, options)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	ULID id or kebab-case name of the schedule.
limit	number	query	No	Page size.Default: `20`
nextToken	string	query	No	Cursor from a previous page.

Response

{
  "success": true,
  "data": [
    {
      "id": "01J9...",
      "scheduleId": "01J8X8Q1Z6R3N9V6K5Y2W1T4C0",
      "organizationId": "org_123",
      "taskType": "run_prompt",
      "status": "success",
      "startedAt": "2026-08-31T00:00:00.000Z",
      "completedAt": "2026-08-31T00:00:12.000Z",
      "durationMs": 12000,
      "destinationsDispatched": true
    }
  ],
  "nextToken": null
}

Returns 404 (`schedule_not_found`) if the schedule doesn't exist in this org or was soft-deleted.
Requires `admin`, `member-only`, or `read-only` scope.

16 endpoints

Integrations

Configure and run CRM/CSV sync as reusable DataSources: field mappings resolved manually, from a template, or via AI matching, plus on-demand runs and recurring schedules.

POST/api/v1.1/integrations/datasourcesSecret keySDK

Create a DataSource

Creates a sync config (a DataSource) that maps a CRM or CSV provider's fields to Personize properties. Mappings are resolved manually, from a built-in or saved template, or via AI field matching, depending on `mode`.

Usage: Use this to set up a sync between a connected CRM (or CSV upload) and Personize memory, choosing how field mappings get resolved.

SDK: client.integrations.datasources.create(options)

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	Display name for the DataSource.
provider	string	body	Yes	Source system.Options: `hubspot`, `salesforce`, `apollo`, `apollo-oauth`, `csv`
entityType	string	body	Yes	Target Personize entity type (e.g. `contact`, `company`).
mode	string	body	No	How `propertyMappings` gets resolved.Default: `manual`Options: `manual`, `template`, `ai`
propertyMappings	PropertyMapping[]	body	No	Required and non-empty when `mode='manual'`. Each item: `{ source \| staticValue, target, direction?, extractMemories?, aiGenerated? }`.
template	object	body	No	Required when `mode='template'`. One of `{ type: 'builtin', id }`, `{ type: 'user', id }`, or `{ type: 'collections', collectionIds }`.
ai	object	body	No	Used when `mode='ai'`. `{ collectionIds?, minConfidence? (default 0.4), fallbackToTemplate? (default true) }`.

Request

{
  "name": "HubSpot Contacts",
  "provider": "hubspot",
  "entityType": "contact",
  "mode": "template",
  "template": { "type": "builtin", "id": "hubspot_contacts_standard" }
}

Response

{
  "success": true,
  "data": {
    "id": "ds_01j...",
    "organizationId": "org_123",
    "createdAt": "2026-09-01T00:00:00.000Z",
    "payload": {
      "name": "HubSpot Contacts",
      "provider": "hubspot",
      "entityType": "contact",
      "direction": "in",
      "mappingMode": "manual",
      "propertyMappings": [...],
      "status": "active"
    },
    "mode": "template",
    "template": { "type": "builtin", "id": "hubspot_contacts_standard" }
  }
}

SDK Example

const ds = await client.integrations.datasources.create({
  name: 'HubSpot Contacts',
  provider: 'hubspot',
  entityType: 'contact',
  mode: 'template',
  template: { type: 'builtin', id: 'hubspot_contacts_standard' },
});
await client.integrations.datasources.run(ds.data!.id, { direction: 'in' });

`mode='template'` or `mode='ai'` (managed mappings) automatically get an identity field and the CRM's native record id appended to `propertyMappings` when the template or matcher didn't already include them, so writeback and dedupe always resolve to a real key. `mode='manual'` is stored exactly as authored.
Preview what a template or AI match would produce first with `POST /integrations/mapping/suggest`, without creating a DataSource.

GET/api/v1.1/integrations/datasourcesSecret keySDK

List DataSources

Lists the org's DataSource configs, newest first.

Usage: Use this to see what syncs are configured for the org.

SDK: client.integrations.datasources.list(options)

Parameters

Field	Type	Where	Required	Description
limit	number	query	No	Page size.Default: `50`

Response

{
  "success": true,
  "data": [
    {
      "id": "ds_01j...",
      "organizationId": "org_123",
      "createdAt": "2026-09-01T00:00:00.000Z",
      "updatedAt": "2026-09-01T00:00:00.000Z",
      "payload": { "name": "HubSpot Contacts", "provider": "hubspot", "entityType": "contact", "direction": "in", "status": "active" }
    }
  ]
}

GET/api/v1.1/integrations/datasources/:idSecret keySDK

Get a DataSource

Fetches one DataSource config by id, including its full mapping payload.

Usage: Use this to inspect a DataSource's current mappings and settings before editing or running it.

SDK: client.integrations.datasources.get(id)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The DataSource id.

Response

{
  "success": true,
  "data": {
    "id": "ds_01j...",
    "organizationId": "org_123",
    "createdAt": "2026-09-01T00:00:00.000Z",
    "payload": { "name": "HubSpot Contacts", "provider": "hubspot", "entityType": "contact", "direction": "in", "propertyMappings": [...], "status": "active" }
  }
}

Returns 404 (`not_found`) if the id doesn't resolve to a DataSource in this org.

PATCH/api/v1.1/integrations/datasources/:idSecret keySDK

Update a DataSource

Partially updates a DataSource's mappings or settings.

Usage: Use this to change field mappings, direction, schedule, or status without recreating the DataSource.

SDK: client.integrations.datasources.patch(id, options)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The DataSource id.
name	string	body	No	New display name.
direction	string	body	No	New sync direction.Options: `in`, `out`, `bidirectional`
identityFields	object	body	No	Replace the identity field configuration.
mappingMode	string	body	No	New mapping mode.Options: `manual`, `all`
propertyMappings	PropertyMapping[]	body	No	Replace the mapping array.
writeStrategy	string	body	No	New sync-out behavior.Options: `upsert`, `create_only`, `update_only`
onNoMatch	string	body	No	New no-match behavior.Options: `create`, `skip`
conflictPolicy	string	body	No	New conflict resolution policy.Options: `personize_wins`, `crm_wins`
maxRecords	number	body	No	New per-run record cap.
filters	object	body	No	New provider-side filter criteria.
scheduleEnabled	boolean	body	No	Enable or disable the recurring sync.
scheduleFrequency	string	body	No	New cadence.Options: `hourly`, `daily`, `weekly`, `manual-only`
status	string	body	No	New status.Options: `active`, `paused`, `error`, `retrying`

Request

{ "scheduleEnabled": true, "scheduleFrequency": "daily" }

Response

{
  "success": true,
  "data": {
    "id": "ds_01j...",
    "organizationId": "org_123",
    "payload": { "name": "HubSpot Contacts", "scheduleEnabled": true, "scheduleFrequency": "daily", "status": "active" }
  }
}

This is a shallow merge over the existing payload, not a full replace.
If the DataSource has managed mappings (created with `mode='template'` or `mode='ai'`) and you replace `propertyMappings`, the identity and native-id floor is automatically reapplied so writeback doesn't silently lose the CRM record id.
Returns 404 (`not_found`) if the id doesn't resolve to a DataSource in this org.

DELETE/api/v1.1/integrations/datasources/:idSecret keySDK

Delete a DataSource

Removes a DataSource config.

Usage: Use this to stop and remove a sync you no longer need.

SDK: client.integrations.datasources.delete(id)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The DataSource id.

Response

204 No Content

Removes the DataSource config only. It does not revoke or disconnect the underlying CRM OAuth connection.
Returns 404 (`not_found`) if the id doesn't resolve to a DataSource in this org.

POST/api/v1.1/integrations/datasources/:id/runsSecret keySDK

Run a DataSource

Triggers a sync run for one DataSource, either a real run or a dry-run preview.

Usage: Use this to pull records in from the CRM, push Personize changes out, or validate what a run would do before touching the provider.

SDK: client.integrations.datasources.run(id, options)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The DataSource id.
direction	string	body	Yes	Which way to sync.Options: `in`, `out`, `both`
dryRun	boolean	body	No	Validate and preview without touching the provider.Default: `false`

Request

{ "direction": "in", "dryRun": false }

Response

{
  "success": true,
  "data": {
    "dataSourceId": "ds_01j...",
    "direction": "in",
    "runId": "run_01j...",
    "queuedAt": "2026-09-01T00:00:00.000Z",
    "pollAt": "/api/v1.1/integrations/datasources/ds_01j.../runs",
    "note": "Run dispatched. Poll GET .../runs to watch runId reach a terminal status; the run row's eventId feeds GET .../runs/{eventId} for sampleRecords."
  }
}

`direction='in'` imports from the CRM into Personize; `'out'` writes Personize data back to the CRM; `'both'` runs sync-in inline, then schedules a delayed sync-out follow-up.
A real run (`dryRun: false`) returns 202 immediately and dispatches async. `runId` is present for `direction='in'` or `'both'`; poll `GET .../runs` to watch it reach a terminal status, then use its `eventId` with `GET .../runs/:eventId` for the sampleRecords preview.
`dryRun: true` returns 200 synchronously with a preview (`provider`, `entityType`, `mappingMode`, `propertyMappingsCount`, `writeStrategy`, `onNoMatch`, `conflictPolicy`) and touches nothing. No records are fetched or pushed.

GET/api/v1.1/integrations/datasources/:id/runsSecret keySDK

List DataSource runs

Lists run history for one DataSource, newest first.

Usage: Use this to check whether a sync completed and to grab the eventId for a detailed run report.

SDK: client.integrations.datasources.listRuns(id, options)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The DataSource id.
limit	number	query	No	Page size.Default: `20`

Response

{
  "success": true,
  "data": [
    {
      "runId": "run_01j...",
      "dataSourceId": "ds_01j...",
      "status": "completed",
      "direction": "in",
      "provider": "hubspot",
      "entityType": "contact",
      "triggerType": "manual",
      "startedAt": "2026-09-01T00:00:00.000Z",
      "completedAt": "2026-09-01T00:00:12.000Z",
      "recordsFetched": 120,
      "recordsPushed": 0,
      "recordsFailed": 0,
      "eventId": "evt_01j..."
    }
  ]
}

A row's `eventId`, when present, chains to `GET .../runs/:eventId` for that run's sampleRecords.

GET/api/v1.1/integrations/datasources/:id/runs/:eventIdSecret keySDK

Get run detail

Fetches the audit row(s) for one run, including a small sample-records preview.

Usage: Use this to debug a run: per-direction counts, timing, first error, and a preview of the records that were processed.

SDK: client.integrations.datasources.getRun(id, eventId)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The DataSource id.
eventId	string	path	Yes	The run's event id, from `listRuns` or the run-dispatch response.

Response

{
  "success": true,
  "data": [
    {
      "eventId": "evt_01j...",
      "organizationId": "org_123",
      "dataSourceId": "ds_01j...",
      "provider": "hubspot",
      "entityType": "contact",
      "direction": "in",
      "triggerType": "manual",
      "status": "completed",
      "startedAt": "2026-09-01T00:00:00.000Z",
      "completedAt": "2026-09-01T00:00:12.000Z",
      "durationMs": 12000,
      "recordCount": 120,
      "successCount": 118,
      "failedCount": 2,
      "skippedCount": 0,
      "sampleRecords": [...]
    }
  ]
}

Returns one audit row per direction, so a `'both'` run can return two rows.
Returns 404 (`not_found`) if there's no audit row for that event yet.

GET/api/v1.1/integrations/datasources/:id/scheduleSecret keySDK

Get DataSource schedule

Returns a focused view of the DataSource's recurring-sync schedule.

Usage: Use this to check whether a DataSource is on a recurring schedule and when it last ran in each direction.

SDK: client.integrations.datasources.getSchedule(id)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The DataSource id.

Response

{
  "success": true,
  "data": {
    "dataSourceId": "ds_01j...",
    "enabled": true,
    "frequency": "daily",
    "lastSyncInAt": "2026-09-01T02:00:00.000Z",
    "lastSyncOutAt": null
  }
}

PUT/api/v1.1/integrations/datasources/:id/scheduleSecret keySDK

Set DataSource schedule

Enables, disables, or re-tunes the recurring sync for one DataSource.

Usage: Use this to put a DataSource on a recurring cadence instead of running it manually each time.

SDK: client.integrations.datasources.setSchedule(id, options)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The DataSource id.
enabled	boolean	body	Yes	Turn the recurring sync on or off.
frequency	string	body	No	Cadence. Required to enable.Options: `hourly`, `daily`, `weekly`, `manual-only`

Request

{ "enabled": true, "frequency": "daily" }

Response

{
  "success": true,
  "data": { "dataSourceId": "ds_01j...", "enabled": true, "frequency": "daily", "lastSyncInAt": null, "lastSyncOutAt": null }
}

Enabling a schedule (`enabled: true`) requires a real `frequency`: `hourly`, `daily`, or `weekly`. Passing `enabled: true` with `frequency` omitted or `'manual-only'` returns 400.
One underlying schedule exists per (org, frequency) bucket, firing on a fixed cadence (top of the hour / 02:00 UTC / Monday 02:00 UTC), not at a caller-chosen time.

DELETE/api/v1.1/integrations/datasources/:id/scheduleSecret keySDK

Disable DataSource schedule

Disables the recurring sync for one DataSource.

Usage: Use this to stop a DataSource from firing on its schedule while keeping the DataSource itself.

SDK: client.integrations.datasources.deleteSchedule(id)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The DataSource id.

Response

{
  "success": true,
  "data": { "dataSourceId": "ds_01j...", "enabled": false, "frequency": "daily", "lastSyncInAt": "2026-09-01T02:00:00.000Z", "lastSyncOutAt": null }
}

Disables the recurring sync but keeps the last frequency saved, so re-enabling later is a one-field `PUT`.

GET/api/v1.1/integrations/templatesSecret keySDK

List mapping templates

Lists built-in and org-saved mapping templates, optionally filtered by provider and entity type.

Usage: Use this to find a starting-point mapping before creating a DataSource with `mode='template'`.

SDK: client.integrations.templates.list(options)

Parameters

Field	Type	Where	Required	Description
provider	string	query	No	Filter by provider.
entityType	string	query	No	Filter by entity type.

Response

{
  "success": true,
  "data": {
    "builtIns": [{ "id": "hubspot_contacts_standard", "kind": "builtin", "provider": "hubspot", "entityType": "contact" }],
    "user": []
  }
}

POST/api/v1.1/integrations/templatesSecret keySDK

Save a mapping template

Saves a reusable, org-scoped mapping template.

Usage: Use this to turn a set of field mappings you've tuned once into a reusable template for future DataSources.

SDK: client.integrations.templates.save(options)

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	Template name.
provider	string	body	Yes	Source system this template applies to.
entityType	string	body	Yes	Target Personize entity type.
propertyMappings	PropertyMapping[]	body	Yes	Non-empty mapping array.
description	string	body	No	Template description.
defaultDirection	string	body	No	Default sync direction for DataSources created from this template.Options: `in`, `out`, `bidirectional`
defaultIdentityField	string	body	No	Default identity field for DataSources created from this template.

Request

{
  "name": "My HubSpot Mapping",
  "provider": "hubspot",
  "entityType": "contact",
  "defaultDirection": "in",
  "propertyMappings": [
    { "source": "email", "target": "email", "direction": "both" },
    { "source": "jobtitle", "target": "Job Title", "direction": "in" }
  ]
}

Response

{
  "success": true,
  "data": { "id": "tpl_01j...", "kind": "user", "name": "My HubSpot Mapping", "provider": "hubspot", "entityType": "contact", "propertyMappings": [...] }
}

GET/api/v1.1/integrations/templates/:idSecret keySDK

Get a mapping template

Fetches one template by id.

Usage: Use this to inspect a template's mappings before applying it.

SDK: client.integrations.templates.get(id)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Built-in template id (e.g. `hubspot_contacts_standard`) or a saved template's UUID; both are tried.

Response

{
  "success": true,
  "data": { "id": "hubspot_contacts_standard", "kind": "builtin", "provider": "hubspot", "entityType": "contact", "propertyMappings": [...] }
}

Returns 404 (`not_found`) if neither a built-in nor a saved template matches the id.

DELETE/api/v1.1/integrations/templates/:idSecret keySDK

Delete a mapping template

Deletes a saved (user) template.

Usage: Use this to remove a template you no longer need.

SDK: client.integrations.templates.delete(id)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The saved template's id.

Response

204 No Content

Built-in templates cannot be deleted; returns 400 (`cannot_delete_builtin`).

POST/api/v1.1/integrations/mapping/suggestSecret keySDK

Suggest field mappings

Resolves the `propertyMappings` a template or AI match would produce for a provider and entity type, without creating a DataSource.

Usage: Use this to preview and edit suggested mappings before committing to a DataSource, or to build a review step in your own UI.

SDK: client.integrations.suggestMappings(options)

Parameters

Field	Type	Where	Required	Description
provider	string	body	Yes	Source system.
entityType	string	body	Yes	Target Personize entity type.
mode	string	body	Yes	Resolution strategy. `manual` is not accepted here.Options: `template`, `ai`
template	object	body	No	Required when `mode='template'`. Same shape as in `POST /integrations/datasources`.
ai	object	body	No	Used when `mode='ai'`. `{ collectionIds?, minConfidence?, fallbackToTemplate? }`.
csvColumns	string[]	body	No	Required only when `provider='csv'` with a `collections` template or `mode='ai'`.

Request

{
  "provider": "hubspot",
  "entityType": "contact",
  "mode": "template",
  "template": { "type": "builtin", "id": "hubspot_contacts_standard" }
}

Response

{
  "success": true,
  "data": {
    "mode": "ai",
    "provider": "hubspot",
    "entityType": "contact",
    "propertyMappings": [...],
    "defaults": { "direction": "in", "identityField": "email" }
  }
}

`mode='manual'` returns 400 (nothing to suggest, the caller already has mappings).
Does not create a DataSource. Review or edit the returned `propertyMappings`, then pass them to `POST /integrations/datasources` with `mode='manual'`.

3 endpoints

CRM Passthrough

Proxy raw REST calls to a customer's connected CRM using the org's managed OAuth connection, so the caller never has to store or handle CRM credentials directly.

POST/api/v1.1/crm/hubspot/passthroughSecret keySDK

HubSpot passthrough

Forwards one REST call to the HubSpot API using the org's connected HubSpot integration. Personize authenticates the call with the connection made once in the dashboard, so the caller never handles a HubSpot token.

Usage: Use this for HubSpot endpoints not covered by the SDK's typed wrappers, or when you want raw control over the request.

SDK: client.hubspot.request(opts)

Parameters

Field	Type	Where	Required	Description
method	string	body	Yes	HTTP method to forward.Options: `GET`, `POST`, `PATCH`, `PUT`, `DELETE`
path	string	body	Yes	HubSpot API path, must start with `/`. Must start with one of: /crm/, /marketing/, /cms/, /automation/, /files/, /communication-preferences/, /properties/, /owners/, /oauth/.
query	object	body	No	Query string parameters.
body	object	body	No	Request body forwarded as-is (ignored for GET/HEAD).
headers	object	body	No	Caller headers to forward. Only `idempotency-key`, `if-match`, `if-none-match`, and `accept-language` are allowlisted; anything else is dropped.
timeoutMs	number	body	No	Per-call timeout.

Request

{
  "method": "GET",
  "path": "/crm/v3/objects/contacts",
  "query": { "limit": 10 }
}

Response

{
  "status": 200,
  "headers": { "x-hubspot-ratelimit-daily-remaining": "39500" },
  "body": { "results": [...] },
  "meta": {
    "provider": "hubspot",
    "upstreamRequestId": "abc-123",
    "durationMs": 210,
    "rateLimit": { "remaining": 39500 }
  }
}

SDK Example

const raw = await client.hubspot.request({ method: 'GET', path: '/owners/v2/owners' });
// Typed wrappers over this same endpoint:
const page = await client.hubspot.contacts.list({ limit: 10 });

The response envelope is `{ status, headers, body, meta }`, not the `{ success, data }` shape used elsewhere in this API. `status` and `body` mirror HubSpot's actual response.
Errors use `{ error: { code, message }, requestId }` instead of `{ success: false }`. `connection_not_found` and `connection_disconnected` (both 409) mean the org needs to (re)connect HubSpot in the dashboard.
`path` is validated against an allowlist of HubSpot API prefixes; anything else is rejected with 400 (`invalid_path`).
The SDK also exposes typed wrappers over this same endpoint: `client.hubspot.contacts`, `.companies`, `.deals`, `.tasks`, `.notes`.

POST/api/v1.1/crm/salesforce/passthroughSecret keySDK

Salesforce passthrough

Forwards one REST call to the Salesforce API using the org's Nango-managed Salesforce connection. Personize resolves the instance URL and access token, so the caller never handles Salesforce credentials.

Usage: Use this for Salesforce endpoints not covered by the SDK's typed wrappers, or when you want raw control over the request.

SDK: client.salesforce.request(opts)

Parameters

Field	Type	Where	Required	Description
method	string	body	Yes	HTTP method to forward.Options: `GET`, `POST`, `PATCH`, `PUT`, `DELETE`
path	string	body	Yes	Salesforce API path, must start with `/`. Must start with one of: /services/data/, /services/apexrest/.
query	object	body	No	Query string parameters.
body	object	body	No	Request body forwarded as-is (ignored for GET/HEAD).
headers	object	body	No	Caller headers to forward. Only `idempotency-key`, `if-match`, `if-none-match`, and `accept-language` are allowlisted; anything else is dropped.
timeoutMs	number	body	No	Per-call timeout.

Request

{
  "method": "GET",
  "path": "/services/data/v59.0/query",
  "query": { "q": "SELECT Id, Name FROM Account LIMIT 10" }
}

Response

{
  "status": 200,
  "headers": { "sforce-limit-info": "api-usage=15/15000" },
  "body": { "totalSize": 10, "records": [...] },
  "meta": {
    "provider": "salesforce",
    "upstreamRequestId": "abc-123",
    "durationMs": 180,
    "rateLimit": { "remaining": 14985 }
  }
}

SDK Example

const result = await client.salesforce.query('SELECT Id, Name FROM Account LIMIT 10');
for await (const lead of client.salesforce.queryAll('SELECT Id FROM Lead')) { /* ... */ }
await client.salesforce.sobject('Account').create({ Name: 'Acme' });

The response envelope is `{ status, headers, body, meta }`, not the `{ success, data }` shape used elsewhere in this API.
Errors use `{ error: { code, message }, requestId }` instead of `{ success: false }`. `connection_not_found` and `connection_disconnected` (both 409) mean the org needs to (re)connect Salesforce in the dashboard.
`path` is validated against an allowlist of Salesforce API prefixes; anything else is rejected with 400 (`invalid_path`).
The SDK also exposes typed wrappers over this same endpoint: `client.salesforce.query()`, `.queryAll()`, `.sobject(type)`.

POST/api/v1.1/crm/apollo-oauth/passthroughSecret key

Apollo passthrough

Forwards one REST call to the Apollo.io API using the org's Apollo OAuth connection (Nango-managed). Same request, response, and error contract as the HubSpot and Salesforce passthroughs.

Usage: Use this to call Apollo.io endpoints using the org's connected Apollo account, without the caller handling an Apollo API key.

Parameters

Field	Type	Where	Required	Description
method	string	body	Yes	HTTP method to forward.Options: `GET`, `POST`, `PATCH`, `PUT`, `DELETE`
path	string	body	Yes	Apollo API path, must start with `/v1/`.
query	object	body	No	Query string parameters.
body	object	body	No	Request body forwarded as-is (ignored for GET/HEAD).
headers	object	body	No	Caller headers to forward. Only `idempotency-key`, `if-match`, `if-none-match`, and `accept-language` are allowlisted; anything else is dropped.
timeoutMs	number	body	No	Per-call timeout.

Request

{
  "method": "GET",
  "path": "/v1/auth/health"
}

Response

{
  "status": 200,
  "headers": {},
  "body": { "is_logged_in": true },
  "meta": {
    "provider": "apollo-oauth",
    "upstreamRequestId": null,
    "durationMs": 140
  }
}

No SDK wrapper exists for Apollo. There is no `client.apollo.*` namespace; call this endpoint directly over HTTP with your secret key.
The response envelope is `{ status, headers, body, meta }`, not the `{ success, data }` shape used elsewhere in this API.
Errors use `{ error: { code, message }, requestId }` instead of `{ success: false }`. `connection_not_found` and `connection_disconnected` (both 409) mean the org needs to (re)connect Apollo in the dashboard.

5 endpoints

Billing

Look up the platform's per-call credit rates, check the current credit balance from a billing-specific path, and manage low-balance alert thresholds.

GET/api/v1.1/billing/ratesSecret keySDK

Get credit rates

Returns the live, SSM-backed credit rate sheet (per-operation costs) so customers can budget calls without inferring pricing from 402 responses.

Usage: Use this to build cost estimates or a pre-flight budget check before running billable operations.

SDK: client.billing.rates()

Response

{
  "success": true,
  "data": {
    "rates": {
      "version": "...",
      "memorize": { "basic": "...", "pro": "...", "pro_fast": "...", "ultra": "..." },
      "recall": { "fast": "...", "deep": "..." },
      "smartContext": { "fast": "...", "deep": "..." },
      "similar": "...",
      "segment": "...",
      "smartUpdate": "..."
    },
    "memorizeTierConfig": {...},
    "generatedAt": "2026-09-01T00:00:00.000Z",
    "source": "ssm-backed (refreshed every 10 min server-side)"
  }
}

Free to call, no credit deduction.
Response is cached for 5 minutes (`Cache-Control: private, max-age=300`).
BYOK rates are surfaced with a `_byok` suffix on the relevant keys, so you can compare managed vs. BYOK pricing.

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

Credit balance (billing alias)

Alias of the Analytics category's Credit balance endpoint, kept under `/billing/*` because that's where customers look for it. Served by the exact same handler as `GET /analytics/credits`, so the response is identical.

Usage: Use this path if you're already integrating against the billing surface and don't want to also wire up the analytics endpoint for the same data.

SDK: client.billing.credits()

Identical response payload to the Analytics category's Credit balance endpoint (`GET /analytics/credits`); see that entry for the full response shape.
Always free, no credit cost.
Requires `admin`, `member-only`, or `read-only` scope.

POST/api/v1.1/billing/thresholdsSecret keySDK

Create a credit threshold alert

Registers a credit-balance alert threshold. When the org's available credits cross below the given percent, Personize emits a `CreditThresholdCrossed` event delivered to your configured webhook destinations (HMAC-signed).

Usage: Use this to get notified before an org runs out of credits, instead of discovering it from a 402 response.

SDK: client.billing.thresholds.create(input)

Parameters

Field	Type	Where	Required	Description
percent	number	body	Yes	Threshold as a whole-number percent of the credit balance.Range: `1–100`

Request

{ "percent": 20 }

Response

{
  "success": true,
  "data": { "thresholdId": "thr_01j...", "percent": 20, "createdAt": "2026-09-01T00:00:00.000Z" }
}

`percent` must be a whole number (integer) between 1 and 100; other values return 400.
Each threshold fires at most once per billing cycle and resets the next month.
Pair this with `POST /destinations` to set up a webhook receiver for the `CreditThresholdCrossed` event.

GET/api/v1.1/billing/thresholdsSecret keySDK

List credit threshold alerts

Lists the org's registered credit threshold alerts.

Usage: Use this to see what low-balance alerts are currently configured.

SDK: client.billing.thresholds.list()

Response

{
  "success": true,
  "data": {
    "thresholds": [
      { "thresholdId": "thr_01j...", "percent": 20, "createdAt": "2026-09-01T00:00:00.000Z" }
    ],
    "count": 1
  }
}

Thresholds are returned sorted by `percent` descending (highest threshold first).

DELETE/api/v1.1/billing/thresholds/:idSecret keySDK

Delete a credit threshold alert

Unregisters a credit threshold alert.

Usage: Use this to stop getting notified at a threshold you no longer care about.

SDK: client.billing.thresholds.delete(id)

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	The `thresholdId` returned by create or list.

Response

{
  "success": true,
  "message": "Threshold thr_01j... deleted."
}

Deleting a threshold id that doesn't exist still returns 200; the delete is idempotent.

15 endpoints

RAG & Multimodal

Three distinct capabilities that all mount at the router root (no shared path prefix): our own project-scoped document RAG (`/rag/*`), a customer's bring-your-own external RAG backend (`/external-rag/*`), and multimodal image/file memorize + search (`/multimodal/*`). Do not conflate `/rag/*` (our LanceDB-backed store) with `/external-rag/*` (a customer's own RAG service that Personize calls out to).

POST/api/v1.1/rag/ingestSecret keySDK

Ingest documents into a RAG project

Chunks and embeds documents into the org's own RAG project -- a LanceDB-backed store separate from the main memory vector store and from context docs.

Usage: Build a lightweight, project-scoped document index for retrieval-augmented generation without going through the memory/context-doc pipeline.

SDK: client.rag.ingest({ projectId, documents })

Parameters

Field	Type	Where	Required	Description
projectId	string	body	Yes	RAG project to ingest into. Created automatically on first use.
documents	object[]	body	Yes	Non-empty array of `{ id?, text, source?, sourceUrl?, title?, metadata? }`.

Request

{
  "projectId": "proj_docs",
  "documents": [
    { "text": "Our refund policy allows returns within 30 days.", "source": "policy.md", "title": "Refund Policy" }
  ]
}

Response

{ "success": true, "data": { "ingested": 1, "errors": [] } }

No separate "create project" call is needed -- the project table is created on first ingest.
Embeddings use the org's configured embedding service.

POST/api/v1.1/rag/searchSecret keySDK

Search a RAG project

Semantic search over documents ingested into one RAG project.

Usage: Retrieve relevant chunks from a project's own document set for RAG-style generation.

SDK: client.rag.searchProject({ projectId, query, limit, minScore })

Parameters

Field	Type	Where	Required	Description
projectId	string	body	Yes	RAG project to search.
query	string	body	Yes	Search query text.
limit	number	body	No	Max results.Default: `10`
minScore	number	body	No	Minimum similarity score to include.Default: `0`

Request

{ "projectId": "proj_docs", "query": "refund window", "limit": 5 }

Response

{
  "success": true,
  "data": {
    "results": [{ "id": "doc_1", "text": "Our refund policy allows returns within 30 days.", "score": 0.87, "source": "policy.md" }],
    "count": 1
  }
}

GET/api/v1.1/rag/projectsSecret keySDK

List RAG projects

Lists the org's RAG project IDs.

Usage: Discover what projects already exist before ingesting into a new or existing one.

SDK: client.rag.listProjects()

Response

{ "success": true, "data": { "projects": ["proj_docs"], "count": 1 } }

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

Delete documents from a RAG project

Removes specific documents from a RAG project by ID.

Usage: Clean up stale or superseded documents from a project's index.

SDK: client.rag.deleteDocuments({ projectId, documentIds })

Parameters

Field	Type	Where	Required	Description
projectId	string	body	Yes	RAG project the documents belong to.
documentIds	string[]	body	Yes	Document IDs to remove.

Request

{ "projectId": "proj_docs", "documentIds": ["doc_1", "doc_2"] }

Response

{ "success": true, "data": { "deleted": 2 } }

Method is POST despite deleting documents -- there is no DELETE-verb route for this operation.

POST/api/v1.1/rag/delete-projectSecret keySDK

Delete an entire RAG project

Drops the entire underlying table for a RAG project, deleting every document in it.

Usage: Tear down a project that's no longer needed.

SDK: client.rag.deleteProject(projectId)

Parameters

Field	Type	Where	Required	Description
projectId	string	body	Yes	RAG project to delete.

Request

{ "projectId": "proj_docs" }

Response

{ "success": true, "message": "Project proj_docs deleted" }

Irreversible.

GET/api/v1.1/external-rag/configSecret key

Get external RAG config (legacy single connection)

Returns the org's legacy single external-RAG connection config with the API key masked, or `{ configured: false }` if none is set.

Usage: Check the currently active external RAG connection before querying or updating it.

Response

{
  "success": true,
  "data": {
    "configured": true,
    "url": "https://partner.example.com/rag",
    "enabled": true,
    "timeout": 10000,
    "maxResults": 10,
    "apiKey": "sk-a...1234"
  }
}

Legacy single-connection surface -- prefer the named-connection endpoints (`GET/POST /external-rag/configs`, `DELETE /external-rag/configs/:name`) for new integrations, which support multiple simultaneous external RAG backends.

POST/api/v1.1/external-rag/configSecret keySDK

Set external RAG config (legacy single connection)

Configures the org's legacy single external-RAG connection (stored under the name `default`).

Usage: Point Personize at a customer-hosted RAG backend so `/external-rag/search` and the unified retrieve engine can query it.

SDK: client.rag.configure({ url, apiKey, timeout, maxResults })

Parameters

Field	Type	Where	Required	Description
url	string	body	Yes	Base URL of the external RAG service (must expose `/search` and `/health`).
apiKey	string	body	Yes	Bearer token sent as `Authorization: Bearer <apiKey>` to the external service.
timeout	number	body	No	Request timeout in ms.
maxResults	number	body	No	Default result cap for this connection.

Request

{ "url": "https://partner.example.com/rag", "apiKey": "sk-partner-key", "timeout": 10000, "maxResults": 10 }

Response

{ "success": true, "data": { "configured": true } }

Always sets `enabled: true`.
For multiple named connections use `POST /external-rag/configs` instead.

GET/api/v1.1/external-rag/configsSecret keySDK

List named external RAG connections

Lists all of the org's named external RAG connections (Phase 1.x multi-RAG), API keys masked. Includes the legacy single-config row as `name: "default"` if one is set.

Usage: Discover which external RAG connections are configured, for example before filtering the unified retrieve endpoint to specific `connectionNames`.

SDK: client.externalRag.listConfigs()

Response

{
  "success": true,
  "data": {
    "count": 1,
    "configs": [{ "name": "partner-kb", "description": "Partner knowledge base", "url": "https://partner.example.com/rag", "enabled": true, "timeout": 10000, "maxResults": 10, "apiKey": "sk-p...5678" }]
  }
}

POST/api/v1.1/external-rag/configsSecret keySDK

Create or update a named external RAG connection

Creates or updates one named external RAG connection, independent of the legacy single-config row. Companion CRUD for the unified retrieve endpoint's per-source fan-out.

Usage: Register multiple external RAG backends and address them individually via `intent.perSource.external.connectionNames` on the unified retrieve endpoint.

SDK: client.externalRag.saveConfig(config)

Parameters

Field	Type	Where	Required	Description
name	string	body	Yes	Connection name, must match `[a-z0-9][a-z0-9_-]{0,63}` (case-insensitive).
url	string	body	Yes	Base URL of the external RAG service.
apiKey	string	body	Yes	Bearer token for the external service.
enabled	boolean	body	No	Whether this connection is active.Default: `true`
timeout	number	body	No	Request timeout in ms.
maxResults	number	body	No	Default result cap.
description	string	body	No	Human-readable label for this connection.

Request

{ "name": "partner-kb", "url": "https://partner.example.com/rag", "apiKey": "sk-partner-key", "description": "Partner knowledge base" }

Response

{ "success": true, "data": { "name": "partner-kb", "configured": true } }

400 if `name` doesn't match `[a-z0-9][a-z0-9_-]{0,63}` (case-insensitive).
If calling via `client.externalRag.saveConfig()`: the SDK's `ExternalRAGNamedConfig` TypeScript type declares field names (`endpointUrl`, `headers`, `timeoutMs`) that this route does NOT read -- the server only reads `url` / `apiKey` / `timeout` / `maxResults` / `description` as documented above. Construct the request body with those field names rather than relying on the SDK type verbatim, or the call fails with 400 ("url is required").

DELETE/api/v1.1/external-rag/configs/:nameSecret keySDK

Delete a named external RAG connection

Removes one named external RAG connection.

Usage: Decommission an external RAG backend that's no longer in use.

SDK: client.externalRag.deleteConfig(name)

Parameters

Field	Type	Where	Required	Description
name	string	path	Yes	Connection name to delete.

Response

{ "success": true, "data": { "name": "partner-kb", "deleted": true } }

POST/api/v1.1/external-rag/searchSecret keySDK

Search the external RAG backend

Directly queries the org's configured external RAG backend -- the legacy single (`default`) config set via `POST /external-rag/config`.

Usage: Query a customer's own RAG service directly, outside of the unified retrieve fan-out.

SDK: client.rag.search({ query, limit, context })

Parameters

Field	Type	Where	Required	Description
query	string	body	Yes	Search query text.
limit	number	body	No	Max results.Default: `10`
context	object	body	No	Optional `{ recordId?, type? }` passed through to the external service for context-aware search.

Request

{ "query": "refund policy for enterprise plan", "limit": 5 }

Response

{
  "success": true,
  "data": {
    "results": [{ "text": "Enterprise plans get a 60-day refund window.", "score": 0.9, "source": "partner-kb", "url": "https://partner.example.com/docs/refunds" }],
    "count": 1
  }
}

400 if no external RAG config is set, or the config is disabled -- set one first via `POST /external-rag/config`.
Queries the single legacy config, not a specific named connection from `/external-rag/configs`.

POST/api/v1.1/external-rag/testSecret keySDK

Test the external RAG connection

Health-checks the org's configured external RAG endpoint.

Usage: Verify connectivity and latency to a customer's RAG backend before relying on it in production.

SDK: client.rag.test()

Response

{ "success": true, "data": { "healthy": true, "latencyMs": 142 } }

400 if no external RAG config is set.
5-second timeout on the health probe; returns `healthy: false` on any failure or timeout rather than erroring.

POST/api/v1.1/multimodal/memorizeSecret keySDK

Memorize an image or file

Stores an image/document attachment against a record: uploads the original file to S3, generates a multimodal embedding, and (if no `content` is supplied) has an LLM write a short text description for text-search compatibility.

Usage: Make an image or file attachment findable through the same search surface as text memories.

SDK: client.multimodal.memorize({ recordId, type, attachment, mimeType, content })

Parameters

Field	Type	Where	Required	Description
recordId	string	body	Yes	Record to associate the attachment with.
attachment	string	body	Yes	Base64-encoded file content.
mimeType	string	body	Yes	MIME type of the attachment, e.g. `image/png`.
type	string	body	No	Attachment category label.Default: `attachment`
content	string	body	No	Pre-written text description. If omitted, one is generated by an LLM.

Request

{ "recordId": "rec_abc123", "attachment": "<base64>", "mimeType": "image/png" }

Response

{
  "success": true,
  "data": {
    "stored": true,
    "sourceUrl": "s3://bucket/multimodal/org_abc123/rec_abc123/1735689600000.png",
    "dimensions": 1024,
    "provider": "openai",
    "textDescription": "A screenshot of a pricing table with three tiers."
  }
}

Gated behind `MULTIMODAL_ENABLED=true` -- returns 400 if the feature isn't enabled for this deployment.
Marked `@internal` in the SDK: not part of the public surface yet -- image similarity search currently falls back to text-only matching against the generated description.

POST/api/v1.1/multimodal/searchSecret keySDK

Search multimodal attachments

Searches multimodal-tagged entries. Currently falls back to text-only matching against the description generated at memorize time -- real vector image-similarity search (`mm_vector`) is not yet implemented.

Usage: Find previously memorized images/files by description text.

SDK: client.multimodal.search({ image, mimeType, query, limit })

Parameters

Field	Type	Where	Required	Description
image	string	body	No	Base64-encoded query image. Either `image` or `query` is required.
query	string	body	No	Text query. Either `image` or `query` is required.
limit	number	body	No	Max results.Default: `10`

Request

{ "query": "pricing table screenshot", "limit": 5 }

Response

{
  "success": true,
  "data": {
    "results": [{ "recordId": "rec_abc123", "score": 0.81, "text": "A screenshot of a pricing table with three tiers.", "sourceUrl": "s3://bucket/multimodal/org_abc123/rec_abc123/1735689600000.png", "mimeType": "image/png" }],
    "count": 1
  }
}

Falls back to a generic text query ("multimodal attachment") when neither a usable `query` nor `image` is available -- full `mm_vector` similarity search is not yet implemented.

GET/api/v1.1/multimodal/statusSecret keySDK

Check multimodal feature status

Reports whether multimodal embedding is enabled for this deployment, and if so which provider/model/dimension it uses.

Usage: Check this before calling memorize/search -- both return 400 when multimodal is disabled.

SDK: client.multimodal.status()

Response

{
  "success": true,
  "data": { "enabled": true, "provider": "openai", "model": "...", "dimensions": 1024 }
}

When disabled: `{ "success": true, "data": { "enabled": false, "message": "Multimodal not enabled. Set MULTIMODAL_ENABLED=true." } } `.

4 endpoints

Setup Kits

Browse the catalog of pre-packaged setup kits, install a kit (or your own manifest) into the organization attached to your key, poll the install, and export your organization's setup as a kit manifest.

GET/api/v1.1/kitsSecret keySDK

List kits

Returns the catalog of available setup kits.

Usage: Use this to find the `kitId` to pass to the install endpoint.

SDK: client.kits.list()

Response

{
  "success": true,
  "data": [
    {
      "id": "personize-starter",
      "name": "...",
      "version": "...",
      "author": "...",
      "description": "..."
    }
  ]
}

SDK Example

const result = await client.kits.list();
console.log(result.data);

Requires `admin`, `member-only`, or `read-only` scope.

POST/api/v1.1/kitsSecret keySDK

Install a kit

Starts installing a kit into the organization attached to the API key. Pass either a catalog `kitId` or an inline `manifest`. The install runs in the background: the call returns `202` with an `installId` that you poll with the install status endpoint.

Usage: Use this to provision a ready-made setup, or to replay a manifest you exported from another organization.

SDK: client.kits.install()

Parameters

Field	Type	Where	Required	Description
kitId	string	body	No	ID of a catalog kit from the list endpoint (for example `personize-starter`). Provide exactly one of `kitId` or `manifest`.
manifest	object	body	No	Inline kit manifest, for example the `data` returned by the export endpoint. Provide exactly one of `kitId` or `manifest`.
overwriteEdits	boolean	body	No	When `false`, guidelines your organization has edited since the last kit install are kept. When `true`, edited guidelines are replaced with the kit's version. Any non-boolean value returns `400`.Default: `false`

Request

{
  "kitId": "personize-starter",
  "overwriteEdits": false
}

Response

{
  "success": true,
  "installId": "inst_abc123",
  "status": "pending",
  "message": "Kit install started. Poll GET /api/v1/kits/inst_abc123."
}

SDK Example

const started = await client.kits.install({ kitId: 'personize-starter' });
const status = await client.kits.getInstallStatus(started.installId);

Requires an `admin` or `member-only` key; `read-only` keys cannot install.
Returns `400` when neither `kitId` nor `manifest` is provided, when `overwriteEdits` is not a boolean (`Validation Error`), or when the kit cannot be resolved or is invalid (`Invalid Kit`).
Reinstalling a kit is safe: guidelines your organization edited are left alone and reported with the `kept_edits` outcome, while guidelines you have not edited are updated to the kit's current text. Set `overwriteEdits: true` to replace the edited ones too.
Per-resource `outcome` values in the install record are `created`, `updated`, `skipped`, `failed`, `conflict`, and `kept_edits`.

GET/api/v1.1/kits/:installIdSecret keySDK

Get install status

Returns the install record for a kit install started by your organization, including the overall status and a result for each resource.

Usage: Poll this after starting an install until `status` is `completed`, `completed_with_errors`, or `failed`.

SDK: client.kits.getInstallStatus()

Parameters

Field	Type	Where	Required	Description
installId	string	path	Yes	The `installId` returned by the install endpoint.

Response

{
  "success": true,
  "data": {
    "organizationId": "org_123",
    "installId": "inst_abc123",
    "kitId": "personize-starter",
    "version": "...",
    "status": "completed",
    "startedAt": "2026-09-01T00:00:00.000Z",
    "finishedAt": "2026-09-01T00:00:30.000Z",
    "results": [
      { "resourceType": "...", "slug": "...", "outcome": "created" },
      { "resourceType": "...", "slug": "...", "outcome": "kept_edits", "message": "..." }
    ]
  }
}

SDK Example

const record = await client.kits.getInstallStatus('inst_abc123');
console.log(record.data.status, record.data.results);

`status` is one of `pending`, `tailoring`, `running`, `completed`, `completed_with_errors`, `failed`.
Each `results[].outcome` is one of `created`, `updated`, `skipped`, `failed`, `conflict`, `kept_edits`.
Returns `404` when the install does not exist for your organization.
Requires `admin`, `member-only`, or `read-only` scope.

GET/api/v1.1/kits/exportSecret keySDK

Export setup as a kit

Exports the setup of the organization attached to the API key as a kit manifest. The organization comes from the key only.

Usage: Use this to snapshot a setup and replay it into another organization by passing `data` to the install endpoint as `{ manifest }`.

SDK: client.kits.export()

Response

{
  "success": true,
  "data": { "...": "kit manifest" },
  "meta": {
    "skipped": [
      { "section": "...", "reason": "..." }
    ]
  }
}

SDK Example

const exported = await client.kits.export();
await client.kits.install({ manifest: exported.data });

Admin keys only; other scopes are rejected.
`meta.skipped` lists any sections left out of the export, each with a reason.
`data` can be passed to the install endpoint as `{ manifest }`.