Authorization: Bearer mesh_<43 base64url characters>

export MESH=https://mesh.example.com
export TOKEN=mesh_…

# 1. The agent.
curl -sS -X POST $MESH/api/agents \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"slug":"scout","display_name":"Scout"}'

# 2. Its persona (system-prompt text), then make that revision active.
curl -sS -X POST $MESH/api/agents/scout/persona \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"body":"You are Scout, the on-call helper for the platform team. …"}'

# 3. A model provider and ITS OWN key — the agent's, not yours.
curl -sS -X POST $MESH/api/agents/scout/model-provider \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"provider":"openrouter","api_key":"sk-or-…"}'

# 4. Memory, in bulk (below).
# 5. A connector: Slack manifest + credentials, or Telegram. Save the Slack
#    connector BEFORE pointing the Slack app's Event Subscriptions at Mesh:
#    the ingress looks the connector up by (api_app_id, team_id) before it
#    verifies a signature, so Slack's URL challenge gets a 401 until this row
#    exists. The body needs app_id, bot_token and signing_secret.
curl -sS $MESH/api/agents/scout/connectors/slack/manifest -H "Authorization: Bearer $TOKEN"
curl -sS -X POST $MESH/api/agents/scout/connectors/slack \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"app_id":"A0…","bot_token":"xoxb-…","signing_secret":"…"}'

# 5b. Or a phone number people can text (docs/connectors/phone.md). With the
#     instance phone account set (PUT /api/settings/phone, owner), buy one:
curl -sS "$MESH/api/agents/scout/connectors/phone/shared/available?country=US&area_code=415" \
  -H "Authorization: Bearer $TOKEN"
curl -sS -X POST $MESH/api/agents/scout/connectors/phone/shared \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"buy":"+14155550100","country":"US","allowed_senders":["+15557654321"]}'
#     …or connect a number on the agent's OWN account: list, then connect.
curl -sS -X POST $MESH/api/agents/scout/connectors/phone/numbers \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"provider":"twilio","account_id":"AC…","api_secret":"…"}'
curl -sS -X POST $MESH/api/agents/scout/connectors/phone \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"provider":"twilio","account_id":"AC…","api_secret":"…","number_id":"PN…","allowed_senders":["+15557654321"]}'

# 6. Tools: capture the agent's own credential for a package, then enable.
curl -sS -X POST $MESH/api/agents/scout/tool-secrets/github_pat \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"value":"ghp_…"}'
curl -sS -X POST $MESH/api/agents/scout/tools/checkout_github_repo/enable -H "Authorization: Bearer $TOKEN"
curl -sS -X PUT $MESH/api/agents/scout/tool-config/mesh.github \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"values":{"default_repository":"TextureHQ/mesh"}}'

{
  "audience": { "kind": "public" },
  "skip_duplicates": true,
  "dry_run": false,
  "entries": [
    {
      "kind": "fact",
      "body": "The deploy window is Friday afternoon.",
      "source": {
        "system": "openclaw",
        "ref": "memory/2026-08-01.md#3",
        "created_at": "2026-08-01T15:04:05Z"
      }
    },
    { "kind": "preference", "body": "Prefers terse replies." }
  ]
}

{
  "batch_id": "6f1c…",
  "audience": { "kind": "public" },
  "imported": 1,
  "skipped": 1,
  "entries": [
    { "index": 0, "status": "imported", "id": "9a3e…" },
    { "index": 1, "status": "skipped_duplicate" }
  ]
}

{
  "format": "mesh.agent-export/v1",
  "exported_at": "2026-09-10T18:00:00Z",
  "agent": { "slug", "display_name", "disabled", "model_provider", "model_primary", "model_fast", "model_heartbeat", "budget_max_iterations" },
  "persona": { "revision", "body", "created_at" },
  "memory": [ { "id", "kind", "body", "visibility", "source_type", "current_revision", "created_at", "updated_at", "import_source": { "system", "ref", "original_created_at", "batch_id", "imported_at" } } ],
  "tools": { "enabled": ["checkout_github_repo"], "config": { "mesh.github": { "default_repository": "TextureHQ/mesh" } } },
  "connectors": [ { "type", "external_app_id", "external_workspace_id", "status" } ]
}

