PercelX API Reference

The PercelX API is a REST API that returns JSON. It provides access to behavioral assessments, domain analysis, Uri intelligence queries, MIT transformation plans, and developer account management.

All responses follow a consistent envelope:

{
  "success": true,
  "data":    { /* endpoint-specific payload */ },
  "meta":    { "requestId": "req_7xk2...", "timestamp": "2026-03-20T..." }
}

Authentication

All API requests must include your API key in the Authorization HTTP header as a Bearer token.

Authorization: Bearer pxk_live_a3f7e9b2...

Key types

Code examples

curl -X POST https://api.percelx.org/api/v1/assess \
  -H "Authorization: Bearer pxk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId":"usr_abc","domain":"athletic","variables":{"fear_of_failure":8}}'

// Node.js / browser fetch
const res = await fetch('https://api.percelx.org/api/v1/assess', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.PERCELX_API_KEY}`,
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({ userId: 'usr_abc', domain: 'athletic', variables: { fear_of_failure: 8 } }),
});
const data = await res.json();

import requests, os

headers = {
    "Authorization": f"Bearer {os.environ['PERCELX_API_KEY']}",
    "Content-Type":  "application/json",
}
payload = {"userId": "usr_abc", "domain": "athletic", "variables": {"fear_of_failure": 8}}
r = requests.post("https://api.percelx.org/api/v1/assess", json=payload, headers=headers)
data = r.json()

Rate Limits

Rate limits are enforced per API key. Limits reset on a rolling 24-hour window (daily) and a rolling 60-second window (per-minute). Exceeding either limit returns 429 Too Many Requests.

Rate limit response headers

Every response includes these headers so you can monitor usage:

X-RateLimit-Limit-Day:      1000
X-RateLimit-Remaining-Day:  847
X-RateLimit-Limit-Min:      20
X-RateLimit-Remaining-Min:  19
X-RateLimit-Reset:          2026-03-20T08:00:00.000Z

Exceeded limit response

{
  "error":      "RATE_LIMIT_EXCEEDED",
  "message":    "Daily limit of 1000 requests exceeded",
  "retryAfter": 3600   // seconds until reset
}

Errors

The API uses standard HTTP status codes. Error responses always include a machine-readable error field and a human-readable message.

SDKs & Libraries

Community libraries and helper packages will be listed here as they are published.

Assessment API

curl -X POST https://api.percelx.org/api/v1/assess \
  -H "Authorization: Bearer pxk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId":  "usr_abc123",
    "domain":  "athletic",
    "variables": {
      "fear_of_failure":   8,
      "self_discipline":   5,
      "identity_clarity":  6,
      "coachability":      7,
      "resilience":        4
    },
    "includeRoadmap": true
  }'

const res = await fetch('https://api.percelx.org/api/v1/assess', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    userId: 'usr_abc123',
    domain: 'athletic',
    variables: { fear_of_failure: 8, self_discipline: 5, identity_clarity: 6 },
  }),
});
const { profile, topLimitations, mitPlan } = await res.json();

r = requests.post(
    "https://api.percelx.org/api/v1/assess",
    json={
        "userId": "usr_abc123",
        "domain": "athletic",
        "variables": {"fear_of_failure": 8, "self_discipline": 5},
    },
    headers=headers
)
data = r.json()

{
  "success": true,
  "profile": {
    "sphereScore":  68,
    "tier":         "Growth Zone",
    "domain":       "athletic"
  },
  "topLimitations": ["fear_of_failure", "resilience"],
  "mitPlan": {
    "phase1":    "Identity Rebuild",
    "duration": "21 days",
    "actions":  [{ "day": 1, "task": "Journal fear triggers" }, ...]
  },
  "roadmap": { /* present if includeRoadmap: true */ },
  "requestId": "req_7xk2a9d3"
}

{
  "domains": [
    { "id": "athletic",      "label": "Athletic Performance",   "variables": 28 },
    { "id": "professional",  "label": "Professional Growth",     "variables": 31 },
    { "id": "dating",        "label": "Relationships & Dating",  "variables": 24 },
    { "id": "total",         "label": "Total Life Rhythm",       "variables": 120 }
  ]
}

Uri API

{
  "success": true,
  "insight": {
    "rootPattern":   "fear_of_failure",
    "confidence":    0.87,
    "sphereImpact":  { "mental": -32, "athletic": -28, "identity": -19 },
    "narrative":     "The freeze response is a protection mechanism..."
  },
  "transformation": { "phase1": "Reframe identity under pressure", ... },
  "followUpQuestions": ["How long has this pattern been active?", ...]
}

Keys & Account

{
  "success":          true,
  "plan":             "STARTER",
  "status":           "active",
  "currentPeriodEnd": "2026-04-20T00:00:00.000Z",
  "active":           true
}

Behavioral Domains

Webhook Events

Changelog