aura-labs.ai

AURA API Reference

Version: 2.0 Date: April 14, 2026 Protocol: v2.2 Status: Active

Complete REST API documentation for integrating with AURA. The API is built on Fastify and uses Ed25519 cryptographic authentication. Endpoints are organized by domain, matching the Protocol Specification modules.

Overview

AURA is a REST API that facilitates agent-mediated commerce between Scouts (buyers) and Beacons (sellers) through a neutral broker (AURA Core). The API provides endpoints for:

Implementation status: Endpoints marked (Live) are deployed and operational. Endpoints marked (Phase 7 — Specified) are defined in Protocol Specification v2.2 but not yet deployed.

Base URL

https://aura-labsai-production.up.railway.app

All API requests use HTTPS. Request/response content type is application/json.

API Versioning

URL-path versioning. Current version: v1 (stable).

GET /v1/sessions
POST /v1/agents/register

Version Discovery (Live)

GET /

Returns available API versions with HATEOAS links.

Authentication

Ed25519 Signature Authentication

Every protected request includes three headers:

Header Description
X-Agent-ID The registered agent’s ID (sct_... or bcn_...)
X-Signature Ed25519 signature over method + path + timestamp + body
X-Timestamp ISO 8601 timestamp (must be within 5-minute window)

The signature is verified against the agent’s registered public key. No shared secrets. No bearer tokens.

# Example authenticated request
curl -X GET \
  -H "X-Agent-ID: sct_01HXYZ..." \
  -H "X-Signature: base64-ed25519-signature" \
  -H "X-Timestamp: 2026-04-14T10:00:00Z" \
  https://aura-labsai-production.up.railway.app/v1/sessions/ses_01HABC...

See Protocol Foundation Section 3 for the complete authentication specification.

Unauthenticated Endpoints

GET /, GET /health, GET /health/ready — no authentication required.

Rate Limiting

Tier Limit Scope
Default 60 requests/minute Per agent ID
Session creation 100 sessions/hour Per agent ID
Offer submission 1000 offers/minute Per agent ID

Rate limit headers are included on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Endpoints

Health & Status (Live)

Method Path Description
GET /health System health status
GET /health/ready Readiness probe

Version Discovery (Live)

Method Path Description
GET / API version discovery (unversioned)
GET /v1 HATEOAS navigation root for v1

Principal Management

POST /v1/principals (Live)

Register a principal (legal entity or individual). Optionally present identity credentials for trust level computation.

Request:

{
  "principal_type": "organization",
  "display_name": "Acme Widgets",
  "public_key": "base64-ed25519-public-key",
  "credentials": [
    {
      "format": "vlei",
      "credential": "eyJhbGciOiJFZERTQSIs...",
      "disclosure": null,
      "binding_proof": null
    }
  ],
  "notification_endpoint": "https://acme.example.com/aura/notifications"
}
Field Required Description
principal_type Yes organization or individual
display_name No Display label (self-declared, not verified)
public_key Yes Ed25519 public key for the principal entity
credentials No Array of credential presentations. Defaults to empty (L0).
notification_endpoint No URI for protocol notifications

Response: 201 Created

{
  "principal_id": "prn_01HXYZ...",
  "principal_type": "organization",
  "display_name": "Acme Widgets",
  "trust_level": "entity_verified",
  "trust_profile": {
    "level": "entity_verified",
    "credentials_accepted": [ ... ],
    "computed_at": "2026-04-14T10:00:00Z"
  },
  "registered_at": "2026-04-14T10:00:00Z"
}

GET /v1/principals/:principalId (Live)

Returns principal record including trust level and trust profile.

PUT /v1/principals/:principalId (Live)

Update mutable fields (display_name, notification_endpoint). Trust level changes only through credential management.

POST /v1/principals/:principalId/credentials (Phase 7 — Specified)

Present new identity credential(s) to upgrade trust level.

GET /v1/principals/:principalId/credentials (Phase 7 — Specified)

List accepted credentials for this principal.

GET /v1/principals/:principalId/trust-profile (Phase 7 — Specified)

Returns current trust level with full credential provenance.

GET /v1/principals/:principalId/risk-profile (Phase 7 — Specified)

Returns principal’s clearinghouse risk profile (composite score, dispute rate, enforcement status).

POST /v1/principals/:principalId/business-rules (Phase 7 — Specified)

Declare business rules (binary pass/fail policies enforced at commit time).

GET /v1/principals/:principalId/business-rules (Phase 7 — Specified)

List declared business rules.

Agent Registration (Live)

POST /v1/agents/register

Register an agent with Ed25519 public key, bound to a principal.

Request:

