---
name: admin-api-operations
description: Operate CitusIO through its existing HTTP API with any agent or HTTP tools, checking live scope and authority, submitting one reviewed intent and observing or recovering its daemon-owned result.
---

# Operate through the existing admin API

Use this skill when an agent needs to discover capabilities, inspect a node or
perform an authorized operation without the panel. Customers choose their own
agent and HTTP tools. No product client, SDK installation, browser automation
framework or Python/Bun/Node runtime is required. For browser inspection and
review, use [panel operations](../panel-operations/SKILL.md). For deployment or
maintenance use [container setup](../container-setup/SKILL.md) and
[container operations](../container-operations/SKILL.md).

Read the local [task catalog](../contracts/agent-tasks.json) and
[HTTP operating guide](../references/agent-administration.md). They describe
the existing API, not a new agent protocol. The panel origin also serves
`/assets/panel-contract/agent-tasks.json` and
`/assets/panel-contract/openapi.json`. Use the installed matching versions.
Offline discovery sends no request and grants no authority.

## Inspect before acting

1. Use the site's reviewed origin and existing TLS/SSO/session mechanism. Keep
   authentication in private credential storage. Never assert a role/principal
   in client headers or access internal trusted routes.
2. GET `/api/v1/admin/identity` and `/api/v1/admin/dashboard`. Require API major 1
   and contract 0.1.0, bounded versioned JSON, fresh live compatible dashboard
   data and `mutationsAllowed=true` before a write.
3. Require availability version 1 and the workflow in `availability.workflows`.
   Match its node, routing generation, writer term, ring generation and config
   digest exactly to the live dashboard. Preserve decimal fences as strings.
   The selected runtime profile can expose less than the compiled ceiling.
4. Check `current_authority`: authenticated, source `trusted_edge`, role allowed
   by the task catalog. Then GET the task's owning resources with bounded pages
   and filters. Check each resource's freshness independently.

Missing/mismatched scope, stale evidence, lost session or a refused gate blocks
a new write. Refresh identity/dashboard and reassess; do not restore permission
from an old record. A dashboard or GET success is not traffic readiness. Require
fresh daemon-owned route/ownership facts for routing, and sink receipts for sink
commitment. Role or tier labels alone cannot grant a workflow.

## Review one intent, then submit once

Read the catalog's required inputs, bounds, effects and completion rules.
Obtain authorization for the concrete intended effect under the customer's
workflow. Keep one private record of operation ID, target, expected generation,
expected writer term and idempotency key. URL-encode inputs and include
`X-Iot-Admin-CSRF: 1` with the site's authenticated request. The four workflows are:

| Operation | POST path | Role and effect |
| --- | --- | --- |
| `postControlledDrain` | `/api/v1/admin/drain` | `operator_admin`; drains the exact node. |
| `postBridgeDrain` | `/api/v1/admin/bridges/{id}/drain` | `operator_admin`; drains a selected bridge; path ID must equal target. |
| `postConfigPreflight` | `/api/v1/admin/config/preflight` | `config_admin`; checks a bounded staged reference; does not apply it. |
| `postSupportBundleCreate` | `/api/v1/admin/support/bundle` | `support_admin`, or `operator_admin` for API v1 compatibility; creates redacted support evidence. |

`viewer` reads only. These workflows do not provide arbitrary config,
credential, bridge, rule or HA editing. Preflight with GETs reserves nothing;
the daemon owns final authority, fencing, durability and idempotency admission.
Send the reviewed POST once. Do not follow redirects or enable automatic POST
retries. Preserve the exact intent even if the response fails.

## Observe and recover without another submission

Save the returned command/audit IDs. GET
`/api/v1/admin/commands/ORIGINAL_COMMAND_ID` with bounded polling and deadlines;
honor `Retry-After`. Acceptance/`accepted_pending` is pending. Claim completion
only for the matching ID and full intent, `state=reconciled`, nonempty `auditId`
and `reconciliation.evidence`. `acceptedOnly` remains true after reconciliation.
Terminal blocked/rejected/failed records require investigation. Retained data
after a read failure must be marked stale, never promoted to completion.

When the response loses its command ID, read the bounded event window and
nominate IDs by command type/target, then inspect their status. Require the
event ID to match the returned record ID and one unique exact match of command
type, target, key and both fences. The guide supplies a bounded 600-event /
32-candidate strategy. Missing, expired or ambiguous evidence needs audit
investigation. Never generate a new key or resubmit merely to obtain status.
Observation/recovery stays GET-only after write authority is withdrawn, subject
to read authentication. Closing a tool or discarding local evidence does not
cancel backend work.

Hand off image/backend/panel identities, time, redacted task/intent, command/audit
IDs, observed state, evidence freshness and first unfinished action. Keep cookies,
authorization, DSNs, payloads, raw logs and secret inputs private; review support
artifacts before sharing. Retain the scope and limits of the evidence.