API Reference¶

Identity OS provides a REST API for managing instances, processing observations, and reading execution contracts. The API is designed to be simple, fast, and auditable.

Base URL¶

Environment	URL
Cloud	`https://api.identity-os.dev/v1`
Local (Docker)	`http://localhost:8000/v1`

Authentication¶

All requests require an API key in the Authorization header:

curl -H "Authorization: Bearer idos_sk_your_key_here" \
  https://api.identity-os.dev/v1/instances

Or use an SDK (authentication handled automatically):

from identity_os_sdk import IdentityOS

client = IdentityOS(api_key="idos_sk_your_key_here")

Getting an API Key¶

Visit identity-os.dev
Sign up or log in
Go to Settings → API Keys
Click Create New Key
Copy the key (shown only once)

Key Format¶

Entity	Prefix	Example
API Key	`idos_sk_`	`idos_sk_xxxxxxxxxxxxxxxxxxx`
Instance	`inst_`	`inst_9f190826e20c49ea`
Snapshot	`snap_`	`snap_a1b2c3d4e5f67890`

Rate Limits¶

Identity OS enforces rate limits based on your plan:

Plan	Rate Limit	Monthly Quota	Cost
Free	10 req/min	10K cycles	$0
Indie	60 req/min	100K cycles	$29/mo
Pro	300 req/min	500K cycles	$99/mo
Enterprise	Custom	Custom	Custom

A cycle = one processed observation (one API call).

When you hit a rate limit, the API returns 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "retry_after": 60
}

Wait the indicated seconds before retrying.

Response Format¶

All responses are JSON. Successful responses use 2xx status codes:

{
  "data": {
    "id": "inst_9f190826e20c49ea",
    "name": "Aria",
    "created_at": "2026-03-24T10:15:30Z"
  }
}

Error responses use 4xx/5xx status codes:

{
  "error": "invalid_request",
  "message": "instance_id is required",
  "details": {
    "field": "instance_id",
    "reason": "missing"
  }
}

Common Error Codes¶

Code	Meaning	Action
`400`	Bad request (missing/invalid field)	Fix the request
`401`	Unauthorized (invalid/missing API key)	Check API key
`404`	Not found (instance doesn't exist)	Verify instance ID
`409`	Conflict (duplicate, state mismatch)	Retry or reset
`429`	Rate limit exceeded	Wait and retry
`500`	Server error	Retry with backoff

Endpoints Overview¶

Identity OS exposes 16 REST endpoints across 4 categories:

Instance Management (CRUD)¶

Method	Endpoint	Purpose
POST	`/instances`	Create instance
GET	`/instances`	List instances
GET	`/instances/{id}`	Get instance
PATCH	`/instances/{id}`	Update instance
DELETE	`/instances/{id}`	Delete instance

Engine Operations¶

Method	Endpoint	Purpose
POST	`/instances/{id}/process`	Process observation → get contract
POST	`/instances/{id}/process/batch`	Batch process observations
GET	`/instances/{id}/snapshot`	Get current state
GET	`/instances/{id}/contract`	Get execution contract
POST	`/instances/{id}/reset`	Reset to initial/last stable state
GET	`/instances/{id}/history`	Get observation history
GET	`/instances/{id}/drift`	Get drift events

Testing System¶

Method	Endpoint	Purpose
POST	`/test/submit`	Submit personality test
GET	`/test/questions`	Get test questions

Personas¶

Method	Endpoint	Purpose
GET	`/personas`	List all 12 personas
GET	`/personas/{id}`	Get persona details

Common Patterns¶

Pattern 1: Create and Process¶

# 1. Create instance
curl -X POST https://api.identity-os.dev/v1/instances \
  -H "Authorization: Bearer idos_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Aria"}'

# Response:
# {"data": {"id": "inst_xxx", "name": "Aria", ...}}

# 2. Process observation
curl -X POST https://api.identity-os.dev/v1/instances/inst_xxx/process \
  -H "Authorization: Bearer idos_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mode_target": "EXPLORATION",
    "signal_strength": 0.8,
    "confidence": 0.9
  }'

# Response includes contract

Pattern 2: Get Current Contract¶

curl -X GET https://api.identity-os.dev/v1/instances/inst_xxx/contract \
  -H "Authorization: Bearer idos_sk_xxx"

# Response:
# {
#   "data": {
#     "dominant_modes": ["Order", "Identity"],
#     "allowed_actions": ["execute", "clarify", ...],
#     "stress_state": "LOW",
#     "energy_level": 0.65,
#     ...
#   }
# }

Pattern 3: Batch Processing¶

curl -X POST https://api.identity-os.dev/v1/instances/inst_xxx/process/batch \
  -H "Authorization: Bearer idos_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "observations": [
      {"mode_target": "EXPLORATION", "signal_strength": 0.8},
      {"mode_target": "ORDER", "signal_strength": 0.7},
      {"mode_target": "ASSERTION", "signal_strength": 0.6}
    ],
    "include_intermediate": false
  }'

# Returns final state after all 3 observations

Field Reference¶

Mode Values¶

Use these in requests:

"PERCEPTION"
"EXPLORATION"
"ORDER"
"ASSERTION"
"CONNECTION"
"IDENTITY"
"STRESS_RESPONSE"

Stress States¶

Returned in contracts:

"LOW"
"MED"
"HIGH"
"OVER"

Action Vocabulary¶

Returned in contracts:

"explore"
"question"
"elaborate"
"suggest"
"execute"
"pivot"
"challenge"
"comfort"
"clarify"
"stabilize"
"defer"
"withdraw"

SDKs¶

Official SDKs handle authentication, typing, and serialization:

PythonTypeScript

from identity_os_sdk import IdentityOS, Mode

client = IdentityOS(api_key="idos_sk_xxx")
instance = client.instances.create(name="Aria")
result = client.engine.process(instance.id, Mode.EXPLORATION, 0.8)

import { IdentityOS, Mode } from "@identity-os/sdk";

const client = new IdentityOS({ apiKey: "idos_sk_xxx" });
const instance = await client.instances.create({ name: "Aria" });
const result = await client.engine.process(instance.id, {
  modeTarget: Mode.EXPLORATION,
  signalStrength: 0.8
});

See full SDK docs: Python | TypeScript

Detailed Endpoints¶

For complete documentation of each endpoint, see:

Instances — Instance CRUD and lifecycle
Engine — Core processing endpoints
Personas — Personality archetype references
Testing — Personality test submission

OpenAPI Documentation¶

Interactive API docs are available on local deployments:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

To enable on your local instance, set IDENTITY_OS_DOCS_ENABLED=true.

Note: Interactive docs are disabled on the production API for security.

Changelog¶

v1.0 (Current)¶

Initial public API
16 REST endpoints
Python and TypeScript SDKs
Rate limiting and auth
Full audit trail