How Describa works

Describa gives you a personal email address (username@describa.app) that you can send documents to. We scan them for inappropriate content, generate a searchable summary using AI and forward everything - the original file plus the summary - to your chosen email address. The file is then deleted from our servers.

  • Quickstart - scan a year of paperwork in an afternoon, from signup to a summarised, renamed file
  • Billing - plans, tokens, running out and auto top-up
  • Notion and Dropbox - connect a folder or database as an input and output
  • Troubleshooting - what every rejection code, status and silent failure means

Getting started

  1. Sign up with your email and password
  2. Confirm your email via the link we send you (valid for 24 hours)
  3. Pick a username - this becomes your Describa address (3-30 characters, letters, numbers, dots, underscores and hyphens)
  4. Set your forwarding address in the dashboard - this is where your documents will be sent
  5. Send a document to username@describa.app and it will arrive in your inbox with a summary

For the full walkthrough, including scanner setup and which settings to turn on first, see the quickstart guide.

Supported files

You can send PDF, JPG, PNG, WebP, GIF, HEIC, AVIF, BMP and ZIP files. Other file types are ignored. The total size of all attachments in a single email must be under 20 MB. HEIC, AVIF and BMP files are automatically converted to JPEG before processing. ZIP archives are extracted and each supported file inside is processed individually.

Uploading from the dashboard

You can also drag and drop files directly onto the dashboard page or click to browse. This works the same as emailing them - files are scanned, summarized and forwarded. You can drop .eml email files too and we will extract the attachments from them.

How summaries work

Every document is checked for inappropriate content, then handed to a summary model to generate:

  • A title - a searchable name like "Jon Doe's Optical Prescription - 4/1/2025"
  • Dates - any creation, issuance or signature dates found in the document
  • Issuer - the person, company or agency that produced the document
  • Summary - a concise 2-4 sentence description of the key details

For images, the AI describes what the image shows. Paid plans use one unified Quality setting in Settings for both PDFs and images, while the free plan runs all PDFs on Gemma 4 26B (free tier) at ~10 tokens per page (adjusted around the nominal rate based on document token usage, e.g. 8 to 12 tokens on a 1-page PDF).

If a document cannot be read directly as a PDF, we retry once on Gemini 3.1 Flash-Lite before giving up.

When you send multiple documents in one email, we generate a collection title for the email subject (e.g. "Personal Tax Returns 2009-2013") using a fixed model.

Quality tiers and models

On a paid plan, your Quality selector in Settings controls both document and image processing across four tiers:

TierModelBest forTokens / page
ValueHaiku 5.5 (Value, ~10 tokens/page)Fast extraction for clean scans, receipts and everyday files~10
BalancedSonnet 5.5 (Balanced, ~20 tokens/page)Sharper dates, issuers and summaries on dense multi-page paperwork~20
BestOpus 5.5 (Best, ~40 tokens/page)Extended reasoning for handwritten notes, faded scans and complex photos~40
UltraFable 5.2 (Ultra, ~80 tokens/page)Maximum-depth analysis for archival, legal and difficult multi-language material~80

Public figures, landmarks and events

Enabling Recognize public figures and events in Settings runs web-entity and landmark detection on image uploads so captions and tags name well-known people, places and events. When enabled on a paid plan, image jobs use +10 tokens per image. PDFs add 0 extra tokens.

Active models by provider

The active model pool spans three providers (Anthropic, OpenAI and Google):

Claude (Anthropic)

  • Haiku 5.5 (Value, ~10 tokens/page) - ~10 tokens/page
  • Sonnet 5.5 (Balanced, ~20 tokens/page) - ~20 tokens/page
  • Opus 5.5 (Best, ~40 tokens/page) - ~40 tokens/page
  • Fable 5.2 (Ultra, ~80 tokens/page) - ~80 tokens/page

OpenAI

  • GPT-6 Luna (fast, cheap) - ~10 tokens/page
  • GPT-6.1 Terra (balanced) - ~20 tokens/page

Google

  • Gemma 4 26B (free tier) (free-plan default) - free
  • 3.1 Flash-Lite (fast, cheap) - ~10 tokens/page

