# Use the API (/docs/use/api)



Use the **BSQAI API** from applications, scripts, and developer tools. It is the integration boundary for platform capabilities; do not connect application code directly to internal model gateways or storage services.

## Before you begin [#before-you-begin]

Obtain your installation's API address, a valid credential, and permission for the operation you want to perform. Examples below use `https://api.<platform-domain>/v1`; replace the domain with your deployment's address.

## Choose a credential [#choose-a-credential]

| Credential       | Use it when                                                     | Tenant context                                                        |
| ---------------- | --------------------------------------------------------------- | --------------------------------------------------------------------- |
| API key          | Connecting a tool or script with a key created for your account | Bound to the tenant selected when the key is created                  |
| JWT access token | Integrating with the platform's sign-in flow                    | Select an authorized tenant when the account belongs to more than one |

Create an API key from [Portal → Chat & Work → API Keys](/docs/use/portal/chat-and-work#api-keys). The full key is shown once. Keep it out of source code and shared logs. Creating a key does not grant additional roles or access to other tenants.

Both credentials can be sent as `Authorization: Bearer <credential>`. API keys also support the `X-Api-Key` header. For JWT acquisition and version-specific header compatibility, use the [developer authentication guide](/docs/develop/use-local-models-via-api#authentication-options).

## Make a first request [#make-a-first-request]

List the models exposed by your installation:

```bash
export BSQAI_BASE_URL="https://api.<platform-domain>/v1"
export BSQAI_API_KEY="<your-api-key>"

curl --fail-with-body "$BSQAI_BASE_URL/models" \
  -H "Authorization: Bearer $BSQAI_API_KEY"
```

Check that the request succeeds and returns the expected model IDs. Use an ID from that response in subsequent model requests; a model's display name is not necessarily its API ID.

## Tenant selection [#tenant-selection]

A tenant is identified by its Keycloak Organization UUID. With a JWT belonging to more than one organization, send the selected UUID in `X-Tenant-Id`:

```bash
export BSQAI_TOKEN="<jwt-access-token>"
export BSQAI_TENANT_ID="<keycloak-organization-uuid>"

curl --fail-with-body "$BSQAI_BASE_URL/models" \
  -H "Authorization: Bearer $BSQAI_TOKEN" \
  -H "X-Tenant-Id: $BSQAI_TENANT_ID"
```

The header is optional when the JWT has exactly one organization membership. Browser WebSocket clients use the `tenant_id` query parameter because they cannot set custom handshake headers. An API key's tenant is resolved from the key; the key cannot be moved to another tenant with this header.

## Continue with your task [#continue-with-your-task]

* [Build an AI application](/docs/get-started/build-ai-application) for the end-to-end integration journey.
* [Model requests and SDK examples](/docs/develop/use-local-models-via-api) for generation, streaming, embeddings, reranking, and client configuration.
* [Developer tools](/docs/develop/developer-tools) for coding-agent and local-tool setup.
* [Managed-ingestion API](/docs/develop/data-connectors#api-integration) for data connections and transfers.
* [API reference](/docs/reference#api-endpoints) for the live endpoint and schema reference exposed by your deployment.
* [Roles and permissions](/docs/reference/roles-permissions) when a valid credential cannot perform an operation.