Reference

REST API

Base URL: https://api.credian.io. All endpoints are versioned under /v1.

Authentication

Three authentication methods depending on the caller.

Caller	Method	Header
Agent	API Key (avs_ prefix)	X-API-Key: avs_...
Platform	API Key (avp_ prefix)	X-API-Key: avp_...
Owner	JWT Bearer token	Authorization: Bearer eyJ...

API keys can also be sent as Authorization: Bearer avs_....

Auth

POST

/v1/auth/register

POST

/v1/auth/login

Authenticate an owner. Returns JWT.

Agents

POST

/v1/agents

Owner JWT

GET

/v1/agents

List agents owned by the authenticated owner.

Owner JWT

GET

/v1/agents/me

Get current agent profile from API key.

Agent API Key

GET

/v1/agents/:id

Get agent profile by ID.

Agent API Key

PATCH

/v1/agents/:id

Update agent metadata or display name.

Owner JWT

DELETE

/v1/agents/:id

Deactivate an agent.

Owner JWT

Scores

GET

/v1/agents/:id/score

Get current trust score with classification breakdown.

GET

/v1/scores/:id

Alias for GET /v1/agents/:id/score.

GET

/v1/agents/:id/score/history

Paginated score history snapshots.

POST

/v1/scores/batch

Look up scores for up to 100 agents at once.

GET

/v1/scores/classifications

Get score tier definitions (excellent, good, fair, poor, untrusted).

Events

POST

/v1/events

Submit a self-reported behavioral event.

Agent API Key

GET

/v1/events

List events for the authenticated agent.

Agent API Key

POST

/v1/agents/:id/events

Submit an event on behalf of an agent (platform-reported, full scoring weight).

Platform API Key

GET

/v1/agents/:id/events

Get event history for a specific agent.

Agent API Key

Credentials

POST

/v1/credentials

Issue a trust credential to an agent.

Owner JWT

GET

/v1/credentials

List credentials for an agent.

Owner JWT

GET

/v1/credentials/:id

Get credential details (public).

POST

/v1/credentials/:id/verify

Verify a credential by ID.

Owner JWT

POST

/v1/credentials/verify

Verify a credential (public).

DELETE

/v1/credentials/:id

Revoke a credential.

Owner JWT

Webhooks

POST

/v1/webhooks

Create a webhook subscription.

Owner JWT

GET

/v1/webhooks

List webhook subscriptions.

Owner JWT

DELETE

/v1/webhooks/:id

Delete a webhook subscription.

Owner JWT

Error format

JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid event type",
    "details": { ... }
  }
}

Code	Status	Meaning
VALIDATION_ERROR	400	Invalid request body or parameters
AUTHENTICATION_REQUIRED	401	Missing or invalid credentials
FORBIDDEN	403	Valid credentials but insufficient access
NOT_FOUND	404	Resource does not exist
RATE_LIMIT_EXCEEDED	429	Too many requests

Rate limits

Tier	Requests/min	Lookups/month	Max agents
Free	100	1,000	10
Growth	1,000	50,000	100
Platform	10,000	Unlimited	Unlimited

Event ingestion: 100 events/agent/hour, 1,000 events/platform/hour regardless of tier.

Pagination

All list endpoints use cursor-based pagination. Pass ?cursor=<value>&limit=50 from the nextCursor field in the response. Maximum limit is 100.

Idempotency

All write endpoints accept an Idempotency-Key header. Replayed requests with the same key return the original response without re-executing the operation.