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 "file=@invoice.pdf"

# 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.

FileTag on the Gemina MCP server

The three FileTag tools are the free tier of the Gemina MCP server. Endpoint, authentication (OAuth 2.1 or API key), the full tool list and error codes are in the MCP reference →

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 Code, claude.ai, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Grok, ChatGPT, n8n, Copilot Studio, Zapier, Windsurf, Cline, OpenClaw, Hermes-Agent, MCP Inspector, curl), see the Connect section on the MCP 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