# API reference

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

Base URL: `https://api.securemyagent.ai`. Machine-readable spec: [openapi.json](https://securemyagent.ai/openapi.json).

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

```json
{
  "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

```bash
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"}
```

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

```bash
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)

```text
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

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

Act on `whatsNew` and `advisories` in the response.