Reference Portal

AI Memory Docs

REST routes, WebSocket events, MCP tools, discovery metadata, and error handling in one compact surface for humans and autonomous agents.

Quickstart REST API WebSocket MCP OpenAPI JSON

REST routes

WS events

MCP tools

Domains

Connection map

Know the entry points

Live

REST Bearer


                  https://ai-memory.shop/api/v1

WebSocket Phoenix


                  https://ai-memory.shop/socket

MCP JSON-RPC


                  https://ai-memory.shop/mcp

Reference request

HTTP

POST https://ai-memory.shop/api/v1/memories HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

Reference

Overview

Everything exposed by the application is organized by interface and grouped by real router domains.

REST API

Public endpoints for memories, search, billing, documents, broker flows, and agent onboarding.

WebSocket

One authenticated Phoenix socket and one organization topic for memory and workflow events.

MCP

Machine-readable tool schemas for model-driven clients using JSON-RPC 2.0.

Application coverage

All public router groups appear below.

Agents 1 Billing 7 Clients 9 Deadlines 9 Deals 24 Document templates 9 Documents 13 Memories 9 Search 1

REST docs and OpenAPI paths are generated from the router, while WebSocket and MCP inventories are sourced from live application modules to reduce drift.

Reference

Quickstart

Two lanes for the same platform: portal-first setup for humans and self-serve onboarding for autonomous agents.

Human lane

Portal + REST

Fastest start

Create an account, mint an API key, store data over REST, then subscribe to real-time updates if your UI needs live state.

/signup /portal/api-keys See live events

Step 1

Create an account and issue a Bearer API key from the portal.

Step 2

Store a memory, then expand into search and document workflows from the REST catalog.

HTTP

POST https://ai-memory.shop/api/v1/memories HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{
  "title": "Onboarding Complete",
  "content": "User completed onboarding",
  "entities": [
    {
      "name": "John Doe",
      "type": "user",
      "external_id": "user_123"
    }
  ],
  "memory_type": "episodic"
}

Agent lane

Self-serve onboarding

Robot ready

Agents can register themselves, inspect discovery metadata, call MCP tools, and upgrade usage programmatically.

/for-agents MCP tools Schema

Step 1

HTTP

POST https://ai-memory.shop/api/v1/agents/register HTTP/1.1
Accept: application/json
Content-Type: application/json

JSON body

JSON

{
  "agent_name": "MyAutonomousAgent",
  "capabilities": [
    "memory_storage",
    "semantic_search"
  ],
  "contact_email": "agent@example.com"
}

Step 2

Move to billing when the agent needs plan capacity or direct crypto settlement instructions.

HTTP

POST https://ai-memory.shop/api/v1/billing/checkout HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{
  "plan_id": "{plan_uuid}",
  "flow": "direct_payment",
  "pay_currency": "eth"
}

Reference

REST API

The full public HTTP surface, grouped by domain and rendered from the router so the catalog stays current.

Base URL


                        https://ai-memory.shop/api/v1

Authentication

Send a Bearer API key in the Authorization header.

/api/v1/openapi.json `/api/v1/docs` redirects here

Filter endpoints

Endpoints

Domains

Agents 1 Billing 7 Clients 9 Deadlines 9 Deals 24 Document templates 9 Documents 13 Memories 9 Search 1

Agents

Public routes in the agents domain.

1 routes

POST

Register Agent

/api/v1/agents/register

Create an organization and API key for an autonomous agent (rate limited).

Auth: Bearer Rate limited AgentsController.register

▸

HTTP

POST https://ai-memory.shop/api/v1/agents/register HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{
  "agent_name": "MyAutonomousAgent",
  "callback_url": "https://example.com/callback",
  "capabilities": [
    "memory_storage",
    "semantic_search"
  ],
  "contact_email": "agent@example.com"
}

Success (shape)

JSON

{
  "data": {
    "message": "Welcome, agent! You can now create memories and upgrade your plan.",
    "api_key": "aim_agent_...",
    "organization_id": "org_123",
    "api_docs": "{base_url}/api/v1/openapi.json",
    "mcp_endpoint": "{base_url}/mcp"
  }
}

Billing

Public routes in the billing domain.

7 routes

POST

BillingController.cancel_subscription

/api/v1/billing/cancel

Handled by AiMemoryWeb.Controllers.Api.V1.BillingController#cancel_subscription.

Auth: Bearer Rate limited BillingController.cancel_subscription

▸

HTTP

POST https://ai-memory.shop/api/v1/billing/cancel HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

POST

Create Billing Checkout

/api/v1/billing/checkout

Create a hosted invoice for humans or direct wallet instructions for robots.

Auth: Bearer Rate limited BillingController.create_checkout

▸

HTTP

POST https://ai-memory.shop/api/v1/billing/checkout HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{
  "plan_id": "{plan_uuid}",
  "flow": "direct_payment",
  "pay_currency": "eth"
}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

BillingController.list_plans

/api/v1/billing/plans

Handled by AiMemoryWeb.Controllers.Api.V1.BillingController#list_plans.

Auth: Bearer Rate limited BillingController.list_plans

▸

HTTP

GET https://ai-memory.shop/api/v1/billing/plans HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

GET

BillingController.portal

/api/v1/billing/portal

Handled by AiMemoryWeb.Controllers.Api.V1.BillingController#portal.

Auth: Bearer Rate limited BillingController.portal

▸

HTTP

GET https://ai-memory.shop/api/v1/billing/portal HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

GET

BillingController.status

/api/v1/billing/status

Handled by AiMemoryWeb.Controllers.Api.V1.BillingController#status.

Auth: Bearer Rate limited BillingController.status

▸

HTTP

GET https://ai-memory.shop/api/v1/billing/status HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

GET

BillingController.subscription

/api/v1/billing/subscription

Handled by AiMemoryWeb.Controllers.Api.V1.BillingController#subscription.

Auth: Bearer Rate limited BillingController.subscription

▸

HTTP

GET https://ai-memory.shop/api/v1/billing/subscription HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

GET

BillingController.transaction

/api/v1/billing/transactions/:order_id

Handled by AiMemoryWeb.Controllers.Api.V1.BillingController#transaction.

