get_file · Get a file · Container Trade HQ API

Contract

shape: entity
authority: read
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: safe
emits: none
MCP tool: get_file
REST: POST https://api.containertradehq.com/v1/cap/get_file

Idempotency: a read: calling again changes nothing

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org the file is filed in.
file_id	text	required	26 to 26 characters The file's id.

Response

file_id · string · The file's id.
org_id · string · The org it is filed in.
kind · string · doc, img, att (an attachment), msg (an email message) or gen (a document Trade HQ made).
channel · string · How it arrived.
data_class · string · What kind of fact it holds, which decides who reads its name and bytes.
original_name · stringnull · Its name as it arrived; the mask where the caller's data policy masks its class, null where it denies it.
content_type · string · Its content type, as sniffed when it was filed.
size · integer · Its size in bytes.
sha256 · string · The SHA-256 of its bytes, hex.
flags · string[] · large (1 GiB or more) and macro (it carries macros).
created_at · string · When it was filed.
content · stringnull · Its bytes, standard base64, when they are answered.
content_withheld · stringnull · Why no bytes are answered: too_large (more than 180,000 bytes), masked or denied (the caller's data policy), or missing (the store holds no object for it). Null when they are.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "file_id": {
      "type": "string",
      "description": "The file's 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 it is filed in.",
      "x-data-class": "operational"
    },
    "kind": {
      "type": "string",
      "enum": [
        "doc",
        "img",
        "att",
        "msg",
        "gen"
      ],
      "description": "doc, img, att (an attachment), msg (an email message) or gen (a document Trade HQ made).",
      "x-data-class": "operational"
    },
    "channel": {
      "type": "string",
      "enum": [
        "web",
        "api",
        "agent",
        "depot_mail",
        "inventory_mail",
        "messaging",
        "generated"
      ],
      "description": "How it arrived.",
      "x-data-class": "operational"
    },
    "data_class": {
      "type": "string",
      "enum": [
        "operational",
        "commercial",
        "financial",
        "personal"
      ],
      "description": "What kind of fact it holds, which decides who reads its name and bytes.",
      "x-data-class": "operational"
    },
    "original_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Its name as it arrived; the mask where the caller's data policy masks its class, null where it denies it.",
      "x-data-class": "operational"
    },
    "content_type": {
      "type": "string",
      "description": "Its content type, as sniffed when it was filed.",
      "x-data-class": "operational"
    },
    "size": {
      "type": "integer",
      "description": "Its size in bytes.",
      "x-data-class": "operational"
    },
    "sha256": {
      "type": "string",
      "description": "The SHA-256 of its bytes, hex.",
      "x-data-class": "operational"
    },
    "flags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "large (1 GiB or more) and macro (it carries macros).",
      "x-data-class": "operational"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it was filed.",
      "x-data-class": "operational"
    },
    "content": {
      "type": [
        "string",
        "null"
      ],
      "description": "Its bytes, standard base64, when they are answered.",
      "x-data-class": "operational"
    },
    "content_withheld": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "too_large",
        "masked",
        "denied",
        "missing",
        null
      ],
      "description": "Why no bytes are answered: too_large (more than 180,000 bytes), masked or denied (the caller's data policy), or missing (the store holds no object for it). Null when they are.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "file_id",
    "org_id",
    "kind",
    "channel",
    "data_class",
    "original_name",
    "content_type",
    "size",
    "sha256",
    "flags",
    "created_at",
    "content",
    "content_withheld"
  ],
  "additionalProperties": false
}

Refusals

file_tenancy_mismatch · 422 · the stored object does not carry this file's org and id; nothing was answered and the tenancy alarm was raised
files_unavailable · 422 · this deployment has no intake or files store configured yet

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

Surfaces

DesktopF

MobileF

APIF

MCPF

VoiceN

PushN

OneBoxN

OutboundN

Voice: a voice surface reads no file
Push: emits nothing
OneBox: no document originates a file read
Outbound: crosses to no counterparty

Events

None emitted.

delete_file