API Reference

All services are mounted under /api/{service-name}/. The node runs on port 4000 by default.

Base URL: http://localhost:4000/api/{service-name}

---

Table of Contents

1. Auth
2. Entity Storage
3. Blob Storage
4. Document Management
5. Verifiable Storage
6. Synchronised Storage
7. Immutable Proof
8. Logging
9. Identity Auth
10. Attestation
11. Trust
12. Rights Management
13. DPP (Digital Product Passport)
14. IoT Ingest
15. Feedback
16. Regulator
17. Lineage
18. Circular
19. Geo
20. Event Bus
21. Event Stream (WebSocket)
22. Telemetry
23. Background Task
24. Workflow
25. Webhook
26. Sentinel
27. Gateway
28. Wallet
29. Wire Service
30. Identity (Forge)
31. Supply Chain (Trace)
32. NFT (Stamp)
33. Dataspace
34. Data Space Connector
35. Data Processing
36. Federated Catalogue
37. Auditable Item Graph
38. Auditable Item Stream

---

Auth

Authentication and JWT token management.

Method	Path	Description
POST	/api/auth/login	Authenticate with username/password, returns JWT
POST	/api/auth/validate	Validate a JWT token

POST /api/auth/login

// Request
{"username": "alice", "password": "secure_password"}

// Response 200
{"token": "eyJhbGci...", "expires_in": 3600}

---

Entity Storage

JSON entity CRUD with collection-based organization. Supports PostgreSQL or in-memory backend.

Method	Path	Description
POST	/api/entity-storage/{collection}	Create entity in collection
GET	/api/entity-storage/{collection}/{id}	Get entity by ID
PUT	/api/entity-storage/{collection}/{id}	Update entity
DELETE	/api/entity-storage/{collection}/{id}	Delete entity
POST	/api/entity-storage/{collection}/find	Query entities with filter
POST	/api/entity-storage/{collection}/count	Count matching entities

POST /api/entity-storage/{collection}

// Request — any JSON object
{"name": "Widget A", "price": 29.99, "category": "electronics"}

// Response 201
{"id": "uuid-here", "name": "Widget A", "price": 29.99, "category": "electronics"}

POST /api/entity-storage/{collection}/find

// Request
{"filter": {"category": "electronics"}, "limit": 10, "offset": 0}

// Response 200
[{"id": "...", "name": "Widget A", ...}]

---

Blob Storage

Binary object storage with metadata.

Method	Path	Description
POST	/api/blob-storage/blobs/{*key}	Store a blob
GET	/api/blob-storage/blobs/{*key}	Retrieve a blob
DELETE	/api/blob-storage/blobs/{*key}	Delete a blob
GET	/api/blob-storage/metadata/{*key}	Get blob metadata
GET	/api/blob-storage/blobs	List all blobs

---

Immutable Proof

SHA-256 proof generation and blockchain anchoring.

Method	Path	Description
POST	/api/immutable-proof/proofs	Create a SHA-256 proof
GET	/api/immutable-proof/proofs/{id}	Get proof by ID
POST	/api/immutable-proof/proofs/{id}/verify	Verify a proof
POST	/api/immutable-proof/proofs/{id}/anchor	Anchor proof on blockchain

POST /api/immutable-proof/proofs

// Request
{"data": "base64-encoded-data"}

// Response 201
{"id": "proof-uuid", "hash": "sha256-hex", "created_at": "2026-03-20T10:00:00Z"}

---

Identity Auth

DID-based challenge/response authentication.

Method	Path	Description
POST	/api/identity-auth/challenge	Request an auth challenge for a DID
POST	/api/identity-auth/verify	Submit signed challenge for verification

POST /api/identity-auth/challenge

// Request
{"did": "did:kaspa:testnet-12:a1b2c3..."}

// Response 200
{"challenge": "base64-nonce", "expires_at": "2026-03-20T10:05:00Z"}

POST /api/identity-auth/verify

// Request
{"did": "did:kaspa:testnet-12:a1b2c3...", "challenge": "base64-nonce", "signature": "hex-schnorr-sig"}

// Response 200
{"valid": true, "token": "eyJhbGci..."}

---

Event Bus

Pub/sub event distribution.

Method	Path	Description
POST	/api/event-bus/publish	Publish an event to a topic

Event Stream (WebSocket)

Method	Path	Description
GET	/api/event-stream/ws/events	WebSocket connection for real-time events

---

Background Task

Task scheduling and execution.

