add_file · Add a file · 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: intake.received
MCP tool: add_file
decision_set: approve, reject
REST: POST https://api.containertradehq.com/v1/cap/add_file

Through MCP this call returns an approval request first; see Approvals.

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.
content_type	text	required	1 to 255 characters The file's content type, such as application/pdf.
content	text	required	0 to 240000 characters The file's bytes, standard base64.
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 file's intake id.
org_id · string · The org the file is for.
state · string · received: it is waiting to be filed.
size · integer · Its size in bytes.
content_type · string · Its content type, as given.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "upload_id": {
      "type": "string",
      "description": "The file's intake id.",
      "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"
    },
    "state": {
      "type": "string",
      "enum": [
        "received"
      ],
      "description": "received: it is waiting to be filed.",
      "x-data-class": "operational"
    },
    "size": {
      "type": "integer",
      "description": "Its size in bytes.",
      "x-data-class": "operational"
    },
    "content_type": {
      "type": "string",
      "description": "Its content type, as given.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "upload_id",
    "org_id",
    "state",
    "size",
    "content_type"
  ],
  "additionalProperties": false
}

Refusals

file_too_large_for_add_file · 422 · the file is larger than one call carries; a person uploads it with create_upload
content_not_decodable · 422 · content is not standard base64
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

DesktopN

MobileN

APIF

MCPF*

VoiceN

PushF

OneBoxN

OutboundN

Desktop: a person uploads with create_upload
Mobile: a person uploads with create_upload
MCP: approval required
Voice: a voice surface has no file to add
OneBox: a document arrives through the intake's own channels
Outbound: crosses to no counterparty

Events

intake.received planned_webhook

claim_party, create_upload, invite_guest