Welcome to the API documentation! Our API conforms to the REST architectural style, emphasizing principles like statelessness and a uniform interface for resource interaction.

The API communicates using application/json format, ensuring compatibility with various programming languages and platforms, and all interactions are secured via HTTPS (Hypertext Transfer Protocol Secure) to maintain data confidentiality and integrity.

Each marketplace created is issued a unique API key. Depending on the mode (live or test) in which the platform was created, the scope of the API key will be restricted to that specific mode. API keys must be passed in the request headers as Bearer tokens for authentication and authorization purposes.

To facilitate a smooth developer experience, we strive to maintain consistency and backward compatibility across different API versions, helping ensure seamless transitions and minimizing disruptions to existing integrations.

You can access the API using the base URL https://api.candle.so/:version, which provides a clear and standardized entry point for making API requests. Be sure to specify the correct version in the URL and include your API key in the request headers to successfully interact with the API.

Authentication

Authentication for our API is conducted using API keys, which are passed in the request headers for each API call. Depending on whether your platform is in test mode or live mode, the corresponding API key should be included in the Authorization header as a Bearer token.

Header Format

Ensure that the Authorization header follows this format:

• Test Mode: Authorization: Bearer ambient_test_xxx

• Live Mode: Authorization: Bearer ambient_live_xxx

Date Formats

Dates within the API are consistently formatted using the UTC ISO standard (YYYY-MM-DDTHH:MM:SSZ), ensuring uniformity and ease of interpretation across different systems and time zones.

Internally, dates are stored in UTC ISO format, having been converted from the user's preferred timezone to maintain consistency and prevent discrepancies in date representations.

When working with user-specific data, the API respects individual timezone preferences stored in user profiles. All datetime fields such as effective_datetime, issued_datetime, and created timestamps maintain their UTC format while allowing client applications to handle timezone conversion based on user preferences.

Error Handling

Error handling within the API relies on standard HTTP response codes, allowing developers to identify the nature of the error encountered during API interactions.

In addition to HTTP response codes, errors received from third-party integrations, such as Stripe, are passed along to provide detailed insights into the root cause of issues related to external services.