API reference

Every v1 endpoint, its auth, and the M1 request and response shapes. Machine-readable copy at /openapi.json.

Plain Markdown for agents: /docs/api.md

Base URL: https://api.securemyagent.ai. Machine-readable spec: openapi.json.

Authenticated calls send Authorization: Bearer sma_…. Errors always look like this:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry in 30 seconds."
  }
}

Endpoints

Endpoint	Auth	Purpose
`POST /v1/agents/register`	none (rate limit + proof-of-work)	Self-registration. Returns the `sma_` key and `claimUrl`
`POST /v1/agents/challenge`, `/v1/agents/login`	signed challenge	Key-based login with `did:key` or `did:pkh`
`GET /v1/agents/me`, `PATCH /v1/agents/me`	`sma_` key	Profile, inventory, status
`POST /v1/claims/{token}`	human session	Owner claims an agent
`POST /v1/checkups`, `GET /v1/checkups/{id}`	`sma_` key	Upload a signed report. Get score and fixes
`POST /v1/heartbeat`	`sma_` key	Liveness, `whatsNew`, advisories, attestation renewal
`GET /v1/verdicts/{ecosystem}/{id}`	none	Registry lookup. `@version` optional. Ships in M2
`POST /v1/verdicts/batch`	`sma_` key	Up to 200 lookups for an inventory. M2
`POST /v1/reports`	`sma_` key	Report a suspicious skill or server
`GET /v1/verify/{did}`	none	Current attestation, status, revocation. M3
`POST /v1/guard/events`	`sma_` key	Guard event metadata. M4
`GET /v1/advisories`	none	Threat feed as JSON, RSS or `.md`
`POST /v1/billing/checkout`	`sma_` key	Stripe checkout, or x402 on paid endpoints. M4

Live in the M1 spec: register, challenge, me, claim start and confirm, checkups, heartbeat.

Register

curl -sS -X POST https://api.securemyagent.ai/v1/agents/challenge \
  -H 'content-type: application/json' \
  -d '{"did":"did:key:z6Mk…"}'
# {"challenge":"…","difficulty":20,"expiresAt":"2026-10-24T12:00:00Z"}

Find a nonce so sha256(challenge + ":" + nonce) has difficulty leading zero bits.
Sign the challenge string (UTF-8) with your Ed25519 key. Encode the signature as base64url.
Register:

curl -sS -X POST https://api.securemyagent.ai/v1/agents/register \
  -H 'content-type: application/json' \
  -d '{"name":"my-agent","runtime":"claude-code","did":"did:key:z6Mk…","challenge":"…","nonce":"…","signature":"…"}'
# {"agentId":"…","apiKey":"sma_…","claimUrl":"https://securemyagent.ai/claim?token=…","status":"provisional","quotas":{…}}

The apiKey appears once. SMA stores only a keyed hash.

Claim (human, browser)

POST /v1/claims/{token}/start    {"email":"you@example.com"}
POST /v1/claims/{token}/confirm  {"email":"you@example.com","code":"123456"}

Checkup

POST /v1/checkups takes a report with schema sma.checkup/v1. It holds fingerprints and redacted locations only. A secret value in the upload is rejected.

Heartbeat

curl -sS -X POST https://api.securemyagent.ai/v1/heartbeat \
  -H "Authorization: Bearer $SMA_API_KEY"

Act on whatsNew and advisories in the response.