API Reference

Build against the Personize API with endpoint-level detail.

46 public routes across memory, prompts, governance, agents, and key management. SDK-backed endpoints are marked.

Quickstart

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

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

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

This public reference covers external secret-key routes only.

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/testSecret keySDK

Authentication test

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

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

SDK: client.test()

Response

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

SDK Example

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

GET/api/v1/meSecret keySDK

Current context

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

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

SDK: client.me()

Response

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

SDK Example

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

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

5 endpoints

AI And Async

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

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

Smart guidelines

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

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

SDK: client.ai.smartGuidelines()

Parameters

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

Request

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

Response

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

SDK Example

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

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

POST/api/v1/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/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/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/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
  }
}

7 endpoints

Memory

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

POST/api/v1/memorizeSecret keySDK

Memorize content

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

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

SDK: client.memory.memorize()

Parameters

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

Request

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

Response

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

SDK Example

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

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

POST/api/v1/smart-recallSecret keySDK

Smart recall

Runs RAG-style retrieval with reflection and answer assembly.

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

SDK: client.memory.smartRecall()

Parameters

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

Request

{
  "query": "What do we know about Acme's buying timeline?",
  "mode": "deep",
  "websiteUrl": "https://acme.com",
  "limit": 5
}

Response

{
  "success": true,
  "data": {
    "answer": "Based on available context, Acme's budget review is expected in Q2.",
    "query": "What do we know about Acme's buying timeline?",
    "results": [
      {
        "text": "Budget review expected in Q2.",
        "score": 0.93,
        "recordId": "company_acme",
        "createdAt": "2026-03-10T08:00:00.000Z"
      }
    ]
  }
}

SDK Example

const result = await client.memory.smartRecall({
  query: "What do we know about Acme's buying timeline?",
  mode: "deep",
  websiteUrl: "https://acme.com",
  limit: 5,
});
console.log(result.data.answer);

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

POST/api/v1/searchSecret keySDK

Search records

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

Usage: Use this to build exports, segmentation views, or operational record searches.

SDK: client.memory.search()

Parameters

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

Request

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

Response

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

SDK Example

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

POST/api/v1/recallSecret keySDK

Direct recall

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

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

SDK: client.memory.recall()

Parameters

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

Request

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

Response

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

SDK Example

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

POST/api/v1/batch-memorizeSecret keySDK

Batch memorize

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

Usage: Use this for imports from CRMs, warehouses, or spreadsheets.

SDK: client.memory.memorizeBatch()

Parameters

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

Request

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

Response

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

SDK Example

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

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

Smart memory digest

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

Usage: Use this to hydrate an agent, workspace, or UI with the most relevant customer context in one call.

SDK: client.memory.smartDigest()

Parameters

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

Request

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

Response

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

SDK Example

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

POST/api/v1/propertiesSecret keySDK

Get record properties

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

Usage: Use this to read specific property values and understand which properties can be replaced vs appended to.

SDK: client.memory.properties()

Parameters

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

Request

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

Response

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

SDK Example

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

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

8 endpoints

Memory CRUD

Update, audit, and delete memories or record properties with version guards, array operations, and recovery support.

POST/api/v1/memory/updateSecret keySDK

Single update

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

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

SDK: client.memory.update()

Parameters

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

Request

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

Response

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

SDK Example

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

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

Bulk property update

Updates multiple properties on one record in a single request.

Usage: Use this when you need coordinated property changes guarded by one version check.

SDK: client.memory.bulkUpdate()

Parameters

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

Request

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

Response

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

SDK Example

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

POST/api/v1/memory/deleteSecret keySDK

Delete memories

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

Usage: Use this for cleanup and privacy workflows while keeping the recovery window available.

SDK: client.memory.delete()

Parameters

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

Request

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

Response

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

SDK Example

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

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

Delete a record

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

Usage: Use this for entity-level privacy deletion requests.

SDK: client.memory.deleteRecord()

Parameters

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

Request

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

Response

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

SDK Example

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

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

Cancel deletion

Restores a soft-deleted record within the recovery window.

Usage: Use this when a deletion was triggered by mistake and the record should be restored.

SDK: client.memory.cancelDeletion()

Parameters

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

Request

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

Response

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

