VoxSim API v1

1. Overview

VoxSim API v1 is a REST + JSON interface. It uses Sanctum bearer-token authentication scoped to your workspace. All responses are enveloped (data + meta, or error).

• Base URL: https://voxsim.talivio.com/api/v1
• Format: JSON, UTF-8
• Rate limit: Not enforced yet; per-plan rate limits planned (Atölye 60/hr, Saha 600/hr, Karargah 6,000/hr)
• Versioning: URL prefix (/v1)

Response envelope

All successful responses follow this structure:

{
  "data": { ... },
  "meta": {
    "api_version": "v1",
    "generated_at": "2026-04-29T12:34:56+00:00",
    "pagination": {
      "total": 124,
      "per_page": 20,
      "current_page": 1,
      "last_page": 7
    }
  }
}

2. Authentication

Bearer token authentication. Create a separate token for each workspace; the token carries a workspace-bound ability (workspace:{id}).

1. Go to: Workspace → API settings
2. Create a token (workspace owner only).
3. Copy the token — it's shown only once. Use it in the Authorization header.

curl https://voxsim.talivio.com/api/v1/me \
  -H "Authorization: Bearer 1|abc123def456..." \
  -H "Accept: application/json"

Never commit tokens to source control, never expose in public clients. Use .env or a secret manager.

3. GET /me

Authenticated user, active workspace, and token metadata.

Example response

{
  "data": {
    "user": {
      "id": 1,
      "name": "Eren Erdem",
      "email": "[email protected]",
      "role_in_workspace": "owner"
    },
    "workspace": {
      "id": 1,
      "name": "Talivio Lab",
      "slug": "talivio-lab",
      "plan": "karargah",
      "modules_unlocked": ["a","b","d","f","g","h","i","j"],
      "seats_used": 1,
      "seats_max": 10,
      "status": "active"
    },
    "token": {
      "name": "production-server",
      "abilities": ["workspace:1"],
      "last_used_at": "2026-04-29T12:30:00+00:00"
    }
  },
  "meta": { ... }
}

4. GET /simulations

Paginated list of simulations in your workspace. Newest first.

Query parameters

• module — a, b, d, f, g, h, i, j
• status — queued, running, completed, failed, cancelled
• per_page — 1-100, default 20

curl "https://voxsim.talivio.com/api/v1/simulations?module=a&status=completed&per_page=10" \
  -H "Authorization: Bearer 1|abc..."

5. GET /simulations/{public_id}

Full details of a single simulation (segments, sample quotes, cost, error message).

{
  "data": {
    "public_id": "01KQB4535MXAN9C951181RPWX3",
    "title": "Asgari ücret söylemi",
    "module": "a",
    "status": "completed",
    "persona": { "id": 1, "name": "Örnek Aday A", "short_code": "ornek-aday-a" },
    "policy_text": "...",
    "result_segments": {
      "sosyal_demokrat": {"anger":35,"fear":70,"apathy":5,"hope":5,"support":10}
    },
    "result_summary": { ... },
    "tokens_in": 1728,
    "tokens_out": 8322,
    "cost_eur": 0.0438,
    "accuracy_score": null,
    "completed_at": "2026-04-28T16:48:35+00:00"
  }
}

6. POST /simulations

Creates a new Module A (Discourse Test) simulation and queues it. Runs asynchronously — request returns 201 immediately; poll the show endpoint for results.

Request body

{
  "persona_id": 1,
  "title": "Asgari ücret söylemi",
  "policy_text": "Asgari ücret 30.000 TL'ye yükselmeli...",
  "mock": false
}

Pass mock=true to skip LLM calls and get synthetic data (for test/CI).

Example

curl -X POST https://voxsim.talivio.com/api/v1/simulations \
  -H "Authorization: Bearer 1|abc..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "persona_id": 1,
    "title": "Test simulation",
    "policy_text": "Asgari ücreti enflasyon karşısında eritmeyeceğiz...",
    "mock": false
  }'

Returns 201 with status=queued. Worker (Horizon) starts processing, status flips to running, then completed after ~60-120s.

7. GET /personas

All active personas in your workspace (draft, awaiting_approval, approved). Use persona_id when creating a simulation.

{
  "data": [
    {
      "id": 1,
      "name": "Örnek Aday A",
      "short_code": "ornek-aday-a",
      "is_known": true,
      "status": "approved",
      "axes": {"economic": 2, "cultural": 4, "religious": 2, "nationalist": 3}
    }
  ]
}

7.1 Additional endpoints

GET /api/v1/usage

Current month usage summary: simulations by module, plan limits, token and estimated cost.

curl https://voxsim.talivio.com/api/v1/usage \
  -H "Authorization: Bearer $VOXSIM_TOKEN"

POST /api/v1/personas

Create a persona programmatically. Required: name + axes (1-5 each). Auto-approved.

curl -X POST https://voxsim.talivio.com/api/v1/personas \
  -H "Authorization: Bearer $VOXSIM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Örnek Aday A",
    "axes": {"economic": 2, "cultural": 4, "religious": 2, "nationalist": 3},
    "tagline_tr": "Sosyal demokrat aday"
  }'

POST /api/v1/simulations/{id}/counter-narrative

Module F (Saha+). Spawns child simulation with alternative framings for the highest-anger segment.

POST /api/v1/simulations/{id}/optimizer

Module I (Saha+). Generates 6 ranked policy variants. Manipulative variants are ethics-rejected.

POST /api/v1/simulations/{id}/crisis-break

Module B (Karargah+). Defensive vulnerability analysis. PDF output expires automatically after 30 days.

GET /api/v1/simulations/{id}/report

Returns watermarked PDF binary. X-Watermark-Token response header contains the steganographic token id.

curl https://voxsim.talivio.com/api/v1/simulations/{public_id}/report \
  -H "Authorization: Bearer $VOXSIM_TOKEN" \
  -o report.pdf

DELETE /api/v1/simulations/{id}

Soft-delete (status → cancelled). Audit trail preserved 6 months for EU AI Act. Refuses if simulation is running or queued.

8. Error handling

Error responses include both an HTTP status and a JSON body:

{
  "error": {
    "code": "persona_not_in_workspace",
    "message": "Persona not accessible in this workspace",
    "details": []
  }
}

Error codes