Agent-Native API

HatiData's agent-native endpoints give AI agents long-term memory with vector search, tamper-evident reasoning traces, and semantic triggers that fire when data matches natural language concepts. These endpoints are available through both the Control Plane REST API and the Proxy MCP Server (see MCP Tools Reference).

Authentication

All agent-native endpoints require one of three authentication methods:

Method	Header	Typical Use
JWT	`Authorization: Bearer <jwt>`	Dashboard users
API Key	`Authorization: ApiKey <key>`	Agents and SDKs (`hd_live_`, `hd_agent_`)
Federated	`Authorization: Bearer <cloud_token>`	AWS STS, GCP WIF, Azure MI

# API key example (used in all curl examples below)
export HATIDATA_API_KEY="hd_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
export HATIDATA_ORG_ID="550e8400-e29b-41d4-a716-446655440000"
export HATIDATA_BASE="https://api.hatidata.com"

Agent Memory API

Store, search, and manage long-term memories for AI agents. Memories are automatically embedded for vector search when the embedding pipeline is configured.

Scopes

Operation	Required Scope
List, search memories	`MemoryRead`
Create, delete, re-embed	`MemoryWrite`

Create Memory

POST /v1/organizations/{org_id}/agent-memory

Store a new memory entry. HatiData automatically embeds the content for semantic search when Qdrant and an embedding provider are available. If embedding fails, the memory is stored with embedding_status: "pending" and can be re-embedded later.

Request Body:

Field	Type	Required	Description
`agent_id`	string	Yes	Agent identifier (e.g., `"research-agent"`)
`memory_type`	string	Yes	Category: `"semantic"`, `"episodic"`, `"procedural"`, or custom
`content`	string	Yes	Memory content (auto-embedded for vector search)

curl -X POST "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/agent-memory" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "research-agent",
    "memory_type": "semantic",
    "content": "User prefers PostgreSQL with Drizzle ORM over Prisma for performance-critical applications"
  }'

Response (200):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "org_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "research-agent",
  "memory_type": "semantic",
  "content": "User prefers PostgreSQL with Drizzle ORM over Prisma for performance-critical applications",
  "created_at": "2026-03-20T14:30:00.000Z",
  "access_count": 0,
  "embedding_provider": "openai",
  "has_embedding": true,
  "embedding_model": "text-embedding-3-small",
  "embedding_dimensions": 1536,
  "embedding_status": "embedded"
}

Embedding Models by Tier

Tier	Model	Dimensions	Provider
Free	bge-small-en-v1.5	384	Local sidecar
Cloud	text-embedding-3-small	1536	OpenAI
Growth	text-embedding-3-large	3072	OpenAI
Enterprise	text-embedding-3-large	3072	OpenAI

If OpenAI is unavailable, all tiers fall back to the local BGE sidecar (384 dimensions).

List Memories

GET /v1/organizations/{org_id}/agent-memory

List memories for an organization with optional filters.

Query Parameters:

Parameter	Type	Default	Description
`agent_id`	string	--	Filter by agent
`memory_type`	string	--	Filter by type (`"semantic"`, `"episodic"`, etc.)
`limit`	integer	`50`	Max results (capped at 100)
`embedding_model`	string	--	Filter by embedding model name
`embedding_status`	string	--	Filter by status: `"embedded"`, `"pending"`, `"failed"`

curl "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/agent-memory?agent_id=research-agent&limit=10" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "org_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "research-agent",
    "memory_type": "semantic",
    "content": "User prefers PostgreSQL with Drizzle ORM over Prisma for performance-critical applications",
    "created_at": "2026-03-20T14:30:00.000Z",
    "access_count": 3,
    "embedding_status": "embedded"
  }
]

Search Memories (Vector Search)

GET /v1/organizations/{org_id}/agent-memory/search

Search memories using semantic similarity. HatiData auto-embeds your query text, runs ANN (approximate nearest neighbor) search via Qdrant, then fetches full metadata from the database. If Qdrant is unavailable, falls back to token-overlap text search.

Query Parameters:

Parameter	Type	Default	Description
`query`	string	(required)	Natural language search query. HatiData auto-embeds this text using the org's configured embedding model.
`agent_id`	string	--	Filter results to a specific agent
`top_k`	integer	`10`	Number of results to return (max 50)

The query parameter accepts any natural language text string. You do not need to pre-compute embeddings -- HatiData handles embedding automatically using the same model that was used to embed the stored memories.

The top_k parameter controls how many results are returned, ranked by cosine similarity. Higher values return more results but may include lower-relevance matches.

The optional agent_id parameter restricts search to memories belonging to a specific agent, which is useful in multi-agent systems where each agent maintains its own memory space.

curl "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/agent-memory/search?query=database+ORM+preferences&agent_id=research-agent&top_k=5" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

Each result includes a score field representing cosine similarity between the query and memory embeddings. Scores range from 0.0 (no similarity) to 1.0 (identical). Results are sorted by score descending.

[
  {
    "entry": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "org_id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "research-agent",
      "memory_type": "semantic",
      "content": "User prefers PostgreSQL with Drizzle ORM over Prisma for performance-critical applications",
      "created_at": "2026-03-20T14:30:00.000Z",
      "access_count": 3,
      "embedding_provider": "openai",
      "has_embedding": true,
      "embedding_model": "text-embedding-3-small",
      "embedding_dimensions": 1536,
      "embedding_status": "embedded"
    },
    "score": 0.92
  },
  {
    "entry": {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "org_id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "research-agent",
      "memory_type": "semantic",
      "content": "SQLite is preferred for local development; PostgreSQL for production deployments",
      "created_at": "2026-03-19T09:15:00.000Z",
      "access_count": 1,
      "embedding_status": "embedded"
    },
    "score": 0.78
  }
]

Fallback Behavior

When vector search infrastructure is unavailable (no Qdrant or embedding provider configured), search falls back to token-overlap text matching. In this mode, all results return score: 1.0. You can check whether a memory has been embedded by inspecting the embedding_status field.

Delete Memory

DELETE /v1/organizations/{org_id}/agent-memory/{memory_id}

Delete a memory entry and its associated vector embedding.

curl -X DELETE "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/agent-memory/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

{
  "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "deleted"
}

Embedding Stats

GET /v1/organizations/{org_id}/agent-memory/embedding-stats

Get aggregate embedding statistics for an organization's memories.

curl "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/agent-memory/embedding-stats" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

{
  "models": [
    {
      "model": "text-embedding-3-small",
      "count": 1250,
      "dimensions": 1536
    },
    {
      "model": "bge-small-en-v1.5",
      "count": 340,
      "dimensions": 384
    }
  ],
  "total_embedded": 1590,
  "total_pending": 45,
  "total_failed": 3,
  "migration_in_progress": false
}

Re-embed Memory

POST /v1/organizations/{org_id}/agent-memory/{memory_id}/re-embed

Queue a single memory for re-embedding with the current active model. Useful after upgrading tiers or switching embedding providers.

Tier requirement: Growth or higher.

curl -X POST "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/agent-memory/a1b2c3d4-e5f6-7890-abcd-ef1234567890/re-embed" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

{
  "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued"
}

Bulk Re-embed

POST /v1/organizations/{org_id}/agent-memory/bulk-re-embed

Re-embed multiple memories in a single request.

Tier requirement: Enterprise only.

curl -X POST "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/agent-memory/bulk-re-embed" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_ids": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ]
  }'

Response (200):

{
  "queued": 2,
  "skipped": 0
}

Chain-of-Thought API

Immutable, hash-chained reasoning traces for AI agents. The CoT ledger provides tamper-evident audit trails of agent decisions, enabling compliance review, session replay, and human-in-the-loop approval workflows.

Scopes & Roles

Operation	Required Scope	Required Role
List sessions, replay, verify, export	`CotRead`	Auditor or Admin
Ingest traces, approve/reject	`CotWrite`	Auditor or Admin (ingest), Admin (approvals)

List Sessions

GET /v1/cot/sessions

List all CoT sessions for the authenticated organization.

curl "$HATIDATA_BASE/v1/cot/sessions" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