Auth: Bearer Rate limited BillingController.transaction Path params: order_id

▸

HTTP

GET https://ai-memory.shop/api/v1/billing/transactions/:order_id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

Clients

Public routes in the clients domain.

9 routes

GET

ClientInteractionController.index

/api/v1/clients/:entity_id/interactions

Handled by AiMemoryWeb.Controllers.Api.V1.ClientInteractionController#index.

Auth: Bearer Rate limited ClientInteractionController.index Path params: entity_id

▸

HTTP

GET https://ai-memory.shop/api/v1/clients/:entity_id/interactions HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

POST

ClientInteractionController.create

/api/v1/clients/:entity_id/interactions

Handled by AiMemoryWeb.Controllers.Api.V1.ClientInteractionController#create.

Auth: Bearer Rate limited ClientInteractionController.create Path params: entity_id

▸

HTTP

POST https://ai-memory.shop/api/v1/clients/:entity_id/interactions HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

ClientInteractionController.stats

/api/v1/clients/:entity_id/interactions/stats

Handled by AiMemoryWeb.Controllers.Api.V1.ClientInteractionController#stats.

Auth: Bearer Rate limited ClientInteractionController.stats Path params: entity_id

▸

HTTP

GET https://ai-memory.shop/api/v1/clients/:entity_id/interactions/stats HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

GET

ClientInteractionController.profile

/api/v1/clients/:entity_id/profile

Handled by AiMemoryWeb.Controllers.Api.V1.ClientInteractionController#profile.

Auth: Bearer Rate limited ClientInteractionController.profile Path params: entity_id

▸

HTTP

GET https://ai-memory.shop/api/v1/clients/:entity_id/profile HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

POST

ClientInteractionController.analyze_sentiment

/api/v1/clients/analyze-sentiment

Handled by AiMemoryWeb.Controllers.Api.V1.ClientInteractionController#analyze_sentiment.

Auth: Bearer Rate limited ClientInteractionController.analyze_sentiment

▸

HTTP

POST https://ai-memory.shop/api/v1/clients/analyze-sentiment HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

ClientInteractionController.pending_follow_ups

/api/v1/clients/follow-ups

Handled by AiMemoryWeb.Controllers.Api.V1.ClientInteractionController#pending_follow_ups.

Auth: Bearer Rate limited ClientInteractionController.pending_follow_ups

▸

HTTP

GET https://ai-memory.shop/api/v1/clients/follow-ups HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

DELETE

ClientInteractionController.delete

/api/v1/clients/interactions/:id

Handled by AiMemoryWeb.Controllers.Api.V1.ClientInteractionController#delete.

Auth: Bearer Rate limited ClientInteractionController.delete Path params: id

▸

HTTP

DELETE https://ai-memory.shop/api/v1/clients/interactions/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "deleted": true
  }
}

GET

ClientInteractionController.show

/api/v1/clients/interactions/:id

Handled by AiMemoryWeb.Controllers.Api.V1.ClientInteractionController#show.

Auth: Bearer Rate limited ClientInteractionController.show Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/clients/interactions/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

PUT

ClientInteractionController.update

/api/v1/clients/interactions/:id

Handled by AiMemoryWeb.Controllers.Api.V1.ClientInteractionController#update.

Auth: Bearer Rate limited ClientInteractionController.update Path params: id

▸

HTTP

PUT https://ai-memory.shop/api/v1/clients/interactions/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

Deadlines

Public routes in the deadlines domain.

9 routes

GET

DeadlineController.index

/api/v1/deadlines

Handled by AiMemoryWeb.Controllers.Api.V1.DeadlineController#index.

Auth: Bearer Rate limited DeadlineController.index

▸

HTTP

GET https://ai-memory.shop/api/v1/deadlines HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

POST

DeadlineController.create

/api/v1/deadlines

Handled by AiMemoryWeb.Controllers.Api.V1.DeadlineController#create.

Auth: Bearer Rate limited DeadlineController.create

▸

HTTP

POST https://ai-memory.shop/api/v1/deadlines HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

DeadlineController.show

/api/v1/deadlines/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DeadlineController#show.

Auth: Bearer Rate limited DeadlineController.show Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/deadlines/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

PUT

DeadlineController.update

/api/v1/deadlines/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DeadlineController#update.

Auth: Bearer Rate limited DeadlineController.update Path params: id

▸

HTTP

PUT https://ai-memory.shop/api/v1/deadlines/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

POST

DeadlineController.complete

/api/v1/deadlines/:id/complete

Handled by AiMemoryWeb.Controllers.Api.V1.DeadlineController#complete.

Auth: Bearer Rate limited DeadlineController.complete Path params: id

▸

HTTP

POST https://ai-memory.shop/api/v1/deadlines/:id/complete HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

DeadlineController.overdue

/api/v1/deadlines/overdue

Handled by AiMemoryWeb.Controllers.Api.V1.DeadlineController#overdue.

Auth: Bearer Rate limited DeadlineController.overdue

▸

HTTP

GET https://ai-memory.shop/api/v1/deadlines/overdue HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

GET

DeadlineController.list_reminders

/api/v1/deadlines/reminders

Handled by AiMemoryWeb.Controllers.Api.V1.DeadlineController#list_reminders.

Auth: Bearer Rate limited DeadlineController.list_reminders

▸

HTTP

GET https://ai-memory.shop/api/v1/deadlines/reminders HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

POST

DeadlineController.dismiss_reminder

/api/v1/deadlines/reminders/:id/dismiss

Handled by AiMemoryWeb.Controllers.Api.V1.DeadlineController#dismiss_reminder.

Auth: Bearer Rate limited DeadlineController.dismiss_reminder Path params: id

▸

HTTP

POST https://ai-memory.shop/api/v1/deadlines/reminders/:id/dismiss HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

DeadlineController.upcoming

/api/v1/deadlines/upcoming

Handled by AiMemoryWeb.Controllers.Api.V1.DeadlineController#upcoming.

Auth: Bearer Rate limited DeadlineController.upcoming

▸

HTTP

GET https://ai-memory.shop/api/v1/deadlines/upcoming HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

Deals

Public routes in the deals domain.