On the free plan, documents run on Gemma 4 26B (free tier) at ~10 tokens per page to keep free-plan inference cost at $0. Upgrading to a paid plan activates your selected quality tier immediately.

We publish measured accuracy and cost per model against a corpus of difficult documents (faded scans, handwriting, multi-column forms and screenshots). See the model benchmarks.

Content moderation always runs on a fixed model regardless of your quality tier or plan, so a user cannot weaken or inflate the cost of their own content check.

Forwarded email format

The forwarded email includes:

  • A metadata section with extracted dates and issuer (when found)
  • The AI-generated summary
  • The original file(s) as attachments
  • A footer with a job ID and unsubscribe link

The email subject is set to the document title (e.g. "Invoice #4821 from Acme Corp - March 2025 [Describa]"). Reply-to is set to your Describa address.

Settings

Free plan restrictions

The free plan gives you 1,000 tokens a month, PDF only. It does not support:

  • Images or other non-PDF files - a free-plan send of a JPG, PNG or similar is forwarded as-is with an upgrade prompt and no summary.
  • Rename attachments, date in filename and inline images - these are Plus-only and stay off on the free plan regardless of what is saved in your settings.
  • Splitting multiple attachments into separate emails - the "max attachments per email" setting has no effect on free.
  • Higher quality tiers and entity search - Balanced, Best, Ultra and public-figure search require a paid plan.

None of this applies once you're on a paid plan. See the billing guide for plans and pricing.

