---
title: "Reserve Upload"
method: POST
path: "/api/v1/files/reserve"
tags: ["files"]
---

# Reserve Upload

`POST /api/v1/files/reserve`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/files/reserve`
- Auth: none declared

Reserve quota and return a presigned PUT URL for the upload.

The client computes the sha256 ahead of time so the server can dedup
against the active set on this workspace. Repeated calls with the
same sha256 from the same workspace return 409; when the existing file
is in the same context as the request and is ``uploaded``, the 409 body
carries it as a top-level ``existing_file`` (``FileObjectOut``) so the
SDK can use it instead of uploading again (#1693). An earlier upload
that has not completed (``reserved``) is not handed out, and a
duplicate in another context names no file (#1136).

## Headers

- `authorization` string, nullable

## Request body

- FileReserveRequest: Body for ``POST /api/v1/files/reserve``.
  - `workspace_id` string, uuid, required
  - `context_id` string, uuid, nullable: Optional owning context (Issue #1136). When set, the caller must have write access to it and the file inherits that context's ACL for all later read/write/list access. Omit for a workspace-scoped file (legacy behaviour: any workspace viewer can download it).
  - `filename` string, required
  - `content_type` string, required
  - `size_bytes` integer, required
  - `sha256` string, required: Hex sha256 of the bytes the client will PUT. Accepts upper- or lower-case; the service canonicalizes to lowercase before any storage / dedup / signing use.

## Response `201`

Successful Response

- FileReserveResponse
  - `file_id` unknown, required
  - `upload_url` unknown, required
  - `expires_at` unknown, required

## Other responses

- `409`: The workspace already holds an active file with this sha256 (`RES-002`). When that file is in the same context as the request (both unbound counts as the same) and its upload has completed (`status` `uploaded`), the body also carries it as a top-level `existing_file` object; otherwise it is omitted.
- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)