REST API Reference

Base URL

https://api.temporal-cortex.com

Authentication

All /api/v1/* endpoints require a Bearer token — your API key from the Temporal Cortex dashboard.

curl -H "Authorization: Bearer sk_live_abc123_..." \
  https://api.temporal-cortex.com/api/v1/dashboard/summary

API keys use the format sk_live_<prefix>_<base64url>. Create and manage keys in the dashboard under API Keys.

Public endpoints

These endpoints require no authentication.

Health check

GET /health

Returns 200 OK if the API is running.

Public availability

GET /public/{slug}/availability?date=2026-03-15

Query a user’s public availability by their slug. Returns free slots for the requested date.

Public booking

POST /public/{slug}/book
Content-Type: application/json

{
  "title": "Meeting with Alice",
  "start": "2026-03-15T14:00:00Z",
  "end": "2026-03-15T15:00:00Z",
  "attendee_email": "[email protected]"
}

Book a slot on a user’s calendar via their public booking endpoint. Uses Two-Phase Commit to prevent double-booking.

Identity resolution

GET /[email protected]

Resolve a person’s identity to check if they have a Temporal Cortex profile and public availability.

TOON encode

POST /api/v1/toon/encode
Content-Type: application/json

{
  "json": { "key": "value", "nested": { "array": [1, 2, 3] } }
}

Convert JSON to TOON (Token-Optimized Object Notation). Reduces token count by ~40%.

Authenticated endpoints

Dashboard

GET /api/v1/dashboard/summary

Returns plan info, usage stats, and connected calendars for the authenticated tenant.

Response:

{
  "plan": {
    "tier": "starter",
    "user_type": "individual",
    "calendars_connected": 2,
    "calendars_limit": null,
    "bookings_used": 5,
    "bookings_limit": 20,
    "calls_today": 42,
    "calls_daily_limit": null
  },
  "calendars": [
    { "provider": "google", "email": "[email protected]", "calendar_count": 3 }
  ],
  "recent_activity": []
}

Activity feed

GET /api/v1/activity

Returns recent booking and calendar activity for the tenant.

Calendar management

List connected providers:

GET /api/v1/calendars

Connect CalDAV provider:

POST /api/v1/calendars/caldav
Content-Type: application/json

{
  "server_url": "https://caldav.example.com/dav/",
  "username": "user",
  "password": "password"
}

Disconnect a provider:

DELETE /api/v1/calendars/{provider}

Where {provider} is google, outlook, or caldav.

API key management

Create a key:

POST /api/v1/keys
Content-Type: application/json

{ "name": "Production Key" }

Response: Returns the full API key (only shown once).

List keys:

GET /api/v1/keys

Delete a key:

DELETE /api/v1/keys/{id}

Settings

Get all settings:

GET /api/v1/settings

Update slug:

PUT /api/v1/settings/slug
Content-Type: application/json

{ "slug": "my-scheduling-page" }

Toggle Open Scheduling:

PUT /api/v1/settings/open-scheduling
Content-Type: application/json

{ "enabled": true }

Update booking rules:

PUT /api/v1/settings/booking-rules
Content-Type: application/json

{
  "max_advance_days": 30,
  "min_notice_hours": 2,
  "confirm_before_booking": false
}

Update user type:

PUT /api/v1/settings/user-type
Content-Type: application/json

{ "user_type": "developer" }

Valid values: "individual" or "developer".

Caller profiles

Create a caller:

POST /api/v1/callers
Content-Type: application/json

{
  "email": "[email protected]",
  "display_name": "Alice Smith",
  "trust_level": "trusted"
}

List callers:

GET /api/v1/callers

Update a caller:

PUT /api/v1/callers/{id}

Delete a caller:

DELETE /api/v1/callers/{id}

Policies

Create a policy:

POST /api/v1/policies
Content-Type: application/json

{
  "name": "Block external bookings",
  "condition_type": "caller_domain",
  "condition_value": "external",
  "action": "deny",
  "priority": 100
}

List policies:

GET /api/v1/policies

Get, update, or delete a policy:

GET    /api/v1/policies/{id}
PUT    /api/v1/policies/{id}
DELETE /api/v1/policies/{id}

Billing

Create Stripe Checkout session:

POST /api/v1/billing/checkout
Content-Type: application/json

{ "plan_tier": "pro" }

Returns { "url": "https://checkout.stripe.com/..." } — redirect the user to complete payment.

Create Stripe Customer Portal session:

POST /api/v1/billing/portal

Returns { "url": "https://billing.stripe.com/..." } — redirect the user to manage their subscription.

Usage metrics

GET /api/v1/usage/daily

Returns daily usage breakdown for the current billing period.

Webhooks

Temporal Cortex receives webhooks from external services:

• Clerk (POST /api/v1/webhooks/clerk): User creation/update events for tenant provisioning.
• Stripe (POST /api/v1/webhooks/stripe): Subscription lifecycle events for plan management.

Both endpoints verify webhook signatures (Svix for Clerk, HMAC-SHA256 for Stripe).

Rate limits

Error responses

All errors return JSON with an error field:

{
  "error": "Booking conflict: existing event 'Team Standup' at 14:00-14:30"
}

Common HTTP status codes:

• 400 — Bad request (missing/invalid parameters)
• 401 — Unauthorized (missing or invalid Bearer token)
• 404 — Not found
• 409 — Conflict (booking collision)
• 429 — Rate limited
• 500 — Internal server error