Documentation

API documentation

One endpoint, one request body. Send the interaction with whatever context you hold on it and Humoniq returns the response to send and, if you ask for them, the actions that should go with it.

POST https://api.humoniq.com/v1/responsesAccess by request

Quickstart

Authenticate with a bearer token, post the interaction, read the response. There is no SDK to install and no model to select. The example below is a real duplicate-charge complaint arriving by email.

Request

curl https://api.humoniq.com/v1/responses \
  -H "Authorization: Bearer $HUMONIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "context": {
      "thread": [
        {
          "role": "customer",
          "text": "I was charged twice for March and nobody has replied in a week. Can you refund one and tell me why it happened?",
          "sent_at": "2026-04-02T09:14:00Z"
        }
      ],
      "customer": { "id": "cus_8412", "plan": "growth", "locale": "en-GB" },
      "account_facts": { "duplicate_charge": true, "invoice": "INV-2291" }
    },
    "return": ["response", "next_actions"]
  }'

Response

{
  "id": "res_01JQ4W8ZK9RT",
  "mode": "generated",
  "intent": {
    "label": "billing.duplicate_charge",
    "confidence": 0.94
  },
  "response": {
    "text": "Hi Sam, you were charged twice for March and that one is on us...",
    "language": "en-GB",
    "channel": "email"
  },
  "scores": {
    "style": 0.91,
    "accuracy": 0.97,
    "solution": 0.89
  },
  "next_actions": [
    {
      "type": "refund.issue",
      "label": "Refund the duplicate charge on INV-2291",
      "confidence": 0.88,
      "payload": { "invoice": "INV-2291", "amount": "full" }
    },
    {
      "type": "ticket.close",
      "label": "Close the ticket once the refund clears",
      "confidence": 0.72,
      "payload": { "after": "refund.issue" }
    }
  ],
  "usage": { "input_tokens": 812, "output_tokens": 214 }
}

Augmenting an agent draft

Pass the text your agent has already written as draft and the reply comes back sharpened rather than rewritten from nothing.

Node

const result = await fetch("https://api.humoniq.com/v1/responses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HUMONIQ_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    channel: "chat",
    draft: agentDraft,
    context: { thread, customer, account_facts: facts },
    return: ["response", "next_actions"]
  })
})

const { response, next_actions } = await result.json()

Inputs

The input is the customer interaction and its context. The more of that context you send, the less Humoniq has to infer, and inference is where a wrong answer starts. Nothing you send is required to follow a schema beyond the fields below.

channelstringRequired: Where the interaction is happening: email, chat, ticket, voice or custom. It sets the length and formatting budget, so the same thread returns a three-line chat reply or a structured email.
context.threadarray of message objectsRequired: The conversation so far, oldest first. Each message takes a role of customer, agent or system, the text itself and an optional sent_at timestamp. Send the whole thread rather than the last message, since intent usually lives in what came before.
context.customerobjectOptional: Who you are talking to. Any of id, plan, segment, locale, lifetime value or signup date. Nothing here is mandatory, and every field you add sharpens the intent prediction.
context.account_factsobjectOptional: Free-form key and value pairs that are true about this account right now: an open invoice, a failed payment, seats in use, a shipment that is late. Humoniq treats these as ground truth and will not contradict them.
draftstringOptional: An agent draft to work from. Include it and the reply comes back as an augmented version of what your person wrote, holding their intent and fixing the gaps. Leave it out and the response is generated from scratch.
localestringOptional: Force an output language as a BCP 47 tag such as fr-CA. Defaults to auto, which detects the customer language from the thread and answers in it.
optimize_forarray of stringsOptional: Which of style, accuracy and solution to weight hardest when several drafts score closely. All three are always evaluated. Defaults to a balance of the three.
returnarray of stringsOptional: What you want back: response, next_actions, intent or scores. Defaults to response and intent. Ask only for what you use, since next_actions costs a little more latency.

Outputs

The output is a quality-maximized response, plus optional next actions. The response has already been drafted, scored and rewritten inside the call, so what you receive is the best version rather than a first pass for you to check.

response.textstringOptional: The quality-maximized response. This is the draft that survived scoring on style, accuracy and solution, written for the channel you named and ready to send or to hold for review.
response.languagestringOptional: The language the response was written in, as a BCP 47 tag. Matches the customer unless you forced a locale.
modestringOptional: Either augmented, when you supplied a draft and it was refined, or generated, when the response was written from the context alone.
intentobjectOptional: The predicted intent as a dotted label such as billing.duplicate_charge, with a confidence between 0 and 1. Useful for routing, tagging and reporting even when you discard the response.
scoresobjectOptional: The three factor scores for the returned draft. Gate on these if you want auto-send above a threshold and human review below it.
next_actionsarray of action objectsOptional: Optional. What should happen alongside the reply, each with a type, a human-readable label, a confidence and a structured payload. Surface them as one-click suggestions for the agent, or run them directly if the confidence clears your bar. Humoniq never performs an action itself.
usageobjectOptional: Input and output token counts for the call, so you can attribute cost per queue or per team.

Integration notes

The details that decide how this behaves once it is in front of real customers.

Language

Humoniq detects the customer language from the thread and answers in it, including when a thread switches language halfway through. Formality is matched too, so a message written informally in German does not come back in the formal register. Set locale to force a language, which is the usual choice when your team can only support replies in the ones they read. If a thread mixes languages, the most recent customer message wins.

Channels

One endpoint serves every channel and the channel field changes the shape of what comes back. Chat returns short turns with no greeting or sign-off, email returns a full message with structure, ticket returns a reply with the internal note separated out, and voice takes a transcript and returns the wrap-up plus the follow-up message. Set channel to custom and pass a format hint if you serve a surface that is none of these.

Authentication and keys

Bearer token in the Authorization header. Keys are server-side only, so call Humoniq from your backend and never from a browser or mobile client. Each key is scoped to one environment, and the sandbox key returns real responses against synthetic accounts so you can integrate before any customer data moves.

Retries and idempotency

Send an Idempotency-Key header with each request and a retry after a timeout returns the original response instead of generating a second one. Errors come back with standard HTTP status codes and a machine-readable error code in the body. Rate limits are per key and returned on every response in the usual headers.

Data handling

Interaction content is processed to produce the response and is not used to train shared models across customers. Refinement happens against your own outcome signals, inside your own account. Retention windows and regional processing are set per agreement, so tell us your constraints when you request access.

Access

Contact for access

Humoniq is in limited access while we work with early teams one at a time. Tell us the channel, the volume and the systems it would sit between, and we will come back with a sandbox key, rate limits and pricing for your case.

Request access access@humoniq.com

Already talking to us? Reply on the same thread and we will get your key moved up. Terms are in the Terms of Service.