# Base URL & Environments

Every Welkin API request is scoped to a specific **tenant** and **instance**. Understanding this two-part structure is essential before making your first call.

## Base URL Pattern

```
https://api.welkinhealth.com/{tenantName}/{instanceName}/
```

| Variable       | Description                                                                               |
| -------------- | ----------------------------------------------------------------------------------------- |
| `tenantName`   | Your organization's unique identifier, provided during onboarding (e.g., `acme-health`)   |
| `instanceName` | The target environment within your tenant: `live`, `sandbox`, or a named staging instance |

**Example — production request:**

```
GET https://api.welkinhealth.com/acme-health/live/patients
```

**Example — sandbox request:**

```
GET https://api.welkinhealth.com/acme-health/sandbox/patients
```

## Environments

Welkin tenants have multiple isolated environments that share the same configuration (CDTs, programs, roles) but maintain completely separate patient data.

| Environment              | Purpose                                                                                       |
| ------------------------ | --------------------------------------------------------------------------------------------- |
| `live`                   | Production environment — real patient data, active care delivery                              |
| `sandbox`                | Integration testing — safe to create, modify, and delete records without affecting production |
| Custom (e.g., `staging`) | Some organizations have additional named environments for UAT or QA                           |

> **Important:** Always test against `sandbox` before running integrations against `live`. Data written to `live` affects real patient records.

## Finding Your Tenant Name

Your `tenantName` is provided by Welkin during onboarding. You can also find it in the URL when logged into the Welkin Care or Admin portal:

```
https://app.welkinhealth.com/{tenantName}/...
```

## HTTPS Required

All API requests must use HTTPS. HTTP requests will be rejected. TLS 1.2 or higher is required.

## Request Headers

Every API request requires:

```
Authorization: Bearer {access_token}
Content-Type: application/json
```

See [Authentication](/developer-and-integration-guide/getting-started/authentication.md) for how to obtain a Bearer token.

***

## Related Topics

* [Authentication](/developer-and-integration-guide/getting-started/authentication.md) — obtain a Bearer token
* [Core Concepts](/developer-and-integration-guide/getting-started/core-concepts.md) — tenants, instances, patients, and data model overview
* [Provisioning API Client](https://welkin-health-1.gitbook.io/welkin-health-docs/admin/provisioning-api-client) — set up API credentials in Admin


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.welkinhealth.com/developer-and-integration-guide/getting-started/base-url-and-environments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.