Introduction to the HypLab REST API -- base URL, authentication, request/response formats, and WebSocket protocol.

API Overview

HypLab provides a REST API for programmatic access to all features. This page covers the basics you need to start making API calls.

Base URL

http://localhost:4096/api/v1

All API endpoints are prefixed with /api/v1.

Authentication

Authentication is token-based (Bearer token). Include your token in the Authorization header:

Authorization: Bearer your-token-here

Generate API keys from Settings > Integrations > API Keys.

Request format

Content-Type: application/json for all request bodies.
Query parameters are used for filtering, pagination, and sorting.

Response format

Success responses

Single resource:

{
  "id": "abc123",
  "name": "Enterprise Decision Maker",
  "category": "B2B",
  "created_at": "2026-01-15T10:30:00Z"
}

List of resources:

{
  "items": [...],
  "total": 100,
  "page": 1,
  "page_size": 20
}

Error responses

{
  "detail": "Person not found",
  "details": {
    "field_name": "Field-specific error message"
  }
}

Pagination

List endpoints support pagination with query parameters:

Parameter	Default	Max	Description
`page`	1	--	Page number
`page_size`	20	100	Items per page

Example:

GET /api/v1/people?page=2&page_size=10

HTTP status codes

Code	Meaning
200	Success (GET, PUT)
201	Created (POST)
204	No Content (DELETE)
400	Validation error -- check the request body
401	Unauthorized -- missing or invalid token
403	Forbidden -- you don't have access
404	Not found -- the resource doesn't exist
409	Conflict -- duplicate or conflicting data
500	Server error -- something went wrong

WebSocket protocol

AI agent operations (template generation, people generation) use WebSocket for real-time progress streaming.

Connection

Connect to the agent's WebSocket endpoint:

ws://localhost:4098/ws/{task_id}

Message types

Client to server (start a task):

{
  "type": "start",
  "payload": {
    "workspace_id": "...",
    "options": {}
  }
}

Server to client (progress update):

{
  "type": "progress",
  "payload": {
    "step": "generating",
    "progress": 45,
    "message": "Generating person 3 of 5..."
  }
}

Server to client (complete):

{
  "type": "complete",
  "payload": {
    "result": { ... }
  }
}

Server to client (error):

{
  "type": "error",
  "payload": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input"
  }
}

Quick examples

cURL

# Health check
curl http://localhost:4096/health

# List people
curl http://localhost:4096/api/v1/people?page=1&page_size=10

# Create a person
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"}'

JavaScript

const response = await fetch('http://localhost:4096/api/v1/people?page=1&page_size=10')
const data = await response.json()
console.log(data.items) // Array of people
console.log(data.total) // Total count

Python

import requests

response = requests.get('http://localhost:4096/api/v1/people', params={'page': 1, 'page_size': 10})
data = response.json()
print(data['items'])
print(data['total'])

Next: API Endpoints -- full endpoint reference with request/response examples.

API Overview

On this page