# Gemina FileTag API

Tag, rename, and enrich documents via REST or MCP. Free up to 1,500 tags/month — no credit card.

- HTML version: https://www.gemina.co/docs/filetag
- Product page: https://www.gemina.co/filetag
- MCP manifest: https://www.gemina.co/.well-known/mcp.json
- Gemina API docs (markdown): https://www.gemina.co/docs.md

## 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 URL:** `https://api.gemina.co`
- **Authentication:** `X-API-Key: your-api-key`
- **Free tier:** 1,500 tags/month, no credit card required
- **Get an API key:** https://console.gemina.co/registration/create-account

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

```bash
# 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 "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

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

```json
{
  "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, Cline, Codex, Windsurf, OpenClaw, Hermes-Agent, MCP Inspector, and others.

- **MCP endpoint:** `https://api.gemina.co/api/v1/mcp/`
- **Transport:** Streamable HTTP
- **Auth header:** `X-API-Key` or `Authorization: Bearer`

### Tools

- `files_create_upload` — Reserve a pre-signed upload slot. Returns `file_id` and a PUT URL to upload the document bytes to.
- `tag_file` — Tag a previously-uploaded file by `file_id`. Returns metadata, six suggested filename patterns, and a short-lived enriched-file URL.
- `tag_url` — Fetch and tag a publicly-accessible HTTPS URL directly. Returns metadata, six suggested filename patterns, and a short-lived enriched-file URL.

### Three-line example (Python agent calling MCP)

```python
# 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

# Pull the enriched copy back when you need it
enriched = download(result.enriched_file_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 product page: https://www.gemina.co/filetag#install

Install snippets, runnable examples, and the agent-ready `llms-install.md` guide also live in the **gemina-mcp** repository on GitHub: https://github.com/tommyil/gemina-mcp

## Reference

### MCP Tools

- `files_create_upload`
- `tag_file`
- `tag_url`

### REST Endpoints

- `POST /api/v1/filetag`
- `POST /api/v1/files/uploads`

### Supported file types

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

### Rate limits

- ~10 tags/second burst per API key
- 1,500 tags/month on the free tier
- Larger allowances on paid plans (see https://www.gemina.co/pricing)

### Privacy & retention

- Files deleted within 7 days of upload (configurable per plan)
- Documents are never used to train AI models
- AES-256 at rest, TLS 1.3 in transit
- Configurable data residency on paid plans

## Get started

- Free API key: https://console.gemina.co/registration/create-account
- Pricing: https://www.gemina.co/pricing
- Contact: info@gemina.co