Forwarding options

  • Show original sender name - when on, the "from" name on forwarded emails shows who sent the original email. When off, it shows your Describa address.
  • Rename attachments - when on, files are renamed to the AI-generated title (e.g. Jon Doe's Prescription.pdf). Multiple files are numbered.
  • Date in filename - appends the document's creation date to the filename in your chosen format: 20250401 or 01-Apr-25. Only applies when rename is on.
  • Inline images - when on, image attachments are displayed in the email body below their summary. PDFs are always attached as files.
  • Max attachments per email - if an email has more attachments than this limit, the forwarded email is split into multiple messages. Set to "1 (one email per document)" to always get separate emails. "Don't separate" keeps everything together.

Content moderation

Every document is checked for inappropriate content before summarisation. You can choose how strict this check is:

  • Strict (default) - rejects anything inappropriate in a professional context, including nudity, suggestive content, violence and explicit language
  • Standard - rejects clearly harmful content like pornography, extreme violence, hate speech and illegal material
  • Permissive - only rejects illegal content (CSAM), explicit pornography and extreme gore. Swimwear, artistic nudity and similar content is allowed

All levels always reject illegal content. Content moderation cannot be fully disabled.

Sender rules

You can control who can send documents to your Describa address:

  • Allow/block rules - block specific senders or allow them. Use *@domain.com to match an entire domain. Allow rules override blocks.
  • Allowlist-only mode - when on, only senders with an explicit "allow" rule can send you documents. Everyone else is rejected.
  • Your own email address is always allowed regardless of rules.

Auto-clear

Controls how long job records are kept in your dashboard:

  • Never (default) - keep all records
  • When done - clear immediately after successful processing. Failed jobs are kept for 1 hour.
  • 1 day / 7 days / 30 days / 1 year - clear after the specified period

Cleared records have personal information removed but we retain anonymized commercial data (token usage, model, timestamps) for billing purposes.

Jobs table

The "Recent jobs" table shows your last 10 processed documents with:

  • Job - a short identifier for the job
  • Via - whether the document arrived by email or was dropped on the page
  • Status - received, processing, forwarded, rejected, failed, backlogged, spam or blocked. See the status glossary for what each one means.
  • Model - which AI model was used, shown as a short code (H5.5, S5.5, O5.5, F5.2, 6L, 6.1T, G4, G3.1L)
  • Pages - document pages counted in the file
  • Tokens - plan tokens charged for that job
  • Cost - estimated AI inference cost for that job

Failed jobs have a retry button. All jobs can be deleted individually with the × button.

Estimated costs

The dashboard shows estimated AI costs based on token usage. Approximate pricing per million tokens:

ModelInputOutput
Claude
Haiku 5.5$0.10$0.50
Sonnet 5.5$2.00$10.00
Opus 5.5$4.00$20.00
Fable 5.2$8.00$40.00
OpenAI
GPT-6 Luna$0.10$0.50
GPT-6.1 Terra$1.00$5.00
Gemma
Gemma 4 26B (default)$0.00$0.00
Gemini
3.1 Flash-Lite$0.25$1.50

This table is generated from the same model registry the app uses to route jobs, so a new model shows up here automatically.

Each document typically uses a few thousand tokens for moderation (always Gemini 3.1 Flash-Lite, regardless of your chosen provider) plus a few thousand for summarisation (your chosen model or Gemma 4 26B on the free plan).

Limits

  • Maximum attachment size per email: 20 MB
  • Supported file types: PDF, JPG, PNG, WebP, GIF, HEIC, AVIF, BMP, ZIP
  • Username: 3-30 characters
  • Password: 8+ characters
  • Login attempts: 10 per hour
  • Signup attempts: 5 per hour

Security and privacy

  • Documents are deleted from our servers after forwarding
  • We do not store the contents of your documents long-term
  • Sender cooldowns automatically rate-limit abusive senders (by email and IP address)
  • Passwords are hashed with PBKDF2 (100,000 iterations) and a server-side pepper; each hash stores its own iteration count, so the work factor can rise without invalidating old passwords
  • Sessions expire after 7 days

Unsubscribing

Every forwarded email includes an unsubscribe link. If you unsubscribe:

  1. We stop forwarding to your email immediately
  2. Incoming documents are still received, scanned and held for you
  3. You can log in and re-enable forwarding at any time to receive waiting documents
  4. If you don't re-enable, we send a reminder after your grace period (default 14 days), a final warning 7 days later and suspend service 7 days after that

Vouchers and promotional codes

Enter your voucher or promotional code in the "Promotional code" section on the Billing page and click Apply. VIP credit codes add reserve tokens to your account, while plan vouchers activate a Plus plan for a set number of months. Each voucher carries a redeem-by expiry date and a redemption cap (once per account). Once you redeem a VIP token voucher, the granted tokens stay in your balance until spent.

If you are on a complimentary plan voucher and want to switch to a paid plan, remove the plan voucher on Billing first. This returns your account to the Free plan immediately so you can subscribe to any plan; any reserve token credits you redeemed stay in your balance. Removing a plan voucher cannot be undone - if you remove it by accident, email hello@describa.app and we will sort it out.

For plans, token allowances and how auto top-up works, see the billing guide.

API

You can upload files and retrieve results programmatically using the API. Create an API key from the dashboard under "API keys" - each key is shown once on creation and cannot be retrieved later.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer idk_your-key-here

Endpoints

POST /api/upload - upload one or more files for processing. Returns job IDs for polling.

curl -X POST https://describa.app/api/upload \
  -H "Authorization: Bearer idk_..." \
  -F "files=@invoice.pdf"

Response:

{ "ok": true, "count": 1, "job_ids": ["abc-123-..."] }

Upload modes - control where results are sent using the mode query parameter:

ParameterEmailNotion/DropboxUse case
(none)YesYesFull processing
?mode=no_emailNoYesSync to services, skip email
?mode=metadataNoNoJust get the data back

GET /api/jobs/:id - poll for job status and results. The done field is true when processing is complete.

curl https://describa.app/api/jobs/abc-123-... \
  -H "Authorization: Bearer idk_..."

Response (when done):

{
  "ok": true,
  "id": "abc-123-...",
  "status": "forwarded",
  "done": true,
  "title": "Invoice #4821 from Acme Corp - March 2025",
  "summary": "Monthly invoice for consulting services...",
  "tags": ["invoice", "consulting"],
  "doc_type": "invoice",
  "dates": "March 2025",
  "issuer": "Acme Corp",
  "model_used": "claude-sonnet-5-5",
  "page_count": 2,
  "pages_charged": 40,
  "tokens_charged": 40,
  "file_size": 184320
}

GET /api/credits - check your remaining token balance before uploading.

{ "ok": true, "plan": "free", "total": 870, "tokens_remaining": 870 }

If you upload with no tokens remaining, the API returns 402 with "error": "no_credits".

Classify media

POST /api/classify - rate an image or a video from sample frames. You send up to 4 frames and the API returns a work-safety rating: R, PG-15, U or clean. It can also return a category, a tone, a safety level and a language. On request it adds tags, a caption and a translation of the title.

curl -X POST https://describa.app/api/classify \
  -H "Authorization: Bearer idk_your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_hash": "<64 lowercase hex characters, the SHA-256 of the file>",
    "title": "Beach day with the dog",
    "frames": ["<base64 JPEG>", "<base64 PNG>"],
    "options": {
      "threshold": 0.75,
      "compute": ["rating", "fields", "enrich"],
      "target_lang": "en"
    }
  }'

