---
id: meta-v1
slug: /apis/meta-v1
title: 'Meta API (meta.v1)'
description: 'Discover the asset types, attribute definitions and operations your Agility instance actually supports, before you address them through rest-1.v1.'
sidebar_label: 'Overview'
sidebar_position: 1
tags: ['api', 'meta', 'metadata', 'schema', 'discovery']
---

## 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`](/apis/rest-1) 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.

:::warning[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:

| URL                          | Returns                                                |
| ---------------------------- | ------------------------------------------------------ |
| `/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.

```bash title="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:

```bash
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.

:::tip[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:

| Property           | Meaning                                                       |
| ------------------ | ------------------------------------------------------------- |
| `name`, `token`    | How to address the attribute in a `rest-1.v1` URL.            |
| `attributetype`    | The value's data type. See [Attribute types](/reference/attribute-types). |
| `isrequired`       | Whether a value must be supplied when creating an asset.      |
| `isreadonly`       | Whether the attribute can be written at all.                  |
| `ismultivalue`     | Whether the attribute holds one value or a collection.        |
| `RelatedAsset`     | For relations, the asset type on the other end.               |
| `ReciprocalRelation` | The 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`](/apis/rest-1) using the tokens
   `meta.v1` gave you.

## Related Topics

- [Query examples](/apis/meta-v1/query-examples) — all four request shapes with
  real responses.
- [Security & errors](/apis/meta-v1/security-and-errors) — the authentication
  position and error payload format.
- [Attribute types](/reference/attribute-types) — the authoritative list of
  `attributetype` values.
- [REST API (rest-1.v1)](/apis/rest-1) — addressing the data this schema
  describes.
- [Information model](/apis/rest-1/information-model) — how asset types,
  attribute definitions, assets and attributes fit together.