EmpatiQ API / Documentation

Emotion. Emery.
Digital twins.

Integrate emotion analysis, the full Emery experience with memory and tools, and digital twin creation into your product.

Explore emotion analysis, Emery conversations, and digital twin creation. The persona catalog and persona chat reference covers the existing public endpoints.

Quickstart · persona API#

1. Arrange API access

   Contact the EmpatiQ team to set up your API account, personas, and usage allowance. You’ll need an API key and at least one active persona.

2. Save your key on your server

   Set EMPATIQ_API_KEY in your server environment or secret manager. Don’t include it in frontend code or a mobile app bundle.

   TerminalCopy

   export EMPATIQ_API_KEY="emp_YOUR_API_KEY"

3. List your personas

   Make an authenticated request and copy an id from the returned list.

   cURLJavaScriptPython

   TerminalCopy

   curl https://empatiqapp.com/api/platform/v1/personas \
     -H "Authorization: Bearer $EMPATIQ_API_KEY"

   An empty personas array means the account has no active personas. Ask your account administrator to check persona setup.

4. Send a message

   Replace PERSONA_ID with the ID you just copied.

   cURLJavaScriptPython

   TerminalCopy

   curl https://empatiqapp.com/api/platform/v1/personas/PERSONA_ID/chat \
     -H "Authorization: Bearer $EMPATIQ_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "message": "I want to talk about what happened.",
       "conversationHistory": []
     }'

   Example response:

   JSONCopy

   {
     "message": "I'm glad you brought it up. What would you like me to understand?",
     "success": true
   }

Authentication#

Send your API key as a Bearer token. A key authorizes requests for the platform account that owns it.

Authorization: Bearer emp_YOUR_API_KEY

Keys start with emp_ followed by 32 hexadecimal characters. The raw key is returned once when created; only its SHA-256 hash and display prefix are stored.

Keep keys on your backend

Route requests through your server. Browser CORS support does not make an API key safe to publish. For rotation, create a replacement, update your server, then revoke the previous key.

Key creation and revocation use authenticated account-management endpoints. A public API key cannot create more keys. Contact your account administrator for provisioning.

Emotion analysis#

Analyze the emotional tone expressed in a single user or assistant message. Return a primary label, intensity, confidence, and eight independent emotion scores.

Set EMPATIQ_INTEGRATION_URL to the emotion-analysis URL supplied for your integration. The following request and result show an example format.

{
  "role": "user",
  "text": "I felt unheard when you left before I finished."
}

{
  "emotion": {
    "emotion": "sadness",
    "intensity": "mid",
    "confidence": 0.92,
    "scores": {
      "joy": 0.01,
      "trust": 0.08,
      "fear": 0.15,
      "surprise": 0.04,
      "sadness": 0.55,
      "disgust": 0.02,
      "anger": 0.32,
      "anticipation": 0.07
    }
  }
}

These fields match the app’s existing message-emotion result. The analysis describes the tone of the supplied text, not a diagnosis or a claim about the speaker’s internal state. Ambiguous text can return unclear; low-evidence text can return neutral.

# Use the endpoint URL supplied for your integration.
curl "$EMPATIQ_INTEGRATION_URL" \
  -H "Authorization: Bearer $EMPATIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "role": "user",
  "text": "I felt unheard when you left before I finished."
}'

The full Emery experience#

Bring ongoing Emery conversations into your application, including persistent memory, relevant context, and connected tools. Emery can carry a conversation forward, work with shared material, and take actions through the tools connected to your integration.

Conversation memory and tools

During setup, define how your users and conversations are identified, what context is remembered, how long it is retained, and which tools Emery may use. Tools can connect documents, notes, or actions in your own workflow.

The example below continues an existing conversation and saves a next step. Set EMPATIQ_INTEGRATION_URL to your Emery integration URL. Conversation IDs and tool names are illustrative; follow the contract agreed for your integration.

{
  "message": "I still feel unheard by Alex. Help me continue our conversation and save the next step.",
  "conversation_id": "conversation_example",
  "locale": "en"
}

{
  "conversation_id": "conversation_example",
  "message": "Earlier, you wanted to explain the hurt without turning this into another argument. Let’s build on the wording we worked on.\n\nYou could say: “When you left before I finished, I felt unheard. I’d like to finish what I was saying, and then hear your side. Is now a good time?”\n\nI’ve saved your next step to this conversation: ask Alex for a time to talk, start with what happened, and leave room for their perspective.",
  "emotion": {
    "emotion": "sadness",
    "intensity": "mid",
    "confidence": 0.92,
    "scores": {
      "joy": 0.01,
      "trust": 0.08,
      "fear": 0.15,
      "surprise": 0.04,
      "sadness": 0.55,
      "disgust": 0.02,
      "anger": 0.32,
      "anticipation": 0.07
    }
  },
  "tool_results": [
    {
      "name": "recall_conversation",
      "status": "completed",
      "summary": "Retrieved the earlier conversation goal and wording."
    },
    {
      "name": "save_note",
      "status": "completed",
      "summary": "Saved the next step to this conversation."
    }
  ]
}

In this example, message contains Emery’s complete reply, conversation_id keeps continuity, and tool_results reports the configured actions used during the turn. emotion uses the fields described in emotion analysis.

