Core API

Extract

Interpret natural-language content into a structured EDM artifact. Extraction depth depends on chosen profile: Essential (24 fields), Extended (50 fields), or Full (96 fields). 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').
subject_id	string	optional	Your internal user identifier. Links the artifact to a subject for longitudinal tracking and VitaPass association.
profile	string	optional	Extraction depth: 'essential' (24 fields) \| 'extended' (50 fields) \| 'full' (96 fields) \| 'partner:<profile_id>' (e.g. 'partner:com.deepadata.journaling.v1'). Default: 'essential'. See EDM v0.8.0 Section 3.7.6.
chunking_strategy	string	optional	Metadata label for analytics (e.g., 'per_turn', 'per_session', 'semantic'). Does not affect extraction behavior.

Chunking: Split content before calling /v1/extract using your preferred tool — LangChain RecursiveCharacterTextSplitter, LlamaIndex node parsers, or custom logic. Pass chunking_strategy as a label for analytics. Each chunk is one /v1/extract call.

Partner Profiles: The profile field accepts partner: prefixed partner profile IDs per EDM v0.8.0 Section 3.7.6. The partner: prefix is required. Bare profile IDs without the prefix are non-conforming per ADR-0017.

{
  "content": "...",
  "profile": "partner:com.deepadata.journaling.v1"
}

Example Request

curl -X POST https://deepadata.com/api/v1/extract \
  -H "Authorization: Bearer dda_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Just got these photos and what an absolute ball I had competing in my physie comps! About 8 years ago I was diagnosed with psoriatic arthritis which affects my joints. However continuing to move really keeps it at bay. Not only does physie do this for me it is also so good for my mental health.",
    "profile": "essential",
    "subject_id": "user-12345",
    "jurisdiction": "GDPR",
    "consent_basis": "consent"
  }'

Example Response

{
  "success": true,
  "data": {
    "artifact": {
      "meta": {
        "id": "edm_01HV8X3K2M...",
        "version": "0.8.0",
        "profile": "essential",
        "created_at": "2026-03-15T10:30:00.000Z",
        "consent_basis": "consent",
        "pii_tier": "moderate"
      },
      "core": {
        "anchor": "physie competitions",
        "spark": "receiving competition photos",
        "wound": "psoriatic arthritis",
        "fuel": "supportive community of women",
        "bridge": "returning to dance",
        "echo": "feeling youthful again"
      },
      "constellation": {
        "emotion_primary": "joy",
        "emotion_subtone": ["pride", "gratitude"],
        "narrative_arc": "transformation"
      },
      "governance": {
        "jurisdiction": "GDPR",
        "consent_basis": "consent",
        "visibility": "private",
        "pii_tier": "moderate",
        "subject_rights": {
          "portable": true,
          "erasable": true
        }
      },
      "telemetry": {
        "entry_confidence": 0.94,
        "extraction_model": "claude-sonnet-4-20250514"
      }
    }
  },
  "meta": {
    "version": "0.8.0",
    "extracted_at": "2026-03-15T10:30:01.000Z",
    "latency_ms": 1840,
    "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