The Boses API is a REST API. All endpoints accept and return JSON unless otherwise noted, and are prefixed with /api/v1.
Base URLs
| Environment | Base URL |
|---|
| Production | https://api.temujintechnologies.com/api/v1 |
| Staging | https://api-staging.temujintechnologies.com/api/v1 |
Authentication
Every request (except /health and the /auth endpoints) must include a valid JWT access token in the Authorization header:
Authorization: Bearer <your_access_token>
POST /auth/login. Tokens expire after 15 minutes. Use POST /auth/refresh to rotate them without re-entering credentials. The refresh token is stored as an HttpOnly cookie and is valid for 30 days.
See Auth Endpoints for the full authentication flow.
Rate limits
Certain endpoints are rate-limited to prevent abuse. When you exceed a limit, you receive a 429 Too Many Requests response.
| Endpoint | Limit |
|---|
POST /auth/signup | 10 requests per hour |
POST /auth/login | 20 requests per minute |
POST /auth/forgot-password | 5 requests per hour |
Rate limits apply per IP address. If you are running automated integration tests, use the staging environment and space out your requests accordingly.
Asynchronous operations
Two types of operations run in the background and return immediately with a 202 Accepted status:
- Persona generation —
POST /persona-groups/{group_id}/generate returns 202 and starts generating personas in the background. Poll GET /persona-groups/{group_id} and check the generation_status field until it reads complete or failed.
- Simulations —
POST /simulations returns 201 Created and starts the simulation immediately. Poll GET /simulations/{simulation_id} and watch the status field progress through pending → running → generating_report → complete.
Both endpoints include a progress field in their status responses so you can show live progress to your users.
Company scoping
All resources in the Boses API are scoped to your company. When you authenticate, every read and write operation is automatically restricted to your organization’s data. You cannot access projects, personas, or simulation results belonging to other companies.
Resource IDs
All resource IDs are UUIDs, for example: 3fa85f64-5717-4562-b3fc-2c963f66afa6. Pass them as path parameters wherever {project_id}, {group_id}, {simulation_id}, or similar placeholders appear in endpoint paths.
Timestamps
All timestamps are returned as UTC ISO 8601 strings: "2026-04-07T08:30:00".
Errors
Error responses follow a consistent shape:
{
"detail": "Simulation not found"
}
| Status code | Meaning |
|---|
400 | Bad request — check your request body or query parameters |
401 | Unauthenticated — missing or expired access token |
403 | Forbidden — valid token but insufficient permissions |
404 | Not found — the resource does not exist or does not belong to your company |
422 | Validation error — request body failed schema validation |
429 | Too many requests — rate limit exceeded |
500 | Server error — something went wrong on our end |
Health check
You can verify that the API is reachable without authenticating:
curl https://api.temujintechnologies.com/api/v1/health
Resource overview
| Resource | Base path | Description |
|---|
| Projects | /api/v1/projects | Top-level containers for research initiatives |
| Persona Groups | /api/v1/projects/{project_id}/persona-groups | Demographic definitions and persona generation |
| Personas | /api/v1/projects/{project_id}/persona-groups/{group_id}/personas | Individual AI consumers |
| Briefings | /api/v1/projects/{project_id}/briefings | Product briefs and stimulus materials |
| Simulations | /api/v1/projects/{project_id}/simulations | Research studies run against persona groups |
| Persona Library | /api/v1/library | Reusable cross-project persona pool |
