Skip to main content

Meta API (meta.v1)

Overview​

meta.v1 describes the schema of your Agility instance: which asset types exist, what attributes each one has, how they relate, and which operations can be executed against them.

It exists because rest-1.v1 is schema-driven. Asset types and attributes are not a fixed list — they vary by version, by edition, and by customisation. Rather than hard-coding a schema into your integration, read it from meta.v1 at runtime.

The API is read-only. GET is the only method it accepts.

Prerequisites​

  • A running Agility instance and its application path, for example http://localhost/VersionOne.
  • Nothing else. meta.v1 requires no authentication of any kind — unlike every other Agility API.
No authentication means no permission filtering

Because meta.v1 is unauthenticated, it describes the schema of the instance as a whole, not the subset a particular member can see. Anyone who can reach the endpoint can enumerate your asset types and attribute names. Treat the schema as public information, and do not rely on meta.v1 to tell you what a given member is allowed to read — that is rest-1.v1's job.

The in-product reference also documents a 401 Unauthorized response for meta.v1, which contradicts the "no authentication" statement in the same document. In practice authentication is not required; the 401 documentation appears to be inherited boilerplate.

The URL Shape​

Four request shapes, from broadest to narrowest:

URLReturns
/meta.v1/The entire schema in one response.
/meta.v1/{AssetType}One asset type, with its attribute definitions and operations.
/meta.v1/{AssetType}/{AttributeName}One attribute definition.
/meta.v1/{AssetType}/{OperationName}One operation.

Attribute definitions and operations share the same URL slot, because their names do not collide within an asset type.

What does a Story look like?
curl "${AGILITY_BASE_URL}/meta.v1/Story"

The response is XML by default: a Meta or AssetType root containing AttributeDefinition elements, Operation elements, and reference elements such as DefaultOrderBy and DefaultDisplayBy that suggest how the asset type is normally sorted and labelled.

JSON is available too — send Accept: application/json, or put it in the query string, which is handy in a browser:

curl -H "Accept: application/json" "${AGILITY_BASE_URL}/meta.v1/Story"
curl "${AGILITY_BASE_URL}/meta.v1/Story?accept=application/json"

Either way, every element carries an href you can follow and a token you can use in a rest-1.v1 URL, so you can walk from the schema straight into the data.

Fetch narrowly

GET /meta.v1/ returns the entire schema, which is large. Fetch a single asset type when that is all you need, and cache what you fetch — the schema only changes when the instance is upgraded or customised.

What an Attribute Definition Tells You​

Each AttributeDefinition reports enough for an integration to handle the attribute generically:

PropertyMeaning
name, tokenHow to address the attribute in a rest-1.v1 URL.
attributetypeThe value's data type. See Attribute types.
isrequiredWhether a value must be supplied when creating an asset.
isreadonlyWhether the attribute can be written at all.
ismultivalueWhether the attribute holds one value or a collection.
RelatedAssetFor relations, the asset type on the other end.
ReciprocalRelationThe attribute that points back the other way.

Together these are what let a generic client build a form, validate input, or decide whether act="set" or act="add" is the right update verb.

Operations are simpler: each Operation element carries a name and a Validator reference to the attribute definition that determines whether the operation is currently valid for a given asset.

Typical Use​

  1. GET /meta.v1/{AssetType} once at start-up and cache it.
  2. Use isrequired to work out the minimum payload for creating an asset.
  3. Use attributetype and ismultivalue to serialise values correctly.
  4. Use the operation list to decide which state transitions to offer, and the validator attribute to decide whether to enable each one.
  5. Address the data through rest-1.v1 using the tokens meta.v1 gave you.