Create file

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

file_name*string

content*string

document_type*DocumentType

Document type code from the documents map in the uploads config file. Valid values are defined at deploy time (not a fixed API enum). Examples include avatar, bylaws, license, articles_of_association, tariffs, customer_agreement, and other. The API returns 400 with allowed_types when the code is not configured.

customer_id?|

From UploadCore, and it is read on this route: CreateStandaloneFileUtilCtx requires update permission on that customer (ensureCustomerAccessCtx, refusing with 403) and links the upload to it in the same transaction. On POST /v1/uploads/customer/{customer_id} the path segment overwrites whatever the body carries.

file_extension?string

From UploadCore, and ACCEPTED BUT IGNORED: prepareCreateUpload overwrites it with the media type validateFileContent detects from the decoded content (http.DetectContentType), so what comes back in Upload.file_extension is a media type such as image/png, not the value sent here and not a filename suffix.

approval_needed?number

approval_made?number

signature_needed?number

signature_made?number

active?boolean

metadata?

Response Body

`application/json`

curl -X POST "https://example.com/v1/uploads" \  -H "Content-Type: application/json" \  -d '{    "file_name": "customer_agreement.pdf",    "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9MZW5ndGggND4+",    "document_type": "customer_agreement",    "approval_needed": 1,    "approval_made": 0,    "signature_needed": 1,    "signature_made": 0,    "active": true,    "metadata": {      "department": "legal"    }  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "file_name": "string",
  "document_type": "bylaws",
  "approval_status": "pending",
  "approval_needed": 0.1,
  "approval_made": 0.1,
  "signature_status": "pending",
  "signature_needed": 0.1,
  "signature_made": 0.1,
  "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  "content_length": 0,
  "file_extension": "string",
  "active": true,
  "metadata": {},
  "created_at": "2019-08-24T14:15:22Z",
  "modified_at": "2019-08-24T14:15:22Z",
  "modified_by": "e8d4374d-93a1-4e98-a6c6-fdcf00c5059f",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4"
}

{
  "status": 400,
  "code": "uploads.invalid_file_extension",
  "message": "Invalid file extension"
}

{
  "status": 401,
  "message": "Unauthorized",
  "code": "common.unauthorized",
  "class": "business"
}

{
  "status": 403,
  "message": "No access to the record",
  "code": "common.rbac_no_rec_access",
  "class": "business"
}

{
  "status": 429,
  "message": "Rate limit for 203.0.113.7 to /v1/uploads exceeded.",
  "code": "rate_limits_m.exceeded",
  "class": "temporary",
  "retryable": true
}

{
  "status": 500,
  "message": "Internal server error",
  "code": "common.server_error",
  "class": "business"
}

{
  "overall_status": "unhealthy",
  "message": "Service is shutting down",
  "timestamp": "2026-08-27T15:04:05Z"
}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

429application/json

500application/json

503application/json

Example invalidFileExtension

Example invalidDocumentType

Example invalidUploadInput

Example fileTooLarge

rbac.CanCallAPIv0 denied the endpoint grant — the helper's default code

The tenant's licence does not cover the uploads module

The handler's own record-level check — the common case

The per-user or per-IP limit for this endpoint

The same refusal from common/rbac — the code is a raw English string, not a key

Graceful shutdown — LifecycleMiddleware, root router, not the envelope

ensureCacheAvailable could not reach the auth cache — the envelope

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`