How Describa works
Describa gives you a personal email address (username@stage.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
- Sign up with your email and password
- Confirm your email via the link we send you (valid for 24 hours)
- Pick a username - this becomes your Describa address (3-30 characters, letters, numbers, dots, underscores and hyphens)
- Set your forwarding address in the dashboard - this is where your documents will be sent
- Send a document to
username@stage.describa.appand 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:
| Tier | Model | Best for | Tokens / page |
|---|---|---|---|
| Value | Haiku 5.5 (Value, ~10 tokens/page) | Fast extraction for clean scans, receipts and everyday files | ~10 |
| Balanced | Sonnet 5.5 (Balanced, ~20 tokens/page) | Sharper dates, issuers and summaries on dense multi-page paperwork | ~20 |
| Best | Opus 5.5 (Best, ~40 tokens/page) | Extended reasoning for handwritten notes, faded scans and complex photos | ~40 |
| Ultra | Fable 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
- 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:
20250401or01-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.comto 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:
| Model | Input | Output |
|---|---|---|
| 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:
- We stop forwarding to your email immediately
- Incoming documents are still received, scanned and held for you
- You can log in and re-enable forwarding at any time to receive waiting documents
- 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@stage.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://stage.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:
| Parameter | Notion/Dropbox | Use case | |
|---|---|---|---|
| (none) | Yes | Yes | Full processing |
?mode=no_email | No | Yes | Sync to services, skip email |
?mode=metadata | No | No | Just 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://stage.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://stage.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_hashrequiredThe SHA-256 of the original file, 64 lowercase hex characters. It is the key for caching and replays.
framesrequired1 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.
titleoptionalText 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.thresholdoptionalHow 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.computeoptionalA list drawn from "rating", "fields", "enrich". Default "rating" and "fields". The rating always runs.
options.target_langoptionalTwo lowercase letters. The language to translate the title into when you ask for enrich. Default en.
| Field | Required | Description |
|---|---|---|
file_hash | Yes | The SHA-256 of the original file, 64 lowercase hex characters. It is the key for caching and replays. |
frames | Yes | 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. |
title | No | 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.threshold | No | 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.compute | No | A list drawn from "rating", "fields", "enrich". Default "rating" and "fields". The rating always runs. |
options.target_lang | No | 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_langor 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
enrichand 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
enrichmentcomes back asnull. - 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 thencaptionandsafetyarenull. With no title and no usable frame,enrichmentisnull. If the moderation check flags illegal content, enrichment is skipped andenrichmentisnull.
Errors
An error response has "ok": false and an error field. Most also carry a message. The rate limit response carries retry_after instead.
invalid_requestA field is missing or out of range (the message names the field), or the body is not valid JSON (the message says so).
unsupported_frameA frame is not a JPEG or PNG. The frame field gives its position, counting from 0.
no_creditsNo tokens remaining. pages_remaining shows the balance.
in_progressThe same file is already being classified. Retry after the number of seconds in the Retry-After header.
payload_too_largeThe request is over 6 MiB.
frame_too_largeA frame is over 1 MiB. The frame field gives its position.
rate_limitedMore than 300 requests in a minute with one key. Wait for retry_after seconds.
classifier_failedThe classifier could not rate the item. Nothing is charged. Retry later.
classifier_unavailableClassification is temporarily unavailable. Retry later.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_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). |
| 400 | unsupported_frame | A frame is not a JPEG or PNG. The frame field gives its position, counting from 0. |
| 402 | no_credits | No tokens remaining. pages_remaining shows the balance. |
| 409 | in_progress | The same file is already being classified. Retry after the number of seconds in the Retry-After header. |
| 413 | payload_too_large | The request is over 6 MiB. |
| 413 | frame_too_large | A frame is over 1 MiB. The frame field gives its position. |
| 429 | rate_limited | More than 300 requests in a minute with one key. Wait for retry_after seconds. |
| 502 | classifier_failed | The classifier could not rate the item. Nothing is charged. Retry later. |
| 503 | classifier_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.
scan.sh- process a single filebatch-scan.sh- process an entire folder
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://stage.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://stage.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://stage.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://stage.describa.app/scan.sh -o scan.sh && chmod +x scan.sh curl -sfL https://stage.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.
| Variable | Default | Description |
|---|---|---|
DESCRIBA_API_KEY | (required) | Your API key |
DESCRIBA_RENAME | false | Rename file to AI-generated title. A taken name gets a number: Title 2.pdf |
DESCRIBA_TAGS | true | Add Finder tags |
DESCRIBA_COMMENT_FILENAME | true | Include the original filename in the Finder comment, so it survives a rename |
DESCRIBA_NOTIFY | false | Show macOS notifications |
DESCRIBA_POLL_INTERVAL | 3 | Seconds between status checks |
DESCRIBA_MAX_POLLS | 60 | Max 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.