# 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.
- Interactive password login requires GET /api/login/captcha first. Keep its cookie, display the returned image to a human,
  then POST /api/login with user, pass, captcha_id and captcha, plus the challenge csrf_token as X-CSRF-Token.
  The challenge expires in 120 seconds and is consumed by one attempt. Refresh it after every failure.
  Keep the successful session cookie and use the new csrf_token as X-CSRF-Token for subsequent writes.
  Password login and captcha fetching are IP rate limited (HTTP 429, Retry-After). Automation should use scoped API tokens.
- 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 and show the before/after difference, then PUT /api/domains/{provider}/{domain}/records/{recordId}
   with expected_version from that record's version and only the fields to change. DELETE also requires expected_version in its JSON body.
   POST requires expected_revision from the list response's revision plus the new record fields. All writes require dns:write.
   A fresh cloud read rejects stale versions with HTTP 409. HTTP 202 / verified:false means unconfirmed; do not retry writes automatically.
   Only verified:true confirms cloud readback, not worldwide DNS propagation. DNS change history is administrator-session-only at GET /api/dns/changes.
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. IP checks request http://IP/ and accept HTTP 2xx/3xx without following redirects; results and timestamps persist on the server.
- 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.