---
id: payload-patterns
title: 'Payload Patterns Guide'
description: 'The canonical request shapes for querying, creating, updating and operating on Agility assets'
sidebar_label: 'Payload Patterns'
sidebar_position: 3
tags: ['guides', 'payloads']
---

Every task here, querying, creating, updating, and operating on assets, has one
canonical request shape. Each section shows that shape and links to the
reference page that documents it in full.

## Read: the Query Document

The same document structure works on `query.v1` and as the
[Bulk API's query command](/apis/asset-bulk/queries). The complete,
correctly-bounded template:

```json
{
  "from": "Story",
  "where": { "Scope": "Scope:0" },
  "filter": ["Status.RollupState='Active'", "Estimate>'2'"],
  "select": ["Number", "Name", "Status.Name", "Owners.Name"],
  "sort": ["-ChangeDateUTC"],
  "page": { "size": 50, "start": 0 }
}
```

- `where` is exact match; `filter` takes the
  [comparison grammar](/reference/query-grammar/filter-expressions), values
  quoted
- Fetch by OID with `"where": { "ID": "Story:1207" }`
- Project grouped child objects with a nested subquery:
  `{ "from": "Children:Task", "select": ["Number", "Name"] }`
- **Never omit `page`** on a list query —
  [there is no default page size](/guides/query-size-and-performance)

## Create

**Bulk API** — an object with `AssetType` is a create command; relations
(including multi-value) set directly:

```json
[
  {
    "AssetType": "Story",
    "Name": "My new story",
    "Scope": "Scope:0",
    "Owners": ["Member:20"]
  }
]
```

**rest-1.v1** — XML, or JSON with the `Attributes` wrapper:

```xml
<Asset>
  <Attribute name="Name" act="set">My new story</Attribute>
  <Relation name="Scope" act="set"><Asset idref="Scope:0"/></Relation>
</Asset>
```

See [creating assets](/apis/asset-bulk/creating-assets) and
[rest-1 update examples](/apis/rest-1/update-examples).

## Update

**Bulk API** — `{from, update}`; scalars set directly, multi-relations take
`add`/`remove`:

```json
[
  {
    "from": "Story:1207",
    "update": {
      "Estimate": 3,
      "Timebox": "Timebox:1010",
      "Owners": { "add": ["Member:20"], "remove": ["Member:1035"] }
    }
  }
]
```

**rest-1.v1** — the same effect in XML (`act="set"`, per-asset
`act="add"`/`act="remove"` inside a `<Relation>`), or JSON:

```json
{ "Attributes": { "Estimate": { "value": 3, "act": "set" } } }
```

[Relation updates](/apis/asset-bulk/relation-updates) covers every
shorthand; [dates](/apis/conventions/dates) covers the exclusive-EndDate
trap before you write date pairs.

## Operations

```text
POST ~/rest-1.v1/Data/Story/1207?op=Inactivate     (empty body)
```

or the Bulk API's [execute command](/apis/asset-bulk/operations) to run one
operation across many assets. Remember:
[Inactivate closes, Delete soft-deletes](/concepts/operations#the-lifecycle-quartet),
and rest-1's `Copy` returns the new asset's OID.

## Compose with Aliases

Later commands in a Bulk request can reference earlier ones — a create can
cite another create. This bootstrap (from a real integration) builds a
scope, a team, a team room and team-scoped statuses in one request:

```json
[
  { "@scope": { "AssetType": "Scope", "Parent": "Scope:0", "Name": "My Space", "BeginDate": "2026-09-01", "Scheme": "Scheme:1001" } },
  { "@team":  { "AssetType": "Team", "Name": "My Space" } },
  { "@ready": { "AssetType": "StoryStatus", "Name": "Ready", "RollupState": "0",  "Team": "@team" } },
  { "@doing": { "AssetType": "StoryStatus", "Name": "Doing", "RollupState": "64", "Team": "@team" } },
  { "@story": { "AssetType": "Story", "Name": "First story", "Scope": "@scope", "Team": "@team" } }
]
```

Aliases have [real limitations](/apis/asset-bulk/aliases-and-projection) —
notably, an operation's output cannot be referenced.

## YAML, If You Prefer It

`api/asset` accepts `text/yaml`; a stream of documents separated by `---`
is the array:

```yaml
AssetType: Story
Name: First
Scope: Scope:0
---
from: Story:1207
update:
  Estimate: 3
```

See [request format](/apis/asset-bulk/request-format) — and the
[sibling-alias trap](/apis/asset-bulk/aliases-and-projection#limitations)
before you hand-write YAML with aliases.

## Related Topics

- [Bulk API](/apis/asset-bulk) — the full command reference
- [Examples](/examples/curl) — these shapes as runnable code
- [Query grammar](/reference/query-grammar)