[
  {
    "session_id": "sess-research-2026-03-20",
    "agent_id": "research-agent",
    "total_steps": 12,
    "chain_valid": true,
    "started_at": "2026-03-20T14:00:00Z",
    "ended_at": "2026-03-20T14:05:32Z"
  }
]

Ingest Traces

POST /v1/cot/ingest

Ingest flight recorder traces from an agent framework (hatiOS, LangChain, etc.). Traces are stored immutably with SHA-256 content hashes for tamper detection. Batch limit: 1,000 traces per request.

Request Body:

Field	Type	Required	Description
`traces`	array	Yes	Array of trace objects (max 1,000)

Each trace object:

Field	Type	Required	Description
`trace_id`	UUID	Yes	Unique trace identifier
`session_id`	string	Yes	Session grouping key
`agent_id`	string	Yes	Agent that generated the trace
`timestamp`	ISO 8601	Yes	When the trace was captured
`trace_type`	string	Yes	`"thought"`, `"tool_call"`, `"tool_result"`, `"llm_request"`, `"llm_response"`
`content`	object	Yes	Trace payload (any JSON)
`content_hash`	string	Yes	SHA-256 hex hash of `content`
`parent_trace_id`	UUID	No	Links related traces (e.g., request to response)

curl -X POST "$HATIDATA_BASE/v1/cot/ingest" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "traces": [
      {
        "trace_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "session_id": "sess-research-2026-03-20",
        "agent_id": "research-agent",
        "timestamp": "2026-03-20T14:00:01Z",
        "trace_type": "thought",
        "content": {
          "text": "User asked about NVDA stock. I should query recent price data and analyst ratings.",
          "reasoning": "Financial query requires both quantitative data and qualitative analysis"
        },
        "content_hash": "a3f2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
      },
      {
        "trace_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "session_id": "sess-research-2026-03-20",
        "agent_id": "research-agent",
        "timestamp": "2026-03-20T14:00:02Z",
        "trace_type": "tool_call",
        "content": {
          "tool": "run_sql",
          "input": "SELECT date, close_price FROM stock_prices WHERE ticker = 'NVDA' ORDER BY date DESC LIMIT 30"
        },
        "content_hash": "b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3",
        "parent_trace_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
      }
    ]
  }'

Response (200):

{
  "ingested": 2,
  "trace_ids": [
    "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "d4e5f6a7-b8c9-0123-defa-234567890123"
  ]
}

Replay Session

GET /v1/cot/sessions/{session_id}/replay

Replay the full chain-of-thought trace for a session, with hash chain verification.

curl "$HATIDATA_BASE/v1/cot/sessions/sess-research-2026-03-20/replay" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

{
  "session_id": "sess-research-2026-03-20",
  "agent_id": "research-agent",
  "total_steps": 2,
  "chain_valid": true,
  "steps": [
    {
      "trace_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "step_index": 0,
      "trace_type": "thought",
      "content": {
        "text": "User asked about NVDA stock. I should query recent price data and analyst ratings.",
        "reasoning": "Financial query requires both quantitative data and qualitative analysis"
      },
      "content_hash": "a3f2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2",
      "timestamp": "2026-03-20T14:00:01Z",
      "parent_trace_id": null
    },
    {
      "trace_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "step_index": 1,
      "trace_type": "tool_call",
      "content": {
        "tool": "run_sql",
        "input": "SELECT date, close_price FROM stock_prices WHERE ticker = 'NVDA' ORDER BY date DESC LIMIT 30"
      },
      "content_hash": "b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3",
      "timestamp": "2026-03-20T14:00:02Z",
      "parent_trace_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
    }
  ]
}

The chain_valid field indicates whether all content hashes in the session are consistent (non-empty, valid hex). A false value indicates potential tampering.

Verify Session Integrity

GET /v1/cot/sessions/{session_id}/verify

Verify hash chain integrity for a session without returning full trace content.

curl "$HATIDATA_BASE/v1/cot/sessions/sess-research-2026-03-20/verify" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

{
  "session_id": "sess-research-2026-03-20",
  "chain_valid": true,
  "total_traces": 12,
  "invalid_hashes": []
}

