Free forever

Tag, rename, and enrich documents from your agent

Turn any PDF or image into structured metadata, smart filenames, and an enriched copy you can download. Call it via MCP or REST.

1,500 free tags every month — no credit card.

Get Free API Key Try it in browser

What FileTag does

One call, three outputs.

One tool in Gemina's harness for document AI.

Tag

Vendor, date, total, type, document number — extracted as structured fields, not free text.

vendorAcme Corp

date2026-02-15

total7,200 ILS

Rename

Returns six filename patterns. Your agent picks the one that fits your filing convention.

2026-02-15_Acme-Corp_Invoice.pdf+ 5 more patterns

Enrich

Embeds metadata into PDF or EXIF. Download via a short-lived URL.

invoice.pdfmetadata embedded · 15-min URL

Use cases

What you can build with FileTag.

Wherever a document needs structured metadata — agent, pipeline, or product.

Organize files

Your agent files user uploads to consistent folders — no custom parsers per document type.

Enrich RAG

Tag documents on ingestion so you can filter your vector search by vendor, date, or type.

Route documents

Send receipts to accounting, contracts to legal, invoices to AP — by structured tag, not regex.

Tag uploads

Enrich user uploads in your product backend — cheaper than per-document LLM calls.

How it works

Three lines, one tool call, structured JSON.

Your agent calls

# 1. Reserve an upload slot
upload = mcp.call("files_create_upload", filename="invoice.pdf")

# 2. PUT the file to the signed URL
upload_to(upload.url, file_bytes)

# 3. Tag it
result = mcp.call("tag_file", file_id=upload.file_id)
# → metadata, six filename patterns, enriched-file URL

# Then: pull back the enriched copy whenever you need it
enriched = download(result.enriched_file_url)

Or use tag_url if your file already lives at a public URL.

FileTag returns

{
  "document_id": "abc-123",
  "suggested_filename": "2026-02-15_Acme-Corp_Invoice_12345.pdf",
  "metadata": {
    "document_type": "invoice",
    "vendor": "Acme Corp",
    "date": "2026-02-15",
    "amount": 7200,
    "currency": "ILS",
    "document_number": "12345",
    "title": "Invoice",
    "tags": ["vendor", "invoice"]
  },
  "filename_patterns": {
    "date_first": "2026-02-15_Invoice_12345.pdf",
    "type_first": "Invoice_12345_2026-02-15.pdf",
    "vendor_first": "Acme-Corp_Invoice_2026-02-15.pdf",
    "date_vendor": "2026-02-15_Acme-Corp.pdf",
    "vendor_date": "Acme-Corp_2026-02-15.pdf",
    "compact": "Acme-Corp_Invoice.pdf"
  },
  "enriched_file_url": "https://api.gemina.co/files/tmp_abc123.pdf",
  "enriched_file_expires_at": "2026-02-15T12:15:00Z"
}

Full reference: endpoints, response shapes, rate limits, error codes — Read the FileTag docs

Install

Connect FileTag to your stack

Drop the snippet into your client config, paste your API key, restart.

OpenClawPopular

Docs

openclaw mcp set gemina '{"url":"https://api.gemina.co/api/v1/mcp/","transport":"streamable-http","headers":{"X-API-Key":"<paste-your-key-here>"}}'

Hermes-AgentPopular

YAML config for Nous Research's agent. Drop under mcp_servers in ~/.hermes/config.yaml.

Docs

mcp_servers:
  gemina:
    url: "https://api.gemina.co/api/v1/mcp/"
    headers:
      X-API-Key: "<paste-your-key-here>"

Claude Code

One-line CLI registration — recommended for terminal-first workflows.

Docs

claude mcp add --transport http gemina https://api.gemina.co/api/v1/mcp/ \
  --header "X-API-Key: <paste-your-key-here>"

LangChain (Python)

Call the FileTag REST endpoint from any Python/LangChain pipeline.

import requests

def gemina_tag(file_path: str) -> dict:
    """Tag a document via Gemina's FileTag REST API."""
    with open(file_path, "rb") as f:
        response = requests.post(
            "https://api.gemina.co/api/v1/filetag",
            headers={"X-API-Key": "<paste-your-key-here>"},
            files={"file": f},
        )
    response.raise_for_status()
    return response.json()

# Use the returned metadata to enrich your vector store entries.
# Example: attach vendor + date + type to each chunk for RAG filtering.

Claude Desktop

Drop into claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\).

Docs

{
  "mcpServers": {
    "gemina": {
      "url": "https://api.gemina.co/api/v1/mcp/",
      "headers": {
        "X-API-Key": "<paste-your-key-here>"
      }
    }
  }
}

Cursor

Same JSON shape as Claude Desktop. Drop into ~/.cursor/mcp.json.

Docs

{
  "mcpServers": {
    "gemina": {
      "url": "https://api.gemina.co/api/v1/mcp/",
      "headers": {
        "X-API-Key": "<paste-your-key-here>"
      }
    }
  }
}

VS Code

Native MCP support in VS Code. Drop into .vscode/mcp.json per workspace.

Docs

{
  "servers": {
    "gemina": {
      "type": "http",
      "url": "https://api.gemina.co/api/v1/mcp/",
      "headers": {
        "X-API-Key": "<paste-your-key-here>"
      }
    }
  }
}

Codex CLI

