---
id: base-url
slug: /apis/conventions/base-url
title: 'Base URL'
description: 'How to build the base URL that every Agility API request is relative to, from your instance host and instance name.'
sidebar_label: 'Base URL'
sidebar_position: 2
tags: ['api', 'conventions', 'base-url']
---

Every request to the Agility API is built from a **host** and an **instance**. Together they
form the base URL that all endpoint paths are appended to.

## Finding Your Host and Instance

Look at the URL you use to reach Agility in a browser. It generally looks like this:

```text
https://www7.v1host.com/V1Instance
```

In that URL:

| Part               | Value              | Meaning                                                                 |
| ------------------ | ------------------ | ----------------------------------------------------------------------- |
| `www7.v1host.com`  | your **host**      | The server your instance is hosted on.                                   |
| `V1Instance`       | your **instance**  | The application path segment identifying your specific Agility instance. |

So the base URL is:

```text
https://{host}/{instance}
```

### Base URL Placeholder

Code examples throughout this site use *~/* as a placeholder for your Agility instance base URL. For example, *~/api/webhook* means
  `https://{V1Host}/{V1Instance}/api/webhook` — for an instance at `https://www7.v1host.com/MyInstance`.

:::tip
Enter your base URL in the field at the top of any page and every *~/* on the page becomes your actual URL, so you can copy a request and run it as-is. Your instance URL stays in your browser's local storage and is never sent anywhere.

For example: `~/meta.v1/`
:::

## Building an Endpoint URL

Append the endpoint path to the base URL:

```text
https://www7.v1host.com/V1Instance/api/tags/all
https://www7.v1host.com/V1Instance/rest-1.v1/Data/Story
https://www7.v1host.com/V1Instance/query.v1
https://www7.v1host.com/V1Instance/meta.v1
```

:::note On-premises and custom deployments
The instance segment is not always present. Some on-premises deployments host Agility at the
root of a site (`https://agility.example.com/`) or under a different application path
(`https://intranet.example.com/agility`). Use whatever path segment appears before
`rest-1.v1`, `query.v1`, `meta.v1` or `api/` in your own browser URL. If the application is at
the site root, the base URL is simply `https://{host}`.
:::

:::warning Do not drop version suffixes
Endpoint names carry version numbers that are part of the path, not decoration:
`rest-1.v1`, `query.v1`, `meta.v1` and `loc-2.v1`. The `-2` in `loc-2.v1` in particular is
significant — `loc.v1` is a different, older endpoint.
:::

## One URL That Works by Accident

`<base>/rest-1.v1/query.v1` answers queries — but it is a malformed URL that
only happens to work, not a real route. `query.v1` is its own endpoint at the
instance root:

```text
https://www7.v1host.com/MyInstance/query.v1        ✓ canonical
https://www7.v1host.com/MyInstance/rest-1.v1/query.v1   ✗ works today, not a contract
```

Integrations built on the accidental form have shipped (it appears in real
customer configurations), so it is worth recognizing — and worth fixing to
the canonical URL when you touch such code.

## Related Topics

- [HTTP headers](/apis/conventions/http-headers) — the headers every request needs
- [Authentication](/getting-started/authentication) — how to fill in the `Authorization` header
- [Quickstart](/getting-started/quickstart) — your first authenticated call