API Reference

POST /v1/activate_reason

Three-step significance reasoning. Classify the query, retrieve 50 candidates from a TurboPuffer namespace, then reason across EDM fields to return a grounded answer with cited sources.

POST/v1/activate_reasonscope: extract

Overview

/v1/activate_reason extends /v1/activate with a reasoning step. Where /v1/activate returns field filters and arc_types in a single classification call, /v1/activate_reason runs the three-stage pipeline defined in ADR-0018.

Step	Component	Output
1. Classify	Kimi K2 classifier	arc_types, field_filters, reasoning_fields, significance_gate
2. Retrieve	TurboPuffer ANN	50 candidate artifacts, field-filtered, vector-ranked
3. Reason	Kimi K2 reasoning agent	answer grounded in candidates, sources sliced to top_k (default 5)

Key constraint: reasoning only functions over EDM artifacts. Patterns such as identity_thread, tether_type, and regulation_state exist only because EDM encoded them at capture time. Without EDM artifacts, the reasoning layer degrades to generic RAG.

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_reason with Authorization header and JSON body:

POST /v1/activate_reason
Authorization: Bearer dda_live_...

{
  "query": "when was I most afraid of losing her",
  "namespace": "pepys-1665",
  "top_k": 5,
  "subject_vp_id": "vp-01HZ..." // optional
}

Field	Type	Required	Description
query	string	required	Natural language query to classify and reason over.
namespace	string	required	TurboPuffer namespace to retrieve candidates from. Each subject corpus lives in its own namespace.
top_k	number	optional	Number of source artifacts to return alongside the answer. Default 5, max 20. Retrieval always pulls 50 candidates for reasoning regardless of top_k.
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. If it is false, the reasoning steps are skipped, no reasoning event is written, the call is not billed, and answer is null.

{
  "success": true,
  "data": {
    "arc_reasoning_event_id": "rea_01HZ...",
    "answer": "The entry that most directly evidences this fear is...",
    "sources": [
      {
        "date": "1665-09-04",
        "narrative": "...",
        "arc_type": "grief",
        "emotional_weight": 0.82,
        "identity_thread": "marriage",
        "tether_type": "person"
      }
    ],
    "reasoning_fields_used": ["tether_type", "identity_thread", "viscosity"],
    "arc_types": ["grief"],
    "confidence": 0.87,
    "significance_gate": true,
    "candidate_count": 50
  },
  "meta": {
    "query": "when was I most afraid of losing her",
    "namespace": "pepys-1665",
    "reasoning_model": "kimi-k2",
    "activated_at": "2026-04-26T10:30:01Z"
  }
}

Field	Type	Description
arc_reasoning_event_id	string \| null	UUID of the persisted reasoning event for partner-side correlation, audit, or feedback. Null when significance_gate is false.
answer	string \| null	Reasoning agent response grounded in the retrieved candidates. Null when significance_gate is false.
sources	array	Top-k candidate artifacts surfaced for the answer. Each carries date, narrative, arc_type, emotional_weight, identity_thread, tether_type.
reasoning_fields_used	string[]	EDM fields the reasoning agent was instructed to attend to, derived from arc_signatures.reasoning_weights (ADR-0019).
arc_types	string[]	Arc types detected by the classifier for this query.
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 short-circuits reasoning and billing.
candidate_count	number	Number of candidates retrieved from TurboPuffer for reasoning. 50 on a successful reasoning pass, 0 when significance_gate is false.

Pricing

$0.005 per significance-reasoning query — five times the /v1/activate rate ($0.001), reflecting the additional retrieval and reasoning stages on top of classification. Billed against a dedicated activate_reason meter, separate from the activate meter.

Billing fires only when significance_gate is true. Factual or conversational queries that fail the gate return early without retrieval, reasoning, or charge.

Errors

Status	Condition	Message
400	Missing query	'query' field is required
400	Missing namespace	'namespace' 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	Reasoning pipeline failure	Reasoning failed (or upstream error message)

Example Request

const response = await fetch(
  'https://deepadata.com/api/v1/activate_reason',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer dda_live_...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: 'when was I most afraid of losing her',
      namespace: 'pepys-1665',
      top_k: 5
    })
  }
);
const { data } = await response.json();
// data.answer       → grounded reasoning response
// data.sources      → cited candidate artifacts
// data.arc_reasoning_event_id → server-side event id for correlation

Activate API

Single-step classification — field filters and arc_types

Extract API

Create EDM artifacts from content

Pricing

Per-event rates and conformance tiers

POST /v1/activate_reason

Overview

Authentication

Request

Response

Pricing

Errors

Example Request

Related