FileTag API Documentation

Overview

FileTag exposes the same product through two channels: a REST API (use it from any backend) and an MCP server (use it from any agent client). The same API key works on both.

Base URLhttps://api.gemina.co

AuthenticationX-API-Key: your-api-key

Free tier1,500 tags/month

REST API

Call POST /api/v1/filetag with a multipart form upload. You get back metadata, filename suggestions, and a short-lived URL where you can download the enriched copy.

Example: curl

# 1. Tag the file (returns enriched_file_url in the JSON response)
curl -X POST https://api.gemina.co/api/v1/filetag \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]"

# 2. Download the enriched copy from the URL the API returned
curl -OJ "https://api.gemina.co/files/tmp_abc123.pdf"

Example: Python

import requests

with open("invoice.pdf", "rb") as f:
    response = requests.post(
        "https://api.gemina.co/api/v1/filetag",
        headers={"X-API-Key": "YOUR_API_KEY"},
        files={"file": f},
    )

result = response.json()
print(result["suggested_filename"])
print(result["metadata"])

# Pull the enriched copy back from the signed URL
enriched = requests.get(result["enriched_file_url"]).content
with open(result["suggested_filename"], "wb") as f:
    f.write(enriched)

Response shape

Every successful call returns the same JSON envelope: metadata, six suggested filename patterns, and a short-lived URL where you can download the enriched copy.

{
  "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"
}

MCP Integration

Gemina's MCP server speaks Streamable HTTP. Mount it as a tool source in any compatible client — Claude Desktop, Cursor, VS Code, Codex, Windsurf, and others.

MCP endpointhttps://api.gemina.co/api/v1/mcp/

TransportStreamable HTTP

Auth headerX-API-Key or Authorization: Bearer

Tools

files_create_upload — reserve a pre-signed upload slot, returns file_id and a PUT URL.
tag_file — tag a previously-uploaded file by file_id.
tag_url — fetch and tag a publicly-accessible HTTPS URL.

For client-specific setup snippets (Claude Desktop, Cursor, OpenClaw, Hermes-Agent, VS Code, Codex, Windsurf, MCP Inspector, curl), see the Install section on the FileTag page →

Reference

MCP Tools

files_create_upload
tag_file
tag_url

REST Endpoints

POST /api/v1/filetag
POST /api/v1/files/uploads

Supported Types

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

Rate Limits

~10 tags/second burst
1,500 tags/month free tier
Larger allowances on paid plans

Ready to plug FileTag into your stack?

Grab a free API key and start tagging in minutes. No credit card, 1,500 tags/month included.

Get Free API Key Back to FileTag