SDK Example

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

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

Property history

Fetches a paginated history of property changes for one record.

Usage: Use this for audit trails, debugging, and change review interfaces.

SDK: client.memory.propertyHistory()

Parameters

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

Request

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

Response

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

SDK Example

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

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

Natural-language property query

Searches one property across records using natural-language matching.

Usage: Use this when deterministic operators are too rigid and you need semantic matching on one field.

SDK: client.memory.queryProperties()

Parameters

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

Request

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

Response

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

SDK Example

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

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

Deterministic property filter

Filters records with explicit property operators and pagination.

Usage: Use this when you want exact field filtering with no LLM involvement.

SDK: client.memory.filterByProperty()

Parameters

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

Request

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

Response

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

SDK Example

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

13 endpoints

Governance And Schema

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

GET/api/v1/guidelinesSecret keySDK

List guidelines

Lists guidelines with pagination and tag-based filters.

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

SDK: client.guidelines.list()

Parameters

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

Response

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

SDK Example

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

POST/api/v1/guidelinesSecret keySDK

Create a guideline

Creates a new guideline or governance variable.

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

SDK: client.guidelines.create()

Parameters

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

Request

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

Response

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

SDK Example

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

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

Guideline heading structure

Returns the extracted markdown headings for one guideline.

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

SDK: client.guidelines.getStructure()

Parameters

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

Response

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

SDK Example

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

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

Guideline section content

Returns the content under a specific heading inside a guideline.

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

SDK: client.guidelines.getSection()

Parameters

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

Response

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

SDK Example

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

PATCH/api/v1/guidelines/:idSecret keySDK

Update a guideline

Partially updates guideline metadata or content.

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

SDK: client.guidelines.update()

Parameters

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

Request

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

Response

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

SDK Example

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

DELETE/api/v1/guidelines/:idSecret keySDK

Delete a guideline

Deletes a guideline by ID.

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

SDK: client.guidelines.delete()

Parameters

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

Response

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

SDK Example

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

GET/api/v1/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/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/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/collectionsSecret keySDK

Create a collection

Creates a collection and optionally seeds its property schema.

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	No	Canonical collection name.
name	string	body	No	SDK alias for `collectionName`.
collectionId	string	body	No	Optional custom ID.
definition	string	body	No	Description or extraction instructions.
entityType	string	body	No	Entity type such as `Contact` or `Company`.
properties	object[]	body	No	Initial property definitions.

Request

{
  "collectionName": "Contact Properties",
  "entityType": "Contact",
  "definition": "Customer profile fields for GTM workflows",
  "properties": [
    {
      "propertyName": "Lifecycle Stage",
      "type": "text",
      "description": "Current funnel stage"
    }
  ]
}

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: "text", description: "Current funnel stage" },
  ],
});
console.log(result.data.id);

PATCH/api/v1/collections/:idSecret keySDK

Update a collection

Updates collection metadata or property definitions.

Usage: Use this to evolve schemas without recreating the collection.

SDK: client.collections.update()

Parameters

Field	Type	Where	Required	Description
id	string	path	Yes	Collection ID.
collectionName	string	body	No	Updated display name.
definition	string	body	No	Updated instructions.
properties	object[]	body	No	Updated property definitions.
historyNote	string	body	No	Human-readable change note.

Request

{
  "definition": "Customer profile fields for GTM and success workflows",
  "historyNote": "Expanded collection scope"
}

Response

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

SDK Example

const result = await client.collections.update("col_contact", {
  definition: "Customer profile fields for GTM and success workflows",
});
console.log(result.data.updated);

DELETE/api/v1/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/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);

4 endpoints

Agents And Evaluation

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

GET/api/v1/agentsSecret keySDK

List agents

Lists available agents for the current organization.

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

SDK: client.agents.list()

Parameters

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

Response

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

SDK Example

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

GET/api/v1/agents/:idSecret keySDK

Get agent details

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

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

SDK: client.agents.get()

Parameters

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

Response

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

SDK Example

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

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

Run an agent

Executes an agent by ID and optionally streams its output.

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

SDK: client.agents.run()

Parameters

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

Request

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

Response

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

SDK Example

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

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

POST/api/v1/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/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/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/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/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/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/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/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.