Request fields

file_hashrequired

The SHA-256 of the original file, 64 lowercase hex characters. It is the key for caching and replays.

framesrequired

1 to 4 base64 strings, each a JPEG or PNG image of at most 1 MiB once decoded. The whole request may be at most 6 MiB.

titleoptional

Text that goes with the file, at most 500 characters. It helps the category, tone and language answers. A longer title is rejected, not cut.

options.thresholdoptional

How sure the rating must be before a tier counts. One of 0.50, 0.55, 0.60, 0.65, 0.70, 0.75, 0.80, 0.85, 0.90, 0.95. Default 0.75. A lower value flags more files. You can change it later and the same stored scores are re-tiered.

options.computeoptional

A list drawn from "rating", "fields", "enrich". Default "rating" and "fields". The rating always runs.

options.target_langoptional

Two lowercase letters. The language to translate the title into when you ask for enrich. Default en.

Response

The response carries file_hash, rating_version (currently wr1-2026-11), cached and usage. rating holds the tier, the three scores, the threshold you used and the answers behind the tier. fields appears when you ask for it and enrichment (tags, caption, language, translation and a safety label) appears when you ask for enrich. The rating version changes whenever the questions or the tier rules change, so store it with the result.

{
  "ok": true,
  "file_hash": "...",
  "rating_version": "wr1-2026-11",
  "cached": false,
  "rating": {
    "tier": "PG-15",
    "scores": { "R": 0.2, "PG-15": 0.81, "U": 0.93 },
    "flash_r": 0.12,
    "threshold": 0.75,
    "decided_by": "clef",
    "passes": ["clef-flash", "clef"],
    "hits": [ ... ]
  },
  "fields": { "category": { "value": "travel", "confidence": 0.9 }, ... },
  "enrichment": { "tags": ["beach", "dog"], "caption": "...", "translation": null, ... },
  "usage": { "frames": 2, "pages_charged": 20, "pages_remaining": 860, ... }
}

Cost

A classification that runs the rating models costs 10 tokens and running enrichment costs 10 tokens (20 tokens when both run together). The other cost rules:

  • Repeating a request you already made is free, except for enrich: it runs again when the stored enrichment is older than 24 hours, was made for another target_lang or never produced anything.
  • A repeat that only re-runs enrich is charged only when an enrichment is produced. Enrichment that produces nothing adds no cost.
  • A result another account already produced is free unless you also ask for enrich and it has to be run for you.
  • A request that fails costs nothing.
  • After 3 enrich runs that produce nothing for a file, no more are tried for that file and rating version, and enrichment comes back as null.
  • Classification works on every plan, including Free. This differs from email and upload, where Free is PDF only.

Caching

cached: true means you sent the same file_hash before and the rating version is unchanged. cached: "shared" means another account already classified the same file with the same frames and the same title. That tells you someone else classified it. Nothing else about them is shared. A repeat that only adds enrichment to a stored rating also reports cached: true and charges 10 tokens. Read usage.pages_charged for the cost of a request.

What we keep

  • Frames are never stored. They are used for the request and dropped.
  • The numeric scores are kept so a file can be re-tiered at another threshold.
  • Tags, caption and translation are replayed for up to 24 hours to a repeat request. A daily job clears them after that.
  • The title is kept only as a keyed fingerprint, used to match shared results. It cannot be turned back into the title without our secret key.
  • For enrich, the first frame goes to the enrichment model only when the frames are the ones that were rated, both rating passes score the item well below R and a moderation check passes. Otherwise enrichment uses the title alone, and then caption and safety are null. With no title and no usable frame, enrichment is null. If the moderation check flags illegal content, enrichment is skipped and enrichment is null.

