# Elucora

> Elucora turns a public web source into a signed evidence receipt that anyone can verify without
> trusting Elucora. Give it a URL and optionally the exact passage or field that matters; it
> fetches the source, hashes the bytes it received, signs a record of what was served and when,
> and appends that record to a public append-only log.

## What a receipt proves

- These exact bytes were served at this URL at this time.
- The quoted passage or field is the one that was selected, and matches its own hash.
- Elucora issued the receipt and nobody has altered it since: ES256 over RFC 8785 canonical JSON.
- The entry existed by a stated time: RFC 3161 timestamp, then a Bitcoin anchor via OpenTimestamps.

## What a receipt does NOT prove

- It does not prove the source was telling the truth. A page can say anything and seal honestly.
- It does not prove what the page said before capture, or that it has not changed since.
- It does not prove who wrote the source, or that the publisher endorses the claim.
- Do not describe a receipt as proof that a statement is true. It is proof of what was served.

## Two kinds of receipt, and the difference matters

- `capture_method: "http"` — Elucora fetched the URL itself. The receipt is evidence about what
  that source served at that moment.
- `capture_method: "attested"` — the caller sent a hash of content they already held, and Elucora
  never saw the source. The receipt proves that this account submitted this digest at this time,
  and that the record has not changed since. It says nothing about where the content came from.
  Never present an attested receipt as evidence about a web source; a caller chooses what the hash
  was computed over.

## Authentication

Send an API key as a bearer token: `Authorization: Bearer elu_live_...`
Keys are created in the dashboard at https://elucora.com/dashboard/keys and are shown once.
Keys belong server-side. Never put one in browser code, a prompt, or a repository.

## Endpoints

- POST https://elucora.com/v1/receipts — capture a source and return a signed receipt. Consumes quota.
- POST https://elucora.com/v1/attestations — seal a SHA-256 hash you already hold. Send {"hash": "sha256:..."}
  and optionally content_type, size_bytes and metadata. Only the digest is accepted; Elucora stores
  no bytes. Consumes quota, and produces the weaker `attested` receipt described above.
- GET https://elucora.com/v1/receipts/{id} — the public receipt. No key required.
- POST https://elucora.com/v1/verify — verify a receipt. Send {"id": "rcpt_..."}, or the receipt document as
  received, or {"payload": {...}, "signature": "..."}. No key required.
- GET https://elucora.com/v1/transparency/{id} — the log entry, timestamp and anchor state for a receipt.
- GET https://elucora.com/v1/transparency/{id}/ots — the OpenTimestamps proof file for `ots verify`.
- GET https://elucora.com/v1/transparency — recent log entries and the current head.
- GET https://elucora.com/v1/transparency/checkpoint — a signed statement of the head, worth archiving.
- GET https://elucora.com/.well-known/jwks.json — the public keys. Verification needs nothing else from us.
- GET https://elucora.com/v1/health — dependency and signing health.
- POST https://elucora.com/mcp — MCP server (tools: elucora_capture, elucora_attest, elucora_get_receipt,
  elucora_verify). Verifying and reading receipts need no key; capturing and attesting do.

Full machine-readable contract: https://elucora.com/openapi.json

## Capturing

```
POST /v1/receipts
Authorization: Bearer elu_live_...
Content-Type: application/json

{
  "url": "https://api.example.com/quotes/BTC",
  "selector": { "type": "json-pointer", "value": "/price" },
  "metadata": { "run": "backtest-2026-08" }
}
```

Selectors are optional. Two kinds:
- `{"type": "json-pointer", "value": "/path/to/field"}` for JSON, RFC 6901.
- `{"type": "text-quote", "exact": "...", "prefix": "...", "suffix": "..."}` for text and HTML.

Send `Idempotency-Key` on retries so a repeated call returns the original receipt rather than
consuming quota twice.

Every capture answers with how much of the month is left, so a caller never meets the ceiling
without warning:

- `x-elucora-monthly-limit` — receipts included this month.
- `x-elucora-monthly-remaining` — receipts left.
- `x-elucora-monthly-reset` — when the allowance refills, as an ISO instant.
- `x-elucora-quota-state` — ok, approaching (80%), critical (95%), or exhausted.

Watch `x-elucora-quota-state` and tell the customer before it reaches exhausted; at that point
captures answer 429 monthly_quota_exceeded until the reset.

Capture the source at the moment your code reads it. Sealing something hours later records what the
page said then, not what your work was based on.

## When it refuses

- 401 authentication_required / invalid_api_key — the key is missing, wrong, or revoked.
- 429 rate_limit_exceeded — too many captures per minute; back off and retry.
- 429 monthly_quota_exceeded — the plan's monthly receipts are used up; it resets, or upgrade.
- 400 invalid_url / unsafe_source — private addresses, credentials in URLs and odd ports are refused.
- 400 selector_not_found — the passage or field was not in what the source returned.
- 502 source_http_error — the source itself failed. This is not an Elucora fault; try again later.

Errors are RFC 9457 problem+json with a stable `code`. Read the code, not the prose.

## Plans

- Free: 500 receipts/month, 20 requests/minute, 1 API key, 1 months source custody, free
- Builder: 5,000 receipts/month, 120 requests/minute, 3 API keys, 12 months source custody, $29/month
- Pro: 25,000 receipts/month, 600 requests/minute, 10 API keys, 37 months source custody, $99/month
- Scale: 100,000 receipts/month, 1200 requests/minute, 25 API keys, 85 months source custody, $249/month

## Verifying without us

A receipt verifies offline against the published keys. There is a short Python verifier at
https://elucora.com/docs that rebuilds the canonical form and re-checks the signature and the evidence hash,
so a receipt saved today still verifies if this service disappears tomorrow.

## Contact

support@elucora.com — one engineer, Bangkok. Answers come from a person, not a rota.