Method	Path	Description
POST	/api/background-task/tasks	Submit a new task
GET	/api/background-task/tasks	List all tasks
GET	/api/background-task/tasks/stats	Task statistics
GET	/api/background-task/tasks/{id}	Get task by ID
DELETE	/api/background-task/tasks/{id}	Remove a task
POST	/api/background-task/tasks/{id}/start	Start a task
POST	/api/background-task/tasks/{id}/complete	Mark task complete
POST	/api/background-task/tasks/{id}/cancel	Cancel a task
POST	/api/background-task/tasks/{id}/pause	Pause a task
POST	/api/background-task/tasks/{id}/resume	Resume a paused task

Scheduler Endpoints

Method	Path	Description
POST	/api/background-task/scheduler/tasks	Create scheduled task
GET	/api/background-task/scheduler/tasks	List scheduled tasks
GET	/api/background-task/scheduler/tasks/{id}	Get scheduled task
POST	/api/background-task/scheduler/check	Check and trigger due tasks

---

DPP

Digital Product Passport — ESPR/EPCIS/GS1 compliant.

Method	Path	Description
POST	/api/dpp/dpp	Create a new passport
GET	/api/dpp/dpp	List all passports
GET	/api/dpp/dpp/{id}	Get passport by ID
PUT	/api/dpp/dpp/{id}	Update passport
POST	/api/dpp/dpp/{id}/lifecycle	Add a lifecycle stage
POST	/api/dpp/dpp/{id}/anchor	Anchor passport hash on Kaspa
POST	/api/dpp/dpp/{id}/epcis	Ingest EPCIS event → auto-map to lifecycle
GET	/api/dpp/dpp/{id}/qr	Generate QR code (PNG) with GS1 Digital Link

POST /api/dpp/dpp

// Request
{
  "product_name": "Li-Ion Battery Module 48V",
  "gtin": "04012345000010",
  "manufacturer": "did:kaspa:testnet-12:abc123",
  "category": "EV Battery",
  "batch_id": "BATCH-2026-001"
}

// Response 201
{
  "id": "dpp-uuid",
  "product_name": "Li-Ion Battery Module 48V",
  "gtin": "04012345000010",
  "lifecycle_stages": [],
  "anchors": [],
  "created_at": "2026-03-20T10:00:00Z"
}

POST /api/dpp/dpp/{id}/epcis

// Request
{
  "event_type": "ObjectEvent",
  "action": "OBSERVE",
  "biz_step": "urn:epcglobal:cbv:bizstep:commissioning",
  "disposition": "urn:epcglobal:cbv:disp:active",
  "event_time": "2026-03-20T10:00:00Z",
  "read_point": "urn:epc:id:sgln:0012345.11111.0"
}

// Response 200
{"lifecycle_stage": "Manufacturing", "event_recorded": true}

GET /api/dpp/dpp/{id}/qr

Returns Content-Type: image/png — a QR code encoding the GS1 Digital Link URI.

---

IoT Ingest

Sensor data ingestion for DPP lifecycle updates.

Method	Path	Description
POST	/api/iot-ingest/iot/devices	Register an IoT device
GET	/api/iot-ingest/iot/devices	List registered devices
GET	/api/iot-ingest/iot/devices/{id}	Get device details
PUT	/api/iot-ingest/iot/devices/{id}	Update device
POST	/api/iot-ingest/iot/ingest	Batch ingest sensor readings
GET	/api/iot-ingest/iot/readings	List recent readings
GET	/api/iot-ingest/iot/devices/{id}/readings	Readings for a specific device
POST	/api/iot-ingest/iot/thresholds	Create threshold rule
GET	/api/iot-ingest/iot/thresholds	List threshold rules
DELETE	/api/iot-ingest/iot/thresholds/{id}	Delete threshold rule

POST /api/iot-ingest/iot/ingest

// Request
{
  "device_id": "sensor-001",
  "readings": [
    {"sensor_type": "Temperature", "value": 42.5, "unit": "CEL", "timestamp": "2026-03-20T10:00:00Z"},
    {"sensor_type": "Humidity", "value": 65.0, "unit": "P1", "timestamp": "2026-03-20T10:00:00Z"}
  ]
}

// Response 200
{"ingested": 2, "threshold_alerts": 0, "lifecycle_updates": 0}

---

Feedback

Consumer micropayment feedback with sompi rewards.

Method	Path	Description
POST	/api/feedback/feedback	Submit feedback for a product
GET	/api/feedback/feedback	List all feedback
GET	/api/feedback/feedback/{id}	Get feedback by ID
GET	/api/feedback/feedback/passport/{passport_id}	Feedback for a passport
GET	/api/feedback/feedback/stats	Feedback statistics
GET	/api/feedback/feedback/config	Get reward configuration
PUT	/api/feedback/feedback/config	Update reward configuration