Errors

An error response has "ok": false and an error field. Most also carry a message. The rate limit response carries retry_after instead.

400invalid_request

A field is missing or out of range (the message names the field), or the body is not valid JSON (the message says so).

400unsupported_frame

A frame is not a JPEG or PNG. The frame field gives its position, counting from 0.

402no_credits

No tokens remaining. pages_remaining shows the balance.

409in_progress

The same file is already being classified. Retry after the number of seconds in the Retry-After header.

413payload_too_large

The request is over 6 MiB.

413frame_too_large

A frame is over 1 MiB. The frame field gives its position.

429rate_limited

More than 300 requests in a minute with one key. Wait for retry_after seconds.

502classifier_failed

The classifier could not rate the item. Nothing is charged. Retry later.

503classifier_unavailable

Classification is temporarily unavailable. Retry later.

Shell scripts (macOS)

We provide two shell scripts for processing files locally. Both write the AI summary into the file's Finder comment (visible in Get Info), add Finder tags and stamp a com.indecs.processed extended attribute with a timestamp so files aren't processed twice.

Both require jq (brew install jq) and optionally tag (brew install tag) for Finder tags.

Single file (scan.sh)

Upload one file, poll for results, write metadata. Piped straight from curl:

DESCRIBA_API_KEY="idk_your-key-here" bash <(curl -sfL --connect-timeout 5 https://describa.app/scan.sh) /path/to/file.pdf

Or download it first and read it before running - a reasonable thing to do before piping any remote script into bash:

curl -sfL https://describa.app/scan.sh -o scan.sh && chmod +x scan.sh
DESCRIBA_API_KEY="idk_your-key-here" ./scan.sh /path/to/file.pdf

DESCRIBA_API_KEY on the command line lands in your shell history and, if used inline in a Hazel rule, in Hazel's own plain-text config. If that's a problem for your setup, keep the key in a ~/.describa file and source it from a small wrapper script instead.

Hazel integration

To automatically process files dropped into a folder, create a Hazel rule with action "Run shell script" and paste:

DESCRIBA_API_KEY="idk_your-key-here" bash <(curl -sfL --connect-timeout 5 https://describa.app/scan.sh) "$1"

Batch processing (batch-scan.sh)

Process every supported file in a folder. Skips files that already have Describa metadata, shows a progress bar with ETA and resumes where it left off if interrupted:

# Download both scripts
curl -sfL https://describa.app/scan.sh -o scan.sh && chmod +x scan.sh
curl -sfL https://describa.app/batch-scan.sh -o batch-scan.sh && chmod +x batch-scan.sh

# Process a folder
DESCRIBA_API_KEY="idk_your-key-here" ./batch-scan.sh ~/Documents/scans

# Re-process everything (including already-tagged files)
DESCRIBA_API_KEY="idk_your-key-here" ./batch-scan.sh --force ~/Documents/scans

Errors are logged to batch-scan-errors.log in the target folder. A .batch-scan-state file tracks progress so you can Ctrl-C and resume later.

Configuration

Both scripts accept these environment variables. The older INDECS_* names still work.

VariableDefaultDescription
DESCRIBA_API_KEY(required)Your API key
DESCRIBA_RENAMEfalseRename file to AI-generated title. A taken name gets a number: Title 2.pdf
DESCRIBA_TAGStrueAdd Finder tags
DESCRIBA_COMMENT_FILENAMEtrueInclude the original filename in the Finder comment, so it survives a rename
DESCRIBA_NOTIFYfalseShow macOS notifications
DESCRIBA_POLL_INTERVAL3Seconds between status checks
DESCRIBA_MAX_POLLS60Max poll attempts before giving up

batch-scan.sh also accepts SCAN_SH to point to a custom location for scan.sh.

Diagnostics

Force-reject mode is a testing feature that rejects all incoming documents with code R0. This triggers the sender cooldown system so you can test how blocking and escalation work without sending inappropriate content.

Closing your account

You can permanently delete your account from the bottom of the dashboard. This removes all your data and cannot be undone.