---
title: "Initiate a direct billing-file upload"
method: POST
path: "/v1/org/{org_id}/uploads/initiate"
tags: ["Uploads"]
---

# Initiate a direct billing-file upload

`POST /v1/org/{org_id}/uploads/initiate`

## Request

- Base URL: `https://api.archera.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.archera.ai/v1/org/{org_id}/uploads/initiate`
- Auth: none declared

Creates a PENDING billing upload and returns a short-lived, one-write S3 PUT URL. PUT raw file bytes to upload_url using upload_method and every upload_headers value; do not use multipart form data. A 412 response means the bytes already reached storage, so POST to /uploads/{upload_id}/complete instead of retrying the PUT or initiating another upload. This is intended for clients that can access a local file but cannot pass file bytes through the API call, such as remote MCP clients.

## Request body

- CreatePublicUploadInitiation
  - `file_name` string, required
  - `content_type` string, required
  - `size_bytes` integer, required
  - `description` string, nullable: Optional partner-supplied context for the uploaded billing file

## Response `201`

Created

- PublicUploadInitiation
  - `upload_id` string, uuid, required
  - `upload_url` string, required
  - `upload_method` string, required
  - `upload_headers` object, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `409`: Conflict
- `422`: Unprocessable Content
- `500`: Internal server error
- `default`: Default error response

## Changes

- **2026-10-13** `8b1de9447803`: 31 info
  - added the optional property `status` to the response with the `400` status
  - added the optional property `status` to the response with the `401` status
  - added the optional property `status` to the response with the `403` status
  - added the optional property `status` to the response with the `404` status
  - …27 more
- **2026-08-19** `f4d407b9f0f9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/archera/apis/archera-ai-api/changes/v1/org/:org_id/uploads/initiate/post.md)

---

[API](https://skmtc.dev/archera/apis/archera-ai-api.md) - [All operations](https://skmtc.dev/archera/apis/archera-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/archera/apis/archera-ai-api/revisions/8b1de9447803?raw)