API Reference

Exact endpoint map from current backend routes and auth middleware.

Quick Start

Base URL: https://api.registrai.cc

# Public read
curl "https://api.registrai.cc/stats"

# Developer-auth write
curl -X POST "https://api.registrai.cc/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: kya_..." \
  -d '{"url":"https://example.com/hook","events":["feedback.received"]}'

# Admin-auth call
curl "https://api.registrai.cc/admin/overview" \
  -H "X-Admin-Key: ..."

Note: Non-GET endpoints generally require `X-API-Key`, except registration build/confirm and admin routes.

Core Public

These are public reads plus registration helper writes.

GET/healthPublic

API health and basic counts.

GET/statsPublic

Global ecosystem stats.

GET/agentsPublic

List agents with filters/pagination.

GET/agents/:idPublic

Get full agent profile.

GET/agents/:id/reputationPublic

Current reputation snapshot.

GET/agents/:id/reputation/historyPublic

Historical reputation snapshots.

GET/agents/:id/attestationsPublic

SATI attestations for an agent.

POST/agents/register/buildPublic

Build unsigned ERC-8004 register tx.

POST/agents/register/confirmPublic

Record submitted registration tx hash.

Feedback / Presence / Link

POST/agents/:id/feedbackX-API-Key

Store feedback comment metadata.

GET/agents/:id/feedbackPublic

List feedback comments.

PATCH/agents/:id/feedback/:commentId/txX-API-Key

Attach on-chain tx hash to comment.

POST/agents/:id/feedback/buildX-API-Key

Build unsigned giveFeedback tx.

GET/agents/:id/feedback/chainsPublic

List chains where feedback can be sent.

POST/agents/:id/presenceX-API-Key

Add verified presence address.

GET/agents/:id/presencePublic

List presence claims.

DELETE/agents/:id/presenceX-API-Key

Remove presence claim.

POST/agents/linkX-API-Key

Link two agent wallets.

GET/agents/:id/linksPublic

Get link info for an agent.

DELETE/agents/:id/linksX-API-Key

Unlink linked wallets.

Developer Self-Service

Requires a valid developer key in `X-API-Key`.

GET/meX-API-Key

Get current developer profile.

GET/me/usageX-API-Key

30-day usage summary for this developer.

GET/me/quotaX-API-Key

Current quota, remaining, 429 stats, active plan.

GET/me/planX-API-Key

Current effective plan and quota.

GET/me/billingX-API-Key

Current subscription + today usage counters.

GET/me/keysX-API-Key

List developer API keys.

POST/me/keysX-API-Key

Create additional API key.

POST/me/keys/rotateX-API-Key

Rotate currently-used API key.

DELETE/me/keys/:keyIdX-API-Key

Revoke one API key.

GET/me/organizationsX-API-Key

List organizations you belong to.

GET/me/organizations/:organizationId/usageX-API-Key

Org-level 30-day usage (member only).

Webhooks (Developer)

Managed by developer key.

POST/webhooksX-API-Key

Create webhook subscription.

GET/webhooksX-API-Key

List your webhooks.

GET/webhooks/:idX-API-Key

Get one webhook.

PATCH/webhooks/:idX-API-Key

Update webhook URL/events/active.

DELETE/webhooks/:idX-API-Key

Delete webhook.

GET/webhooks/:id/deliveriesX-API-Key

List webhook delivery attempts.

Admin

Requires `X-Admin-Key`.

GET/admin/overviewX-Admin-Key

Operational overview metrics.

GET/admin/auditX-Admin-Key

Audit log stream.

GET/developersX-Admin-Key

List developers.

POST/developersX-Admin-Key

Create developer and issue initial key.

GET/developers/:idX-Admin-Key

Developer detail.

POST/developers/:id/keysX-Admin-Key

Issue key for developer.

GET/developers/:id/keysX-Admin-Key

List developer keys.

DELETE/developers/:id/keys/:keyX-Admin-Key

Revoke developer key.

GET/developers/:id/usageX-Admin-Key

Developer 30-day usage.

GET/developers/:id/webhooksX-Admin-Key

Developer webhook list.

GET/organizationsX-Admin-Key

List organizations.

POST/organizationsX-Admin-Key

Create organization.

GET/organizations/:id/membersX-Admin-Key

List organization members.

POST/organizations/:id/membersX-Admin-Key

Upsert organization member role.

DELETE/organizations/:id/members/:developerIdX-Admin-Key

Remove organization member.

GET/organizations/:id/usageX-Admin-Key

Organization 30-day usage.

GET/admin/plansX-Admin-Key

List plans.

POST/admin/plansX-Admin-Key

Create plan.

GET/admin/developers/:id/planX-Admin-Key

Get active developer plan assignment.

POST/admin/developers/:id/planX-Admin-Key

Assign plan to developer.

GET/admin/billing/overviewX-Admin-Key

Billing KPIs (MRR/ARR etc).

GET/admin/billing/subscriptionsX-Admin-Key

List subscriptions.

POST/admin/billing/subscriptions/upsertX-Admin-Key

Create/update subscription record.

POST/admin/billing/events/ingestX-Admin-Key

Ingest external billing events.

GET/admin/billing/usage-exportX-Admin-Key

Export usage metering (json/csv).