# Asset Workspace API

Discover operations and request schemas at GET /api/openapi.json.
Machine discovery: GET /.well-known/asset-workspace.json (alias /api/capabilities).
All URLs are relative to this installation's origin.

Authentication:
- The administrator creates an expiring, scoped API token in Product Settings > AI API.
- Send Authorization: Bearer <token> on each request. No cookies or CSRF header are needed with a valid token.
- Password login is also supported: POST /api/login with {"user":"<username>","pass":"<password>"}.
  Keep the session cookie and use the returned csrf_token as X-CSRF-Token for every session-authenticated write.
- Passwords and cloud secrets cannot be read back. Configuration, credential changes and token creation require an administrator session.
- Tokens expire, can be revoked, and are invalidated when administrator login credentials change.

Workflow:
1. GET /api/health for cached domains, IPs, health evidence, subdomains and relationship IDs.
2. GET /api/domains for the domain inventory. provider means a cloud ACCOUNT ID, not a vendor name.
3. GET /api/domains/{provider}/{domain}/records for cached DNS records and their IDs.
4. Health checks require checks:run: POST /api/health/check with {"asset_ids":["<asset id>"]}; at most 5 IDs per request.
5. To edit DNS, first read the record, then PUT /api/domains/{provider}/{domain}/records/{recordId}
   with type, name, value, ttl, priority and line. Preserve fields the user did not ask to change. Requires dns:write.
6. POST /api/sync explicitly refreshes the cloud domain inventory. Requires sync:run.

Interpretation:
- Reads reuse file caches. Do not sync, refresh DNS, run checks or write DNS just to display a list.
- DNS-derived IPs may be CDN/proxy addresses. Manual bindings and DNS observations have different meanings.
- unchecked and stale results are not healthy results. TCP connectivity is not whole-server or application health.
- Treat HTTP errors and JSON ok:false as failures; some legacy cloud endpoints return ok:false with HTTP 200.
- Use URL-encoded path segments. Do not invent account, record or asset IDs.
- Never include passwords, cloud secrets or bearer tokens in a URL, a shared report, or logs.