API Documentation

Integrate Unveila's predictive intelligence into your quantitative models, internal dashboards, and automated workflows.

https://api.unveila.ioFree for all users

Authentication

All requests require an API key sent via the Authorization header. Create keys in Settings → API Keys.

http

GET /v1/predictions HTTP/1.1
Host: api.unveila.io
Authorization: Bearer uvla_live_YOUR_API_KEY

Security: Never send keys as query parameters. Never commit to version control. Keys prefixed with uvla_ are detected by GitHub secret scanning.

Rate Limits

Free (All Users)

Daily1,000

Per minute60

Response Headers

X-RateLimit-Limit-Day

X-RateLimit-Remaining-Day

X-RateLimit-Limit-Minute

X-RateLimit-Remaining-Minute

X-RateLimit-Reset

Scopes

Keys can be restricted to specific resources. Unauthorized requests return 403.

predictions

Predictions, performance, compare

entities

Entity detail and timeline

signals

Signal data via entities

search

Entity search

macro

Macro environment

crypto

Crypto tokens and protocols

data_feed

Bulk data feed export

Endpoints

GET/v1/predictionspredictions

List active predictions with filtering, ranking, pagination

Params: use_case, severity, direction, confidence_min, sort_by, page, limit

GET/v1/predictions/{id}predictions

Full prediction detail with evidence chains, signals, calibration

GET/v1/entities/{id}entities

Entity detail with predictions, features, relationships, timeline

GET/v1/entities/{id}/timelineentities

Chronological timeline of events, signals, predictions

Params: page, limit

GET/v1/searchsearch

Fuzzy entity search across equity and crypto

Params: q, limit

GET/v1/macromacro

Current macro environment indicators (yield curve, credit stress, CRE, consumer)

GET/v1/comparepredictions

Compare 2-5 entities side by side

Params: ids (comma-separated)

GET/v1/crypto/tokenscrypto

List crypto tokens/protocols with risk scores and TVL

Params: sort_by, page, limit

GET/v1/crypto/tokens/{id}crypto

Crypto token detail with signals, features, relationships

GET/v1/performancepredictions

Historical accuracy metrics, calibration, Called It highlights

GET/v1/proof/latestpublic

Latest Merkle root commitment — on-chain verified prediction set

GET/v1/proof/verify/{prediction_id}public

Merkle proof for a specific prediction — cryptographic verification

GET/v1/proof/historypublic

Historical Merkle root commitments

Params: limit

Response Format

json

{
  "predictions": [
    {
      "prediction_id": "8dff8c26-...",
      "entity_name": "ORACLE CORP",
      "ticker": "ORCL",
      "prediction_type": "layoff_imminent",
      "score": 0.859,
      "confidence": 0.50,
      "severity": "high",
      "direction": "negative",
      "time_horizon": "14d",
      "trust_label": "moderate_signal",
      "signal_count": 2,
      "entity_type": "company",
      "is_public": true
    }
  ],
  "total": 223,
  "page": 1,
  "has_more": true
}

Quick Start

Python

python

import httpx

API_KEY = "uvla_live_YOUR_KEY_HERE"
BASE = "https://api.unveila.io"
headers = {"Authorization": f"Bearer {API_KEY}"}

# List high-risk predictions
resp = httpx.get(f"{BASE}/v1/predictions?sort_by=rank&limit=10", headers=headers)
for p in resp.json()["predictions"]:
    print(f'{p["ticker"]:>6} | {p["score"]:.2f} | {p["severity"]:>6} | {p["prediction_type"]}')

cURL

bash

# List predictions sorted by risk
curl https://api.unveila.io/v1/predictions?sort_by=rank&limit=5 \
  -H "Authorization: Bearer uvla_live_YOUR_KEY_HERE"

# Search entities
curl "https://api.unveila.io/v1/search?q=oracle&limit=5" \
  -H "Authorization: Bearer uvla_live_YOUR_KEY_HERE"

On-Chain Prediction Proof

Every prediction set is committed daily as a Merkle root. Verify any prediction was made before its outcome was known. The /v1/proof/* endpoints are public — no API key required.

bash

# Get latest Merkle root
curl https://api.unveila.io/v1/proof/latest

# Verify a specific prediction
curl https://api.unveila.io/v1/proof/verify/8dff8c26-...

json

{
  "merkle_root": "9a35156bf3efc713...",
  "prediction_count": 704,
  "as_of_timestamp": "2026-04-05T11:21:16Z",
  "chain": "base",
  "tx_hash": null
}

Key Management Features

Scoped Access

Restrict keys to specific resource types. A key for your alpha model only needs the 'predictions' scope.

IP Allowlisting

Lock keys to CIDR ranges. Requests from non-allowed IPs are rejected with 403.

Zero-Downtime Rotation

Rotate keys with a grace period (1-168 hours). Both old and new keys work during transition.

Usage Monitoring

Track daily/minute usage and per-endpoint breakdown via the usage endpoint.

Error Codes

200Success

401Invalid, revoked, or expired API key

403Insufficient scope, IP not allowed, or plan limit

404Resource not found

429Rate limit exceeded — check Retry-After header

500Internal server error

API data is subject to the same disclaimers as the web platform. Predictions are not investment advice. See our disclaimer and terms of service.

Home Terms Privacy