Reward Calculation

• Base reward: 1,000 sompi
• Photo bonus: +500 sompi
• Defect report bonus: +2,000 sompi
• Daily cap: 10,000 sompi per user

---

Regulator

Regulatory compliance query responder.

Method	Path	Description
POST	/api/regulator/regulator/reports	Create compliance report
GET	/api/regulator/regulator/reports	List reports
GET	/api/regulator/regulator/reports/{id}	Get report by ID
POST	/api/regulator/regulator/query	Execute regulatory query
GET	/api/regulator/regulator/carbon/{passport_id}	Carbon footprint report
GET	/api/regulator/regulator/materials/{passport_id}	Material composition report
GET	/api/regulator/regulator/battery/{passport_id}	Battery-specific report
POST	/api/regulator/regulator/compliance/{passport_id}	Run compliance checks
POST	/api/regulator/regulator/carbon	Submit carbon data
POST	/api/regulator/regulator/materials	Submit material declaration
POST	/api/regulator/regulator/battery	Submit battery data
GET	/api/regulator/regulator/audit	Get audit trail

Pre-built Compliance Checks

EU Battery Regulation (5 checks):

1. Carbon footprint below threshold
2. Recycled content minimums met
3. State of health monitoring active
4. Material composition complete
5. Due diligence documentation present

ESPR (4 checks):

1. Data completeness (all required fields)
2. Lifecycle coverage (all stages recorded)
3. Tamper evidence (blockchain anchored)
4. Data carrier available (QR/Digital Link)

---

Lineage

Product-to-product DAG for supply chain traceability.

Method	Path	Description
POST	/api/lineage/lineage/nodes	Create a lineage node
GET	/api/lineage/lineage/nodes	List all nodes
GET	/api/lineage/lineage/nodes/{id}	Get node by ID
POST	/api/lineage/lineage/edges	Create an edge (with cycle detection)
GET	/api/lineage/lineage/edges	List all edges
GET	/api/lineage/lineage/nodes/{id}/edges	Edges for a specific node
GET	/api/lineage/lineage/nodes/{id}/trace	Trace ancestors (upstream)
GET	/api/lineage/lineage/nodes/{id}/impact	Trace descendants (downstream)
GET	/api/lineage/lineage/path	Find shortest path between nodes
GET	/api/lineage/lineage/roots	List root nodes (no parents)
GET	/api/lineage/lineage/leaves	List leaf nodes (no children)
GET	/api/lineage/lineage/stats	Graph statistics

Node Types

RawMaterial, Component, SubAssembly, Assembly, FinishedProduct, Facility, Mine, Recycler

Edge Relationships

ContainedIn, SourcedFrom, ManufacturedAt, AssembledFrom, RecycledInto, TestedAt, ShippedVia, OwnedBy

---

Circular

Circular economy marketplace for end-of-life materials.

Method	Path	Description
POST	/api/circular/circular/listings	Create material listing
GET	/api/circular/circular/listings	List all listings
GET	/api/circular/circular/listings/{id}	Get listing by ID
PUT	/api/circular/circular/listings/{id}	Update listing
DELETE	/api/circular/circular/listings/{id}	Withdraw listing
POST	/api/circular/circular/search	Search with geospatial filter
POST	/api/circular/circular/listings/{id}/bids	Place a bid
GET	/api/circular/circular/listings/{id}/bids	List bids
POST	/api/circular/circular/listings/{id}/bids/{bid_id}/accept	Accept a bid
POST	/api/circular/circular/listings/{id}/bids/{bid_id}/reject	Reject a bid
GET	/api/circular/circular/stats	Market statistics

POST /api/circular/circular/search

// Request
{
  "material_type": "Lithium",
  "max_distance_km": 500,
  "location": {"lat": 52.37, "lon": 4.89},
  "min_quantity": 100
}

// Response 200
[{"id": "listing-uuid", "material": "Lithium", "quantity": 500, "distance_km": 123.4, ...}]

---

Geo

Geospatial supply chain tracking.

Method	Path	Description
POST	/api/geo/geo/locations	Batch ingest location data
GET	/api/geo/geo/locations/{entity_id}	Location history for entity
GET	/api/geo/geo/locations/{entity_id}/latest	Latest location
GET	/api/geo/geo/locations/{entity_id}/route	Route (ordered waypoints)
POST	/api/geo/geo/fences	Create a geofence
GET	/api/geo/geo/fences	List geofences
GET	/api/geo/geo/fences/{id}	Get geofence details
DELETE	/api/geo/geo/fences/{id}	Delete geofence
GET	/api/geo/geo/fences/{id}/crossings	Fence crossing events
POST	/api/geo/geo/nearby	Search nearby entities
GET	/api/geo/geo/stats	Geospatial statistics

