API Reference

The Dublr API lets you create sessions, send messages, and retrieve results programmatically — integrate negotiation and survey capabilities into your own tools.

Base URL https://api.dublr.ai/v1

Early access: The Dublr API is in private beta. Request access at hello@dublr.ai. API keys are issued per-organization.

Authentication

All API requests require a bearer token in the Authorization header. Keys can be managed from your dashboard settings.

# Example cURL request
curl https://api.dublr.ai/v1/sessions \
  -H "Authorization: Bearer dbl_sk_..." \
  -H "Content-Type: application/json"

Sessions

A session is a single conversation thread with a synthetic persona (Negotiate) or population (Survey). Sessions persist until explicitly deleted.

POST /sessions Create a new session

Creates a new negotiation or survey session and returns a session object with an ID you'll use for subsequent requests.

Request body

Parameter	Type	Description
`mode`required	`"negotiate" \| "survey"`	The session type.
`persona_id`optional	`string`	ID of a saved persona. Omit to use the default for the mode.
`topic`optional	`string`	The negotiation topic or survey subject.
`goal`optional	`string`	Desired outcome for negotiate mode.
`community`optional	`string`	Target community for survey mode. One of `urban`, `policy`, `business`, `healthcare`, or a custom string.
`population_size`optional	`integer`	Number of synthetic respondents for survey mode. Default: `25`. Range: 5–100.

Example request

POST /v1/sessions
{
  "mode": "negotiate",
  "topic": "Q3 infrastructure budget reallocation",
  "goal": "Secure a $2.4M reallocation from facilities to infrastructure",
  "persona_id": "prs_maria_budget_director"
}

Response

{
  "id": "ses_01HXYZ...",
  "mode": "negotiate",
  "status": "active",
  "created_at": "2026-06-13T14:22:00Z",
  "persona": {
    "id": "prs_maria_budget_director",
    "name": "Maria Santos",
    "role": "Budget Director"
  },
  "opening_message": "I've reviewed the Q3 projections. I'll be honest — I'm concerned about the timing of this request..."
}

POST /sessions/{session_id}/messages Send a message and get a response

Sends a user message to the session and returns the persona's response along with updated metrics.

Request body

Parameter	Type	Description
`content`required	`string`	The user's message.
`role`optional	`"user"`	Always `user` for human messages. Default: `user`.

Response

{
  "message_id": "msg_01HYZ...",
  "response": "I understand the urgency, but I need to see the full impact analysis...",
  "metrics": {
    "flexibility": 0.62,
    "effectiveness": 0.74,
    "sensibility": 0.81,
    "confidence": 0.58
  },
  "coaching_note": "Good acknowledgment of their constraint. Try quantifying the risk of inaction."
}

POST /surveys/{session_id}/questions Submit a survey question

Submits a question or statement to the synthetic population and returns the sentiment distribution across all respondents.

Request body

Parameter	Type	Description
`question`required	`string`	The statement or question to put to the population.
`framing`optional	`string`	Context framing for the question. Affects how the population interprets the statement.

Response

{
  "question_id": "qst_01HZA...",
  "distribution": {
    "strong_support": 18,
    "support": 41,
    "neutral": 12,
    "oppose": 20,
    "strong_oppose": 9
  },
  "dominant_theme": "Cost concerns outweigh environmental benefits for middle-income respondents.",
  "shift_from_prior": +4 // net support change vs previous question
}

Errors

Dublr uses standard HTTP response codes. Errors return a JSON body with a code and human-readable message.

Code	Meaning
`400`	Bad request — missing or invalid parameters.
`401`	Unauthorized — invalid or missing API key.
`404`	Not found — session or persona does not exist.
`429`	Rate limited — reduce request frequency. See rate limit headers.
`500`	Internal error — Dublr-side issue. Retry with exponential backoff.