Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt

Use this file to discover all available pages before exploring further.

When you protect content on Truthlocks, AI automatically analyzes your file to generate metadata — including a suggested title, description, category, and tags. This enriches your protection records and makes them easier to search, share, and verify.

​
How it works

When you upload a file on the Protect page, Truthlocks sends the file name, type, size, and a preview (for text-based files) or EXIF data (for images) to an AI model. The file itself stays in your browser — only metadata is sent for analysis.
1

File selected

You select or drag a file onto the Protect page.
2

Metadata extracted

Truthlocks reads basic file properties (name, MIME type, size) and, where applicable, extracts EXIF data from images or a text preview from code and document files.
3

AI analysis

The extracted metadata is sent to the AI model, which returns a structured response with category, content type, description, suggested title, tags, and more.
4

Review and edit

AI-generated fields appear as suggestions. You can edit any field before confirming your protection.
AI metadata extraction is automatic and runs in the background as soon as you select a file. You always have the final say — edit or override any suggestion before protecting.

​
Supported categories

The AI classifies your content into one of the following categories based on file type and content analysis:
CategoryFile types
PhotographyJPEG, PNG, WebP, TIFF, RAW formats
Digital artPSD, AI, SVG, Procreate, HEIC
Source codeJS, TS, Python, Go, Rust, Java, C/C++, and 30+ other languages
DocumentPDF, DOCX, TXT, Markdown, LaTeX
MusicMP3, WAV, FLAC, AAC, MIDI
VideoMP4, MOV, AVI, WebM, MKV
DesignFigma, Sketch, XD files
DataCSV, JSON, XML, SQL, Parquet

​
Generated metadata fields

The AI produces the following fields for each file:
FieldDescription
categoryContent category (see table above)
content_typeSpecific content type within the category (e.g., “landscape photography”)
suggested_titleA human-readable title based on file name and content
descriptionA short description of what the file contains
tagsRelevant keywords for search and discovery
languageProgramming language (for source code files)
frameworkDetected framework or library (for source code files)
license_hintDetected or suggested license (if identifiable)
subject_matterThe primary subject or topic of the content

​
Proof summaries

Every protection certificate includes an AI-generated summary that describes what was protected and when. The summary appears on the public proof page below the certificate details and is designed for sharing and link previews. Proof summaries are generated automatically when anyone views a proof page. You do not need to configure or trigger them.
DetailDescription
ContentA 2–3 sentence explanation of the protection — what was protected, its category, and the protection date
FallbackIf AI is unavailable, a template-based summary is generated instead so the proof page always displays a readable description
IndicatorAI-generated summaries show a small sparkle icon and an “AI-generated summary” label
CachingSummaries are cached per proof page and revalidated every five minutes. Subsequent visitors see the cached version, reducing latency and AI usage

​
How caching works

When the first visitor loads a proof page, the platform generates an AI summary and caches it. For the next five minutes, all visitors see the cached result. After five minutes, the next request triggers a fresh AI generation and refreshes the cache. If the AI model is unavailable at generation time, the cached result is a template-based fallback instead. The cache still applies — the fallback is served for up to five minutes before the platform retries AI generation.
Proof summaries are cached and revalidate every five minutes. The first visitor to a proof page triggers the summary generation, and subsequent visitors see the cached version until it refreshes. You do not need to manage caching yourself.

​
Fallback summaries

When the AI model is unavailable, the proof page displays a deterministic template summary instead. Template summaries include:
  • The content category and protection date.
  • A note that the cryptographic proof is anchored to the Truthlocks transparency log.
  • A provenance indicator — if the content was uploaded by a person (rather than via API), the summary includes a note confirming human submission.
Template summaries do not show the sparkle icon, so you can always tell whether a summary was AI-generated.
Proof summaries use only the metadata you provided when protecting your content — title, description, category, and date. Your original file is never accessed.

​
Similarity detection

Before minting a protection, Truthlocks checks whether a similar file hash already exists. This prevents duplicate protections and alerts you if the content was previously registered — either by you or by another user. If a match is found, you see a warning with details about the existing protection before proceeding. Each match includes:
  • Similarity score — how closely the content matches an existing protection.
  • Owner — the username of the person who protected the original.
  • Date — when the original protection was created.
  • Exact match flag — whether the content hash is identical to an existing record.

​
Using AI metadata with the API

When calling the mint endpoint, you can include AI-extracted fields to enrich your protection record: 
curl -X POST https://api.truthlocks.com/v1/consumer/mint \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content_hash": "e3b0c44298fc1c149afbf4c8...",
    "title": "Sunset at Big Sur",
    "description": "Landscape photograph taken at Pfeiffer Beach",
    "file_name": "sunset-big-sur.jpg",
    "file_size": 4521984,
    "content_type": "landscape photography",
    "category": "photography",
    "tags": ["landscape", "sunset", "california", "beach"],
    "visibility": "public"
  }'
When using the API, you can skip AI extraction and provide your own metadata directly. The AI extraction feature is available on the web interface and runs automatically.

​
Privacy

AI metadata extraction follows the same privacy model as the rest of Truthlocks:
  • Your file never leaves your browser. Only the file name, MIME type, size, and a small preview or EXIF data are sent for analysis.
  • No file content is stored by the AI service. Metadata is generated in real time and returned to your browser.
  • You control what ships. Review and edit all AI-generated fields before confirming your protection.

​
Next steps

Content protection

Full guide to protecting your content with cryptographic attestations.

Consumer portal

Manage protections, credentials, and settings from your dashboard.

Embeddable badges

Add verification badges to your website or README.

Public portfolio

Showcase verified work on a public profile page.