---
id: choosing-an-api
title: 'Choosing an API'
description: 'Decide between query.v1, rest-1.v1, api/asset and meta.v1 for your Agility integration.'
sidebar_label: 'Choosing an API'
sidebar_position: 3
tags: ['getting-started', 'api', 'query', 'rest', 'bulk', 'meta']
---

Agility exposes several API surfaces. They overlap, and how you query —
tight projections, real filters, explicit paging — matters more than which
one you pick. But each surface has capabilities the others lack, and starting
on the right one saves rework later. This page is the decision point: read it
before you write any code.

Typically start with `api/asset` and `meta.v1`:
- `api/asset` is the one-stop shop: its query command carries the same document structure as `query.v1`, and the same
surface creates, updates and invokes operations — one asset at a time or in batches. 
- `meta.v1` tells you what the schema looks like before you touch it. 

Reach for the other surfaces when they offer something `api/asset` does not.

| If you want to…                                                                     | Use                             |
| ----------------------------------------------------------------------------------- | ------------------------------- |
| Query, create, update and run operations — most data work                           | [`api/asset`](/apis/asset-bulk) |
| Discover asset types, attributes, relations, operations                             | [`meta.v1`](/apis/meta-v1)      |
| Read history, read as of a past moment, or get a defaulted template for a new asset | [`rest-1.v1`](/apis/rest-1)     |
| Read with a leaner response shape                                                   | [`query.v1`](/apis/query-v1)    |
| Localize labels and terminology                                                     | [`loc-2.v1`](/apis/loc-2-v1)    |
| React to changes instead of polling                                                 | [Webhooks](/apis/webhooks)      |

## Decision Table

| Dimension          | `api/asset`                                                          | `meta.v1`                                  | `rest-1.v1`                                                                       | `query.v1`                                                                 |
| ------------------ | -------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Primary purpose    | One-stop shop: query, create, update, run operations                  | Describe the schema                        | Read/write individual assets, history, templates                                   | Read assets                                                                  |
| Direction          | Read and write                                                        | Read only                                  | Read and write                                                                     | Read only                                                                    |
| Payload style      | YAML or JSON commands (query/create/update/execute)                   | JSON/XML schema documents                  | URL-addressed asset + JSON or XML body                                             | JSON query document (`from`/`select`/`where`/…)                              |
| Filtering power    | The same query document as `query.v1`, embedded as its query command  | N/A                                        | Full filter grammar via `where`/`filter`; flat attribute-path selection via `sel`  | `where`, `filter`, `sort`, `page`, `asof`, plus nested relation projection   |
| Writes per request | Many assets                                                           | None                                       | One asset                                                                          | None                                                                         |
| Relations          | Traverse and project in queries; set in writes                        | Describes relations, doesn't return data   | One hop at a time                                                                  | Traverse and project nested relations                                        |
| Historical data    | Yes (`asof` in the query command)                                     | No                                         | Yes (the `/rest-1.v1/Hist` namespace, `asof`)                                      | Yes (`asof`, moments)                                                        |
| Typical latency    | One round trip per batch                                              | Cacheable, changes rarely                  | One round trip per asset                                                           | One round trip for a whole graph                                             |
| Best for           | Most integrations: imports, migrations, read-modify-write, mass changes | Dynamic forms, validation, code generation | History audits, new-asset templates, XML clients                                   | Lean read-only feeds and dashboards                                          |
| Avoid when         | You need a defaulted new-asset template                               | You need actual asset data                 | You are touching hundreds of assets in a loop                                      | You need to write, or need response metadata such as total counts            |

## How to Choose, in Order

1. **Start with `api/asset`.** Its query command gives you the full query
   document — filtering, sorting, paging, relation projection — and the same
   surface creates, updates and runs operations, singly or in batches. It is
   the only surface that mixes reads, writes and operations in one request.
2. **Pair it with `meta.v1`.** Learn the schema first, cache the result, and
   validate against it. Attribute names differ between instances because of
   custom fields.
3. **Reach for `rest-1.v1` when you need what `api/asset` does not offer**:
   the `/rest-1.v1/Hist` namespace to enumerate an asset's full change
   history, `/rest-1.v1/New` for a defaulted new-asset template, or an XML
   payload. (Point-in-time reads need no switch — `asof` works in `api/asset`
   and `query.v1` too.)
4. **Use `query.v1` when a leaner response is worth it.** It shares its query
   semantics with `api/asset`'s query command and returns a smaller response
   structure — but that response omits metadata such as total counts, which
   matters as soon as you page through a large result set.
5. **Do you need to know when something changed?** Prefer
   [webhooks](/apis/webhooks) over polling on a timer.

The same decision as a picture:

```mermaid
flowchart TD
    Start([What do you need?]) --> Notify{React to changes<br/>as they happen?}
    Notify -- yes --> WH[webhooks]
    Notify -- no --> Schema{Discover types,<br/>attributes, operations?}
    Schema -- yes --> Meta[meta.v1]
    Schema -- no --> Special{Change history, new-asset<br/>template, or XML?}
    Special -- yes --> R1[rest-1.v1]
    Special -- no --> Lean{Read-only feed where a<br/>lean response matters?}
    Lean -- yes --> Q1[query.v1]
    Lean -- no --> AA[api/asset — the default]
```

:::tip
Most integrations need only two surfaces: `meta.v1` once at startup to learn
the schema, and `api/asset` for everything else. Adding `rest-1.v1` for
history or templates, or `query.v1` for lean read feeds, is normal — but they
are additions, not the starting point.
:::

:::warning
Do not use `rest-1.v1` in a loop as a substitute for `api/asset`. It multiplies
round trips, and every request carries the full authentication and processing
overhead.

Note that `api/asset` is not one atomic transaction — it deliberately breaks the
work into several, which is what stops a large import from blocking other users.
See [Performance](/guides/performance#what-batching-actually-saves).
:::

## Related Topics

- [Quickstart](/getting-started/quickstart) — make your first authenticated call
- [Authentication](/getting-started/authentication) — access tokens, Basic authentication and headers
- [Assets](/concepts/assets) and [Attributes](/concepts/attributes) — the data model
- [Payload patterns](/guides/payload-patterns) — request shapes that work well