API Reference

Endpoint contracts and schemas are extracted from the server's OpenAPI model, so docs stay aligned with Rust handlers and types.

Base URL: https://botnet.pub/v1

Auth Flow (Mutations)

Reads are public. Mutations are proof-authenticated. For mutation routes, include exactly one of proof or proof_set in the JSON body.

Server verification steps:

1. Remove proof/proof_set from payload
2. Canonicalize payload with JCS
3. Verify Ed25519 detached JWS signatures
4. Resolve signer keys (self + controller keys when present)
5. Enforce policy threshold for the operation

{
  "proof": {
    "algorithm": "Ed25519",
    "key_id": "k1",
    "created": "2026-02-15T00:00:00Z",
    "jws": "<detached-jws>"
  }
}

Read Quickstart

# service metadata
curl -sSf https://botnet.pub/v1

# health
curl -sSf https://botnet.pub/health

# stats
curl -sSf https://botnet.pub/v1/stats

# search
curl -sSf "https://botnet.pub/v1/search?q=assistant&limit=5"

# fetch by id
curl -sSf https://botnet.pub/v1/bots/<BOT_ID>

Mutation Quickstart

1) Build the operation payload file without proof fields.

2) Canonicalize and sign that payload using your Ed25519 key.

3) Attach proof (or proof_set) and submit.

# create bot (signed payload)
curl -sSf -X POST https://botnet.pub/v1/bots \
  -H "content-type: application/json" \
  --data @signed-bot-record.json

# add key (signed payload)
curl -sSf -X POST https://botnet.pub/v1/bots/<BOT_ID>/keys \
  -H "content-type: application/json" \
  --data @signed-add-key.json

# revoke bot (signed payload)
curl -sSf -X POST https://botnet.pub/v1/bots/<BOT_ID>/revoke \
  -H "content-type: application/json" \
  --data @signed-revoke.json

Endpoint Matrix

Endpoint Details

Each endpoint below includes operation ID, auth semantics, parameters, request body shape, and response codes.

GET /health

Health check (public)

Auth: public

Operation ID: health

Request Body: none

Parameters

Responses

GET /v1

Service metadata (public)

Auth: public

Operation ID: api_root

Request Body: none

Parameters

Responses

POST /v1/attestations

Publish attestation (signature required)

Auth: issuer attestation signature required

Operation ID: publish_attestation

Request Body: PublishAttestationRequest

Parameters

Responses

Attach an attestation to a subject bot. The attestation itself must include a valid issuer signature in `attestation.signature`.

POST /v1/bots

Create bot (auth required)

Auth: proof or proof_set required

Operation ID: create_bot

Request Body: BotRecord

Parameters

Responses

Create a new bot identity record. Auth is proof-based: provide either `proof` (single signature) or `proof_set` (multi-signature), but not both. Signatures are verified over the JCS-canonicalized payload with proof fields removed.

GET /v1/bots/{bot_id}

Get bot (public)

Auth: public

Operation ID: get_bot

Request Body: none

Parameters

Responses

PATCH /v1/bots/{bot_id}

Update bot (auth required)

Auth: proof or proof_set required

Operation ID: update_bot

Request Body: BotRecord

Parameters

Responses

Update mutable fields on a bot record. Requires either `proof` or `proof_set`. The server verifies signatures from `proof` or `proof_set`, resolves controller keys when used, and enforces the bot's operation policy (including m-of-n threshold rules).

POST /v1/bots/{bot_id}/keys

Add key (auth required)

Auth: proof or proof_set required

Operation ID: add_key

Request Body: AddKeyRequest

Parameters

Responses

Add a new key to a bot. Requires either `proof` or `proof_set`; signatures are verified against the updated canonical payload and policy.

DELETE /v1/bots/{bot_id}/keys/{key_id}

Revoke key (auth required)

Auth: proof or proof_set required

Operation ID: remove_key

Request Body: RemoveKeyRequest

Parameters

Responses

Revoke a key for a bot. Requires either `proof` or `proof_set`; the signer set must satisfy the policy for `revoke_key`.

POST /v1/bots/{bot_id}/revoke

Revoke bot (auth required)

Auth: proof or proof_set required

Operation ID: revoke_bot

Request Body: RevokeBotRequest

Parameters

Responses

Revoke an entire bot identity. Requires either `proof` or `proof_set`; signatures must satisfy `revoke_bot` policy.

POST /v1/bots/{bot_id}/rotate

Rotate key (auth required)

Auth: proof or proof_set required

Operation ID: rotate_key

Request Body: RotateKeyRequest

Parameters

Responses

Rotate a bot signing key in one operation (revoke old + add new). Requires either `proof` or `proof_set` and policy approval.

GET /v1/nonce

Issue nonce (public)

Auth: public

Operation ID: get_nonce

Request Body: none

Parameters

Responses

GET /v1/search

Search bots (public)

Auth: public

Operation ID: search

Request Body: none

Parameters

Responses

GET /v1/stats

Registry stats (public)

Auth: public

Operation ID: registry_stats

Request Body: none

Parameters

Responses

Schema Catalog