Spatial Algorithms

• Haversine distance: Great-circle distance between two points
• Point-in-polygon: Ray casting algorithm for geofence containment
• Fence crossing detection: Entry/exit event generation
• Nearby search: Radius-based entity search

---

Sentinel

Anomaly detection and integrity watchdog.

Method	Path	Description
POST	/api/sentinel/sentinel/rules	Create monitoring rule
GET	/api/sentinel/sentinel/rules	List all rules
GET	/api/sentinel/sentinel/rules/{id}	Get rule by ID
PUT	/api/sentinel/sentinel/rules/{id}	Update rule
DELETE	/api/sentinel/sentinel/rules/{id}	Delete rule
POST	/api/sentinel/sentinel/ingest	Ingest data points
GET	/api/sentinel/sentinel/alerts	List alerts (with filtering)
GET	/api/sentinel/sentinel/alerts/{id}	Get alert by ID
POST	/api/sentinel/sentinel/alerts/{id}/acknowledge	Acknowledge alert
POST	/api/sentinel/sentinel/alerts/{id}/resolve	Resolve alert
POST	/api/sentinel/sentinel/analyze	Run manual analysis
GET	/api/sentinel/sentinel/stats	Alert statistics

Rule Types

Type	Description	Key Parameters
AnchorFrequency	Detect gaps in blockchain anchoring	max_gap_hours
GapDetection	Detect missing data points	max_gap_hours
ValueThreshold	Detect sudden value changes	threshold_percent
SequenceCheck	Detect out-of-order events	expected_sequence (array)
VolumeBaseline	Detect volume anomalies (std deviation)	window_size, std_dev_threshold
ComplianceWatch	Detect expiring certifications	warning_days

Alert Filtering

GET /api/sentinel/sentinel/alerts?severity=high&acknowledged=false&since=2026-03-01T00:00:00Z

---

Gateway

API key management and rate limiting.

Method	Path	Description
POST	/api/gateway/gateway/keys	Create API key (raw key shown once)
GET	/api/gateway/gateway/keys	List all keys (no hashes exposed)
GET	/api/gateway/gateway/keys/{id}	Get key info
PUT	/api/gateway/gateway/keys/{id}	Update key (name, permissions, limits)
DELETE	/api/gateway/gateway/keys/{id}	Revoke key
POST	/api/gateway/gateway/keys/{id}/rotate	Rotate key (new key, old revoked)
GET	/api/gateway/gateway/keys/{id}/usage	Usage report
POST	/api/gateway/gateway/validate	Validate a raw API key

POST /api/gateway/gateway/keys

// Request
{
  "name": "production-frontend",
  "permissions": ["dpp:read", "dpp:write", "wallet:read"],
  "rate_limit": {"requests_per_minute": 120, "requests_per_hour": 5000, "requests_per_day": 50000}
}

// Response 201
{
  "id": "key-uuid",
  "name": "production-frontend",
  "key": "kw_a1b2c3d4...",  // SHOWN ONCE — save this!
  "key_prefix": "kw_a1b2c",
  "permissions": ["dpp:read", "dpp:write", "wallet:read"],
  "rate_limit": {"requests_per_minute": 120, ...},
  "warning": "Store this key securely. It will not be shown again."
}

POST /api/gateway/gateway/validate

// Request
{"key": "kw_a1b2c3d4..."}

// Response 200
{"valid": true, "key_id": "key-uuid", "permissions": ["dpp:read", ...], "rate_limited": false}

---

Wallet

BIP-39 HD wallet management.

Method	Path	Description
POST	/api/wallet/wallets	Create wallet (mnemonic shown once)
GET	/api/wallet/wallets/{id}	Get wallet info (no secrets)
GET	/api/wallet/wallets/{id}/balance	Query balance
GET	/api/wallet/wallets/{id}/utxos	List UTXOs
POST	/api/wallet/wallets/{id}/derive	Derive next address
POST	/api/wallet/wallets/{id}/send	Send KAS

POST /api/wallet/wallets

// Request
{"network": "testnet-12"}

// Response 201
{
  "id": "wallet-uuid",
  "address": "kaspatest:qr...",
  "network": "testnet-12",
  "mnemonic": "word1 word2 ... word12",  // SHOWN ONCE
  "created_at": "2026-03-20T10:00:00Z"
}

POST /api/wallet/wallets/{id}/send

// Request
{"to": "kaspatest:qr...", "amount": 100000000, "fee": 30000}

