Docs Getting started

Getting started

UCFP — Universal Content Fingerprinting — turns text, images, and audio into compact, comparable digests. This page gets you from zero to a working request in under five minutes.

1. Pick a path

Path Use when
Hosted demo You want to poke at it from the browser. No signup. Per-IP rate limited.
Hosted SaaS You want an API key, dashboard, usage metering, and quotas.
Self-hosted Rust binary You want full control of storage and you trust your own infra.

Hosted demo is the green pill on the landing page. Below covers the SaaS and self-hosted paths.

2. Get an API key (hosted)

  1. Sign up at /signup with email + password.
  2. From the dashboard, Keys → New key. Copy the plaintext token — it is shown once.
  3. Tokens have the prefix ucfp_ followed by 32 random bytes (base64url).

Defaults per key: 600 requests / minute, 50 000 / day. Bump from the dashboard.

3. Your first fingerprint

curl -sS https://ucfp.dev/api/fingerprint \
  -H 'Authorization: Bearer ucfp_…' \
  -H 'Content-Type: text/plain' \
  --data-binary 'The quick brown fox jumps over the lazy dog.'

Response:

{
  "tenant_id": 17,
  "record_id": "01HZX2K8M9P0Q1R2S3T4U5V6W7",
  "modality": "text",
  "algorithm": "txtfp-minhash-h128-v1",
  "format_version": 1,
  "config_hash": "0x9c1ab40f5fe2c7d3",
  "fingerprint_bytes": 1024,
  "has_embedding": false
}

The record_id is a ULID generated by the SvelteKit proxy. Persist it if you need to query the record later.

4. The /api/fingerprint contract

POST /api/fingerprint is a thin proxy in front of the Rust server. It selects a modality from Content-Type:

Content-Type Modality Default algorithm
text/* (or no body type) text minhash-h128
image/* image multi
audio/* audio wang
multipart/form-data from the modality field per modality

You can override the algorithm with the ?algorithm= query parameter. See the per-modality references for the full list.

5. Modality routes (direct upstream)

If you want full control of every parameter, hit the typed routes:

  • POST /v1/ingest/text/{tenant}/{record}?algorithm=…
  • POST /v1/ingest/image/{tenant}/{record}?algorithm=…
  • POST /v1/ingest/audio/{tenant}/{record}?algorithm=…
  • POST /v1/ingest/audio/{tenant}/{record}/watermark
  • POST /v1/ingest/audio/{tenant}/{record}/stream
  • POST /v1/ingest/text/{tenant}/{record}/stream
  • POST /v1/ingest/text/{tenant}/{record}/preprocess/{html|markdown|pdf}

The hosted plane forwards these for you and rewrites the bearer to the service token. If you self-host the Rust binary you call them directly.

6. Self-host

cargo install ucfp --features full
UCFP_TOKEN=$(openssl rand -base64 32) UCFP_BIND=0.0.0.0:8080 ucfp serve

Single-tenant. All algorithms compiled in (--features full). See Authentication for multi-tenant mode.

7. Where next