Quickstart

Five minutes from "I have a paid account" to "I'm reading transcripts in code."

1. Generate an API key

In the app: Settings → API Keys → Generate API Key.

Give the key a name you'll recognize (e.g. Zapier — onboarding study). The full key is shown once — copy it now. You'll only ever see ue_live_••••••••wXyZ after this.

If you lose a key, generate a new one and revoke the old.

2. Verify the key works

Every API client should start with a GET /v1/me to confirm the key is active and identify the workspace it belongs to.

curl https://api.userevaluation.com/v1/me \
  -H "Authorization: Bearer ue_live_..."

A 200 OK with data.email matching your account means you're in.

If you see:

Code	What it means
401 unauthorized	Header missing or key invalid/revoked
402 plan_required	Your account is on Free — upgrade to use the API
403 forbidden	You're signed in as a participant, not a researcher

3. List your projects

curl https://api.userevaluation.com/v1/projects \
  -H "Authorization: Bearer ue_live_..."

{
  "data": [
    { "id": "65f8...", "name": "Onboarding study", ... }
  ],
  "meta": { "next_cursor": null }
}

4. Pull a transcript

Files in UE include videos, audio recordings, PDFs, and other documents. Take any file id from a project's files sub-resource:

curl https://api.userevaluation.com/v1/projects/<projectId>/files \
  -H "Authorization: Bearer ue_live_..."

Then fetch its transcript:

curl https://api.userevaluation.com/v1/files/<fileId>/transcript \
  -H "Authorization: Bearer ue_live_..."

{
  "data": {
    "file_id": "65f8...",
    "segments": [
      { "speaker": "Researcher", "start_seconds": 0, "end_seconds": 5, "text": "Tell me about..." },
      { "speaker": "Participant",  "start_seconds": 5, "end_seconds": 12, "text": "Sure, so I..." }
    ]
  }
}

5. Trigger AI work and poll for the result

AI endpoints return a 202 Accepted with a job id. Poll /v1/jobs/:id until status is succeeded or failed.

curl -X POST https://api.userevaluation.com/v1/projects/<projectId>/reports \
  -H "Authorization: Bearer ue_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarize key insights"}'

{ "data": { "id": "65f9...", "type": "report", "status": "queued" } }

curl https://api.userevaluation.com/v1/jobs/<jobId> \
  -H "Authorization: Bearer ue_live_..."

When status reads succeeded, the result object will reference the resource that was created (e.g. result.report_id).

What's next

• Authentication — header format, key rotation, scopes
• Conventions — pagination, errors, idempotency, dates
• Webhooks — receive events instead of polling
• Rate limits — per-tier caps and the headers we return