---
title: "POST /files"
method: POST
path: "/files"
tags: ["files"]
---

# POST /files

`POST /files`

Upload a short-lived file (auto-deleted ~24h after upload).

## Response `200`

File uploaded

- TempFile — Stateless temporary file metadata. Stored under a dedicated `tmp/` prefix in object storage and removed by storage lifecycle policy ~24h after upload. No database row is created; clients must persist the URL/name themselves if they need to track it.
  - `content_length` integer, required — Size of the uploaded payload in bytes.
  - `content_type` string, required — MIME type as reported by the client.
  - `created_at` string, date-time, required — Time the file was uploaded.
  - `expires_at` string, date-time, required — Advisory expiration (~24h after upload). Object deletion is performed by storage lifecycle and may lag this timestamp by up to a day. Treat HTTP 404 from `url` as "expired".
  - `name` string, required — Original filename (sanitized — slashes / control characters replaced).
  - `url` string, required — Public URL where the file can be downloaded until it expires.

## Other responses

- `413` — File exceeds 100MB limit
- `429` — Per-user rate limit exceeded

## Changes

- **2026-04-25** `78e336468650` — 1 info
  - endpoint added
- **2026-03-16** `eb2c08128881` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/timbal-ai/apis/timbal-platform-api/changes/files/post.md)

---

[API](https://skmtc.dev/timbal-ai/apis/timbal-platform-api.md) · [All operations](https://skmtc.dev/timbal-ai/apis/timbal-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/timbal-ai/timbal-platform-api/revisions/bee7dcae732e/schema)