create_upload · Start a file upload · Container Trade HQ API

Contract

shape: entity
authority: act
evidence: none
subscription: false
permission: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency: keyed
emits: none
MCP tool: none
decision_set: approve, reject
REST: POST https://api.containertradehq.com/v1/cap/create_upload

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org the file is for.
name	name	required	1 to 255 characters The file's name, as people will see it. It is never part of where the file is stored.
size	integer	required	0 to 1125899906842624 The file's exact size in bytes; the link accepts no other. At most 5 GiB (5368709120).
content_type	text	required	1 to 255 characters The file's content type, such as application/pdf; the link accepts no other.
data_class	one_of	optional	one of operational, commercial, financial, personal; default "operational" What kind of fact the file holds, which decides who may read its bytes: operational (the default), commercial, financial or personal.

Response

upload_id · string · The upload's id, for complete_upload.
org_id · string · The org the file is for.
method · string · Always PUT.
upload_url · string · Where to PUT the bytes, with the content-length and content-type headers as declared.
expires_at · string · When the link stops accepting the PUT.
size · integer · The size the link accepts.
content_type · string · The content type the link accepts.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "upload_id": {
      "type": "string",
      "description": "The upload's id, for complete_upload.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org the file is for.",
      "x-data-class": "operational"
    },
    "method": {
      "type": "string",
      "description": "Always PUT.",
      "x-data-class": "operational"
    },
    "upload_url": {
      "type": "string",
      "description": "Where to PUT the bytes, with the content-length and content-type headers as declared.",
      "x-data-class": "operational"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the link stops accepting the PUT.",
      "x-data-class": "operational"
    },
    "size": {
      "type": "integer",
      "description": "The size the link accepts.",
      "x-data-class": "operational"
    },
    "content_type": {
      "type": "string",
      "description": "The content type the link accepts.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "upload_id",
    "org_id",
    "method",
    "upload_url",
    "expires_at",
    "size",
    "content_type"
  ],
  "additionalProperties": false
}

Refusals

file_too_large · 422 · the declared size is above the 5 GiB single-upload ceiling
files_unavailable · 422 · this deployment has no intake or files store configured yet
org_is_a_test_twin · 422 · the org is a test twin; files belong to its live org
retry_key_mismatch · 409 · the Idempotency-Key was already used with other inputs
retry_key_in_flight · 409 · a request with this Idempotency-Key is still running
retry_key_lost · 409 · another request took over this Idempotency-Key first; nothing was created

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF

MobileF

APIF

MCPN

VoiceN

PushN

OneBoxN

OutboundN

MCP: an agent adds a file with add_file and is never given a link (Q9)
Voice: a voice surface has no file to upload
Push: emits nothing
OneBox: a document arrives through the intake's own channels
Outbound: crosses to no counterparty

Events

None emitted.

add_file, claim_party, invite_guest