API Reference

The Nexus Suite API is a RESTful HTTP service hosted at api.nexus-suite.dev. It handles authentication, billing, entitlements, encrypted sync, the Skills Hub, and MCP hosting.

Base URL

https://api.nexus-suite.dev/v1

All endpoints are versioned under /v1.

Authentication

Most endpoints require a JWT bearer token in the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

JWTs are issued by the Authentication API and signed with RS256. Clients validate tokens using the public key from the JWKS endpoint.

See Authentication for details on obtaining tokens.

Sections

Section	Description
Authentication	Registration, login, OAuth, device code flow, sessions, SSO
Entitlements	Feature gating, tier management, trial management
Billing	Subscription management, Stripe checkout, webhooks
Sync	Encrypted settings and data sync (Pro+)
Skills Hub	Skill publishing, search, and installation (Pro+)
MCP Hosting	Private MCP server provisioning (Studio)

Common Response Format

Success

{
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com"
  }
}

Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Password must be at least 12 characters",
    "details": {
      "field": "password",
      "min_length": 12
    }
  }
}

Error Codes

Code	HTTP Status	Description
VALIDATION_ERROR	400	Invalid input data
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Insufficient permissions or tier
EMAIL_UNVERIFIED	403	Account requires email verification
TIER_REQUIRED	403	Feature requires a higher subscription tier
NOT_FOUND	404	Resource not found
CONFLICT	409	Duplicate resource (e.g., email already registered)
ACCOUNT_LOCKED	423	Account temporarily locked due to failed login attempts
QUOTA_EXCEEDED	413	Storage or publishing quota exceeded
RATE_LIMITED	429	Rate limit exceeded
WEBHOOK_INVALID	400	Invalid Stripe webhook signature
INTERNAL_ERROR	500	Unexpected server error

Rate Limiting

API requests are rate-limited per authenticated user based on subscription tier:

Tier	Limit
Core	60 requests/minute
Pro	300 requests/minute
Studio	1,000 requests/minute

Unauthenticated endpoints (registration, login) are limited to 20 requests/minute per IP.

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating when you can retry.

Stripe webhook endpoints are exempt from per-user rate limits but require signature verification.

System Endpoints

These endpoints do not require authentication:

Method	Path	Description
GET	/health	Liveness check
GET	/ready	Readiness check (verifies DB + Redis connectivity)
GET	/status	Module status for the public status page
GET	/metrics	Prometheus-compatible metrics (internal)

Retry Strategy

For client implementations:

• 5xx errors: Retry with exponential backoff and jitter. Maximum 3 retries.
• 401 errors: Attempt a token refresh. If refresh fails, prompt re-authentication.
• 429 errors: Wait for the duration specified in the Retry-After header.