API Endpoints

Complete reference for all HypLab REST API endpoints. Base URL: http://localhost:4096/api/v1

Health

`GET /health`

Check if the API is running.

curl http://localhost:4096/health

Response (200):

{ "status": "healthy", "service": "api" }

People

`GET /api/v1/people`

List people with pagination.

Query parameters: page, page_size, workspace_id

curl "http://localhost:4096/api/v1/people?page=1&page_size=20&workspace_id=ws_123"

Response (200):

{
  "items": [
    {
      "id": "abc123",
      "first_name": "Jane",
      "last_name": "Smith",
      "source_type": "synthetic",
      "workspace_id": "ws_123",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20
}

`GET /api/v1/people/:id`

Get a single person by ID.

curl http://localhost:4096/api/v1/people/abc123

Response (200): Full person object with all populated fields.

Response (404): {"detail":"Person not found"}

`POST /api/v1/people`

Create a person manually.

curl -X POST http://localhost:4096/api/v1/people \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_123",
    "first_name": "Jane",
    "last_name": "Smith",
    "primary_email": "jane@example.com"
  }'

Response (201): The created person object with id.

`PUT /api/v1/people/:id`

Update a person.

curl -X PUT http://localhost:4096/api/v1/people/abc123 \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Janet"}'

Response (200): The updated person object.

`DELETE /api/v1/people/:id`

Delete a person.

curl -X DELETE http://localhost:4096/api/v1/people/abc123

Response (204): No content.

`POST /api/v1/people/generate`

Generate people from a template (triggers AI agent).

curl -X POST http://localhost:4096/api/v1/people/generate \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl_456",
    "workspace_id": "ws_123",
    "count": 5
  }'

Response (200): Generated people array and persona information.

Templates

`GET /api/v1/templates`

List templates with pagination.

Query parameters: page, page_size, workspace_id, category

`GET /api/v1/templates/:id`

Get a single template by ID.

`POST /api/v1/templates`

Create a manual template.

curl -X POST http://localhost:4096/api/v1/templates \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_123",
    "name": "Enterprise CTO",
    "description": "Senior technology decision makers",
    "category": "B2B",
    "people_fields": ["first_name","last_name","primary_email","company_name","role"],
    "persona_fields": ["buyer_profile","buying_trigger","desired_outcomes"]
  }'

Response (201): The created template object.

`PUT /api/v1/templates/:id`

Update a template.

`DELETE /api/v1/templates/:id`

Delete a template.

`GET /api/v1/templates/search`

Search templates by keyword.

Query parameters: q, workspace_id

`GET /api/v1/templates/by-use-case`

Get templates grouped by use case.

Query parameters: workspace_id

Personas

`GET /api/v1/personas`

List personas with pagination.

Query parameters: page, page_size, workspace_id, type (B2B/B2C)

`GET /api/v1/personas/:id`

Get a single persona by ID.

`POST /api/v1/personas`

Create a persona manually.

curl -X POST http://localhost:4096/api/v1/personas \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_123",
    "name": "Enterprise CTO",
    "type": "B2B",
    "buyer_profile": {
      "tagline": "Senior technology leader driving digital transformation"
    }
  }'

Response (201): The created persona object.

`PUT /api/v1/personas/:id`

Update a persona.

`DELETE /api/v1/personas/:id`

Delete a persona.

`POST /api/v1/personas/:id/people`

Add people to a persona.

curl -X POST http://localhost:4096/api/v1/personas/pers_789/people \
  -H "Content-Type: application/json" \
  -d '{"people_ids": ["abc123", "def456"]}'

`DELETE /api/v1/personas/:id/people/:person_id`

Remove a person from a persona.

Organizations

`GET /api/v1/organizations`

List organizations the current user belongs to.

`GET /api/v1/organizations/:id`

Get organization details.

`POST /api/v1/organizations`

Create an organization.

`PUT /api/v1/organizations/:id`

Update an organization.

Workspaces

`GET /api/v1/workspaces`

List workspaces in the current organization.

`GET /api/v1/workspaces/:id`

Get workspace details.

`GET /api/v1/workspaces/:id/onboarding-status`

Check the onboarding status of a workspace.

Onboarding

`POST /api/v1/onboarding/start`

Start the onboarding process for a workspace.

`GET /api/v1/onboarding/status`

Check onboarding status.

`GET /api/v1/onboarding`

Get current onboarding data.

`PUT /api/v1/onboarding`

Update onboarding data.

Settings

`GET /api/v1/settings/onboarding`

Get workspace onboarding settings.

`GET /api/v1/settings/custom-fields`

List custom fields for the workspace.

`POST /api/v1/settings/custom-fields`

Create a custom field.

`GET /api/v1/settings/system-fields`

Get the standard field library.

`GET /api/v1/settings/preferences`

Get workspace preferences.

`PUT /api/v1/settings/preferences`

Update workspace preferences.

`GET /api/v1/settings/integrations`

Get integration settings (API keys, webhooks).

Error handling

All errors follow a consistent format:

{
  "detail": "Main error message",
  "details": {
    "field_name": "Field-specific error"
  }
}

Common error codes:

Status	Error type	Example
400	Validation error	Missing required field, invalid format
404	Not found	Resource doesn't exist
409	Conflict	Duplicate resource

Next: Telemetry -- configure tracing and logging.

API Endpoints

On this page