Export Session

GET /v1/cot/sessions/{session_id}/export

Download a session's full trace as a JSON file. Returns Content-Disposition: attachment for browser download.

curl "$HATIDATA_BASE/v1/cot/sessions/sess-research-2026-03-20/export" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY" \
  -o cot-session-export.json

Approve or Reject Decision

POST /v1/cot/approvals

Record a human approval or rejection of an agent's decision. This creates an immutable audit record linking the reviewer to the session and decision.

Request Body:

Field	Type	Required	Description
`session_id`	string	Yes	Session being reviewed
`agent_id`	string	Yes	Agent whose action is being reviewed
`decision`	string	Yes	`"approve"` or `"reject"`
`trace_id`	UUID	No	Specific trace being acted on
`reason`	string	No	Reviewer's rationale

curl -X POST "$HATIDATA_BASE/v1/cot/approvals" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-research-2026-03-20",
    "agent_id": "research-agent",
    "decision": "approve",
    "trace_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "reason": "Agent correctly identified the data sources and query approach"
  }'

Response (200):

{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "decision": "approve",
  "session_id": "sess-research-2026-03-20",
  "reviewed_by": "admin@example.com",
  "created_at": "2026-03-20T15:30:00Z"
}

Merge Approval from CoT Context

POST /v1/cot/sessions/{session_id}/merge-approval

Approve or reject a branch merge from within a CoT session context. This dual-logs to both the CoT ledger and the branch audit trail.

Tier requirement: Growth or higher.

Request Body:

Field	Type	Required	Description
`branch_id`	UUID	Yes	Branch to approve/reject
`decision`	string	Yes	`"approve"` or `"reject"`
`reason`	string	No	Rationale for the decision
`cot_step_references`	array	No	Related CoT step IDs

curl -X POST "$HATIDATA_BASE/v1/cot/sessions/sess-research-2026-03-20/merge-approval" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "branch_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "decision": "approve",
    "reason": "Branch analysis is complete and verified",
    "cot_step_references": ["step-1", "step-2"]
  }'

Response (200):

{
  "session_id": "sess-research-2026-03-20",
  "branch_id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "decision": "approve",
  "cot_logged": true,
  "branch_updated": true
}

Semantic Triggers API

Register natural language concepts that fire actions when data or agent activity matches semantically. Triggers use cosine similarity against pre-computed concept embeddings, with configurable thresholds and cooldown periods.

Scopes

Operation	Required Scope
List triggers, test trigger	`TriggerRead`
Create, update, delete, re-embed	`TriggerManage`
List trigger fire events	`QueryAuditRead`

List Triggers

GET /v1/organizations/{org_id}/triggers

List all semantic triggers for an organization.

curl "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/triggers" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

[
  {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "org_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "cost-alert",
    "concept": "high query cost exceeding budget thresholds",
    "threshold": 0.85,
    "actions": ["webhook", "flag_for_review"],
    "cooldown_secs": 300,
    "enabled": true,
    "fire_count": 42,
    "created_at": "2026-03-15T10:00:00Z",
    "embedding_model": "text-embedding-3-small",
    "event_source": "semantic",
    "embedding_dimensions": 1536
  }
]

Create Trigger

POST /v1/organizations/{org_id}/triggers

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Human-readable trigger name
`concept`	string	Yes	Natural language concept to match against
`threshold`	number	Yes	Cosine similarity threshold (`0.0` to `1.0`). Higher values require closer matches.
`actions`	array	Yes	Actions to execute: `"webhook"`, `"agent_notify"`, `"flag_for_review"`, `"write_event"`
`cooldown_secs`	integer	No	Minimum seconds between firings (default: `300`)
`event_source`	string	No	`"semantic"` (default) or `"branch_lifecycle"`

curl -X POST "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/triggers" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pii-detection",
    "concept": "queries accessing personally identifiable information like SSN, email, phone number",
    "threshold": 0.82,
    "actions": ["flag_for_review", "webhook"],
    "cooldown_secs": 60
  }'

Response (200):

