---
id: conventions
slug: /apis/conventions
title: 'API Conventions'
description: 'Base URLs, HTTP headers, error shapes and terminology shared by every Agility API.'
sidebar_label: 'Overview'
sidebar_position: 1
tags: ['api', 'conventions']

draft: false
---

Every Agility API shares a common foundation. Rather than repeat it on each endpoint page, it
is collected here.

## Overview

| Page                                                                  | What it covers                                                           |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [Base URL](/apis/conventions/base-url)                                 | Deriving `https://{host}/{instance}` from the URL you already use.        |
| [HTTP headers](/apis/conventions/http-headers)                         | `Authorization`, `Content-Type` and `Accept` — required on every request. |
| [Errors](/apis/conventions/errors)                                     | The status codes these APIs return and how to read an error body.         |
| [Attribute definition syntax](/apis/conventions/attribute-definitions) | Pointer to the normative query grammar reference.                        |
| [Terminology](/apis/conventions/terminology)                           | Asset, asset type, asset state, attribute definition, Oid.                |

## The Short Version

Build the base URL from your instance host and instance name, send the headers, and address
assets by Oid token:

```bash title="A complete, minimal request"
curl "https://www7.v1host.com/V1Instance/rest-1.v1/Data/Member?where=IsSelf='true'&sel=Username" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"
```

If that returns your own username, your base URL and credentials are correct and every other
endpoint in this documentation is reachable the same way.

## Conventions Used in This Documentation

- *~/* at the start of a path is shorthand for the base URL, `https://{host}/{instance}`. For example, *~/api/webhook* means `https://www7.v1host.com/MyInstance/api/webhook` — for an instance at `https://www7.v1host.com/MyInstance`. Enter your instance URL in the field at the top of the page and every occurrence of the shorthand on this site becomes a real URL for your instance (saved only in your browser's local storage).
- **`:id`, `:OidToken`, `:AssetType`** in a URL are path placeholders you substitute.
- **`{host}` / `{instance}`** are the two parts of your base URL.
- Endpoint names are given exactly as they appear on the wire, version suffixes included:
  `rest-1.v1`, `query.v1`, `meta.v1`, `loc-2.v1`, `api/asset`, `api/webhook`, `api/tags`,
  `api/ActivityStream`.

## Related Topics

- [Quickstart](/getting-started/quickstart)
- [Authentication](/getting-started/authentication)
- [Choosing an API](/getting-started/choosing-an-api)
- [Query grammar reference](/reference/query-grammar) — the normative query syntax