Skip to main content

API Conventions

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

Overview​

PageWhat it covers
Base URLDeriving https://{host}/{instance} from the URL you already use.
HTTP headersAuthorization, Content-Type and Accept — required on every request.
ErrorsThe status codes these APIs return and how to read an error body.
Attribute definition syntaxPointer to the normative query grammar reference.
TerminologyAsset, 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:

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.