---
id: asset-bulk
slug: /apis/asset-bulk
title: 'Bulk API (api/asset)'
description: 'Create, update, query and invoke operations on many assets in a single request against ~/api/asset.'
sidebar_label: 'Overview'
sidebar_position: 1
tags: ['api', 'bulk', 'asset', 'batch']
---

The Bulk API lets you create, update, query, and invoke operations on one or
more assets with a single HTTP request, using either JSON or YAML. It builds on
the SQL-like syntax originally available in [`query.v1`](/apis/query-v1).

```text
POST ~/api/asset
Content-Type: application/json   (or text/yaml)
```

:::tip If you only learn one endpoint, learn this one
`api/asset` is the closest thing Agility has to a one-stop shop: queries, creates,
updates and operations all go through the same endpoint, in the same request if you
want. It is arguably the simplest, most intuitive and most powerful surface in the
product.

Two things it is **not**:

- **Not a server-side speed optimisation.** Batching saves round trips between your
  client and the server. The server does the same work either way.
- **Not one big transaction.** It deliberately splits the work into several. That is
  a feature: unlike a spreadsheet import, a large `api/asset` job will not force the
  server to block everyone else's updates until it finishes.
  :::

A few behaviours in this section are flagged as unverified on their page —
treat those with more care than the rest.

## What Makes This Endpoint Different

Unlike [`rest-1`](/apis/rest-1) and [`query.v1`](/apis/query-v1), a single
`api/asset` request can mix command kinds freely:

| Command kind | Shape | Page |
| --- | --- | --- |
| Create | `AssetType` + attributes | [Creating assets](/apis/asset-bulk/creating-assets) |
| Update | `from` + optional `where` / `filter` / `with` + `update` | [Updating assets](/apis/asset-bulk/updating-assets) |
| Execute operation | `from` + optional `where` / `filter` / `with` + `execute` | [Operations](/apis/asset-bulk/operations) |
| Query | `from` + `select` / `where` / `filter` / `sort` | [Queries](/apis/asset-bulk/queries) |
| Configuration | `config` | [Request and response format](/apis/asset-bulk/request-format) |

The server fulfils every request in **two phases** — projection, then
processing. Understanding that split is the key to understanding aliases,
hierarchy flattening, deferrals, and preview mode. Start with
[Projection, processing and aliases](/apis/asset-bulk/aliases-and-projection).

## A First Request

```json title="POST ~/api/asset"
{
  "AssetType": "Story",
  "Scope": "Scope:0",
  "Name": "First Story"
}
```

```json title="Response"
{
  "assetsCreated": { "oidTokens": ["Story:1585"], "count": 1 },
  "assetsModified": { "oidTokens": [], "count": 0 },
  "assetsOperatedOn": { "oidTokens": [], "count": 0 },
  "commandFailures": { "commands": [], "count": 0 },
  "queryResult": { "results": [], "count": -1 }
}
```

The same request in YAML:

```yaml title="POST ~/api/asset (Content-Type: text/yaml)"
AssetType: Story
Scope: Scope:0
Name: First Story
```

## Section Contents

- [Request and response format](/apis/asset-bulk/request-format) — content
  types, the JSON-array / YAML-multi-document equivalence, the response
  envelope, `resultMetaData`, and `config counts-only`.
- [Creating assets](/apis/asset-bulk/creating-assets) — single, multiple,
  hierarchies, scope by name vs. OID token, relations set from a subquery.
- [Updating assets](/apis/asset-bulk/updating-assets) — update one asset,
  update everything matching a query, ordering, updating deleted assets.
- [Updating multi-value relations](/apis/asset-bulk/relation-updates) — the
  full add/remove grammar, including the object-keys form and subqueries.
- [Find and replace](/apis/asset-bulk/find-and-replace) — conditional
  replacement on scalar text attributes and on relations.
- [Operations](/apis/asset-bulk/operations) — `execute` in its bare, `args`,
  `list`, and subquery forms; Delete and Undelete.
- [Queries](/apis/asset-bulk/queries) — single and multiple independent result
  sets, nested selects, querying an alias.
- [Projection, processing and aliases](/apis/asset-bulk/aliases-and-projection)
  — the two-phase model, auto-aliasing, user-aliasing, request-hierarchy
  flattening, and deferrals.
- [Preview mode](/apis/asset-bulk/preview-mode) — `?previewOnly=true`, and
  round-tripping a projection back to the server.
- [Errors and partial failures](/apis/asset-bulk/errors) — the failure-cascade
  shape, `sourceCommandIndex`, `#ContextOid`, and safe reissue.
- [Compound requests](/apis/asset-bulk/compound-requests) — the capstone
  example that combines every feature.

## Related Topics

- [Choosing an API](/getting-started/choosing-an-api)
- [Query API (query.v1)](/apis/query-v1)
- [Operations](/concepts/operations)
- [Assets](/concepts/assets)