24 routes

GET

DealController.index

/api/v1/deals

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#index.

Auth: Bearer Rate limited DealController.index

▸

HTTP

GET https://ai-memory.shop/api/v1/deals HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

POST

DealController.create

/api/v1/deals

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#create.

Auth: Bearer Rate limited DealController.create

▸

HTTP

POST https://ai-memory.shop/api/v1/deals HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

DELETE

DealController.delete

/api/v1/deals/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#delete.

Auth: Bearer Rate limited DealController.delete Path params: id

▸

HTTP

DELETE https://ai-memory.shop/api/v1/deals/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "deleted": true
  }
}

GET

DealController.show

/api/v1/deals/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#show.

Auth: Bearer Rate limited DealController.show Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/deals/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

PATCH

DealController.update

/api/v1/deals/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#update.

Auth: Bearer Rate limited DealController.update Path params: id

▸

HTTP

PATCH https://ai-memory.shop/api/v1/deals/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

PUT

DealController.update

/api/v1/deals/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#update.

Auth: Bearer Rate limited DealController.update Path params: id

▸

HTTP

PUT https://ai-memory.shop/api/v1/deals/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

POST

DealController.close

/api/v1/deals/:id/close

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#close.

Auth: Bearer Rate limited DealController.close Path params: id

▸

HTTP

POST https://ai-memory.shop/api/v1/deals/:id/close HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

DealController.list_commission_splits

/api/v1/deals/:id/commission

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#list_commission_splits.

Auth: Bearer Rate limited DealController.list_commission_splits Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/deals/:id/commission HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

POST

DealController.create_commission_split

/api/v1/deals/:id/commission

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#create_commission_split.

Auth: Bearer Rate limited DealController.create_commission_split Path params: id

▸

HTTP

POST https://ai-memory.shop/api/v1/deals/:id/commission HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

DealController.compliance

/api/v1/deals/:id/compliance

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#compliance.

Auth: Bearer Rate limited DealController.compliance Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/deals/:id/compliance HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

POST

DealController.attach_document

/api/v1/deals/:id/documents

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#attach_document.

Auth: Bearer Rate limited DealController.attach_document Path params: id

▸

HTTP

POST https://ai-memory.shop/api/v1/deals/:id/documents HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

DealController.intelligence

/api/v1/deals/:id/intelligence

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#intelligence.

Auth: Bearer Rate limited DealController.intelligence Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/deals/:id/intelligence HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

POST

DealController.create_milestone

/api/v1/deals/:id/milestones

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#create_milestone.

Auth: Bearer Rate limited DealController.create_milestone Path params: id

▸

HTTP

POST https://ai-memory.shop/api/v1/deals/:id/milestones HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

POST

DealController.complete_milestone

/api/v1/deals/:id/milestones/:milestone_id/complete

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#complete_milestone.

Auth: Bearer Rate limited DealController.complete_milestone Path params: id, milestone_id

▸

HTTP

POST https://ai-memory.shop/api/v1/deals/:id/milestones/:milestone_id/complete HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

DealController.next_actions

/api/v1/deals/:id/next-actions

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#next_actions.

Auth: Bearer Rate limited DealController.next_actions Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/deals/:id/next-actions HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

GET

DealController.risk_assessment

/api/v1/deals/:id/risks

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#risk_assessment.

Auth: Bearer Rate limited DealController.risk_assessment Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/deals/:id/risks HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

PUT

DealController.update_stage

/api/v1/deals/:id/stage

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#update_stage.

Auth: Bearer Rate limited DealController.update_stage Path params: id

▸

HTTP

PUT https://ai-memory.shop/api/v1/deals/:id/stage HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

POST

DealController.add_stakeholder

/api/v1/deals/:id/stakeholders

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#add_stakeholder.

Auth: Bearer Rate limited DealController.add_stakeholder Path params: id

▸

HTTP

POST https://ai-memory.shop/api/v1/deals/:id/stakeholders HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

DELETE

DealController.remove_stakeholder

/api/v1/deals/:id/stakeholders/:entity_id

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#remove_stakeholder.

Auth: Bearer Rate limited DealController.remove_stakeholder Path params: id, entity_id

▸

HTTP

DELETE https://ai-memory.shop/api/v1/deals/:id/stakeholders/:entity_id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "deleted": true
  }
}

GET

DealController.win_probability

/api/v1/deals/:id/win-probability

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#win_probability.

Auth: Bearer Rate limited DealController.win_probability Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/deals/:id/win-probability HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

GET

DealController.analytics

/api/v1/deals/analytics

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#analytics.

Auth: Bearer Rate limited DealController.analytics

▸

HTTP

GET https://ai-memory.shop/api/v1/deals/analytics HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

GET

DealController.bottlenecks

/api/v1/deals/bottlenecks

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#bottlenecks.

Auth: Bearer Rate limited DealController.bottlenecks

▸

HTTP

GET https://ai-memory.shop/api/v1/deals/bottlenecks HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

GET

DealController.revenue_forecast

/api/v1/deals/revenue-forecast

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#revenue_forecast.

Auth: Bearer Rate limited DealController.revenue_forecast

▸

HTTP

GET https://ai-memory.shop/api/v1/deals/revenue-forecast HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

GET

DealController.templates

/api/v1/deals/templates

Handled by AiMemoryWeb.Controllers.Api.V1.DealController#templates.

Auth: Bearer Rate limited DealController.templates

▸

HTTP

GET https://ai-memory.shop/api/v1/deals/templates HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

Document templates

Public routes in the document templates domain.

9 routes

GET

DocumentTemplateController.index

/api/v1/document-templates

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentTemplateController#index.

Auth: Bearer Rate limited DocumentTemplateController.index

▸

HTTP

GET https://ai-memory.shop/api/v1/document-templates HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

POST

DocumentTemplateController.create

/api/v1/document-templates

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentTemplateController#create.

Auth: Bearer Rate limited DocumentTemplateController.create

▸

HTTP

POST https://ai-memory.shop/api/v1/document-templates HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

DELETE

DocumentTemplateController.delete

/api/v1/document-templates/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentTemplateController#delete.

Auth: Bearer Rate limited DocumentTemplateController.delete Path params: id

