v1.0.1

REST APIv1.0.0

REST Endpoints Catalog

Complete reference for all endpoints implemented in BehaviorSim API v1.

Complete reference for all HTTP endpoints verified against the BehaviorSim API codebase.

1. Health & Readiness Probes

GET/health

Public

Process Liveness Probe

Lightweight liveness check verifying the application process is running. Performs no database calls.

Response Payload (JSON)

response.json

{
  "status": "ok",
  "version": "1.0.0"
}

curl Request

terminal

curl -s https://api.behavioursim.vedaangsharma.in/health

GET/ready

Public

Service Readiness Probe

Readiness probe verifying the service can accept traffic by executing a database connectivity check.

Response Payload (JSON)

response.json

{
  "status": "ready",
  "database": "connected",
  "version": "1.0.0"
}

Status Codes

200Service is fully operational

503Database is unavailable or connection timed out

curl Request

terminal

curl -s https://api.behavioursim.vedaangsharma.in/ready

2. Presets Catalog

GET/v1/presets

Public

List Simulation Presets

Retrieve the public catalog of all available simulation presets, supported cohorts, and states.

Response Payload (JSON)

response.json

[
  {
    "name": "education",
    "description": "Adaptive learning telemetry modeling cognitive load and mastery.",
    "available": true,
    "default_profile": "average",
    "supported_profiles": ["average", "fast_accurate", "fast_inaccurate", "slow_accurate", "slow_inaccurate"],
    "supported_states": ["Optimal", "Overload", "Underload"]
  },
  {
    "name": "finance",
    "description": "Synthetic behavioral telemetry for financial trading and risk alerts.",
    "available": true,
    "default_profile": "balanced_investor",
    "supported_profiles": ["conservative_investor", "balanced_investor", "growth_investor", "active_trader"],
    "supported_states": ["Stable", "Active", "Volatile", "Drawdown", "Recovered", "Closed"]
  }
]

curl Request

terminal

curl -s https://api.behavioursim.vedaangsharma.in/v1/presets

GET/v1/presets/{preset}

Public

Get Preset Metadata

Retrieve detailed configuration metadata for a specific preset by name or alias (e.g. 'mobile').

Parameters

Name	Type	Required	Description
preset	string (path)	Yes	Preset name (e.g. 'education', 'finance', 'healthcare', 'mobile_app', 'mobile')

Response Payload (JSON)

response.json

{
  "name": "finance",
  "description": "Synthetic behavioral telemetry for financial trading, risk alerts, drawdowns, and portfolio volatility.",
  "available": true,
  "default_profile": "balanced_investor",
  "supported_profiles": ["conservative_investor", "balanced_investor", "growth_investor", "active_trader"],
  "supported_states": ["Stable", "Active", "Volatile", "Drawdown", "Recovered", "Closed"]
}

Status Codes

200Preset metadata resolved

404Preset not found

curl Request

terminal

curl -s https://api.behavioursim.vedaangsharma.in/v1/presets/finance

3. Simulation Execution

POST/v1/simulations

Session Cookie or API Key5 req/min, 1,000 interactions/req

Execute Behavioral Simulation

Authenticate caller, verify quota, and execute a behavioral simulation run using the BehaviorSim engine.

Request Payload (JSON)

request.json

{
  "preset": "finance",
  "num_interactions": 10,
  "seed": 42,
  "profile": "balanced_investor"
}

Response Payload (JSON)

response.json

{
  "simulation_id": "sim_9f8d7c6b5a4",
  "preset": "finance",
  "num_interactions": 10,
  "seed": 42,
  "data": [
    {
      "sequence_id": 1,
      "interaction_id": 0,
      "state": "Stable",
      "portfolio_value": 1004.2,
      "daily_return": 0.0042,
      "risk_alert": 0
    }
  ],
  "metadata": {
    "behaviorsim_version": "1.0.1",
    "api_version": "1.0.0",
    "compute_ms": 28,
    "reproducible": true
  }
}

Status Codes

200Simulation executed successfully

400Interaction limit exceeded per request

401Missing or invalid credentials

403Monthly interaction quota exhausted

429Rate limit exceeded (5 requests/minute)

curl Request

terminal

curl -X POST https://api.behavioursim.vedaangsharma.in/v1/simulations \
  -H "Authorization: Bearer bs_live_..." \
  -H "Content-Type: application/json" \
  -d '{"preset": "finance", "num_interactions": 10, "seed": 42}'

4. Account & Usage Accounting

GET/v1/account

Session Cookie or API Key

Retrieve Account Profile

Returns authenticated user profile, linked identity providers, and active subscription plan.

Response Payload (JSON)

response.json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "user@example.com",
  "display_name": "Jane Doe",
  "is_active": true,
  "created_at": "2026-09-13T12:00:00Z",
  "authentication_methods": ["github"],
  "plan": "free"
}

GET/v1/usage

Session Cookie or API Key

Retrieve Monthly Quota & Usage

Returns current monthly requests, interaction consumption, plan limits, and remaining entitlements.

Response Payload (JSON)

response.json

{
  "plan": {
    "name": "free",
    "monthly_requests": 100,
    "monthly_interactions": 10000,
    "max_interactions_per_request": 1000,
    "requests_per_minute": 5,
    "max_concurrent_simulations": 1
  },
  "period": {
    "start": "2026-09-01T00:00:00Z",
    "end": "2026-10-01T00:00:00Z"
  },
  "usage": {
    "requests": 14,
    "interactions": 700
  },
  "remaining": {
    "requests": 86,
    "interactions": 9300
  }
}

5. API Key Management

GET/v1/api-keys

Session Cookie or API Key

List API Keys

Returns all active and revoked API key metadata for the authenticated user.

Response Payload (JSON)

response.json

[
  {
    "id": "key_uuid_1",
    "name": "CI Pipeline",
    "key_prefix": "bs_live_a1b2c3",
    "is_active": true,
    "created_at": "2026-09-13T14:30:00Z",
    "last_used_at": "2026-09-13T18:45:00Z",
    "revoked_at": null
  }
]

POST/v1/api-keys

Session Cookie or API Key

Create Developer API Key

Generate a new API key. The raw secret string is returned exactly once in this response.

Request Payload (JSON)

request.json

{
  "name": "Local Development Key"
}

Response Payload (JSON)

response.json

{
  "id": "key_uuid_2",
  "name": "Local Development Key",
  "key": "bs_live_9f8e7d6c5b4a3210987654321fedcba",
  "key_prefix": "bs_live_9f8e7d",
  "created_at": "2026-09-14T00:15:00Z"
}

Status Codes

201Key created successfully

409Maximum active API keys limit (1 on Free plan) exceeded

DELETE/v1/api-keys/{key_id}

Session Cookie or API Key

Revoke Developer API Key

Immediately revokes and disables an API key. Once revoked, it cannot be reactivated.

Parameters

Name	Type	Required	Description
key_id	UUID (path)	Yes	Unique ID of the API key to revoke

Response Payload (JSON)

response.json

{
  "status": "revoked",
  "id": "key_uuid_2"
}

Status Codes

200Key successfully revoked

404Key not found or not owned by user

PreviousAPI Keys

NextErrors & Status Codes