---
title: "POST /api/v1/uploads/sessions"
method: POST
path: "/api/v1/uploads/sessions"
---

# POST /api/v1/uploads/sessions

`POST /api/v1/uploads/sessions`

## Request

- Base URL: `https://falconer.com` (the document declares no server; this is the origin it was published from)
- URL: `https://falconer.com/api/v1/uploads/sessions`
- Auth: none declared

## Headers

- `x-organization-id` string: Required when using OAuth bearer tokens.

## Request body

- CreateUploadSessionRequest
  - `filename` string, required: Filename, including extension
  - `size` integer, required: File size in bytes
  - `mimeType` string: File MIME type
  - `kind` 'auto' | 'image' | 'video' | 'file': Upload kind. Defaults to auto. Files such as PDF, Office, text and code attachments are kind "file".
  - `alt` string: Alt text for images.

## Response `201`

Upload session. PUT the raw file bytes to uploadUrl with the given headers, then complete the session.

- UploadSession
  - `uploadToken` string, required: Opaque token to pass to the complete call after uploading.
  - `uploadUrl` string, required: Short-lived URL to send the raw file bytes to. Never persist it.
  - `method` 'PUT', required
  - `headers` object, required: Headers the upload request must send exactly as given.
  - `expiresAt` string, required: When uploadUrl stops accepting the file (ISO 8601).

## Other responses

- `400`: Bad request

---

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