▸

HTTP

DELETE https://ai-memory.shop/api/v1/document-templates/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "deleted": true
  }
}

GET

DocumentTemplateController.show

/api/v1/document-templates/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentTemplateController#show.

Auth: Bearer Rate limited DocumentTemplateController.show Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/document-templates/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

PATCH

DocumentTemplateController.update

/api/v1/document-templates/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentTemplateController#update.

Auth: Bearer Rate limited DocumentTemplateController.update Path params: id

▸

HTTP

PATCH https://ai-memory.shop/api/v1/document-templates/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

PUT

DocumentTemplateController.update

/api/v1/document-templates/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentTemplateController#update.

Auth: Bearer Rate limited DocumentTemplateController.update Path params: id

▸

HTTP

PUT https://ai-memory.shop/api/v1/document-templates/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

POST

DocumentTemplateController.generate

/api/v1/document-templates/:id/generate

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentTemplateController#generate.

Auth: Bearer Rate limited DocumentTemplateController.generate Path params: id

▸

HTTP

POST https://ai-memory.shop/api/v1/document-templates/:id/generate HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

POST

DocumentTemplateController.render

/api/v1/document-templates/:id/render

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentTemplateController#render.

Auth: Bearer Rate limited DocumentTemplateController.render Path params: id

▸

HTTP

POST https://ai-memory.shop/api/v1/document-templates/:id/render HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

DocumentTemplateController.extraction_schema

/api/v1/document-templates/extraction-schema/:document_type

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentTemplateController#extraction_schema.

Auth: Bearer Rate limited DocumentTemplateController.extraction_schema Path params: document_type

▸

HTTP

GET https://ai-memory.shop/api/v1/document-templates/extraction-schema/:document_type HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

Documents

Public routes in the documents domain.

13 routes

GET

DocumentController.index

/api/v1/documents

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#index.

Auth: Bearer Rate limited DocumentController.index

▸

HTTP

GET https://ai-memory.shop/api/v1/documents HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

POST

DocumentController.create

/api/v1/documents

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#create.

Auth: Bearer Rate limited DocumentController.create

▸

HTTP

POST https://ai-memory.shop/api/v1/documents HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

DELETE

DocumentController.delete

/api/v1/documents/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#delete.

Auth: Bearer Rate limited DocumentController.delete Path params: id

▸

HTTP

DELETE https://ai-memory.shop/api/v1/documents/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "deleted": true
  }
}

GET

DocumentController.show

/api/v1/documents/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#show.

Auth: Bearer Rate limited DocumentController.show Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/documents/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

PATCH

DocumentController.update

/api/v1/documents/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#update.

Auth: Bearer Rate limited DocumentController.update Path params: id

▸

HTTP

PATCH https://ai-memory.shop/api/v1/documents/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

PUT

DocumentController.update

/api/v1/documents/:id

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#update.

Auth: Bearer Rate limited DocumentController.update Path params: id

▸

HTTP

PUT https://ai-memory.shop/api/v1/documents/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

GET

DocumentController.download

/api/v1/documents/:id/download

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#download.

Auth: Bearer Rate limited DocumentController.download Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/documents/:id/download HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

GET

DocumentController.extracted_data

/api/v1/documents/:id/extracted

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#extracted_data.

Auth: Bearer Rate limited DocumentController.extracted_data Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/documents/:id/extracted HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

POST

DocumentController.link_to_client

/api/v1/documents/:id/link-client

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#link_to_client.

Auth: Bearer Rate limited DocumentController.link_to_client Path params: id

▸

HTTP

POST https://ai-memory.shop/api/v1/documents/:id/link-client HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

POST

DocumentController.link_to_deal

/api/v1/documents/:id/link-deal

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#link_to_deal.

Auth: Bearer Rate limited DocumentController.link_to_deal Path params: id

▸

HTTP

POST https://ai-memory.shop/api/v1/documents/:id/link-deal HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

GET

DocumentController.search

/api/v1/documents/search

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#search.

Auth: Bearer Rate limited DocumentController.search

▸

HTTP

GET https://ai-memory.shop/api/v1/documents/search HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

GET

DocumentController.stats

/api/v1/documents/stats

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#stats.

Auth: Bearer Rate limited DocumentController.stats

▸

HTTP

GET https://ai-memory.shop/api/v1/documents/stats HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

GET

DocumentController.document_types

/api/v1/documents/types

Handled by AiMemoryWeb.Controllers.Api.V1.DocumentController#document_types.

Auth: Bearer Rate limited DocumentController.document_types

▸

HTTP

GET https://ai-memory.shop/api/v1/documents/types HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

Memories

Public routes in the memories domain.

9 routes

GET

MemoryController.index

/api/v1/memories

Handled by AiMemoryWeb.Controllers.Api.V1.MemoryController#index.

Auth: Bearer Rate limited MemoryController.index

▸

HTTP

GET https://ai-memory.shop/api/v1/memories HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": []
}

POST

Create Memory

/api/v1/memories

Store a new memory with automatic chunking and background embeddings.

Auth: Bearer Rate limited MemoryController.create

▸

HTTP

POST https://ai-memory.shop/api/v1/memories HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{
  "title": "Onboarding Complete",
  "content": "User completed onboarding",
  "idempotency_key": "optional-idempotency-key",
  "entities": [
    {
      "name": "John Doe",
      "type": "user",
      "external_id": "user_123"
    }
  ],
  "memory_type": "episodic"
}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

DELETE

MemoryController.delete

/api/v1/memories/:id

Handled by AiMemoryWeb.Controllers.Api.V1.MemoryController#delete.

Auth: Bearer Rate limited MemoryController.delete Path params: id

▸

HTTP

DELETE https://ai-memory.shop/api/v1/memories/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "deleted": true
  }
}

GET

MemoryController.show

/api/v1/memories/:id

Handled by AiMemoryWeb.Controllers.Api.V1.MemoryController#show.

Auth: Bearer Rate limited MemoryController.show Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/memories/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

PATCH

MemoryController.update

/api/v1/memories/:id

Handled by AiMemoryWeb.Controllers.Api.V1.MemoryController#update.

Auth: Bearer Rate limited MemoryController.update Path params: id

