API quickstart

One endpoint, POST /v1/ask. Describe who to ask and what to ask, and get back each Digital Twin's answers as JSON.

1. Get an API key

In the platform, go to Developers → API Keys and create a key. The examples below read it from an environment variable:

export ORIGINALVOICES_API_KEY="your-api-key"

Every request sends it as a Bearer token: Authorization: Bearer <key>.

2. Ask a question

curl https://api.originalvoices.ai/v1/ask \
  -H "Authorization: Bearer $ORIGINALVOICES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": { "audience": "US, 25-45, tech professionals" },
    "questions": [
      { "type": "open", "question": "What frustrates you most about project management tools?" }
    ]
  }'

Calls take tens of seconds, so allow a timeout of a few minutes. The TypeScript SDK handles that, plus types and errors, for you.

3. Read the answers

{
  "data": {
    "asked": 25,
    "participants": [
      {
        "twinId": "…",
        "demographics": { "age": 34, "gender": "Male", "country": "US" },
        "answers": {
          "q1": { "answer": "Too many notifications, and nobody updates the board…", "confidence": "high" }
        }
      }
    ]
  }
}

Each participant is one Twin. Answers are keyed by question id, which defaults to q1, q2 and so on.

Next steps

Asking questionsChoice questions, saved audiences, studies and the full response.Errors & limitsStatus codes, timeouts and billing.ReferenceEvery endpoint and field.