Skip to main content

Payload Patterns Guide

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. The complete, correctly-bounded template:

{
  "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, 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

Create​

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

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

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

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

See creating assets and rest-1 update examples.

Update​

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

[
  {
    "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:

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

Relation updates covers every shorthand; dates covers the exclusive-EndDate trap before you write date pairs.

Operations​

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

or the Bulk API's execute command to run one operation across many assets. Remember: Inactivate closes, Delete soft-deletes, 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:

[
  { "@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 — 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:

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

See request format — and the sibling-alias trap before you hand-write YAML with aliases.