FAQ - Frequently Asked Questions
Authentication
How do I get an API token? Member menu (your avatar) → Applications → add a personal application. The token shows once. Admins can disable tokens instance-wide. Authentication.
What headers do I need? Authorization: Bearer <token>,
Content-Type: application/json, Accept: application/json. meta.v1
needs no auth at all. (Basic authentication exists but is effectively a
dev/demo setting — production instances use SSO, where tokens are the
path.)
How long do access tokens last? They don't expire. A token is valid until revoked (Applications page) or until tokens are disabled instance-wide — so rotate deliberately; nothing rotates for you.
Can I limit what a token can do? No — a token always acts with the full rights and privileges of its member. Run integrations as a dedicated member with a minimal role.
Querying
Why is my query returning empty results? Usually not an error: check
the filter (values quoted? OIDs not names?), whether the asset is closed or
deleted, and whether you hit a
silent trap — most Agility traps return 200 with
wrong data rather than failing.
What shape is the response? query.v1 returns an array of result
arrays — no results or query wrapper. Dotted selections arrive as
flattened keys ("Scope.Name"), bare relations as {"_oid": …} objects.
Examples show real responses.
How do I query custom fields? Exactly like any attribute, using the
full token from meta.v1 (usually Custom_…). Discover them there —
not by sampling data.
What's the maximum page size? None is documented — which is not an invitation. Very large pages combined with wide projections can hang; hundreds to low thousands per page works well. Query size and performance.
Writing
Why did my create/update "fail silently"? It didn't — the Bulk API
answers 200 with failures itemised in commandFailures. Check
commandFailures.count on every response.
Errors and partial failures.
How do I find valid status OIDs? Query the list type
(StoryStatus, sorted by Order) — and note a team using a Team Process
restricts which values its items may enter.
Workflows.
Can I update multiple assets at once? Yes — one api/asset request
carries many commands, and later commands can
reference earlier ones by alias.
What's the difference between set, add and remove? set
replaces a value (or a whole multi-relation); add/remove adjust a
multi-relation's membership.
Relation updates.
Why can't I delete an asset? If it's closed:
Violation'AssetCannotDeleteClosed — reactivate first, then delete. And
remember Inactivate is not Delete.
Why can't I edit a closed asset? Closed assets accept backfill
only — attributes that had no value. Changing an existing value fails
with Violation'ClosedAssetCannotEditExistingValues; reactivate to edit.
Can I change an asset's AssetType? Not by update — but conversion
operations exist where it makes sense (ConvertToDefect,
ConvertToTeam). Check the type's operations in meta.v1.
Performance
Is there a rate limit? When rate limiting is enabled, your instance uses configured quota policies, and your queries also share a database with every interactive user — slow queries are everyone's problem.
Should I use parallel requests? Modestly. A handful of concurrent requests is fine; wide fan-out of heavy queries degrades the instance. Prefer fewer, larger, well-projected pages. Performance.
Why are my requests timing out? The SQL timeout is per query, not per request — and a near-timeout query is a signal to narrow projection, filter or page size, not to raise the client timeout.
Data Model
What's the difference between Scope and Timebox? Scope answers where does the work live (organizational, permission-bearing); Timebox answers when is it planned (sprints, via the scope's Schedule). Scopes and projects.
What's an OID? AssetType:id — the permanent identifier
(Story:1207). A third part names a historical moment.
Assets.
How do parent-child relationships work? There are several hierarchies:
Super/Subs for portfolio (Epics), Parent/Children for
theme-classification and task breakdown — Parent means different
things by level. Relations.
Practices
What's the recommended way to change status? An ordinary attribute update, by OID, on either write surface — there is no transition graph to walk, but Team Process value restrictions are enforced. Workflows.
Should I cache API responses? Cache the stable things — meta.v1,
status lists, localization — and invalidate on surprises.
Performance.
How do I handle large migrations? Batch through api/asset, page
without totals, pin one upper time bound per run, and read
extracting at scale
before you start.
How do I test without touching production? Ask your administrator about a test instance — and remember deletes are recoverable until purged, which softens mistakes but is not a sandbox.