{
  "publicKey": "base64-encoded-ed25519-public-key",
  "signature": "base64-encoded-signature",
  "metadata": {
    "name": "MyShoppingAssistant",
    "type": "scout"
  },
  "principal_id": "prn_01HBUYER...",
  "capacity": "agent_for_principal"
}
Field Required Description
publicKey Yes Ed25519 public key (32 bytes, base64)
signature Yes Proof-of-possession signature
metadata.type Yes scout or beacon
principal_id Yes Reference to the registered principal
capacity Yes agent_for_principal, principal_direct, or platform_delegated

Response: 201 Created

{
  "agentId": "sct_01HXYZ...",
  "keyId": "key_01H...",
  "status": "active",
  "principal_id": "prn_01HBUYER...",
  "capacity": "agent_for_principal"
}

GET /v1/agents/:agentId (Live)

Returns agent details including principal binding and enforcement status.

GET /v1/agents/:agentId/enforcement-status (Phase 7 — Specified)

Returns enforcement status (standard, elevated, restricted, blocked, suspended).

Beacon Registration (Live)

POST /v1/beacons/register

Register a Beacon (seller) with capabilities and webhook endpoint.

Request:

{
  "name": "AcmeStoreBeacon",
  "categories": ["electronics", "home_appliances"],
  "capabilities": ["offers", "inventory_check", "dynamic_pricing"],
  "principal_id": "prn_01HSELLER...",
  "capacity": "agent_for_principal",
  "webhookUrl": "https://acme.example.com/aura/webhook"
}

Response: 201 Created

{
  "beaconId": "bcn_01HXYZ...",
  "principal_id": "prn_01HSELLER...",
  "principal_trust_level": "domain_verified",
  "capacity": "agent_for_principal",
  "_links": {
    "self": { "href": "/v1/beacons/bcn_01HXYZ..." },
    "sessions": { "href": "/v1/beacons/sessions" }
  }
}

GET /v1/beacons/:beaconId (Live)

Get Beacon details by ID.

GET /v1/beacons/sessions (Live)

Get available sessions for Beacons to poll. Only returns non-expired sessions. Scout constraints are projected per the Disclosure Projection model (Section 6.6) — Beacons see structured requirements, not full intent.

Sessions — Commerce Flow (Live)

POST /v1/sessions

Create a new commerce session with NLP-parsed intent.

Request:

{
  "intent": "Looking for wireless headphones under $100",
  "constraints": {
    "maxPrice": 100,
    "category": "electronics"
  },
  "completeness": {
    "confidence": 0.65,
    "categories": { "what": { "present": true }, "how_much_cost": { "present": true } },
    "attestedBy": "scout-sdk"
  },
  "profile_id": "prf_retail"
}
Field Required Description
intent Yes Natural language intent
constraints No Structured constraints (maxPrice, category, etc.)
completeness No Optional completeness attestation from Scout SDK
profile_id No Market Profile to use. Defaults to deployment default.

Agent identity from Ed25519 signature headers, not request body.

Response: 201 Created

{
  "sessionId": "ses_01HABC...",
  "state": "collecting_offers",
  "matchedBeacons": ["bcn_01H..."],
  "createdAt": "2026-04-14T10:00:00Z",
  "_links": {
    "self": { "href": "/v1/sessions/ses_01HABC..." },
    "offers": { "href": "/v1/sessions/ses_01HABC.../offers" },
    "commit": { "href": "/v1/sessions/ses_01HABC.../commit", "method": "POST" },
    "cancel": { "href": "/v1/sessions/ses_01HABC.../cancel", "method": "POST" }
  }
}

GET /v1/sessions/:sessionId (Live)

Get session state, offers, and transaction details.

POST /v1/sessions/:sessionId/offers (Live)

Submit a signed offer from a Beacon. Requires Ed25519 signature over canonical offer payload.

Request:

{
  "product": { "name": "Premium Headphones", "sku": "HP-001" },
  "unitPrice": 89.99,
  "quantity": 1,
  "currency": "USD",
  "signature": "<Ed25519 signature over canonical offer payload>"
}

GET /v1/sessions/:sessionId/offers (Live)

Get all offers for a session, ranked by CWR.

POST /v1/sessions/:sessionId/commit (Live)

Commit to an offer, creating a transaction.

Request:

{
  "offerId": "ofr_01HABC...",
  "idempotencyKey": "uuid-v4",
  "authority": {
    "consent_tier": "explicit",
    "delegation_scope_id": "dsc_01HXYZ...",
    "attestation_signature": "base64-ed25519-signature"
  },
  "buyer_identity": { "..." : "..." },
  "shipping_address": { "..." : "..." }
}

POST /v1/sessions/:sessionId/cancel (Live)

Cancel a session. Recorded in reputation.

GET /v1/sessions/:sessionId/attestation (Live)

Get the interpretation attestation — signed binding of original intent to structured interpretation.

GET /v1/sessions/:sessionId/intent-chain (Live)

Get the intent-to-commitment chain of custody (7-link cryptographic chain).

