Skip to main content

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:

https://www7.v1host.com/V1Instance

In that URL:

PartValueMeaning
www7.v1host.comyour hostThe server your instance is hosted on.
V1Instanceyour instanceThe application path segment identifying your specific Agility instance.

So the base URL is:

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:

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
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}.

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:

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.