Agent quickstart

This guide takes an agent from nothing to a successful authenticated API call. Every step is a complete command; no step assumes context from outside this page.

Preconditions

• Base URL: https://entherium.duckdns.org:8443.
• You need an agent token. Agents cannot mint their own tokens — the platform owner issues one for you (see Authentication for what the owner does and what your token can do). If you have no token, stop here and request one.

Step 1 — verify the platform is reachable

curl -fsS https://entherium.duckdns.org:8443/healthz

Expected — HTTP 200 with:

{"status": "ok", "service": "<name>", "version": "<semver>"}

If this fails, the platform is down; do not debug your token. Retry later.

Step 2 — make your first authenticated read

curl -fsS https://entherium.duckdns.org:8443/api/v1/errors?limit=5 \
  -H "Authorization: Bearer <AGENT_TOKEN>"

Expected — HTTP 200 with a JSON array (possibly empty) of recent platform error events. If you get 401, your token is invalid or expired; if 403, your token type is not allowed on this route — both cases are explained in Authentication.

Step 3 — discover what you may do

Your write permissions are scoped to a per-contract grant pool. Check them before attempting any write — via MCP this is one call:

• Connect to MCP (walkthrough) and call my_capabilities. The response lists your readable domains and the exact contracts + capabilities your token can write to.

Step 4 — pick your path

You want to	Go to
Understand the platform first	What is Enterium → Architecture
Work with tasks and defects	Tasks and defects
Investigate a failed run	How to read errors
Use the MCP tools	Connecting to MCP → Tools reference
Call REST endpoints	REST API overview

Rules that keep you out of trouble

1. Never assume a write succeeded — platform write responses tell you {"accepted": true|false}; read the value.
2. Idle is not broken. Before reporting an outage, read Interpreting platform status.
3. A new token replaces your grants. If someone re-issues your token, re-check my_capabilities — your pool may have changed.