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 enrichedFileUrl 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["suggestedFilename"])
print(result["metadata"])

# Pull the enriched copy back from the signed URL
enriched = requests.get(result["enrichedFileUrl"]).content
with open(result["suggestedFilename"], "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.

{
  "documentId": "abc-123",
  "documentExtractionId": "def-456",
  "suggestedFilename": "2026-02-15_Acme-Corp_Invoice_12345.pdf",
  "metadata": {
    "documentType": "invoice",
    "documentNumber": "12345",
    "date": "2026-02-15",
    "title": "Invoice",
    "authors": "Acme Corp",
    "description": "Invoice 12345 from Acme Corp",
    "tags": ["vendor", "invoice"],
    "comments": null,
    "copyright": null
  },
  "filenamePatterns": {
    "dateFirst": "2026-02-15_Invoice_12345.pdf",
    "typeFirst": "Invoice_12345_2026-02-15.pdf",
    "vendorFirst": "Acme-Corp_Invoice_2026-02-15.pdf",
    "dateFirstFull": "2026-02-15_Acme-Corp_Invoice_12345.pdf",
    "typeFirstFull": "Invoice_Acme-Corp_12345_2026-02-15.pdf",
    "vendorFirstFull": "Acme-Corp_Invoice_12345_2026-02-15.pdf"
  },
  "enrichedFileUrl": "https://api.gemina.co/files/tmp_abc123.pdf",
  "enrichedFileExpiresAt": "2026-02-15T12:15:00Z",
  "enrichedFileExpiresInSeconds": 900
}

Errors

A failure does not use the shape above. It returns the standard Gemina error envelope — status is failed, data is null, and the detail is one entry in errors. Branch on error_code, not on the message:

{
  "status": "failed",
  "meta": null,
  "data": null,
  "errors": [
    {
      "error_code": "UNAUTHORIZED_ERROR",
      "description": "API Key Unauthorized: Missing API Key"
    }
  ],
  "createdAt": null,
  "createdAtTimestamp": null,
  "servedAt": "2026-08-11T17:07:54.482226",
  "servedAtTimestamp": 1786468074.482232
}

401 UNAUTHORIZED_ERROR — No API key was sent.
403 ACCESS_DENIED_ERROR — The key is unknown, revoked or expired. Re-sending it will not help.
415 UNSUPPORTED_MEDIA_TYPE_ERROR — The format is not one FileTag accepts.
429 FILETAG_RATE_LIMIT_EXCEEDED — Burst limit. Wait the Retry-After header and retry.
429 FILETAG_QUOTA_EXHAUSTED — The monthly free-tier allowance is spent. Retry-After counts down to the reset; upgrading lifts it sooner.

PDFs over 10 pages are rejected with 422 and DOCUMENT_MAX_PAGES_EXCEEDED_ERROR. Format, size and page checks all run before any processing, so a rejected file costs nothing against your quota.

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, Claude Code, VS Code, Cline, OpenClaw, Hermes-Agent, Codex, Windsurf, MCP Inspector, curl), see the Install section on the FileTag page →

Install snippets, runnable examples, and the agent-ready llms-install.md guide live in the gemina-mcp repository on GitHub

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
HEIC, AVIF — renamed, not embedded
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