▸

HTTP

PATCH https://ai-memory.shop/api/v1/memories/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

PUT

MemoryController.update

/api/v1/memories/:id

Handled by AiMemoryWeb.Controllers.Api.V1.MemoryController#update.

Auth: Bearer Rate limited MemoryController.update Path params: id

▸

HTTP

PUT https://ai-memory.shop/api/v1/memories/:id HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

GET

MemoryController.status

/api/v1/memories/:id/status

Handled by AiMemoryWeb.Controllers.Api.V1.MemoryController#status.

Auth: Bearer Rate limited MemoryController.status Path params: id

▸

HTTP

GET https://ai-memory.shop/api/v1/memories/:id/status HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}

Success (shape)

JSON

{
  "data": {
    "id": "{id}"
  }
}

POST

MemoryController.batch_create

/api/v1/memories/batch

Handled by AiMemoryWeb.Controllers.Api.V1.MemoryController#batch_create.

Auth: Bearer Rate limited MemoryController.batch_create

▸

HTTP

POST https://ai-memory.shop/api/v1/memories/batch HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

POST

MemoryController.batch_delete

/api/v1/memories/batch-delete

Handled by AiMemoryWeb.Controllers.Api.V1.MemoryController#batch_delete.

Auth: Bearer Rate limited MemoryController.batch_delete

▸

HTTP

POST https://ai-memory.shop/api/v1/memories/batch-delete HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

Search

Public routes in the search domain.

1 routes

POST

Search Memories

/api/v1/search

Semantic search with temporal weighting.

Auth: Bearer Rate limited MemoryController.search

▸

HTTP

POST https://ai-memory.shop/api/v1/search HTTP/1.1
Accept: application/json
Authorization: Bearer {api_key}
Content-Type: application/json

JSON body

JSON

{
  "query": "onboarding completion",
  "limit": 5,
  "time_window_days": 30
}

Success (shape)

JSON

{
  "data": {
    "id": "created_id"
  }
}

Reference

WebSocket

Phoenix channels for real-time state changes, with a stable topic contract and event names.

Socket path


                        /socket

Topic


                        memory:events:{organization_id}

Auth

API key with read scope.

JavaScript (Phoenix Socket)

JAVASCRIPT

import { Socket } from "phoenix";

const socket = new Socket("https://ai-memory.shop/socket", {
  params: { token: "YOUR_API_KEY" }
});
socket.connect();

const organizationId = "YOUR_ORG_ID";
const channel = socket.channel(`memory:events:${organizationId}`, {});

channel.join()
  .receive("ok", () => console.log("Joined"))
  .receive("error", (err) => console.log("Join failed", err));

channel.on("memory:created", (payload) => console.log("memory:created", payload));
channel.on("embedding:completed", (payload) => console.log("embedding:completed", payload));
channel.on("deal:updated", (payload) => console.log("deal:updated", payload));

Traffic profile

Inbound messages

Outbound events

Scope

Join once per organization, then consume memory, batch, embeddings, task, goal, deal, deadline, and template updates.

Inbound messages

Client to server

ping Echo request/response; useful for health checks

Payload example

JSON

{
  "timestamp": 1742000000000
}

search:stream Perform a semantic search and stream results over the channel

Payload example

JSON

{
  "query": "onboarding completion",
  "limit": 10,
  "threshold": 0.7
}

search:cancel Cancel an in-flight search (currently a no-op; reserved for async search)

Payload example

JSON

{}

Outbound events

Server to client

memory:created A new memory document was created

Payload example

JSON

{
  "id": "doc_123",
  "title": "Onboarding",
  "memory_type": "episodic"
}

memory:updated A memory document was updated

Payload example

JSON

{
  "id": "doc_123",
  "changes": {
    "title": "New title"
  }
}

memory:deleted A memory document was deleted

Payload example

JSON

{
  "id": "doc_123"
}

embedding:started Embedding generation started for a memory (chunked)

Payload example

JSON

{
  "memory_id": "doc_123",
  "chunks_count": 6
}

embedding:completed A chunk embedding completed successfully

Payload example

JSON

{
  "chunk_id": "chunk_1",
  "memory_id": "doc_123"
}

embedding:failed A chunk embedding failed

Payload example

JSON

{
  "error": "provider_error",
  "chunk_id": "chunk_1",
  "memory_id": "doc_123"
}

memory:ready All chunks embedded; memory is ready for semantic search

Payload example

JSON

{
  "id": "doc_123",
  "chunks_count": 6
}

batch:started A batch operation started

Payload example

JSON

{
  "total": 3,
  "operation_id": "op_123"
}

batch:progress Batch operation progress update

Payload example

JSON

{
  "status": "processing",
  "total": 3,
  "current": 2,
  "operation_id": "op_123"
}

batch:complete Batch operation completed

Payload example

JSON

{
  "failed": 1,
  "succeeded": 2,
  "operation_id": "op_123"
}

relationship:created A knowledge graph relationship was created

Payload example

JSON

{
  "from_entity_id": "ent_1",
  "relationship_type": "depends_on",
  "to_entity_id": "ent_2"
}

relationship:deleted A knowledge graph relationship was deleted

Payload example

JSON

{
  "id": "rel_123"
}

task:created A task was created

Payload example

JSON

{
  "id": "task_123",
  "priority": "high",
  "status": "pending",
  "title": "Follow up"
}

task:updated A task was updated

Payload example

JSON

{
  "id": "task_123",
  "status": "in_progress"
}

task:assigned A task was assigned

Payload example

JSON

{
  "id": "task_123",
  "agent_id": "agent_123"
}

task:completed A task was completed

Payload example

JSON

{
  "id": "task_123",
  "outcome_summary": "Done"
}

goal:created A goal was created

Payload example

JSON

{
  "id": "goal_123",
  "status": "active",
  "title": "Grow pipeline"
}

goal:progress_updated Goal progress updated

Payload example

JSON

{
  "id": "goal_123",
  "progress": {
    "percent": 20
  }
}

decision:created A decision was recorded

Payload example

JSON

{
  "id": "dec_123",
  "title": "Choose DB",
  "outcome": "pending"
}