Transactions — Post-Commitment (Live)

GET /v1/transactions/:transactionId

Get transaction state, payment status, fulfillment status.

PUT /v1/transactions/:transactionId/fulfillment

Update fulfillment status (shipped, delivered).

PUT /v1/transactions/:transactionId/payment

Update payment status (charged, failed, refunded).

Disputes (Phase 7 — Specified)

Method Path Description
POST /v1/disputes File a dispute
GET /v1/disputes/:disputeId Get dispute details
POST /v1/disputes/:disputeId/evidence Submit evidence
POST /v1/disputes/:disputeId/resolve Submit resolution
POST /v1/disputes/:disputeId/appeal Appeal a decision

See Financial Protocol Section 11 for the complete dispute lifecycle.

Clearinghouse (Phase 7 — Specified)

Method Path Description
GET /v1/clearing/:transactionId/status Clearing lifecycle status
POST /v1/clearing/:transactionId/authorize Authorize settlement
GET /v1/settlement/:transactionId/proof Get proof of settlement

See Financial Protocol Section 10.7 for clearinghouse settlement flow.

Market Profiles (Phase 7 — Specified)

Method Path Description
GET /v1/profiles List available profiles
GET /v1/profiles/:profileId Get profile details
GET /v1/profiles/name/:name Get profile by name
GET /v1/profiles/active List active profiles
GET /v1/profiles/:profileId/dimensions/:dimension Get specific dimension config

See Market Profiles Architecture for the parameterization model.

Trust Framework (Phase 7 — Specified)

Method Path Description
GET /v1/trust-framework Active Trust Framework with all rules
GET /v1/trust-framework/rules/:ruleId Specific trust rule details

See Protocol Foundation Section 3.1.4 for the Trust Framework specification.

Settlement Rails (Phase 7 — Specified)

Method Path Description
GET /v1/settlement/adapters List available rail adapters
GET /v1/settlement/adapters/:adapterId/capabilities Adapter capability declaration
GET /v1/settlement/reconciliation Reconciliation status

See Settlement Rails Architecture for the rail interface specification.

Delegation Scopes (Live)

PUT /v1/agents/:agentId/delegation-scope

Set delegation scope defining agent authority boundaries.

GET /v1/agents/:agentId/delegation-scope

Get current delegation scope(s).

Webhook Events

When a Beacon registers with a webhookUrl, AURA dispatches events for state changes:

Event Trigger
transaction.state_changed Transaction advances (committed, fulfilled, completed)
session.offer_received New offer submitted to a session
session.expired Session TTL elapsed

Phase 7 webhooks (Specified):

Event Trigger
clearing.authorized Transaction cleared for settlement
clearing.settled Proof of settlement verified
dispute.filed Dispute opened against a transaction
dispute.resolved Dispute resolution reached
enforcement.status_changed Enforcement tier changed
trust_level.changed Principal trust level upgraded or downgraded
business_rule.violated Commit rejected by business rule gate

Error Codes

Code Name Description
400 Bad Request Malformed request body or invalid parameters
400 session_expired Session TTL has elapsed
400 missing_idempotency_key Commit request missing idempotency key
401 unknown_agent Agent ID not found in registry
401 invalid_signature Ed25519 signature verification failed
403 agent_revoked Agent has been revoked
403 agent_suspended Agent has been suspended
403 BUSINESS_RULE_VIOLATION (Phase 7) Scout violates Beacon business rule
403 CONSENT_ELEVATION_REQUIRED (Phase 7) Transaction requires higher consent tier
404 Not Found Resource not found
409 Conflict Invalid state transition
422 UNTRUSTED_ISSUER Credential issuer not in Trust Framework
422 SETTLEMENT_METHOD_UNSUPPORTED (Phase 7) Payment method not supported
429 Too Many Requests Rate limit exceeded
451 ENFORCEMENT_ACTION (Phase 7) Agent blocked by enforcement

NLP Pipeline

Three-layer architecture (see ADR-002):

Scout SDK (IntentSession)     → Completeness checking before submission
  |
Core API (intent-svc + local) → Authoritative parsing with fallback
  |
Beacon SDK (interpretIntent)  → Domain-specific catalog matching

Shared module: @aura-labs-ai/nlp — 8-category completeness checking, clarification generation, LLM provider abstraction.

See Also

Document History

Version Date Changes
2.0 2026-04-14 Full update for Protocol v2.2. Added principal management endpoints with credential model (DEC-049). Added Phase 7 endpoint tables (clearinghouse, settlement, disputes, market profiles, trust framework). Added profile_id to session creation. Updated Beacon registration with principal_id and capacity. Added Phase 7 webhook events and error codes. Added implementation status markers (Live / Phase 7 — Specified). Added version header and document history.
1.0 2026-03-11 Initial API reference — agent registration, sessions, offers, transactions, webhooks, NLP pipeline.