---
title: "Create Upload"
method: POST
path: "/api/v1/files/upload-url"
tags: ["Files"]
---

# Create Upload

`POST /api/v1/files/upload-url`

## 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/files/upload-url`
- Auth: API key in header `X-API-Key`

Reserve a pre-signed PUT slot for a forthcoming upload.

Returns the signed URL, the headers the agent must echo on the PUT,
the slot expiry, and a ``next_tool_call`` recipe pointing at
``tag_file`` -- the agent copy-pastes the ``file_id`` to run the
pipeline against the uploaded bytes.

## Request body

- FilesCreateUploadInDTO
  - `filename` string, required
  - `mime_type` string, required
  - `size_bytes` integer, required
  - `sha256` string, nullable

## Response `200`

Successful Response

- FilesUploadInstructionsOutDTO
  - `fileId` string, required
  - `upload` FilesUploadDetailsOutDTO, required
    - `method` 'PUT'
    - `url` string, required
    - `headers` object, required
    - `expiresAt` string, date-time, required
    - `maxSizeBytes` integer, required
  - `nextToolCall` FilesNextToolCallOutDTO, required: The operation-specific MCP follow-up for an uploaded slot.
    - `tool` 'tag_file' | 'extract_document'
    - `arguments` object, 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)