Core API

Extract

Interpret natural-language content into a structured EDM artifact with 96 fields across 10 domains. The core operation for creating affective records.

POST/v1/extractscope: extract

Overview

The Extract endpoint uses an LLM to interpret natural-language content and map it to the EDM (Emotional Data Model) schema. It captures expressed emotional significance, themes, relationships, and governance metadata.

Note: This is interpretation, not inference. DeepaData captures what was emotionally significant — expressed or interpreted — not predictions about emotional states. This distinction is critical for EU AI Act Article 5 compliance.

Request Body

Field	Type	Required	Description
content	string	required	The natural-language text to interpret (max 50,000 characters).
image	string	optional	Base64-encoded image for multimodal interpretation.
provider	string	optional	LLM provider: 'openai' \| 'anthropic' \| 'kimi'. Default: from environment.
model	string	optional	Provider-specific model (e.g., 'gpt-4o', 'claude-3-5-sonnet').
options.stateless	boolean	optional	If true, strips identifying info for privacy mode. Default: false.
jurisdiction	string	optional	Governance jurisdiction: 'GDPR' \| 'CCPA' \| 'HIPAA' \| 'PIPEDA' \| 'LGPD' \| 'None' \| 'Mixed'.
consent_basis	string	optional	Legal basis: 'consent' \| 'contract' \| 'legitimate_interest' \| 'vital_interest' \| 'none'. Default: 'consent'.
parent_id	string	optional	UUID linking to parent artifact for session threading.
tags	string[]	optional	User-defined labels for organizing artifacts.
visibility	string	optional	Access level: 'private' \| 'shared' \| 'public'. Default: 'private'.
pii_tier	string	optional	PII sensitivity: 'none' \| 'low' \| 'moderate' \| 'high' \| 'extreme'.
locale	string	optional	Locale identifier (e.g., 'en-us').

Example Request

curl -X POST https://www.deepadata.com/api/v1/extract \
  -H "Authorization: Bearer dda_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Client expressed relief after discussing coping strategies for work stress. They mentioned feeling hopeful about implementing the breathing exercises we practiced.",
    "jurisdiction": "HIPAA",
    "consent_basis": "consent",
    "visibility": "private",
    "pii_tier": "moderate"
  }'

Example Response

{
  "success": true,
  "data": {
    "artifact": {
      "meta": {
        "id": "edm_01HV8X3K2M...",
        "version": "0.5.0",
        "created_at": "2026-02-24T10:30:00.000Z"
      },
      "core": {
        "anchor": "Discussing coping strategies for work stress",
        "spark": "Relief and hope after learning breathing exercises"
      },
      "constellation": {
        "emotion_primary": "relief",
        "emotion_secondary": "hope",
        "valence": 0.7,
        "arousal": 0.4
      },
      "milky_way": {
        "themes": ["stress management", "coping skills", "therapy progress"]
      },
      "gravity": {
        "relationships": ["therapist-client"]
      },
      "impulse": {
        "actions": ["practiced breathing exercises"]
      },
      "governance": {
        "jurisdiction": "HIPAA",
        "consent_basis": "consent",
        "visibility": "private",
        "pii_tier": "moderate"
      },
      "telemetry": {
        "entry_confidence": 0.92,
        "extraction_method": "llm"
      }
    }
  },
  "meta": {
    "version": "0.5.0",
    "extracted_at": "2026-02-24T10:30:01.000Z",
    "latency_ms": 2340,
    "stateless": false
  }
}

Error Codes

400

'content' field is required and must be a string

400

Content exceeds maximum length of 50,000 characters

401

Missing or invalid API key

403

API key does not have 'extract' scope

429

Rate limit exceeded. Check Retry-After header.

500

Interpretation failed (LLM error)

Validate API

Verify artifact against schema

Issue / Seal API

Seal artifact into .ddna envelope

Quick Start

Full Extract → Seal → Verify workflow

EU AI Act Compliance

Interpretation vs inference