# Every session of yours; `current` is the one this cookie holds. The two
# clocks come back as seconds so a client need not hard-code them.
curl -sS $MESH/api/me/sessions -H "Authorization: Bearer $TOKEN"
# → {"sessions":[{"id":"…","created_at":"…","last_seen_at":"…","expires_at":"…","current":false}],
#    "idle_timeout_seconds":86400,"max_age_seconds":604800}

curl -sS -X DELETE $MESH/api/me/sessions/{id} -H "Authorization: Bearer $TOKEN"   # 204; your own only, else 404
curl -sS -X POST $MESH/api/me/sessions/revoke-others -H "Authorization: Bearer $TOKEN"  # → {"revoked":n}; the current cookie survives; a token caller has none and ends all

# Owner: sign another operator out everywhere. They keep their password.
curl -sS -X POST $MESH/api/settings/operators/{id}/sessions/revoke -H "Authorization: Bearer $TOKEN"

# Owner. Idempotent: a second stop keeps the first stop's time, name and reason.
curl -sS -X POST $MESH/api/settings/stop -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"reason":"scout is posting garbage in #support"}'
# → {"stopped":true,"stopped_at":"…","stopped_by_email":"victor@example.com","reason":"…"}
curl -sS -X DELETE $MESH/api/settings/stop -H "Authorization: Bearer $TOKEN"   # → {"stopped":false}
# The state is on GET /api/settings/security as install_stop, and on GET /api/me
# as install_stopped_at while stopped, so every page can say so.

curl -sS $MESH/api/settings/install -H "Authorization: Bearer $TOKEN"
# → {"build":{"commit":"…","commit_time":"…","modified":false,"go_version":"go1.25","module":"github.com/TextureHQ/mesh"},
#    "environment":"production","public_url":"https://mesh.example.com","auth_mode":"local",
#    "hostname":"mesh-7f9c","started_at":"…",
#    "database":{"applied":51,"available":51,"latest":"0051","known":true,"state":"current","missing":[],"unexpected":[]},
#    "secrets":{"master_key_present":true,"fingerprint":"…","verifiable":true},
#    "trusted_proxies":["10.0.0.0/8"]}
# build.commit is empty for a binary built without a VCS stamp (go run,
# -buildvcs=false, a container stage without .git); a dirty checkout is still
# stamped, with build.modified true. database.state compares the ledger with
# the embedded set as SETS: current (identical), behind (the binary embeds
# migrations the ledger lacks — listed in `missing`; auto-migrate off or a
# failed boot migration), ahead (the ledger holds versions this binary does
# not embed — listed in `unexpected`; a rollback the forward-only runner cannot
# follow), diverged (both), or unknown (the ledger could not be read; known
# is false).

# `mesh verify-secrets` from the API: open every stored credential with the
# running key and report per kind. Changes nothing. 409 master_key_missing
# when the process holds no key; 404 not_available where it is not wired.
curl -sS -X POST $MESH/api/settings/install/verify-secrets -H "Authorization: Bearer $TOKEN"
# → {"total":12,"ok":12,"failed":0,"key":"…","descriptor":"…","descriptor_matches":true,
#    "entries":[{"owner_type":"agent_connector","kind":"slack_bot_token","ok":3,"failed":0,"legacy":0}]}

curl -sS $MESH/api/settings/security -H "Authorization: Bearer $TOKEN"
# → {"auth_mode":"local",
#    "sessions":{"max_age_seconds":604800,"idle_timeout_seconds":86400,"cookie_secure":true,"active_count":3},
#    "sign_in_throttle":{"window_seconds":900,"failures_per_account":10,"failures_per_source":30,"trusted_proxies":[]},
#    "passwords":{"min_length":8,"max_length":72},
#    "operators":{"owners":2,"agent_operators":1,"disabled":0,"open_invites":1},
#    "active_api_tokens":4}

