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

# Endpoint conventions

> How CarrotHub URLs are shaped, aliases, and how to migrate from a direct provider integration

Every CarrotHub endpoint sits under a single host:

```
https://api.carrothub.ai
```

The path is what tells CarrotHub which provider and which model you
want. See the [API Reference](https://www.carrothub.ai/docs/api-reference/introduction.md) for the exact
URL of every endpoint.

## Industry aliases

For the few endpoints that have become de-facto industry standards, we
expose short aliases at the root so existing SDKs work with a single
`base_url` swap.

| Alias | Source |
| - | - |
| `/v1/chat/completions` | `/vendors/openai/v1/chat/completions` |
| `/v1/models` | `/vendors/openai/v1/models` |

## Synchronous vs asynchronous endpoints

* **Synchronous / streaming.** Chat completions and similar fast
  endpoints respond within a single HTTP request — switch the base URL
  and you're done.
* **Asynchronous tasks.** Image, video, speech, and music generation
  return a `task_id` immediately and finish out-of-band. Poll
  `GET .../<task-id>` (or use [webhooks](https://www.carrothub.ai/docs/get-started/webhooks.md)) to
  retrieve the result. See [Asynchronous tasks](https://www.carrothub.ai/docs/get-started/async-tasks.md)
  for the full pattern.

## Response headers worth knowing

| Header | What it's for |
| - | - |
| `Traceparent` | A W3C-format trace ID for this request. Include it when filing bug reports so we can find the exact run in our logs. |

## Migrating from a direct provider integration

In most cases, all you need to change is the `base_url`. For example,
moving from OpenAI direct to CarrotHub:

```diff python theme={null}
- client = OpenAI(api_key=OPENAI_KEY)
+ client = OpenAI(
+   api_key=CARROTHUB_KEY,
+   base_url="https://api.carrothub.ai/v1",
+ )
```

For providers that have their own request shape (Google, Kling, Wan,
etc.), use the matching `/vendors/<provider>/...` path. The per-endpoint
reference pages list the exact request and response schemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.