> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference Guidelines

> Learn about the tags, indicators, and documentation standards we use in our API documentation

This guide explains the **tags**, **indicators**, and **standards** we use in our API documentation. Understanding these conventions will help you navigate the reference materials more effectively and build robust integrations.

## API status tags

We use the following tags next to endpoint titles to indicate their status and maturity.

### \[NEW]

This tag indicates that an API endpoint has been recently added to Suki for partners.

* Use this safely in production; it is fully supported and documented.
* The API may receive additional non-breaking features in future updates.

### \[UPDATED]

This tag indicates that an API endpoint has received significant, backward-compatible enhancements or modifications.

* Look for new parameters, response fields, or behavior changes that you can implement.
* Your existing integrations should continue to work without modification.

### \[DEPRECATED]

This tag indicates that an API endpoint is scheduled for removal in a future version.

* You should plan to migrate any existing integrations to the recommended alternatives.
* Check the documentation for the specific migration timeline and replacement APIs. Suki provides migration guides to support your transition.

<Warning>
  You should avoid using this endpoint in new integrations.
</Warning>

### \[EARLY ACCESS]

This tag indicates that an API endpoint is available for testing and feedback but may not be fully stable.

* The API's behavior may change based on feedback, and breaking changes are possible before it becomes generally available.
* Access to this API may require special configuration. We encourage your feedback to help us improve it.

<Warning>
  Use early access APIs with caution.
</Warning>

<Note>
  The <Badge color="orange">ws</Badge> and <Badge color="orange">webhook</Badge> indicators in the API documentation indicate that an API endpoint is a WebSocket or a Webhook endpoint.
</Note>

## Documentation standards

### Parameters

Each parameter in an API request is clearly marked to ensure you know what is required.

* **Required**: You must include these parameters in all API requests. Requests will fail without them.
* **Optional**: Include these parameters to access enhanced functionality. When applicable, the documentation will note the default value used if you don't provide one.

### Examples

All API endpoints include comprehensive examples to guide your implementation.

* **Response examples**: You will find examples of success responses with realistic data, as well as common error responses. Each field in the response is described.
* **Code examples**: You will find practical code snippets, such as `cURL` commands for direct testing and `JSON` payloads to illustrate the request and response structure.

## Using code examples in your integration

Snippets in this reference (Python, TypeScript, cURL, and similar) show real paths, headers, and JSON shapes. To use them in your own systems, do the following:

* **Use real credentials**: Replace placeholders (for example `<partner_id>`, `<partner_token>`, or `<sdp_suki_token>`) with values from your partner integration. Complete the [Partner onboarding](/documentation/partner-onboarding) flow first, then follow [Provider authentication](/api-reference/provider-authentication) for register, login, and how tokens map to API headers. Form Filling APIs follow the same authentication model; see [Form Filling authentication](/form-filling-api-reference/authentication) for that tab’s layout.
* **Use the right base URL**: Examples may use a staging host (for example `https://sdp.suki-stage.com`). Use the base URL Suki gives you for each environment (staging, production, and so on).
* **Keep secrets server-side**: Do not put partner tokens, JWTs, or `sdp_suki_token` in untrusted clients, public repos, or browser bundles where they can be extracted.
* **Python**: Install any dependency the sample assumes (for example `requests` via `pip install requests`). Run calls from a backend service or trusted script with outbound HTTPS to Suki.
* **TypeScript or JavaScript**: Run samples on the **server** using a runtime that provides **`fetch`** (for example **Node.js 18+**, Deno, or Bun). Older Node versions need another HTTP client or a `fetch` polyfill. Calling Suki **directly from a browser** usually hits **CORS** limits unless your integration is explicitly allowed; typical integrations call Suki from **your backend** or **your proxy**.
* **cURL**: Use a shell with `curl` installed; pass the same headers and JSON bodies as in the docs, with real tokens and URL.

## Version management

### API versioning

Our APIs follow semantic versioning principles to make updates predictable.

* **Major versions (`v1`, `v2`)**: Indicate breaking changes that may require you to update your code.
* **Minor versions (`v1.1`, `v1.2`)**: Introduce new features in a backward-compatible way.
* **Patch versions (`v1.1.1`, `v1.1.2`)**: Include backward-compatible bug fixes and minor improvements.

The following table shows which features are available in each version:

| Feature                         | v1 |
| ------------------------------- | -- |
| Authentication (Login/Register) | ✓  |
| Ambient session management      | ✓  |
| Audio streaming (WebSocket)     | ✓  |
| Content retrieval               | ✓  |
| Audio transcription             | ✓  |
| Multilingual support            | ✓  |
| Personalization                 | ✓  |
| Problem-Based Charting (PBC)    | ✓  |
| Webhooks                        | ✓  |
| User preferences                | ✓  |
| Form filling                    | ✓  |
| Dictation                       | ✓  |

### Backward compatibility

We are committed to making platform updates as smooth as possible.

* We communicate breaking changes well in advance and provide migration guidance.
* When we add new optional parameters, your existing integrations will not break.
* Changes to the format of API responses are additive, meaning we may add new fields, but we will not remove or alter existing ones in a breaking way.

## Best practices

### Choosing the right API

* **For production use**: You should use APIs that are unmarked or are tagged as `[NEW]` or `[UPDATED]`. These are stable, fully supported, and have long-term compatibility guarantees.
* **For development and testing**: Consider using `[EARLY ACCESS]` APIs to preview upcoming features and provide feedback. This can help you plan for future integrations.

### Migration strategy

When an API you are using is marked as `[DEPRECATED]`, we recommend the following process:

1. **Assess impact**: Review your current usage of the deprecated endpoint.
2. **Plan timeline**: Check the deprecation timeline in the documentation and plan your migration.
3. **Test alternatives**: Implement and test the recommended replacement API.
4. **Migrate**: Update your integration in phases to minimize disruption.

### Getting help

For questions about API status, migration timelines, or implementation guidance, please contact our **customer success team**.

Read the [API changelog](/api-reference/product-updates/changelog) section for the latest updates and changes to the APIs. For a searchable list of deprecated endpoints, parameters, and SDK properties, refer to the [Deprecation list](/updates/deprecations).

## Next steps

Use the following API to get started with the Suki Platform:

<CardGroup cols={3}>
  <Card title="Ambient API" arrow={true} icon="code" href="/api-reference/ambient-sessions/context">
    Learn about the Ambient API
  </Card>

  <Card title="Form Filling API" arrow={true} icon="code" href="/form-filling-api-reference/overview">
    Learn about the Form Filling API
  </Card>

  <Card title="Dictation API" arrow={true} icon="code" href="/api-reference/ambient-dictation">
    Learn about the Dictation API
  </Card>
</CardGroup>