# Owner: end every session on the install except the caller's own cookie
# session. A token caller keeps none and ends all. API tokens are untouched —
# a token is a program and is revoked one by one, on purpose.
curl -sS -X POST $MESH/api/settings/security/sign-everyone-out -H "Authorization: Bearer $TOKEN"
# → {"revoked":n}

# Owner. Newest first; before= pages older with the cursor a previous page
# returned (opaque; pass it back verbatim); actor= narrows to one operator
# id; limit= 1..200, default 50.
curl -sS "$MESH/api/settings/activity?limit=50" -H "Authorization: Bearer $TOKEN"
# → {"events":[{"id":812,"at":"…",
#      "action":"POST /api/agents/{slug}/disable",   # the route pattern, or auth.*
#      "outcome":"ok","status":200,                  # ok <400, refused 4xx, failed 5xx
#      "actor":{"id":"…","email":"victor@example.com","via":"session"},
#      "source_ip":"203.0.113.7",                    # what the login throttle keys on (MESH_TRUSTED_PROXIES applies)
#      "target":{"slug":"scout"},                    # the route's path parameters; invite tokens are dropped
#      "details":{}}],                               # what the handler added: invited email and role, token name and scope, agent slug, refusal reason
#    "next_cursor":"ODEx"}                          # null on the last page
curl -sS "$MESH/api/settings/activity?before=ODEx&actor=<user id>" -H "Authorization: Bearer $TOKEN"

# The roster: status is active | invited | disabled; `you` marks the caller.
curl -sS $MESH/api/settings/operators -H "Authorization: Bearer $TOKEN"

# Invite by email, with a role. For an agent_operator, the agents to grant.
# The response carries the link ONCE; Mesh stores only a hash.
curl -sS -X POST $MESH/api/settings/operators/invites \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"email":"peer@example.com","role":"agent_operator","agents":["scout"]}'
# → 201 {"operator":{…,"role":"agent_operator","agents":["scout"],"status":"invited"},"invite_url":"https://…/invite/<token>","expires_at":"…"}

# Change what someone is. Absent fields are unchanged; `agents` replaces the
# whole set; promoting to owner clears grants.
curl -sS -X PATCH $MESH/api/settings/operators/{id} \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"role":"agent_operator","agents":["scout","sentry"]}'

# A new link for an existing operator: replaces any open link, and for an
# active operator this is the password reset.
curl -sS -X POST $MESH/api/settings/operators/{id}/invites -H "Authorization: Bearer $TOKEN"

# Disable: ends every session, revokes every API token they created, retires
# any open link, keeps the row (so "who did this" stays answerable). Enable
# clears the flag; the person signs in again with the password they had.
curl -sS -X POST $MESH/api/settings/operators/{id}/disable -H "Authorization: Bearer $TOKEN"
curl -sS -X POST $MESH/api/settings/operators/{id}/enable  -H "Authorization: Bearer $TOKEN"

{
  "enabled": false,
  "mode": "automatic",
  "learning_seconds": 14400,
  "quiet_seconds": 3600,
  "lifecycle_seconds": 86400,
  "grace_seconds": 604800,
  "daily_tokens": 262144,
  "daily_changes": 50
}

{"version":1,"action":"cancel","reason":"No longer needed"}

{
  "kind":"tool_result",
  "tool":"example_query_tool",
  "arguments":{"id":"issue-123"},
  "json_source_pointer":"/text/0",
  "pointer":"/state/name",
  "equals":"Done"
}

{
  "provider": "openrouter",
  "primary": "openrouter/auto",
  "fast": "",
  "heartbeat": "",
  "api_key": "YOUR_PROVIDER_KEY"
}

POST /api/agents/{slug}/model-provider/inherit
Content-Type: application/json

{"provider":null}

{"config":{"mode":"allowlist","allowlist":["api.example.com"],"uncontrolled":"refuse"}}