Your integration determines the exact response shape, memory behavior, and tool outputs. The experience includes the conversation and its actions, as well as the reply your interface displays.

# Use the endpoint URL supplied for your integration.
curl "$EMPATIQ_INTEGRATION_URL" \
  -H "Authorization: Bearer $EMPATIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "I still feel unheard by Alex. Help me continue our conversation and save the next step.",
  "conversation_id": "conversation_example",
  "locale": "en"
}'

Digital twin creation#

Create a conversational digital twin of a person or role for practice, simulation, or a custom product experience. Describe its background, communication style, emotional behavior, and the situation it should respond to.

Provide a profile, scenario, or source material as part of setup. We work with your team to define what the twin represents, the context it can use, and how it participates in conversations.

{
  "name": "Alex",
  "description": "A team lead who is direct, values clear evidence, and becomes defensive when deadlines slip.",
  "purpose": "Practice discussing a missed deadline and agree on a recovery plan.",
  "context": "The project is one week behind schedule. The learner needs to explain the delay and propose a realistic next step."
}

{
  "twin_id": "twin_example",
  "name": "Alex",
  "description": "A direct team lead with a focus on evidence, deadlines, and accountability."
}

The example returns a twin_id your application can use to identify the twin. Creation fields, source-material handling, and the conversation interface are agreed for your integration. Set EMPATIQ_INTEGRATION_URL to your digital twin creation URL.

# Use the endpoint URL supplied for your integration.
curl "$EMPATIQ_INTEGRATION_URL" \
  -H "Authorization: Bearer $EMPATIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Alex",
  "description": "A team lead who is direct, values clear evidence, and becomes defensive when deadlines slip.",
  "purpose": "Practice discussing a missed deadline and agree on a recovery plan.",
  "context": "The project is one week behind schedule. The learner needs to explain the delay and propose a realistic next step."
}'

Discuss a digital twin integration

List personas#

Returns active personas owned by the API key’s account. There are no request parameters or pagination fields.

{
  "personas": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Maya",
      "description": "A persona for practicing supportive conversations",
      "avatar_theme": "notionists",
      "avatar_url": null,
      "voice_id": "alloy",
      "is_active": true
    }
  ]
}

Persona instructions (system_prompt) are kept on the server and are not returned. Errors: 401, 500.

Send a message#

Send a message to a persona owned by your account. Replace {id} with a persona UUID. Include Content-Type: application/json.

{
  "message": "I want to talk about what happened.",
  "conversationHistory": []
}

{
  "message": "I'm glad you brought it up. What would you like me to understand?",
  "success": true
}

message contains the generated reply; success is true on success. Output varies with the persona and conversation. This endpoint returns one JSON response without streaming. Errors: 401, 403, 404, 500.

Public persona catalog#

This endpoint uses the deployment origin, outside the /v1 base path. It needs no API key. Replace {userId} with your platform user UUID.

{
  "personas": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Maya",
      "description": "A persona for practicing supportive conversations",
      "avatar_theme": "notionists",
      "avatar_url": null,
      "voice_id": "alloy",
      "is_active": true
    }
  ],
  "showBranding": true,
  "hasMinutes": true
}

The personas array contains the same public fields as the authenticated listing. showBranding indicates whether to show EmpatiQ branding; hasMinutes indicates available allowance.

Keep the conversation going#

Emery conversation memory

An Emery integration can use persistent conversation IDs and memory, together with connected tools. Keep each user’s conversations associated with that user, and follow the memory and retention behavior agreed during setup.

Persona chat history

The existing persona chat endpoint is stateless. Keep history in your application and include both sides of previous exchanges in the next request. Do not add the current message to history before sending it.

{
  "message": "I felt like I wasn't being heard.",
  "conversationHistory": [
    {
      "role": "user",
      "content": "I want to talk about what happened."
    },
    {
      "role": "assistant",
      "content": "I'm glad you brought it up. What would you like me to understand?"
    }
  ]
}

After a successful response, append your user message and the returned assistant message to history. Keep the order chronological and serialize requests within a conversation so replies remain in order.

The persona chat endpoint uses app-managed history. See the full Emery experience for an integration with ongoing conversation memory and tools.

Usage & limits#

Chat requests consume your platform account’s minutes allowance. The server measures generation time with a minimum of six seconds per successful call, then rounds each call up to whole minutes. A short successful call therefore consumes at least one minute of allowance.

Once the account reaches its allowance, chat returns 403 with Minutes limit exhausted. Persona listings do not consume chat minutes. Allowances and commercial terms depend on your API account.

API access and usage are separate from an EmpatiQ Practice subscription. Contact us to confirm an allowance and plan for your integration.

There is no key-authenticated usage, billing, persona-authoring, or account-management endpoint in this public reference. The current chat implementation caps generated output at 1,024 tokens per call.

Handle errors#

The responses below apply to the existing persona API. For a tailored integration, use the error contract supplied with your endpoint.

Check the HTTP status before using a response. Errors return a JSON object with an error string.

{ "error": "Invalid API key" }

Chat has no idempotency key. Avoid automatically replaying a timed-out POST: it may already have completed and consumed allowance. Use a bounded retry policy for transient failures.