decision:reviewed A decision outcome was reviewed/updated

Payload example

JSON

{
  "id": "dec_123",
  "outcome": "success"
}

skill:created A skill was created

Payload example

JSON

{
  "id": "skill_123",
  "name": "Deploy",
  "version": 1,
  "skill_type": "procedure"
}

skill:executed A skill execution started/recorded

Payload example

JSON

{
  "id": "exec_123",
  "status": "running",
  "skill_id": "skill_123"
}

execution:completed A skill execution completed

Payload example

JSON

{
  "id": "exec_123",
  "status": "completed",
  "skill_id": "skill_123"
}

deal:created A deal was created

Payload example

JSON

{
  "id": "deal_123",
  "status": "active",
  "title": "Buyer lead",
  "stage": "lead"
}

deal:updated A deal was updated

Payload example

JSON

{
  "id": "deal_123",
  "status": "active",
  "stage": "negotiation"
}

deal:closed A deal was closed (won/lost)

Payload example

JSON

{
  "id": "deal_123",
  "status": "won",
  "title": "Buyer lead"
}

milestone:completed A deal milestone was completed

Payload example

JSON

{
  "id": "ms_1",
  "name": "Inspection",
  "completed_at": "2026-03-10",
  "deal_id": "deal_123"
}

stakeholder:added A stakeholder was added to a deal

Payload example

JSON

{
  "role": "buyer",
  "deal_id": "deal_123",
  "entity_id": "ent_3"
}

document:attached A document was attached to a deal

Payload example

JSON

{
  "document_id": "doc_9",
  "document_type": "purchase_agreement",
  "deal_id": "deal_123"
}

deadline:created A deadline was created

Payload example

JSON

{
  "id": "dl_1",
  "priority": "high",
  "title": "Earnest money",
  "due_date": "2026-03-12"
}

deadline:completed A deadline was completed

Payload example

JSON

{
  "id": "dl_1",
  "title": "Earnest money",
  "completed_at": "2026-03-11T12:00:00Z"
}

deadline:missed A deadline was missed

Payload example

JSON

{
  "id": "dl_1",
  "title": "Earnest money",
  "due_date": "2026-03-12"
}

reminder:sent A reminder was sent

Payload example

JSON

{
  "id": "rem_1",
  "message": "Due tomorrow",
  "deadline_id": "dl_1"
}

interaction:logged A client interaction was logged

Payload example

JSON

{
  "id": "int_1",
  "summary": "Discussed terms",
  "entity_id": "ent_7",
  "interaction_type": "call"
}

broker_document:uploaded A broker document was uploaded

Payload example

JSON

{
  "id": "bd_1",
  "status": "active",
  "filename": "contract.pdf",
  "document_type": "purchase_agreement"
}

broker_document:processed A broker document OCR/extraction completed

Payload example

JSON

{
  "id": "bd_1",
  "filename": "contract.pdf",
  "ocr_status": "completed"
}

broker_document:generated A broker document was generated from a template

Payload example

JSON

{
  "id": "bd_2",
  "filename": "offer.pdf",
  "document_type": "offer_letter"
}

document_template:created A document template was created

Payload example

JSON

{
  "id": "tpl_1",
  "name": "Offer Letter",
  "document_type": "offer_letter"
}

Reference

MCP

Model Context Protocol support for tool-driven clients, with schemas taken from the running server.

Protocol summary

Endpoint


                        https://ai-memory.shop/mcp

Revision

MCP 2024-11-05, JSON-RPC 2.0

Authentication

Bearer API key over HTTP POST.

tools/list (JSON-RPC)

JSON

{
  "id": "req-1",
  "params": {},
  "method": "tools/list",
  "jsonrpc": "2.0"
}

tools/call (example)

JSON

{
  "id": "req-2",
  "params": {
    "name": "memory_create",
    "arguments": {
      "content": "User prefers compact UI",
      "memory_type": "episodic"
    }
  },
  "method": "tools/call",
  "jsonrpc": "2.0"
}

`memory_create`

Store a memory document with automatic chunking and embedding generation

required: content

Input schema

JSON

{
  "type": "object",
  "required": [
    "content"
  ],
  "properties": {
    "title": {
      "type": "string",
      "description": "Optional title for the memory"
    },
    "content": {
      "type": "string",
      "description": "The memory content to store"
    },
    "entities": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Entity name"
          },
          "type": {
            "type": "string",
            "description": "Entity type (user, project, customer, etc.)"
          },
          "external_id": {
            "type": "string",
            "description": "External identifier"
          }
        }
      }
    },
    "memory_type": {
      "default": "episodic",
      "type": "string",
      "enum": [
        "episodic",
        "semantic"
      ]
    },
    "event_timestamp": {
      "type": "string",
      "description": "ISO 8601 timestamp for episodic memories"
    },
    "fact_statement": {
      "type": "string",
      "description": "Required when memory_type is semantic"
    },
    "importance_score": {
      "default": 0.5,
      "maximum": 1,
      "type": "number",
      "minimum": 0
    }
  }
}

`memory_search`

Search memories using semantic similarity with temporal weighting

required: query

Input schema

JSON

{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query"
    },
    "limit": {
      "default": 10,
      "type": "number"
    },
    "entity_type": {
      "type": "string",
      "description": "Entity type for external ID filter"
    },
    "entity_external_id": {
      "type": "string",
      "description": "Filter by entity external ID"
    },
    "entity_filter": {
      "type": "object",
      "description": "Filter by entity ID"
    },
    "include_full_document": {
      "type": "boolean",
      "description": "Include full document content in results"
    },
    "recency_weight": {
      "default": 0.3,
      "maximum": 1,
      "type": "number",
      "minimum": 0
    },
    "time_window_days": {
      "default": 30,
      "type": "number",
      "description": "Time window in days"
    }
  }
}

`memory_read`

Read a specific memory by ID

required: id

Input schema

JSON

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Memory ID"
    }
  }
}

`memory_delete`

Delete a memory by ID

required: id

Input schema

JSON

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Memory ID"
    }
  }
}

`memory_batch_create`

Create multiple memories in a single request. Each memory is processed independently.

required: memories

Input schema

JSON