{
  "id": "a2b3c4d5-e6f7-8901-bcde-f23456789012",
  "org_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "pii-detection",
  "concept": "queries accessing personally identifiable information like SSN, email, phone number",
  "threshold": 0.82,
  "actions": ["flag_for_review", "webhook"],
  "cooldown_secs": 60,
  "enabled": true,
  "fire_count": 0,
  "created_at": "2026-03-20T16:00:00Z",
  "embedding_model": "text-embedding-3-small",
  "event_source": "semantic",
  "embedding_dimensions": 1536
}

Update Trigger

PUT /v1/organizations/{org_id}/triggers/{trigger_id}

Update trigger properties. All fields are optional -- only provided fields are changed.

Request Body:

Field	Type	Description
`name`	string	New trigger name
`threshold`	number	New similarity threshold
`actions`	array	New action list
`cooldown_secs`	integer	New cooldown period
`enabled`	boolean	Enable or disable the trigger

curl -X PUT "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/triggers/a2b3c4d5-e6f7-8901-bcde-f23456789012" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threshold": 0.90,
    "enabled": false
  }'

Delete Trigger

DELETE /v1/organizations/{org_id}/triggers/{trigger_id}

curl -X DELETE "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/triggers/a2b3c4d5-e6f7-8901-bcde-f23456789012" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

{
  "trigger_id": "a2b3c4d5-e6f7-8901-bcde-f23456789012",
  "status": "deleted"
}

Test Trigger

POST /v1/organizations/{org_id}/triggers/{trigger_id}/test

Test whether a trigger would fire against sample text. Returns the cosine similarity score and whether it exceeds the threshold. Does not record a fire event.

Request Body:

Field	Type	Required	Description
`text`	string	Yes	Sample text to test against the trigger's concept

curl -X POST "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/triggers/f1a2b3c4-d5e6-7890-abcd-ef1234567890/test" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "SELECT ssn, email, phone FROM customers WHERE region = '\''US'\''"
  }'

Response (200):

{
  "trigger_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "trigger_name": "pii-detection",
  "similarity": 0.91,
  "would_fire": true,
  "model_used": "text-embedding-3-small",
  "model_dimensions": 1536
}

List Trigger Fire Events

GET /v1/organizations/{org_id}/triggers/{trigger_id}/fires

List historical fire events for a trigger.

curl "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/triggers/f1a2b3c4-d5e6-7890-abcd-ef1234567890/fires" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

[
  {
    "id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
    "trigger_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "org_id": "550e8400-e29b-41d4-a716-446655440000",
    "similarity": 0.91,
    "input_text": "SELECT ssn, email FROM customers",
    "action_taken": "flag_for_review",
    "fired_at": "2026-03-20T16:05:00Z"
  }
]

Re-embed Trigger Concept

POST /v1/organizations/{org_id}/triggers/{trigger_id}/re-embed-concept

Re-embed the trigger's concept phrase with the current active embedding model. Useful after switching embedding providers.

curl -X POST "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/triggers/f1a2b3c4-d5e6-7890-abcd-ef1234567890/re-embed-concept" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY"

Response (200):

{
  "trigger_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "status": "queued"
}

Branch Lifecycle Triggers

GET /v1/organizations/{org_id}/triggers/branch-lifecycle POST /v1/organizations/{org_id}/triggers/branch-lifecycle

Branch lifecycle triggers fire on branch-related events rather than semantic content matching.

Tier requirement: Growth or higher.

Valid event types: branch_created, query_count_exceeded, storage_exceeded, idle_timeout, merge_requested

curl -X POST "$HATIDATA_BASE/v1/organizations/$HATIDATA_ORG_ID/triggers/branch-lifecycle" \
  -H "Authorization: ApiKey $HATIDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "branch-idle-alert",
    "event_type": "idle_timeout",
    "actions": ["webhook", "agent_notify"],
    "webhook_url": "https://example.com/hooks/branch-events",
    "threshold": 3600,
    "enabled": true
  }'

Vector Search via SQL

As an alternative to the REST API, you can perform vector search directly via SQL using HatiData's built-in semantic functions. These are auto-transpiled to DuckDB's list_cosine_similarity().

