API Reference — Authentication & Overview

SegOps exposes a REST API for ingesting events, querying segment membership, managing segments and connectors, and exploring user profiles. All responses are JSON.

Base URL#

https://api.segops.ai

All API paths begin with /api/. For self-hosted deployments, replace api.segops.ai with your own domain.

Authentication#

The API supports two authentication schemes:

Obtaining a JWT

curl -X POST https://api.segops.ai/api/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "password": "..." }'

# Response:
# { "access": "eyJ...", "refresh": "eyJ..." }

The access token expires in 60 minutes. Refresh it with:

curl -X POST https://api.segops.ai/api/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{ "refresh": "eyJ..." }'

Using an API Key

curl https://api.segops.ai/api/segments/membership/?user_id=user-123 \
  -H "Authorization: ApiKey sk_live_xxxxxxxxxxxxxxxx"

Rate Limits#

When a limit is exceeded, the server returns 429 Too Many Requests with a Retry-After header.

Error Format#

All errors use a consistent response shape:

{ "detail": "Human-readable error message" }

For field validation errors:

{ "field_name": ["Error message for this field"] }

Pagination#

Large collections use cursor-based pagination:

GET /api/segments/<id>/members/?limit=1000&cursor=<opaque_cursor>
Authorization: ApiKey sk_...

{
  "results": [...],
  "next_cursor": "dXNlci01Njc4",
  "count": 48210
}

Pass next_cursor as the cursor query parameter in subsequent requests. When next_cursor is null, you have reached the end. Standard list endpoints use offset pagination:

{
  "count": 12,
  "next": "https://api.segops.ai/api/segments/?limit=10&offset=10",
  "previous": null,
  "results": [...]
}

Timestamps#

All timestamps are ISO 8601 / RFC 3339 in UTC:

2026-04-25T14:32:00Z

When ingesting events, omit occurred_atto default to the server's receive time.