API Reference
POST /v1/activate
Translate a natural language query into EDM significance field filters. Routes memory retrieval by what mattered, not keyword frequency.
/v1/activatescope: extractOverview
/v1/activate takes a natural language query and returns structured EDM field filters that direct significance-weighted retrieval.
Performance: On 18 hand-written significance-typed queries against the locomo-significance corpus, the live /v1/activate endpoint returned the correct artifact in 83.3% (15/18). Raw vector similarity returned 33.3% (6/18) on the same queries. Source: WhatMattered v5 live evaluation, 2026-04-07 (three consecutive runs, all 15/18 — see planning/BENCHMARK_RECONCILIATION_2026-04-24.md). The queries EDM answered exclusively had zero lexical or semantic overlap between question and answer — they required affective structure to find.
Authentication
Bearer API key in the Authorization header. The key must carry the extract scope. Missing or invalid auth returns 401; missing scope returns 403.
Request
POST /v1/activate with Authorization header and JSON body:
POST /v1/activate
Authorization: Bearer dda_live_...
{
"query": "when was I most afraid of losing her",
"subject_vp_id": "vp-01HZ..." // optional
}| Field | Type | Required | Description |
|---|---|---|---|
| query | string | required | Natural language query to translate into EDM field filters. |
| subject_vp_id | string | optional | VitaPass subject identifier. Logged on the activation event for downstream correlation. |
Response
200 OK on success. significance_gate indicates whether the classifier identified the query as a significance-typed query. Billing fires only when the gate is true.
{
"success": true,
"error": null,
"data": {
"activation_id": "act_01HZ...",
"arc_types": ["grief"],
"primary_domain": "core",
"field_filters": [
{ "field": "arc_type", "operator": "eq", "value": "grief", "weight": 0.9 },
{ "field": "tether_type", "operator": "eq", "value": "person", "weight": 0.8 },
{ "field": "emotional_weight", "operator": "gte", "value": 0.7, "weight": 0.7 }
],
"confidence": 0.87,
"significance_gate": true
},
"meta": {
"query": "when was I most afraid of losing her",
"classifier_model": "kimi-k2",
"activated_at": "2026-04-26T10:30:01Z",
"top_k": 10
}
}| Field | Type | Description |
|---|---|---|
| activation_id | string | null | UUID of the persisted arc_activation_event for downstream correlation, audit, or feedback. |
| arc_types | string[] | Arc types detected by the classifier for this query. |
| primary_domain | string | null | Primary EDM domain associated with the detected arc_types. |
| field_filters | FieldFilter[] | Array of structured filters. Each item has field, operator, value, and weight. Pass to your retrieval layer to route by significance. |
| confidence | number | Classifier confidence in the arc_types and field_filters. |
| significance_gate | boolean | True when the classifier identified the query as significance-typed. False signals a factual or conversational query — billing does not fire. |
Pricing
$0.001 per significance query. Only fires on significance-typed queries (those requiring arc_type routing). Factual or conversational queries are not billed.
Errors
| Status | Condition | Message |
|---|---|---|
| 400 | Missing query | 'query' field is required |
| 401 | Bad or missing API key | Unauthorized |
| 403 | Key lacks extract scope | API key does not have 'extract' scope |
| 429 | Rate limit exceeded | Rate limit exceeded |
| 500 | Activation pipeline failure | Activation failed (or upstream error message) |
Example Request
const response = await fetch(
'https://deepadata.com/api/v1/activate',
{
method: 'POST',
headers: {
'Authorization': 'Bearer dda_live_...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'when was I most afraid of losing her'
})
}
);
const { data } = await response.json();
// data.field_filters → pass to your memory system for retrievalMCP Usage
If using the MCP server, deepadata_activate handles this automatically:
npx deepadata-edm-mcp-server