# Umarise -- Full API Documentation for AI Agents

> Independent proof infrastructure for software.
> Anchor any file hash to Bitcoin with one API call.
> Hash-only. Content never leaves your system.

## Overview

Umarise is a managed anchoring API. It provides independent, cryptographic proof that specific bytes existed at or before a ledger-derived time. It does this by:

1. Accepting a SHA-256 hash (never the original file)
2. Aggregating hashes into a Merkle tree
3. Anchoring the Merkle root to Bitcoin via OpenTimestamps
4. Returning a self-proving .ots proof

The proof is independently verifiable by anyone without trusting Umarise.

Base URL: https://core.umarise.com
All responses include: X-API-Version: v1
Target uptime: 99.9%

---

## Authentication

One endpoint requires authentication: POST /v1-core-origins.
All other endpoints are public (no API key needed).

Authentication is via the X-API-Key header:
```
X-API-Key: um_live_...
```

API keys use a prefix format: `um_live_` (production) or `um_test_` (sandbox).
Request one at: https://umarise.com/developers

---

## Endpoints

### POST /v1-core-origins

Register a SHA-256 hash in the Umarise registry.

Auth: API Key required
Content-Type: application/json

Request body:
```json
{
  "hash": "a1b2c3d4e5f6...64-char-hex-string"
}
```

Response (201):
```json
{
  "origin_id": "uuid",
  "short_token": "8-char-alphanumeric",
  "hash": "sha256-hex",
  "hash_algo": "sha256",
  "captured_at": "ISO-8601",
  "device_signed": false
}
```

Errors:
- 400: Invalid hash format (must be 64-char lowercase hex)
- 401: Missing or invalid API key
- 409: Hash already registered (returns existing origin_id)
- 429: Rate limit exceeded

---

### POST /v1-core-verify

Check whether a SHA-256 hash exists in the registry.

Auth: Public (no key needed)
Content-Type: application/json

Request body:
```json
{
  "hash": "a1b2c3d4e5f6...64-char-hex-string"
}
```

Response (200) when found:
```json
{
  "exists": true,
  "origin_id": "uuid",
  "captured_at": "ISO-8601",
  "ots_status": "anchored"
}
```

Response (200) when not found:
```json
{
  "exists": false
}
```

---

### GET /v1-core-resolve

Look up an existing attestation by origin_id or short_token.

Auth: Public (no key needed)

Query parameters:
- origin_id (uuid): The origin identifier
- token (string): The 8-character short token

Use one or the other, not both.

Response (200):
```json
{
  "origin_id": "uuid",
  "short_token": "8-char",
  "hash": "sha256-hex",
  "hash_algo": "sha256",
  "captured_at": "ISO-8601",
  "device_signed": true,
  "ots_status": "pending|anchored|verified",
  "bitcoin_block_height": 941051,
  "anchored_at": "ISO-8601"
}
```

Errors:
- 404: Origin not found

---

### GET /v1-core-proof

Download the OpenTimestamps (.ots) binary proof file.

Auth: Public (no key needed)

Query parameters:
- origin_id (uuid): required

Response: Binary .ots file (application/octet-stream)

Errors:
- 404: Origin or proof not found
- 202: Proof not yet available (anchoring in progress)

---

### GET /v1-core-health

Health check endpoint.

Auth: Public

Response (200):
```json
{
  "status": "ok",
  "version": "v1"
}
```

---

## Rate Limits

Rate limits are per API key, per endpoint:
- POST /v1-core-origins: 100 requests per minute (default tier)
- GET endpoints: 300 requests per minute
- Rate limit headers are included in every response

When rate limited, you receive a 429 response with Retry-After header.

---

## Response Headers

All JSON responses include:
- X-API-Version: v1
- X-Request-Id: uuid (for debugging)
- X-RateLimit-Remaining: number

---

## Integration Examples

