Getting Started with the API

This guide walks you through obtaining an API key, making your first authenticated request, and understanding rate limits. By the end, you'll be ready to integrate the Pixelated Empathy API into your application.

Table of Contents

1. Prerequisites
2. Create an API Key
3. Make Your First Request
4. Authentication Methods
5. Rate Limits & Quotas
6. Error Handling
7. Next Steps

Prerequisites

• A Pixelated Empathy account with developer access
• Node.js 18+ or Python 3.9+ installed (for SDK usage)
• curl or any HTTP client for testing

Create an API Key

API keys are managed through the admin dashboard. Keys are scoped to specific permissions and have per-key rate limits.

1. Navigate to the API Key Management dashboard
2. Click "Create New Key"
3. Select the scopes your application needs:
   • read — Read access to non-PHI endpoints
   • write — Create/update resources
   • developer:manage — Manage API keys (rotation, revocation)
   • analytics:read — Access analytics endpoints
   • memory:read / memory:write — Memory API access
   • admin — Full admin access (use with caution)
4. Set a name and optional expiration date
5. Copy the generated key — it's shown only once

Make Your First Request

Once you have an API key, make a test request:

curl -X GET https://api.pixelatedempathy.com/api/v1/health \
  -H "X-API-Key: dev_your_api_key_here"

Expected response:

{
  "status": "healthy",
  "version": "1",
  "timestamp": "2026-07-23T00:00:00Z"
}

The response includes the X-API-Version header indicating the API version that served your request.

Authentication Methods

API Key (Recommended for Server-Side)

Include your API key in the X-API-Key header on every request. This is the simplest method for server-to-server integrations.

curl -X GET https://api.pixelatedempathy.com/api/v1/search?q=anxiety \
  -H "X-API-Key: dev_your_api_key_here"

JWT Bearer Token (Session-Based)

For applications using user login flows, use the JWT bearer token from the authentication endpoint. This is useful for browser-based applications.

# First, authenticate to get a JWT
curl -X POST https://api.pixelatedempathy.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "..."}'

# Then use the token
curl -X GET https://api.pixelatedempathy.com/api/v1/profile \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Scopes

Each API key has assigned scopes. Requests requiring a scope your key doesn't have will return 403 Forbidden. Check theAPI reference for required scopes per endpoint.

Rate Limits & Quotas

Every API response includes rate limit headers:

• X-RateLimit-Limit — Maximum requests per minute for your tier
• X-RateLimit-Remaining — Requests remaining in the current window
• X-RateLimit-Reset — Unix timestamp when the window resets
• X-RateLimit-Daily-Remaining — Daily quota remaining
• X-RateLimit-Monthly-Remaining — Monthly quota remaining

When you exceed a limit, the API returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry after 12 seconds.",
  "remaining": 0,
  "resetTimeMs": 180000
}

Error Handling

The API uses standard HTTP status codes:

• 200 — Success
• 201 — Created
• 400 — Bad request (validation error)
• 401 — Unauthorized (missing or invalid key)
• 403 — Forbidden (insufficient scopes)
• 404 — Not found
• 429 — Rate limit exceeded
• 500 — Internal server error

Error responses include a message field with details:

{
  "error": "validation_error",
  "message": "Query parameter 'q' is required",
  "details": { "field": "q", "issue": "required" }
}

Next Steps

• Code examples in TypeScript and Python
• SDK installation and usage guide
• Interactive API reference (Swagger UI)
• API versioning policy