API Reference

Programmatic access to Roux. All endpoints require an agent token passed via the Authorization header.

Authorization: Bearer roux_...

Interviews

Create, list, read, and update interviews.

GET/api/agent/interviewsworkspace

List all interviews in the workspace, sorted by creation date.

Response

{
  "interviews": [
    {
      "id": "uuid",
      "title": "User Research Q1",
      "status": "active",
      "framework": "user-research",
      "response_count": 12,
      "created_at": "2026-03-01T..."
    }
  ]
}

POST/api/agent/interviewsworkspace

Create a new interview. Returns a share_token you can use to build the respondent link.

Request body

{
  "title": "Sprint Retro",          // required
  "description": "...",             // optional
  "goal": "...",                    // optional
  "framework": "team-health",       // brand-sprint | user-research | jtbd
                                    // team-health | competitive | custom
  "tone": "conversational",         // casual | conversational | professional
  "duration": "10-15 min",
  "questions": ["...", "..."],       // optional custom questions
  "context": "...",                  // background context for the AI
  "status": "draft"                  // draft | active
}

Response

{
  "id": "uuid",
  "title": "Sprint Retro",
  "share_token": "abc123",
  "status": "draft",
  "created_at": "2026-03-28T..."
}

// Respondent link: https://roux.link/i/{share_token}

GET/api/agent/interview?interview_id={id}interview

Get a single interview with response statistics.

Response

{
  "id": "uuid",
  "title": "Sprint Retro",
  "status": "active",
  "total_responses": 8,
  "completed": 5,
  "in_progress": 2,
  "abandoned": 1
}

PATCH/api/agent/interview?interview_id={id}interview

Update an interview. Only the fields you include are changed.

Request body

{
  "status": "active",             // activate a draft
  "title": "Updated Title",
  "context": "New background..."
}

Responses

Read respondent sessions, messages, and exercise data.

GET/api/agent/responses?interview_id={id}interview

Get all responses for an interview with full message history and respondent info. Respondent details are redacted when the interview uses anonymous mode.

Response

{
  "responses": [
    {
      "id": "uuid",
      "status": "completed",
      "started_at": "2026-03-20T...",
      "completed_at": "2026-03-20T...",
      "respondent": {
        "name": "Alex",
        "email": "alex@example.com"
      },
      "messages": [
        { "role": "assistant", "content": "Welcome! Let's start..." },
        { "role": "user", "content": "I think the key issue is..." }
      ],
      "exercise_data": { ... },
      "summary": {
        "overview": "...",
        "sections": [ ... ],
        "insights": [ ... ]
      }
    }
  ]
}

Synthesis

Retrieve AI-generated themes, insights, and knowledge graphs across all responses.

GET/api/agent/synthesis?interview_id={id}interview

Get the synthesis bundle for an interview. Includes themes with supporting quotes, a knowledge graph of relationships between insights, and generation metadata.

Response

{
  "id": "uuid",
  "status": "completed",
  "summary": "Respondents consistently...",
  "response_count": 8,
  "themes": [
    {
      "title": "Speed over polish",
      "description": "...",
      "sentiment": "positive",
      "quotes": [
        { "text": "...", "respondent": "Alex" }
      ]
    }
  ],
  "graph": {
    "nodes": [
      { "id": "n1", "kind": "theme", "title": "..." }
    ],
    "edges": [
      { "from_node_id": "n1", "to_node_id": "n2",
        "kind": "supports", "rationale": "..." }
    ]
  }
}

Agent Tokens

Manage tokens programmatically. Workspace tokens can create and revoke interview-scoped tokens.

POST/api/agent-tokensworkspace

Create a new workspace-scoped agent token. The plaintext token is returned exactly once — store it securely.

Request body

{
  "label": "CI Pipeline"   // optional, for your reference
}

Response

{
  "id": "uuid",
  "token": "roux_abc123...",
  "scope_type": "account",
  "label": "CI Pipeline",
  "created_at": "2026-03-28T..."
}

GET/api/agent-tokensworkspace

List all workspace-scoped agent tokens. Tokens are not returned in plaintext after creation.

Response

{
  "tokens": [
    {
      "id": "uuid",
      "scope_type": "account",
      "label": "CI Pipeline",
      "created_at": "...",
      "last_used_at": "...",
      "revoked_at": null
    }
  ]
}

DELETE/api/agent-tokensworkspace

Revoke a token. Revoked tokens immediately stop working.

Request body

{
  "id": "uuid"
}

Errors

All errors return a JSON body with an error field.

{ "error": "A human-readable error message" }

Status	Meaning
`400`	Invalid request — check the error message for details
`401`	Missing or invalid agent token
`403`	Token does not have permission for this resource
`404`	Interview or resource not found
`429`	Rate limited — back off and retry
`500`	Server error — retry or contact support