---
title: "Tag Document"
method: POST
path: "/api/v1/filetag"
tags: ["FileTag"]
---

# Tag Document

`POST /api/v1/filetag`

## Request

- Base URL: `https://api.gemina.co` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gemina.co/api/v1/filetag`
- Auth: API key in header `X-API-Key`

Extract filing metadata (title, type, date, tags, ...) from a single
PDF or image and return a suggested filename plus a set of filename
patterns.

Requires API-key auth (``X-API-Key`` header). Subject to the per-API-key
burst rate limit and -- for free-tier users -- the monthly FileTag
credit allowance.

## Response `200`

Successful Response

- FileTagResultOutDTO: Final FileTagService result -- returned by the REST router and the MCP tool.
  - `documentId` string, uuid, required
  - `documentExtractionId` string, uuid, required
  - `suggestedFilename` string, required: Recommended filename for the enriched file -- one of the six ``filename_patterns``, picked as the safest default for general use. Pair this with ``enriched_file_url`` when saving the downloaded file.
  - `metadata` FileTagMetadataOutDTO, required: Flat, document-type-agnostic metadata extracted by FileTag. Mirrors :class:`app.components.documents.processors.filetag.models.FileTagFieldsModel` but surfaces plain scalar values (unwrapped from the ``{value, coordinates}`` storage shape) so callers don't need to understand the extraction wire format.
    - `title` string, nullable
    - `description` string, nullable
    - `documentType` string, nullable
    - `date` string, nullable
    - `authors` string, nullable
    - `tags` string[], nullable
    - `comments` string, nullable
    - `copyright` string, nullable
    - `documentNumber` string, nullable
  - `filenamePatterns` FileTagFilenamePatternsOutDTO, required: Suggested filename patterns produced by ``generate_filename_patterns``. Six variants are surfaced so the caller can pick the layout that best matches their downstream filing system. Long forms (``*_full``) preserve the full extracted metadata; short forms truncate to a sensible length.
    - `dateFirst` string, required
    - `typeFirst` string, required
    - `vendorFirst` string, required
    - `dateFirstFull` string, required
    - `typeFirstFull` string, required
    - `vendorFirstFull` string, required
  - `enrichedFileUrl` string, required: Short-lived signed URL to the input file with the extracted metadata embedded directly into the document properties (XMP for PDFs, EXIF/XMP for images). This is the canonical enriched output of the tool -- the file the user actually wants. Agents should download it within ``enriched_file_expires_in_seconds`` and save it under ``suggested_filename`` rather than embedding metadata client-side. Skip the download only if the user explicitly asked for the metadata payload alone.
  - `enrichedFileExpiresAt` string, date-time, required: Absolute UTC timestamp when ``enriched_file_url`` stops resolving.
  - `enrichedFileExpiresInSeconds` integer, required: Seconds until ``enriched_file_url`` expires, captured at response time. Easier for agents to reason about than the absolute timestamp.
  - `nextAction` NextActionOutDTO, required: Structured follow-up recipe for an agent capability (not an MCP tool). Sister pattern to :class:`app.components.files.dtos.FilesNextToolCallOutDTO`: that one names a specific MCP tool by literal name (``tag_file``); this one names a generic *capability* (``http_get_and_save``) the agent maps to whatever local mechanism it has -- ``WebFetch``, ``curl`` via shell, a filesystem write tool, etc. We can't bind a specific tool name here because the right one varies per agent host (Claude / GPT / OpenClaw / raw HTTP client all differ). Keeping the field structured (not just a description) defeats the "scratchpad volatility" failure mode where an agent forgets to act on the enriched-file URL after the metadata response satisfies the immediate ask.
    - `action` 'http_get_and_save'
    - `url` string, required
    - `saveAs` string, required
    - `expiresInSeconds` integer, required
    - `instruction` string

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/gemina/apis/gemina-api.md) · [All operations](https://skmtc.dev/gemina/apis/gemina-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gemina/apis/gemina-api/revisions/152fd3f6f6ec?raw)