{
  "type": "object",
  "required": [
    "memories"
  ],
  "properties": {
    "memories": {
      "type": "array",
      "description": "Array of memory objects to create",
      "items": {
        "type": "object",
        "required": [
          "content"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Optional title for the memory"
          },
          "content": {
            "type": "string",
            "description": "The memory content to store"
          },
          "memory_type": {
            "default": "episodic",
            "type": "string",
            "enum": [
              "episodic",
              "semantic"
            ]
          },
          "importance_score": {
            "default": 0.5,
            "maximum": 1,
            "type": "number",
            "minimum": 0
          }
        }
      }
    }
  }
}

`memory_batch_delete`

Delete multiple memories matching filter criteria. At least one filter is required.

required:

Input schema

JSON

{
  "type": "object",
  "properties": {
    "ids": {
      "type": "array",
      "description": "Specific memory IDs to delete",
      "items": {
        "type": "string"
      }
    },
    "memory_type": {
      "type": "string",
      "enum": [
        "episodic",
        "semantic"
      ],
      "description": "Delete all memories of this type"
    },
    "older_than_days": {
      "type": "number",
      "description": "Delete memories older than N days"
    },
    "dry_run": {
      "type": "boolean",
      "description": "If true, returns count without deleting"
    }
  }
}

`entity_create`

Create or get an entity that memories can be associated with

required: type, name

Input schema

JSON

{
  "type": "object",
  "required": [
    "type",
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "Entity name"
    },
    "type": {
      "type": "string",
      "description": "Entity type (user, project, customer, etc.)"
    },
    "external_id": {
      "type": "string",
      "description": "External identifier"
    }
  }
}

`entity_link`

Create a typed relationship between two entities in the knowledge graph

required: from_entity_id, to_entity_id, relationship_type

Input schema

JSON

{
  "type": "object",
  "required": [
    "from_entity_id",
    "to_entity_id",
    "relationship_type"
  ],
  "properties": {
    "properties": {
      "type": "object",
      "description": "Optional relationship properties"
    },
    "from_entity_id": {
      "type": "string",
      "description": "Source entity ID"
    },
    "relationship_type": {
      "type": "string",
      "description": "Type of relationship (e.g., manages, depends_on, located_in)"
    },
    "to_entity_id": {
      "type": "string",
      "description": "Target entity ID"
    },
    "confidence_score": {
      "maximum": 1,
      "type": "number",
      "description": "Confidence in the relationship (0.0-1.0)",
      "minimum": 0
    }
  }
}

`graph_traverse`

Traverse the knowledge graph from a starting entity following specific relationship types

required: entity_id, relationship_types

Input schema

JSON

{
  "type": "object",
  "required": [
    "entity_id",
    "relationship_types"
  ],
  "properties": {
    "direction": {
      "default": "outgoing",
      "type": "string",
      "enum": [
        "outgoing",
        "incoming",
        "both"
      ],
      "description": "Direction of relationships to follow"
    },
    "entity_id": {
      "type": "string",
      "description": "Starting entity ID"
    },
    "max_depth": {
      "default": 5,
      "type": "number",
      "description": "Maximum traversal depth"
    },
    "relationship_types": {
      "type": "array",
      "description": "Relationship types to follow",
      "items": {
        "type": "string"
      }
    }
  }
}

`graph_search`

Find paths between two entities in the knowledge graph

required: from_entity_id, to_entity_id

Input schema

JSON

{
  "type": "object",
  "required": [
    "from_entity_id",
    "to_entity_id"
  ],
  "properties": {
    "from_entity_id": {
      "type": "string",
      "description": "Starting entity ID"
    },
    "to_entity_id": {
      "type": "string",
      "description": "Target entity ID"
    },
    "max_depth": {
      "default": 5,
      "type": "number",
      "description": "Maximum search depth"
    },
    "relationship_types": {
      "type": "array",
      "description": "Optional: relationship types to follow",
      "items": {
        "type": "string"
      }
    }
  }
}

`task_create`

Create a new task with title, description, and optional dependencies

required: title

Input schema

JSON

{
  "type": "object",
  "required": [
    "title"
  ],
  "properties": {
    "priority": {
      "default": "medium",
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high",
        "critical"
      ]
    },
    "description": {
      "type": "string",
      "description": "Task description"
    },
    "title": {
      "type": "string",
      "description": "Task title"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "goal_id": {
      "type": "string",
      "description": "Link to a goal"
    },
    "due_at": {
      "type": "string",
      "description": "ISO 8601 due date"
    },
    "parent_task_id": {
      "type": "string",
      "description": "Parent task for hierarchy"
    }
  }
}

`task_update`

Update task status, assignment, or other properties

required: task_id

Input schema

JSON

{
  "type": "object",
  "required": [
    "task_id"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "in_progress",
        "blocked",
        "completed",
        "cancelled"
      ]
    },
    "outcome_summary": {
      "type": "string",
      "description": "Summary of task outcome"
    },
    "task_id": {
      "type": "string",
      "description": "Task ID to update"
    },
    "assigned_agent_id": {
      "type": "string",
      "description": "Agent to assign"
    }
  }
}

`task_list`

List tasks with optional filters

required:

Input schema

JSON

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "in_progress",
        "blocked",
        "completed",
        "cancelled"
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "assigned_agent_id": {
      "type": "string"
    },
    "goal_id": {
      "type": "string"
    }
  }
}

`task_complete`

Complete a task with outcome summary

required: task_id, outcome_summary

Input schema

JSON

{
  "type": "object",
  "required": [
    "task_id",
    "outcome_summary"
  ],
  "properties": {
    "outcome_summary": {
      "type": "string",
      "description": "Summary of task outcome"
    },
    "task_id": {
      "type": "string",
      "description": "Task ID to complete"
    }
  }
}

`goal_create`

Create a new goal with target metrics

required: title

Input schema

JSON

{
  "type": "object",
  "required": [
    "title"
  ],
  "properties": {
    "description": {
      "type": "string",
      "description": "Goal description"
    },
    "title": {
      "type": "string",
      "description": "Goal title"
    },
    "deadline": {
      "type": "string",
      "description": "ISO 8601 deadline"
    },
    "target_metrics": {
      "type": "object",
      "description": "Target metrics to track"
    }
  }
}

