Administration and IAM
Policies, users, teams, API tokens, tenant configuration, logs and archives.
155 operations · complete schema 191 KB
magicQuery
Executes a Magic Query string and returns the predefined query's JSON result. On a bad noun or parameter, returns a structured error whose 'extensions' carry 'code', 'actionable_message', and 'suggestions' for self-correction.
getMagicQuerySchema
Returns the input JSON Schema and output introspection for a Magic Query noun, so consumers (especially LLMs) can learn its contract before calling magicQuery.
listMagicQueries
Lists every available Magic Query noun with a short description and its options — the discovery entry point.
getMagicQueryGraphQL
Resolves a Magic Query string to the real GraphQL operation and variables it runs, so consumers can graduate from the façade to raw GraphQL. Does not execute.
settings
This instance's settings. Needs tenantPreferences:read or tenantConfig:read; each section then needs the permission that guarded its data before Settings existed, and is null with an error without it.
listDataChangeEventTopics
List all valid data change event topics, grouped by resource. Requires authentication.
generateDefaultDataQuery
Generate a default GraphQL data query for an event topic. Returns a query string with all scalar fields for the resource, or null if the topic has no matching query. The query uses $id as the variable for the resource ID.
iacChangeTimeline
Read up to 100 comments and events, oldest first, with an exclusive cursor. Includes comment capability, never apply authority.
iacGitChangeReviews
Read bounded plan highlights for at most 100 stack-local Change Requests.
iacGitChangeReview
Read a safe projection of the original stored plan. No private inputs, approvals or execution authority are returned.
iacStackOverview
Summarise a stack: revision, owner, last apply, resource kinds and pending changes. Requires stack read access.
iacStackResources
List deployed resources and those only open Change Requests would create, with the last and pending Change Requests for each. Requires stack read access.
iacStackHistory
List a stack's applied revisions, newest first, each linked to the Change Request that produced it. Requires stack read access.
iacStackReadme
Read README.md at the root of the stack's main branch as UTF-8 text; null without main or without a root README. Refused with README_TOO_LARGE above 256 KiB. Requires stack read access.
iacStackPermissions
Read what the viewer may do on a stack, and who may apply its changes.
iacGitRepository
Discover the authenticated Git remote for an authorized stack.
iacGitSnapshot
Read a bounded source snapshot after tenant, IAM and stack-grant authorization.
iacGitChanges
List up to 100 Change Requests, newest first, optionally filtered by branch, status or author. Requires stack read access.
iacGitChange
Read one draft Change Request in its owning stack.
iacModulePackages
Read immutable public GitHub package bytes for editor intelligence; validates lock integrity and creates no executable identity.
iacAdvisoryPlan
Non-executable advisory plan; persists no source, approval, lease or execution state.
iacAdvisorySnapshot
Read-only coordinator capability; ordinary clients cannot invoke it.
iacApplyStatus
Reconcile a lost Apply response. Only the planning principal may inspect the result.
iacStacks
List stacks visible to this user, up to 100 per page.
iacStackState
Read current deployment state; source is held separately in Git.
iacStackSecrets
List a stack's secrets by name with their version history, never their values. Requires stack read access.
iacStackValues
List the current value of every variable the stack holds, set ones only, with secrets listed by name and never by value. Requires stack read access.
iacDeclaredVariables
List the variables a commit's source declares, in declaration order, for checking that a stack holds a value for each before promoting that commit. Requires stack read access.
iacStackRules
Read a stack's rules; a stack that never set any reads the defaults. Requires stack read access.
ping
Health check endpoint
getServiceAccount
Read a BOT service account. Returns null for HUMAN and KIOSK accounts.
getExistingUser
Read an existing user without claiming IaC ownership.
getExistingUserBy
Look up an existing user by email or external identifier without claiming IaC ownership.
getUser
Fetch a user by ID. Requires user:read permission.
getUserBy
Fetch a user by external ID or email. Requires user:read permission.
listUsers
List users with pagination and filtering. Requires user:list permission.
getIAMPolicyAttachment
Read a policy attachment in the current tenant.
listIAMActions
List all available IAM actions grouped by resource. Requires authentication.
me
Who the caller is and which tenant they are acting in. Requires authentication but no permission: a caller asking who they are needs no authority over anything.
myEffectivePermissions
Get current user's effective permissions. Requires authentication.
getIAMPolicy
Fetch an IAM policy by ID. Requires iam:readPolicy permission.
listIAMPolicies
List IAM policies with pagination. Requires iam:listPolicies permission.
listUserPolicies
List policies attached to a user. Requires iam:listUserPolicies permission.
getAPIToken
Fetch an API token by ID (user can only see their own tokens). Requires apitoken:read permission.
listMyAPITokens
List the current user's API tokens with pagination. Requires apitoken:list permission.
listBotAPITokens
List the API tokens belonging to a bot user. Returns an empty list if the target user is not a bot. Requires apitoken:list permission.
listEndpointLogs
List endpoint logs with pagination. Requires incomingWebhook:read permission.
getIncomingWebhookStats
Get aggregate statistics for an incoming webhook endpoint. Requires incomingWebhook:read permission.
queryLogs
Query logs across all drains (webhook, execution, edge app, archive). Requires log:list permission.
iacSchema
The infrastructure-only view of this schema, for declarative tooling. Contains only annotated resources and the types they reach.
iacValidate
Validate an infrastructure artifact. Pure and side-effect free; safe to alias many times in one document.
iacGuides
Every authoring guide, for a tool that syncs them to a folder. Intended for `schema pull` to call once and write to disk, not for an agent to call while authoring — a file can be grepped and re-read in part, where a response arrives whole.
helpChapters
List human-facing manual chapters from the running deployment.
helpChapter
Read a chapter of the current published manual edition.
searchHelp
Search human-facing manuals using shared semantic and text retrieval.
schemaAuthoringCatalog
Compiler-owned vocabulary for the standalone XML JSON Schema dialect, including native form annotations.
compileSchemaXML
Compile standalone XML schema syntax into JSON Schema without persisting it; host restrictions apply when embedded.
renderSchemaXML
Render JSON Schema as native XML without dropping unsupported keywords or changing a saved document.
iacSchemaDocument
Fetch the JSON Schema document a SCHEMA-kind validator references, for declarative tooling.
getTeamMembership
Read a team membership by its own identity. Requires team:read permission.
getTeamBy
Find a team by its unique name in the authenticated tenant. Requires team:read permission.
getTeam
Fetch a team by ID. Requires team:read permission.
listTeams
List teams with pagination. Requires team:list permission.
teamsForUser
Teams an account belongs to. Requires team:read permission.
getTeamMembers
Fetch members of a team. Requires team:read permission.
getTaskDefinition
Fetch a task definition by ID. Requires taskDefinition:read permission.
listTaskDefinitions
List task definitions with pagination. Requires taskDefinition:list permission.
getConfig
Get current tenant configuration. Secret values are redacted. Requires tenantConfig:read permission.
getConfigVersion
Get a specific version of tenant configuration. Secret values are redacted. Requires tenantConfig:read permission.
listConfigVersions
List version history for tenant configuration, newest first, with pagination. Requires tenantConfig:list permission.
platformInfo
Which build of the platform is answering. Compare across deployments to tell them apart, or across time to notice that the server changed under a cached set of workarounds.
getArchiveJob
Fetch a single archive job by id, scoped to the caller's tenant. Null if no such job exists. Requires archiveJob:read permission.
listArchiveJobs
List the tenant's archive jobs as a cursor-paginated connection, filtered and sorted in the database. Requires archiveJob:list permission.
getArchiveExecution
A single archive execution by id, or null if no such execution exists in the caller's tenant. Requires archiveExecution:read permission.
listArchiveExecutions
Run history for one archive job, newest run first (by startedAt), with pagination. Scoped to the caller's tenant. Requires archiveExecution:list permission.
updateUnitSettings
Saves the units section. Other sections are untouched.
updateTimeSettings
Saves the time section. Other sections are untouched.
updateProductionBoardSettings
Saves the production board section. Other sections are untouched.
updateAppAccessSettings
Saves the app access section. Other sections are untouched.
updateStatusRuleSettings
Saves the status rules section. Other sections are untouched.
updateQuotingSettings
Saves the quoting section. Other sections are untouched.
updateMachineLearningSettings
Saves the machine-learning section. Other sections are untouched.
iacAddChangeComment
Append a plain text comment to a proposed or applied Change Request. Retry the same id and body after a lost response.
iacGitDeleteWorkingRef
Immediately delete a working branch with expected-head protection.
iacGitStage
Stage immutable objects without changing branch refs or deployed configuration.
iacGitUpdateWorkingRef
Compare and update a working branch; never publishes main or applies configuration.
iacGitRenameChange
Rename a draft proposal without altering source, state, or approval. Requires stack authoring access.
iacGitUpdateChangeDescription
Replace a draft Change Request's description. Only its author may do this.
iacCancelChange
Close a draft Change Request without applying it. Allowed for its author and for anyone who may apply the stack; the conversation stays readable.
iacGitCreateChange
Capture an immutable draft Change Request; no client-supplied plan is trusted or applied.
iacGitReviseChange
Capture the Change Request branch's pushed head as its next revision, keeping the conversation. Returns the Change Request unchanged when the branch has no new commits.
iacPlanChange
Produce a trusted server plan without applying resources.
iacApplyChange
Atomically Apply the reviewed plan as the actual user, publishing main only on success. The stack's rules must be met (REVIEW_REQUIRED, CHANGES_REQUESTED) unless a stack admin bypasses them.
iacHostedState
Coordinator-only state capability; unavailable to ordinary clients.
iacUpdateEditing
Update authoring presence without changing source or deployment state.
iacLeaveEditing
End an authoring presence session.
iacMigrateStack
Atomically create an absent stack and import legacy state. Requires tenant administration; exact retries are idempotent.
iacCreateStack
Create a hosted Git stack.
iacConfigureStack
Configure stack ownership and archival under stack administration permissions.
iacGrantStack
Manage stack grants; grants never bypass resource permissions.
iacSetStackSecret
Write a new version of a stack secret; earlier versions are kept. Plans made before it need re-planning. Requires stack administration.
iacDeleteStackSecret
Mark a stack secret deleted by writing a deleted version; earlier versions are kept for audit. True when the secret was deleted. Requires stack administration.
iacPurgeStackSecret
Irreversibly destroy stored secret values, for example after a leak. Metadata stays; plans that used a purged version must be re-planned. Requires stack administration.
iacImportStackValues
Seed a stack's non-sensitive values once, when it has none (otherwise VALUES_EXIST); every later change is a reviewed values change. Requires stack administration.
iacProposeValuesChange
Propose new stack values as a values change: a Change Request on refs/cococo/values that plans main's source with the proposed values and is reviewed, gated and applied like any change. One open values change per stack (CHANGE_EXISTS). Secrets are refused with VALUE_SENSITIVITY_MISMATCH.
iacUpdateStackRules
Change a stack's rules. Every change is recorded. Requires stack administration; invalid values are refused with INVALID_RULES.
iacReviewChange
Give a verdict on the current revision; it replaces your earlier verdict on that revision. The Change Request's author and anyone who captured a revision cannot approve (SELF_APPROVAL). Requires stack write access.
iacDismissReview
Withdraw your own review, or, as a stack admin, dismiss someone else's with a reason. Recorded in the timeline.
upsertUser
Create or update a service account. Only BOT accounts are writable through the API — HUMAN users are provisioned by Control and are read-only here. Requires user:write permission.
createUser
Create a new service account. The created user is always a BOT — HUMAN users are provisioned by Control. Requires user:write permission.
updateUser
Update a service account. Only provided fields are changed. HUMAN accounts are provisioned by Control and cannot be updated. Requires user:write permission.
deleteUser
Delete a service account. HUMAN accounts are provisioned by Control and cannot be deleted here. Requires user:delete permission.
createIAMPolicyAttachment
Attach a policy for IaC ownership; an existing attachment must be imported.
deleteIAMPolicyAttachment
Detach the policy without deleting its user or policy.
createIAMPolicy
Create an IAM policy. Requires iam:createPolicy permission.
updateIAMPolicy
Update an IAM policy. Requires iam:updatePolicy permission.
deleteIAMPolicy
Delete an IAM policy. Requires iam:deletePolicy permission.
attachPolicy
Attach a policy to a user. Requires iam:attachPolicy permission.
detachPolicy
Detach a policy from a user. Requires iam:detachPolicy permission.
createAPIToken
Create a new API token for the calling user. Returns the token string only once. Requires apitoken:write permission.
createBotAPIToken
Create a new API token on behalf of a bot user. Fails if the target user is not a bot. Requires apitoken:write permission.
revokeAPIToken
Revoke an API token. Requires apitoken:revoke permission.
revokeBotAPIToken
Revoke an API token belonging to a bot user. Fails if the token's owner is not a bot. Requires apitoken:revoke permission.
createTeamMembership
Create a new membership without adopting an existing one. Requires team:write permission.
setTeamMemberRole
Set a team member's role. Team admins administer the stacks the team owns. Requires team:write permission.
deleteTeamMembership
Delete only the membership, leaving the user and team intact. Requires team:write permission.
upsertTeam
Create or update a team. Requires team:write permission.
createTeam
Create a new team. Requires team:write permission.
updateTeam
Update a team. Only provided fields are changed. Requires team:write permission.
deleteTeam
Delete a team. Requires team:delete permission.
addTeamMember
Add a user to a team. Requires team:write permission.
removeTeamMember
Remove a user from a team. Requires team:write permission.
upsertTaskDefinition
Create or update a task definition. Requires taskDefinition:write permission.
createTaskDefinition
Create a new task definition. Requires taskDefinition:write permission.
updateTaskDefinition
Update a task definition. Only provided fields are changed. Requires taskDefinition:write permission.
deleteTaskDefinition
Delete a task definition. Requires taskDefinition:delete permission.
updateFulfillmentSettings
Save only the fulfillment section, preserving every other settings section
updateConfig
Update tenant configuration. Creates a new version. For SECRET entries with null value, the existing secret is preserved. Requires tenantConfig:write permission.
deleteConfigKey
Delete a config key. Creates a new version. Requires tenantConfig:write permission.
rollbackConfig
Rollback to a previous config version. Creates a new version with the old data. Requires tenantConfig:write permission.
upsertArchiveJob
Create an archive job, or fully overwrite an existing one when `input.id` is given. Unlike updateArchiveJob, omitted optional fields fall back to the existing value and then to the default. Requires archiveJob:write permission.
createArchiveJob
Create a new archive job. Requires archiveJob:write permission.
updateArchiveJob
Update an archive job. Only provided fields are changed. Requires archiveJob:write permission.
deleteArchiveJob
Delete an archive job, cancelling its schedule. Reports notFound if no such job exists for the tenant. Requires archiveJob:delete permission.
runArchiveJob
Run an archive job immediately, regardless of its schedule or isEnabled flag. Enqueues the work and returns a PENDING ArchiveExecution to poll; the run itself happens asynchronously. Requires an authenticated user and archiveJob:execute permission.
updatePaperWeightSettings
Saves the paper weight section. Other sections are untouched.
updateImposingSettings
Saves the imposing section. Other sections are untouched.
updateJmfSettings
Turns the direct JMF endpoint on or off. The token is untouched.
setJmfToken
Sets or replaces the JMF access token with one you supply, e.g. the one your devices already send.
generateJmfToken
Sets or replaces the JMF access token with a new random one, returned once in the result.
removeJmfToken
Removes the JMF access token. While the endpoint is on, anything that can reach it can then post signals.
revealJmfToken
Shows the JMF access token so an operator can set up a device. Every reveal is recorded with who and when.
dataChangeEvents
Subscribe to real-time data change events. Requires read permission on each requested resource.
iacEditingPresence
Observe current collaborators and stack revision changes while editing a stack.
streamLogs
Stream logs across drains (webhook, execution, edge app) as they are written. Requires log:list permission.