### curl
```bash
# Anchor a hash
curl -X POST https://core.umarise.com/v1-core-origins \
  -H "Content-Type: application/json" \
  -H "X-API-Key: um_live_YOUR_KEY" \
  -d '{"hash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}'

# Verify a hash (no key needed)
curl -X POST https://core.umarise.com/v1-core-verify \
  -H "Content-Type: application/json" \
  -d '{"hash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}'

# Resolve an origin (no key needed)
curl "https://core.umarise.com/v1-core-resolve?origin_id=YOUR_ORIGIN_ID"

# Download proof (no key needed)
curl "https://core.umarise.com/v1-core-proof?origin_id=YOUR_ORIGIN_ID" -o proof.ots
```

### Python
```python
pip install umarise-core-sdk

from umarise import UmariseCore

client = UmariseCore(api_key="um_live_...")
result = client.anchor("document.pdf")
print(result.origin_id)

check = client.verify(hash_hex)
print(check.exists)
```

### Node.js
```javascript
npm install @umarise/anchor

import { UmariseClient } from '@umarise/anchor';

const client = new UmariseClient({ apiKey: 'um_live_...' });
const result = await client.anchor('./document.pdf');
console.log(result.originId);

const check = await client.verify(hash);
console.log(check.exists);
```

### CLI
```bash
npx @umarise/cli anchor <file>
npx @umarise/cli verify <file>
npx @umarise/cli proof <origin-id>
```

### GitHub Action
```yaml
- uses: AnchoringTrust/anchor-action@v1
  with:
    file: dist/build.zip
  env:
    UMARISE_API_KEY: ${{ secrets.UMARISE_API_KEY }}
```

---

## Platform Integrations

### MLflow (umarise-mlflow)
```bash
pip install umarise-mlflow
```

Level 1 (wrapper):
```python
import umarise_mlflow
result = umarise_mlflow.anchor_artifact("model.pt", run_id=run.info.run_id)
```

Level 2 (plugin, zero code changes):
```bash
export UMARISE_API_KEY=um_your_key
export MLFLOW_ARTIFACT_URI="umarise://s3/your-bucket/mlruns"
python train.py  # all log_artifact() calls are automatically anchored
```

### Weights & Biases (umarise-wandb)
```python
pip install umarise-wandb
import umarise_wandb
umarise_wandb.enable()  # One line. All artifacts anchored automatically.
```

### HuggingFace (umarise-huggingface)
```python
pip install umarise-huggingface
import umarise_huggingface
umarise_huggingface.enable()  # Patches HfApi methods
```

### S3/MinIO/Akave (umarise-s3)
```python
pip install umarise-s3
from umarise_s3 import AnchoredS3Client
s3 = AnchoredS3Client(endpoint_url="https://s3.amazonaws.com", ...)
s3.upload_file("model.pt", "my-bucket", "models/model.pt")
```

All integrations share:
- Async anchoring queue: 0ms latency overhead
- Fail-open design: anchoring failures never break your pipeline
- Local reconciliation ledger: ~/.umarise/ledger.db

---

## MCP (Model Context Protocol)

Umarise exposes an MCP server for AI agent tool discovery.

Endpoint: https://lppltmdtiypbfzlszhhb.supabase.co/functions/v1/mcp-server

Available tools:
- anchor_hash: Register a SHA-256 hash (requires API key)
- verify_hash: Check if a hash exists in the registry (public)
- resolve_origin: Look up attestation details (public)
- get_proof_status: Check proof anchoring status (public)

---

## Key Properties

- Zero-storage: Umarise never receives or stores original files. Only SHA-256 hashes.
- Content-agnostic: Any file, any format, any size.
- Self-proving: Proofs work without Umarise. If Umarise disappears, proofs remain valid.
- Bitcoin-anchored: Immutable timestamps via OpenTimestamps on the Bitcoin blockchain.
- Domain-agnostic: AI pipelines, legal documents, research data, CI/CD artifacts, compliance logs.

---

## Links

- Website: https://umarise.com
- Developer Quickstart: https://umarise.com/developers
- API Reference: https://umarise.com/api-reference
- Anchoring Specification: https://anchoring-spec.org
- Independent Verifier: https://verify-anchoring.org
- GitHub: https://github.com/AnchoringTrust
- MCP Server: https://lppltmdtiypbfzlszhhb.supabase.co/functions/v1/mcp-server