`semantic_match` -- Filter by Similarity

-- Find memories semantically similar to a concept (default threshold: 0.7)
SELECT content, agent_id
FROM agent_memories
WHERE semantic_match(embedding, 'NVDA breakout pattern');

-- With custom threshold (0.85)
SELECT content, agent_id
FROM agent_memories
WHERE semantic_match(embedding, 'database migration strategy', 0.85);

`semantic_rank` -- Order by Similarity

-- Rank memories by semantic similarity
SELECT content, semantic_rank(embedding, 'NVDA breakout pattern') AS score
FROM agent_memories
WHERE agent_id = 'grader'
ORDER BY score DESC
LIMIT 5;

`JOIN_VECTOR` -- Semantic Joins

-- Join tables on semantic similarity
SELECT m.content, t.name AS trigger_name
FROM agent_memories m
JOIN_VECTOR triggers t ON semantic_match(m.embedding, t.concept);

How SQL Vector Search Works

When you use semantic_match() or semantic_rank(), HatiData's transpiler emits an __HATI_EMBED__('text') marker. The proxy's embedding pipeline intercepts this marker, sends the text to the configured embedding provider (BGE sidecar or OpenAI), and substitutes the actual vector before DuckDB executes the query. This means you write natural language in your SQL and HatiData handles the embedding transparently.

MCP Tool Equivalents

All operations above are also available via the MCP Tools on the proxy (port 5440). Here is the mapping:

REST API	MCP Tool	Description
`POST .../agent-memory`	`store_memory`	Store a memory entry
`GET .../agent-memory/search`	`search_memory`	Semantic search over memories
`DELETE .../agent-memory/{id}`	`delete_memory`	Delete a memory
--	`get_agent_state`	Get key-value state for an agent
--	`set_agent_state`	Set key-value state for an agent
`POST /v1/cot/ingest`	`log_reasoning_step`	Log a single reasoning step
`GET /v1/cot/sessions/{id}/replay`	`replay_decision`	Replay a decision trace
`GET /v1/cot/sessions`	`get_session_history`	Get session history
`POST .../triggers`	`register_trigger`	Register a semantic trigger
`GET .../triggers`	`list_triggers`	List active triggers
`DELETE .../triggers/{id}`	`delete_trigger`	Delete a trigger
`POST .../triggers/{id}/test`	`test_trigger`	Test a trigger against sample text

Authentication​

Agent Memory API​

Scopes​

Create Memory​

List Memories​

Search Memories (Vector Search)​

Delete Memory​

Embedding Stats​

Re-embed Memory​

Bulk Re-embed​

Chain-of-Thought API​

Scopes & Roles​

List Sessions​

Ingest Traces​

Replay Session​

Verify Session Integrity​

Export Session​

Approve or Reject Decision​

Merge Approval from CoT Context​

Semantic Triggers API​

Scopes​

List Triggers​

Create Trigger​

Update Trigger​

Delete Trigger​

Test Trigger​

List Trigger Fire Events​

Re-embed Trigger Concept​

Branch Lifecycle Triggers​

Vector Search via SQL​

semantic_match -- Filter by Similarity​

semantic_rank -- Order by Similarity​

JOIN_VECTOR -- Semantic Joins​

MCP Tool Equivalents​

Stay in the loop

Authentication

Agent Memory API

Scopes

Create Memory

List Memories

Search Memories (Vector Search)

Delete Memory

Embedding Stats

Re-embed Memory

Bulk Re-embed

Chain-of-Thought API

Scopes & Roles

List Sessions

Ingest Traces

Replay Session

Verify Session Integrity

Export Session

Approve or Reject Decision

Merge Approval from CoT Context

Semantic Triggers API

Scopes

List Triggers

Create Trigger

Update Trigger

Delete Trigger

Test Trigger

List Trigger Fire Events

Re-embed Trigger Concept

Branch Lifecycle Triggers

Vector Search via SQL

`semantic_match` -- Filter by Similarity

`semantic_rank` -- Order by Similarity

`JOIN_VECTOR` -- Semantic Joins

MCP Tool Equivalents