API Reference

Complete API documentation for SOVEREIGN\PROVENANCE.

Base URL

The API base URL follows this pattern:

https://api.sovereign.provenance/api/v1

For local development:

http://localhost:3000/api/v1

Versioning

The API is versioned via URL path: /api/v1/...

• Current version: v1
• Breaking changes: Will result in a new version (v2, v3, etc.)
• Non-breaking changes: Added to current version
• Deprecation: Deprecated endpoints will be announced 6 months in advance

When a new version is released, the previous version remains available for at least 12 months.

Authentication

All write endpoints require an API key. Include it in the request header:

X-API-Key: your-api-key-here

Get your API key from the developer dashboard or contact support.

Note: Keep your API key secure. Never commit it to version control or expose it in client-side code.

Endpoints

Identity

Create Identity

POST /identity

Request:

{
  "name": "Aurora Rivers",
  "type": "creator",
  "email": "aurora@example.test",
  "organization": "Aurora Lab",
  "jurisdiction": "US-CA",
  "publicKey": "base64-or-hex-public-key",
  "keyType": "ed25519",
  "trustSignals": [
    { "type": "email_verified", "strength": 0.6 }
  ]
}

Response:

{
  "success": true,
  "data": {
    "id": "urn:sp:identity:...",
    "profile": {
      "name": "Aurora Rivers",
      "type": "creator",
      "email": "aurora@example.test"
    },
    "did": "did:sovprov:...",
    "trustLevel": "light_verified",
    "keys": [
      {
        "id": "urn:sp:key:...",
        "type": "ed25519",
        "publicKey": "base64-or-hex-public-key",
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Get Identity

GET /identity/:id

Returns the same shape as POST /identity, plus the latest trust evaluation snapshot.

Verify Identity Signature

POST /identity/:id/verify

Request:

{
  "message": "base64-encoded-payload",
  "signature": "base64-or-hex-signature",
  "keyId": "urn:sp:key:..."
}

Set the optional headers X-SovProv-Identity, X-SovProv-Signature, and X-SovProv-KeyId when calling other write endpoints (e.g. /passport). The server automatically verifies the headers against the stored keys before executing sensitive mutations.

Passport

Create Passport

POST /passport

Request:

{
  "identityId": "urn:sp:identity:...",
  "sealId": "urn:sp:seal:...",
  "accordId": "urn:sp:accord:...",
  "metadata": {
    "artifactType": "string",
    "createdAt": "ISO8601",
    "tags": ["string"]
  }
}

Get Passport

GET /passport/:id

Verify Passport

GET /passport/:id/verify

Accord

Create Accord

POST /accord

Request:

{
  "attribution": "required" | "optional" | "none",
  "derivatives": "allowed" | "restricted" | "forbidden",
  "aiTraining": "opt_in" | "opt_out" | "restricted",
  "commercial": "allowed" | "licensed" | "forbidden",
  "cultural": {},
  "geographic": {}
}

Evaluate Use

POST /accord/evaluate

Request:

{
  "accordId": "urn:sp:accord:...",
  "proposedUse": {
    "type": "derivative" | "ai_training" | "display" | "commercial_use",
    "commercial": boolean,
    "geographicRegion": "string"
  }
}

Response:

{
  "success": true,
  "data": {
    "allowed": false,
    "reason": "Derivatives are restricted for this artifact",
    "rulesEvaluated": []
  }
}

Synthetic

Register Synthetic Output

POST /ai/synthetic/register

Request:

{
  "aiLabId": "string",
  "modelId": "string",
  "syntheticData": [
    {
      "id": "string",
      "prompt": "string",
      "policy": {
        "allowedUse": "string"
      }
    }
  ]
}

Alternative Request Format:

{
  "modelId": "string",
  "rawOutput": "string",
  "rawInput": "string",
  "metadata": {}
}

Response:

{
  "success": true,
  "data": {
    "id": "urn:sp:synthetic:...",
    "modelId": "urn:sp:model:...",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Verify Synthetic Output

POST /synthetic/verify

Verifies the provenance and lineage of a synthetic output.

Ledger

Write Event

POST /ledger/events

Query Events

GET /ledger/events?type=passport_created&limit=10&offset=0

Query Parameters:

• type - Event type filter (e.g., passport_created, accord_updated, identity_registered)
• identity - Identity ID filter (e.g., urn:sp:identity:abc123)
• since - ISO8601 timestamp (e.g., 2024-01-01T00:00:00Z)
• until - ISO8601 timestamp (e.g., 2024-01-31T23:59:59Z)
• limit - Number of results (default: 100, max: 1000)
• offset - Pagination offset (default: 0)

Example Request:

GET /api/v1/ledger/events?type=passport_created&identity=urn:sp:identity:abc123&limit=10&offset=0

Example Response:

{
  "success": true,
  "data": [
    {
      "id": "urn:sp:event:001",
      "type": "passport_created",
      "timestamp": "2024-01-15T10:30:00Z",
      "identity": "urn:sp:identity:abc123",
      "payload": {
        "passportId": "urn:sp:passport:ghi012",
        "artifactType": "image"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 42,
    "hasMore": true
  }
}

Get Event

GET /ledger/events/:id

Error Responses

All errors follow this format:

{
  "error": true,
  "code": "ERROR_CODE",
  "reason": "Human-readable error message",
  "details": {}
}

Error Codes

• UNAUTHORIZED - Missing or invalid API key
• FORBIDDEN - Insufficient permissions
• VALIDATION_ERROR - Invalid request data
• NOT_FOUND - Resource not found
• INTERNAL_ERROR - Server error

Rate Limiting

Rate limits are applied per API key. Current limits:

• Read endpoints: 1000 requests/minute
• Write endpoints: 100 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000

If you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": true,
  "code": "RATE_LIMIT_EXCEEDED",
  "reason": "Rate limit exceeded. Please try again later.",
  "details": {
    "retryAfter": 60
  }
}