`goal_list`

List goals with optional filters

required:

Input schema

JSON

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "completed",
        "cancelled"
      ]
    }
  }
}

`goal_progress`

Get progress for a specific goal

required: goal_id

Input schema

JSON

{
  "type": "object",
  "required": [
    "goal_id"
  ],
  "properties": {
    "goal_id": {
      "type": "string",
      "description": "Goal ID"
    }
  }
}

`decision_create`

Record a decision with context, alternatives, and reasoning

required: context, selected_alternative, reasoning

Input schema

JSON

{
  "type": "object",
  "required": [
    "context",
    "selected_alternative",
    "reasoning"
  ],
  "properties": {
    "context": {
      "type": "string",
      "description": "The context/situation for the decision"
    },
    "description": {
      "type": "string",
      "description": "Decision description"
    },
    "title": {
      "type": "string",
      "description": "Decision title"
    },
    "reasoning": {
      "type": "string",
      "description": "Reasoning for the decision"
    },
    "selected_alternative": {
      "type": "string",
      "description": "The chosen alternative"
    },
    "alternatives": {
      "type": "array",
      "description": "List of alternatives considered",
      "items": {
        "type": "object"
      }
    },
    "confidence_score": {
      "default": 0.8,
      "maximum": 1,
      "type": "number",
      "minimum": 0
    }
  }
}

`decision_update_outcome`

Update the outcome of a decision

required: decision_id, outcome

Input schema

JSON

{
  "type": "object",
  "required": [
    "decision_id",
    "outcome"
  ],
  "properties": {
    "outcome": {
      "type": "string",
      "enum": [
        "pending",
        "success",
        "partial",
        "failure"
      ],
      "description": "Outcome of the decision"
    },
    "decision_id": {
      "type": "string",
      "description": "Decision ID"
    },
    "outcome_notes": {
      "type": "string",
      "description": "Notes about the outcome"
    }
  }
}

`decision_search`

Search for similar past decisions by context

required: context

Input schema

JSON

{
  "type": "object",
  "required": [
    "context"
  ],
  "properties": {
    "context": {
      "type": "string",
      "description": "Context to search for"
    },
    "limit": {
      "default": 10,
      "type": "number"
    },
    "threshold": {
      "default": 0.7,
      "type": "number"
    }
  }
}

`skill_create`

Create a reusable skill/procedure with parameter validation

required: name, content

Input schema

JSON

{
  "type": "object",
  "required": [
    "name",
    "content"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "Skill name"
    },
    "description": {
      "type": "string",
      "description": "Skill description"
    },
    "content": {
      "type": "object",
      "description": "Skill content with 'steps' array"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "skill_type": {
      "default": "procedure",
      "type": "string"
    },
    "parameters_schema": {
      "type": "object",
      "description": "JSON Schema for parameters"
    }
  }
}

`skill_execute`

Execute a skill with parameters

required: skill_id

Input schema

JSON

{
  "type": "object",
  "required": [
    "skill_id"
  ],
  "properties": {
    "parameters": {
      "type": "object",
      "description": "Parameters for the skill"
    },
    "skill_id": {
      "type": "string",
      "description": "Skill ID to execute"
    },
    "related_task_id": {
      "type": "string",
      "description": "Optional related task"
    }
  }
}

`skill_list`

List available skills with optional filters

required:

Input schema

JSON

{
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "skill_type": {
      "type": "string"
    }
  }
}

`document_search`

Search broker documents by content or filename

required: query

Input schema

JSON

{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query text"
    },
    "limit": {
      "default": 20,
      "type": "number"
    },
    "document_type": {
      "type": "string",
      "description": "Filter by document type"
    },
    "deal_id": {
      "type": "string",
      "description": "Filter by deal ID"
    }
  }
}

`document_get`

Get a broker document with extracted data

required: id

Input schema

JSON

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Document ID"
    }
  }
}

`document_extract_fields`

Extract key fields from document based on its type

required: document_type, text

Input schema

JSON

{
  "type": "object",
  "required": [
    "document_type",
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "description": "OCR text content to extract from"
    },
    "document_type": {
      "type": "string",
      "description": "Type of document (purchase_agreement, insurance_policy, bill_of_lading, invoice)"
    }
  }
}

`document_render_template`

Render a document template with provided values

required: template_id, values

Input schema

JSON

{
  "type": "object",
  "required": [
    "template_id",
    "values"
  ],
  "properties": {
    "values": {
      "type": "object",
      "description": "Values to fill placeholders"
    },
    "template_id": {
      "type": "string",
      "description": "Template ID to render"
    },
    "deal_id": {
      "type": "string",
      "description": "Optional: Link to deal"
    },
    "client_entity_id": {
      "type": "string",
      "description": "Optional: Link to client"
    }
  }
}

`document_list_templates`

List available document templates

required:

Input schema

JSON

{
  "type": "object",
  "properties": {
    "document_type": {
      "type": "string",
      "description": "Filter by document type"
    },
    "industry": {
      "type": "string",
      "description": "Filter by industry"
    }
  }
}

Reference

Machine Endpoints

Discovery documents, auth metadata, and authoritative machine-readable schemas.

Agent discovery

GET /for-agents returns service metadata and quickstart info for bots.

GET /ping provides a minimal discovery check.

OAuth metadata

GET /.well-known/oauth-protected-resource advertises scopes and RFC 9728 metadata.

OpenAPI

GET /api/v1/openapi.json is the authoritative REST schema for generated clients and robots.

MCP endpoint

POST /mcp exposes machine-readable tools with Bearer auth.

Reference

Errors & Limits

Predictable failures and retry hints for clients that need to act without guesswork.

Rate limiting

REST and WebSocket traffic is rate limited. REST responses return 429 with a Retry-After header.

Example (REST)

JSON

{
  "error": "Rate limit exceeded",
  "retry_after_seconds": 30,
  "tokens_remaining": 0
}

Auth errors

Missing or invalid API keys return structured errors plus a WWW-Authenticate hint pointing at the protected-resource metadata URL.

Example (REST)

JSON

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "API key required"
  }
}