Core API
Observe
Capture salience at topic-shift boundaries. A lightweight observation layer that detects emotional shifts without full EDM extraction.
/v1/observescope: extractOverview
The Observe endpoint captures salience records at topic-shift boundaries. Unlike full extraction, it produces lightweight records focused on "what changed + why it matters" rather than complete 96-field EDM artifacts.
Use case: Real-time monitoring of conversations for emotional shifts, escalation signals, and recurrence patterns. Observe records feed into the Observe dashboard for drift detection, escalation matrices, and coverage reports.
Trigger Types
Observe detects several trigger types based on content analysis and caller-provided hints.
| Trigger | Description |
|---|---|
| topic_shift | Content introduces a new topic or theme (default) |
| affect_shift | Emotional valence or intensity changed significantly |
| risk_signal | Content contains potential safety or escalation indicators |
| recurrence | Previously observed theme reappears |
| user_mark | Caller explicitly requested observation (force=true) |
| session_close | End of session summary (is_session_close=true) |
| time_gap | Significant time elapsed since last interaction |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| content | string | required | The text content to observe (max 20,000 characters). |
| subject_id | string | required | Identifier for the subject being observed. |
| session_id | string | optional | Session identifier for grouping observations. |
| parent_id | string | optional | UUID linking to parent artifact for threading. |
| turn_range | [string, string] | optional | Start and end turn IDs covered by this observation. |
| previous | object | optional | Previous state for shift detection (state_change, affect_intensity, affect_valence). |
| force | boolean | optional | Force observation even without detected shift (user_mark trigger). |
| is_session_close | boolean | optional | Indicates this is a session-end summary. |
| time_since_last_ms | number | optional | Milliseconds since last observation (enables time_gap trigger). |
| recurring_themes | string[] | optional | Known themes to check for recurrence. |
Example Request
curl -X POST https://www.deepadata.com/api/v1/observe \
-H "Authorization: Bearer dda_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "I have been thinking more about what we discussed last week. The anxiety around presentations has come back.",
"subject_id": "user-123",
"session_id": "session-456",
"recurring_themes": ["presentation anxiety", "work stress"]
}'Example Response
{
"success": true,
"data": {
"record": {
"passage_hash": "a1b2c3d4...",
"trigger": "recurrence",
"topic_label": "presentation anxiety",
"affect_valence": "negative",
"affect_intensity": 0.6,
"state_change": "Anxiety pattern re-emerging after previous improvement",
"escalate_recommended": false,
"themes": ["anxiety", "presentations", "work stress"],
"risk_markers": []
},
"shift_detected": true,
"confidence": 0.85,
"escalate_recommended": false
},
"meta": {
"observed_at": "2026-02-24T10:30:01.000Z",
"latency_ms": 1240
}
}Response Fields
record.trigger
The type of shift that triggered the observation
record.topic_label
Brief label describing the observed topic
record.affect_valence
Emotional valence: positive, negative, mixed, or neutral
record.affect_intensity
Emotional intensity score (0.0 to 1.0)
record.state_change
Human-readable description of what changed
shift_detected
Whether a meaningful shift was detected
escalate_recommended
Whether the system recommends escalation/intervention
Error Codes
'content' field is required and must be a string
'subject_id' field is required and must be a string
Content exceeds maximum length of 20,000 characters
Missing or invalid API key
API key does not have 'extract' scope
Rate limit exceeded. Check Retry-After header.