Skip to main content

Bulk API (api/asset)

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.

POST ~/api/asset
Content-Type: application/json   (or text/yaml)
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 and query.v1, a single api/asset request can mix command kinds freely:

Command kindShapePage
CreateAssetType + attributesCreating assets
Updatefrom + optional where / filter / with + updateUpdating assets
Execute operationfrom + optional where / filter / with + executeOperations
Queryfrom + select / where / filter / sortQueries
ConfigurationconfigRequest and response 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.

A First Request​

POST ~/api/asset
{
  "AssetType": "Story",
  "Scope": "Scope:0",
  "Name": "First Story"
}
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:

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

Section Contents​

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