OpenAI's coding agent. Append the snippet to ~/.codex/config.toml.

Docs

[mcp_servers.gemina]
url = "https://api.gemina.co/api/v1/mcp/"
http_headers = { "X-API-Key" = "<paste-your-key-here>" }

Windsurf

Codeium's IDE. Drop into ~/.codeium/windsurf/mcp_config.json — note the field is serverUrl, not url.

Docs

{
  "mcpServers": {
    "gemina": {
      "serverUrl": "https://api.gemina.co/api/v1/mcp/",
      "headers": {
        "X-API-Key": "<paste-your-key-here>"
      }
    }
  }
}

MCP Inspector

Anthropic's official protocol explorer — best for first-time integration debugging.

Docs

npx @modelcontextprotocol/inspector

# Then in the Inspector UI:
#   Transport: Streamable HTTP
#   URL:       https://api.gemina.co/api/v1/mcp/
#   Header:    X-API-Key: <paste-your-key-here>

curl

Smoke-test the MCP endpoint from any shell.

curl -X POST https://api.gemina.co/api/v1/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: <paste-your-key-here>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

Full setup details for every platform — Read the FileTag docs

Free forever

1,500 tags every month.

Resets on account anniversary. 1 credit per page. ~10 tags/sec burst.

Need more? Bronze, Silver, and Gold all include larger FileTag allowances plus the full Gemina harness. See paid plans

What you get back

Structured JSON, ready for filenames, routing, and search.

Three uses out of one response — pick the one your code needs, ignore the rest.

{
  "document_id": "abc-123",
  "suggested_filename": "2026-02-15_Acme-Corp_Invoice_12345.pdf",
  "metadata": {
    "document_type": "invoice",
    "vendor": "Acme Corp",
    "date": "2026-02-15",
    "amount": 7200,
    "currency": "ILS",
    "document_number": "12345",
    "title": "Invoice",
    "tags": ["vendor", "invoice"]
  },
  "filename_patterns": {
    "date_first": "2026-02-15_Invoice_12345.pdf",
    "type_first": "Invoice_12345_2026-02-15.pdf",
    "vendor_first": "Acme-Corp_Invoice_2026-02-15.pdf",
    "date_vendor": "2026-02-15_Acme-Corp.pdf",
    "vendor_date": "Acme-Corp_2026-02-15.pdf",
    "compact": "Acme-Corp_Invoice.pdf"
  },
  "enriched_file_url": "https://api.gemina.co/files/tmp_abc123.pdf",
  "enriched_file_expires_at": "2026-02-15T12:15:00Z"
}

Metadata
Vendor, date, type, total. Use for filtering, routing, and RAG metadata enrichment.
Six filename patterns
Your code picks the one that suits your filing system.
Enriched-file download
Short-lived signed URL. The file already has metadata embedded into PDF properties or image EXIF.

Privacy & retention

Your data, on your terms.

7-day deletion

Files are deleted within 7 days of upload (configurable per plan).

No model training

Your documents are never used to train AI models — Gemina's or anyone else's.

GDPR & CCPA compliant

AES-256 at rest, TLS 1.3 in transit. Configurable data residency on paid plans.

FAQ

Common questions

What is MCP?

Model Context Protocol — an open standard for AI agents to call external tools. Claude Desktop, Cursor, OpenClaw, Hermes-Agent and many others support it natively.

Do I need to use MCP, or can I just call the REST API?

Both work. Same endpoints under the hood. MCP is convenient if you're inside an agent client; REST is convenient if you're building from scratch.

I'm building a RAG pipeline / LangChain app — does this fit my stack?

Yes. Call POST /v1/filetag per document during ingestion, attach the metadata to your vector store entries, and filter retrieval at query time. Cheaper and more consistent than per-document LLM calls.

What document types are supported?

PDF, PNG, JPEG, GIF, WebP. Up to 50 MB.

How big can files be?

50 MB. Files larger than 256 KB use a pre-signed upload flow (your MCP client handles this automatically).

What happens when I run out of free credits?

You'll get a clear error. Upgrade to a paid plan for more, or wait until your monthly reset.

Can I use the same API key for both MCP and the REST API?

Yes. One key, both surfaces. The same key also works for Data Extraction and other Gemina REST endpoints — one Gemina account, all surfaces.

Is there a rate limit?

~10 tags/second per API key, on top of the monthly credit cap.

What's coming next?

Indexing across documents and natural-language queries. Sign up now — your existing API key will work for those when they ship.

Ready to plug FileTag into your stack?

Free 1,500 tags every month. No credit card. Built on Gemina's production harness.

Get Free API Key

Docs Pricing Console

Tag, rename, and enrich documents from your agent

One call, three outputs.

Tag

Rename

Enrich

What you can build with FileTag.

Organize files

Enrich RAG

Route documents

Tag uploads

Three lines, one tool call, structured JSON.

Your agent calls

FileTag returns

Connect FileTag to your stack

OpenClawPopular

Hermes-AgentPopular

Claude Code

LangChain (Python)

Claude Desktop

Cursor

VS Code

Codex CLI

Windsurf

MCP Inspector

curl

1,500 tags every month.

Structured JSON, ready for filenames, routing, and search.

Metadata

Six filename patterns

Enriched-file download

Your data, on your terms.

7-day deletion

No model training

GDPR & CCPA compliant

Common questions

Ready to plug FileTag into your stack?