Contract
- shape
- collection
- 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
- list_files
- REST
- POST https://api.containertradehq.com/v1/cap/list_files
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 whose files they are. |
| kind | one_of | optional | one of doc, img, att, msg, gen Only files of this kind. |
| limit | integer | optional | 1 to 200; default 50 The page size. |
| after | text | optional | 26 to 26 characters The previous page's next_after. |
Paginated: next next_after · page_max 200 · walk_max 10000 · ceiling declared
Response
items· object[]next_after· stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"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"
}
},
"required": [
"file_id",
"org_id",
"kind",
"channel",
"data_class",
"original_name",
"content_type",
"size",
"sha256",
"flags",
"created_at"
],
"additionalProperties": false
},
"maxItems": 200
},
"next_after": {
"type": [
"string",
"null"
],
"description": "Pass as `after` for the next page; null on the last one."
}
},
"required": [
"items",
"next_after"
],
"additionalProperties": false
} Refusals
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 lists no files
- Push: emits nothing
- OneBox: no document originates a file listing
- Outbound: crosses to no counterparty
Events
None emitted.