Magic Query

Magic Query is a URI-style façade over the GraphQL schema for non-technical integrators and LLM agents. Pass a short string to magicQuery and it parses, routes to a vetted predefined query, executes it as the calling identity, and returns flat JSON.

Syntax

<noun>[#<id>][?<key>=<value>[,<key>=<value>...]]

• noun — the entity, e.g. jobs (collection) or job (single).
• #id — required for single nouns, e.g. job#job_01H... — the full TypeID, prefix included; job#01H... is rejected with "Expected type JobID".
• ?filters — comma- (or &-) separated key=value pairs, e.g. ?limit=10,status=COMPLETED.

Examples: jobs?limit=10,status=COMPLETED · job#job_01H2XYZ... · customers?active=true

Endpoints

• magicQuery(query): JSON — execute; returns the predefined query's data.
• listMagicQueries: [MagicQueryInfo!]! — every noun + description + options (start here).
• getMagicQuerySchema(query): MagicQuerySchema — { inputSchema (JSON Schema), outputSchema (introspection) } for a noun.
• getMagicQueryGraphQL(query): MagicQueryOperation — the { query, variables } a Magic Query resolves to, for graduating to raw GraphQL.

Discovery loop

listMagicQueries → getMagicQuerySchema("<noun>") to learn the input options and output fields → magicQuery("<noun>?..."). On a bad noun or filter, the error's extensions carry code, actionable_message, and suggestions ("did you mean") so you can correct the string and retry.

Available nouns

Noun	Kind	Description	Options
jobs	COLLECTION	Print/production jobs. Filter by status, name, or tag.	limit, after, name, status, tag
job	SINGLE	A single print/production job by id.	#<id>
customers	COLLECTION	Customer accounts. Filter by name, email, or active state.	limit, after, name, email, active
customer	SINGLE	A single customer account by id.	#<id>
invoices	COLLECTION	Customer invoices. Filter by status, kind, customer, or invoice number.	limit, after, status, kind, customerId, invoiceNumber
invoice	SINGLE	A single invoice by id.	#<id>
estimates	COLLECTION	Customer estimates/quotes. Filter by status, customer, or estimate number.	limit, after, status, customerId, estimateNumber
estimate	SINGLE	A single estimate/quote by id.	#<id>
payments	COLLECTION	Payments received. Filter by invoice, method, or currency.	limit, after, invoiceId, method, currency
payment	SINGLE	A single payment by id.	#<id>
contacts	COLLECTION	People at customer accounts. Filter by customer, email, or last name.	limit, after, customerId, email, lastName, primary
addresses	COLLECTION	Postal addresses. Filter by customer, city, country, or address type.	limit, after, customerId, city, country, addressType
address	SINGLE	A single address by id.	#<id>
businessUnits	COLLECTION	Organisational business units. Filter by name, code, or active state.	limit, after, name, code, active
businessUnit	SINGLE	A single business unit by id.	#<id>
costCenters	COLLECTION	Cost centres within business units. Filter by name, code, unit, or active state.	limit, after, name, code, businessUnitId, active
costCenter	SINGLE	A single cost centre by id.	#<id>
users	COLLECTION	Platform users. Filter by email, name, or kind (HUMAN/BOT/KIOSK).	limit, after, email, name, kind
user	SINGLE	A single user by id.	#<id>
policies	COLLECTION	IAM permission policies. Filter by name.	limit, after, name
policy	SINGLE	A single IAM policy, including its permission statements, by id.	#<id>
devices	COLLECTION	IoT/production devices. Filter by type, manufacturer, network, or active state.	limit, after, deviceType, manufacturer, networkId, active
device	SINGLE	A single device by id.	#<id>
components	COLLECTION	Job components (parts of a job). Filter by job, name, kind, or external id.	limit, after, jobId, name, kind, externalId
component	SINGLE	A single job component by id.	#<id>
operations	COLLECTION	Production operations/steps. Filter by job, component, status, kind, or name.	limit, after, jobId, componentId, status, kind, name
operation	SINGLE	A single production operation by id.	#<id>
teams	COLLECTION	Teams of users. Filter by name.	limit, after, name
team	SINGLE	A single team by id.	#<id>
tasks	COLLECTION	Work tasks. Filter by status, type, assignee, assigned team, or priority.	limit, after, status, type, assignedUserId, assignedTeamId, priority
task	SINGLE	A single task by id.	#<id>

Pagination options limit (→ page size) and after (→ cursor) are available on every collection noun in addition to those listed.