Getting Started

Start making authenticated API calls in minutes.

curl -X POST https://api.clearinitiative.io/graphql \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"{ me { id email } }"}'Copy

Authentication

API Keys (server-to-server)

Pass your key in the Authorization header as a Bearer token:

Authorization: Bearer sk_live_your_key_hereCopy

Session Cookies (browser clients)

Sign in via the auth REST API. The session cookie is set automatically and sent with subsequent requests:

// Sign in
const res = await fetch('/api/auth/sign-in/email', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'your-password',
  }),
});

// Subsequent GraphQL calls (cookie sent automatically)
const data = await fetch('/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ query: '{ me { id email } }' }),
});Copy

Key Lifecycle

• Keys are prefixed sk_live_ and contain 256 bits of entropy
• Only a short prefix is stored for display — the full key is hashed with SHA-256
• Keys can optionally have an expiry date; expired keys are rejected automatically
• Revoking a key is permanent and cannot be undone
• Maximum 10 active keys per account

Error Responses

Unauthenticated or unauthorized requests return standard GraphQL errors:

{
  "errors": [{
    "message": "You must be logged in to perform this action",
    "extensions": { "code": "UNAUTHENTICATED" }
  }],
  "data": null
}Copy

API Reference

Interactive Explorer

Browse the full schema, autocomplete queries, and test requests in the browser.

Base URL & Headers

POST /graphql
Content-Type: application/json
Authorization: Bearer sk_live_...Copy

Request Format

{
  "query": "query { me { id email role } }",
  "variables": {}
}Copy

Code Examples

curl

curl -X POST https://api.clearinitiative.io/graphql \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"{ me { id email role } }"}'Copy

JavaScript (fetch)

const response = await fetch('https://api.clearinitiative.io/graphql', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: \`{ me { id email role } }\`,
  }),
});
const { data } = await response.json();
console.log(data.me);Copy

Python (requests)

import requests

response = requests.post(
    'https://api.clearinitiative.io/graphql',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={'query': '{ me { id email role } }'},
)
data = response.json()['data']
print(data['me'])Copy

Rate Limits

Usage Analytics

API key activity for your account. Last-used timestamps update when a key authenticates a request.