// Response 200
{"tx_id": "hex-txid", "amount": 100000000, "fee": 30000}

---

Wire Service

Encrypted P2P messaging channels (X25519 + XChaCha20-Poly1305 with HKDF-SHA256 directional key separation).

Method	Path	Description
POST	/api/wire/channels	Create channel (generate keypair)
GET	/api/wire/channels	List channels
GET	/api/wire/channels/{id}	Get channel info
POST	/api/wire/channels/{id}/handshake	Exchange peer public key
POST	/api/wire/channels/{id}/messages	Send encrypted message
GET	/api/wire/channels/{id}/messages	List messages (decrypted)
GET	/api/wire/channels/{id}/messages/{msg_id}	Get single message

Channel Lifecycle

1. Create: Generates X25519 keypair, returns public key (hex)
2. Handshake: Accept peer’s public key → derive shared secret
3. Send: Encrypt payload with XChaCha20-Poly1305 (192-bit random nonce) using a per-direction key derived via HKDF-SHA256 from the shared secret
4. Receive: Decrypt messages using shared secret

---

Workflow

Compliance state machine engine.

Method	Path	Description
POST	/api/workflow/workflows	Create workflow definition
GET	/api/workflow/workflows	List definitions
GET	/api/workflow/workflows/{id}	Get definition
DELETE	/api/workflow/workflows/{id}	Delete definition
POST	/api/workflow/workflows/{id}/instances	Create instance from definition
GET	/api/workflow/instances/{id}	Get instance
POST	/api/workflow/instances/{id}/transition	Apply state transition
GET	/api/workflow/instances/{id}/transitions	Available transitions
GET	/api/workflow/instances/{id}/history	Transition history
POST	/api/workflow/instances/{id}/suspend	Suspend instance
POST	/api/workflow/instances/{id}/resume	Resume instance

---

Webhook

HMAC-SHA256 signed outbound event delivery.

Method	Path	Description
POST	/api/webhook/webhooks	Create subscription
GET	/api/webhook/webhooks	List subscriptions
GET	/api/webhook/webhooks/{id}	Get subscription
PUT	/api/webhook/webhooks/{id}	Update subscription
DELETE	/api/webhook/webhooks/{id}	Delete subscription
POST	/api/webhook/webhooks/{id}/test	Send test delivery
GET	/api/webhook/webhooks/{id}/deliveries	Delivery history
GET	/api/webhook/webhooks/{id}/stats	Delivery statistics
POST	/api/webhook/webhooks/trigger	Trigger event for all matching subscriptions

Event Types (14)

DppCreated, DppUpdated, DppAnchored, LifecycleStageAdded, WalletCreated, TransactionSubmitted, AlertGenerated, AlertAcknowledged, FeedbackSubmitted, ComplianceCheckFailed, GeofenceCrossing, WorkflowTransitioned, ApiKeyCreated, ApiKeyRevoked

---

Logging

Structured audit log.

Method	Path	Description
POST	/api/logging/logs	Write a log entry
GET	/api/logging/logs	Query log entries

---

Trust

Gaia-X trust framework and artefact verification.

Routes include trust credential management, compliance checking, and artefact verification.

---

Rights Management

ODRL-based digital rights and policy management.

Routes include policy CRUD, agreement creation, and policy evaluation.

---

Attestation

Credential attestation management.

Routes include attestation creation, verification, and status management.

---

Dataspace

IDSA Dataspace Protocol implementation.

Control Plane

Contract negotiation and transfer process management.

Data Plane

Catalogue queries and data asset access.

---

Federated Catalogue

Cross-organisation asset discovery and registration.

---

Data Space Connector

Organisation-to-organisation data exchange management.

---

Data Processing

ETL pipeline definition and execution.

---

Auditable Item Graph

DAG of auditable items with provenance tracking.

---

Auditable Item Stream

Append-only auditable event stream.

---

Common Response Patterns

Success

// 200 OK
{"id": "uuid", "name": "item", ...}

// 201 Created
{"id": "uuid", "name": "item", ...}

// 204 No Content (for deletes)

Errors

// 400 Bad Request
{"error": "invalid field: name is required"}

// 404 Not Found
{"error": "not found"}

// 409 Conflict
{"error": "already exists"}

// 429 Too Many Requests
{"error": "rate limit exceeded"}

Pagination

Services that support pagination accept limit and offset query parameters:

GET /api/entity-storage/products?limit=20&offset=40

Filtering

Many list endpoints accept query parameters for filtering:

GET /api/sentinel/sentinel/alerts?severity=high&acknowledged=false&since=2026-03-01T00:00:00Z