Environments

Two environments

The Cara API provides two environments for different stages of development:

API key mapping

Each API key type maps to an environment:

• sk_test_* keys — Use with the staging environment. Rate-limited to 100 requests/hour. Data is isolated from production.
• sk_live_* keys — Use with the production environment. Higher rate limits. Operates on real data.

Staging environment

The staging environment is a full replica of the production API with these differences:

• Isolated data — Changes in staging do not affect production.
• Lower rate limits — 100 requests/hour, 1,000/day.
• Test data available — Pre-populated with sample patients, forms, and appointments for testing.
• No real notifications — Emails and SMS are captured but not delivered to real recipients.

Switching environments

Use the environment toggle at the top of these docs to switch code examples between staging and production URLs and keys.

In your application, configure the base URL based on your environment:

const BASE_URL = process.env.NODE_ENV === 'production'
  ? 'https://platform.caramedical.com/api/v1'
  : 'https://staging.platform.caramedical.com/api/v1';
 
const API_KEY = process.env.NODE_ENV === 'production'
  ? process.env.CARA_LIVE_KEY
  : process.env.CARA_TEST_KEY;

Best practices

1. Always start with staging — Develop and test against staging before going live.
2. Use separate keys — Never use live keys in development environments.
3. Test error scenarios — Staging supports simulating errors for integration testing.
4. Monitor rate limits — Check the X-RateLimit-Remaining header in responses.