{ "$comment": "GENERATED by python3 -m tools.devplatform from services/front-door/src/capabilities.json (TRA-302). Never edited.", "input_revision": "fa5200f22a1157a430469d906dfd492defc024c655730ab5cad32f524e5658d7", "catalogue": "Every capability whose mcp cell is F or F*, exactly generate::mcp_tools() unfiltered (gen-capabilities --mcp-tools). This is the catalogue, not what any one caller sees: tools/list answers each principal a projection of it, by the scopes its token carries and the org it acts in (TRA-401).", "endpoint": "https://api.containertradehq.com/mcp", "auth": { "kind": "oauth", "description": "An MCP client signs in with OAuth through Clerk and is resolved to a Trade HQ user. An API key is never an MCP credential, and OpenAPI's apiKey scheme does not apply here." }, "approval": "A tool whose _meta carries containertradehq.com/approval: bound (an F* cell) acts only on a second call carrying the confirmation a person approved in Container Trade HQ.", "tools": [ { "name": "add_file", "title": "Add a file", "description": "Adds one small file to the org from its bytes (base64, up to 180,000 bytes decoded), to be filed as a person's upload is. For an agent acting for a customer; a person uploads with create_upload.", "inputSchema": { "type": "object", "properties": { "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." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "x-normalized": "trimmed, each run of whitespace one space", "description": "The file's name, as people will see it. It is never part of where the file is stored." }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The file's content type, such as application/pdf." }, "content": { "type": "string", "minLength": 0, "maxLength": 240000, "description": "The file's bytes, standard base64." }, "data_class": { "type": "string", "enum": [ "operational", "commercial", "financial", "personal" ], "default": "operational", "description": "What kind of fact the file holds, which decides who may read its bytes: operational (the default), commercial, financial or personal." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "name", "content_type", "content" ], "additionalProperties": false }, "outputSchema": { "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 }, "annotations": { "title": "Add a file", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "advance_flag_wave", "title": "Advance a flag to its next wave", "description": "Moves one registered feature flag one wave up in PostHog: to staff if PostHog does not have it or it is off, then to the beta lists, then 10%, 25% and 50% of customer orgs, then everyone. Name the wave you saw; if the flag has moved since, nothing changes. Refused for a flag on for everyone (removing it is a build) or one with a rule made in PostHog. Each move is recorded with who made it. Send an Idempotency-Key header. Staff only.", "inputSchema": { "type": "object", "properties": { "flag_key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The flag's key, as the registry has it." }, "from": { "type": "string", "enum": [ "absent", "off", "staff", "beta", "orgs_10", "orgs_25", "orgs_50", "everyone", "custom" ], "description": "The wave you saw the flag on (list_flags' wave). If PostHog has it anywhere else, nothing changes." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "flag_key", "from" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "action_id": { "type": "string", "description": "This move's audit row.", "x-data-class": "operational" }, "flag_key": { "type": "string", "description": "The flag moved.", "x-data-class": "operational" }, "action": { "type": "string", "enum": [ "advance", "roll_back", "set_lists" ], "description": "advance, roll_back, or set_lists (TRA-1461: the beta lists chosen).", "x-data-class": "operational" }, "from_wave": { "type": "string", "description": "The wave PostHog had it on.", "x-data-class": "operational" }, "to_wave": { "type": "string", "description": "The wave it is on now.", "x-data-class": "operational" }, "acted_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who moved it: the staff member or agent, never PostHog's key.", "x-data-class": "operational" }, "acted_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" }, "posthog_url": { "type": [ "string", "null" ], "description": "The flag in PostHog; null on a replay.", "x-data-class": "operational" } }, "required": [ "action_id", "flag_key", "action", "from_wave", "to_wave", "acted_by", "acted_at", "posthog_url" ], "additionalProperties": false }, "annotations": { "title": "Advance a flag to its next wave", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "announce_deprecated_versions", "title": "Announce deprecated API versions", "description": "Trade HQ staff, after a release that supersedes an API version: emails the admins of every org holding an active API key pinned to a superseded version that it is deprecated, the day it stops being served, and how to re-pin the key. Name the release just deployed, the current version; every superseded version not announced yet is announced, each once. The dates are the release's, never the caller's.", "inputSchema": { "type": "object", "properties": { "release": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The release just deployed: the current API version, YYYY-MM-DD." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "release" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "superseded": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date" }, "description": "Every version this build serves that a later one superseded, oldest first, each YYYY-MM-DD.", "x-data-class": "operational" }, "announced": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date" }, "description": "The versions this call announced, each YYYY-MM-DD; empty when every one already was.", "x-data-class": "operational" } }, "required": [ "superseded", "announced" ], "additionalProperties": false }, "annotations": { "title": "Announce deprecated API versions", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "anonymize_user", "title": "Anonymize a user", "description": "Permanently anonymizes a user; it cannot be undone. Their records are kept and now show the tombstone \"Deleted user #n\" in place of their name; their email addresses, profile details and sessions are removed, their Clerk user is deleted, and they are deactivated. Calling it again changes nothing. An org admin cannot anonymize anyone (they deactivate); an account owner can anonymize only a user whose every org is in an account they own; staff can anonymize anyone but themselves.", "inputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The user to anonymize." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "user_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The user.", "x-data-class": "operational" }, "tombstone": { "type": "string", "description": "What their records now show: \"Deleted user #n\".", "x-data-class": "operational" }, "tombstone_no": { "type": "integer", "description": "n.", "x-data-class": "operational" }, "orgs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id" }, "description": "The orgs the user belongs to, whose admins the event reaches.", "x-data-class": "operational" } }, "required": [ "user_id", "tombstone", "tombstone_no", "orgs" ], "additionalProperties": false }, "annotations": { "title": "Anonymize a user", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "approve_grant", "title": "Decide a staff access request", "description": "An admin of the org approves or rejects a Trade HQ staff member's request for access to it. Approving makes the access active now, for the hours asked or for `hours` when given (the card's Edit duration), and it ends on its own when they pass; reject refuses it. Either resolves the request's decision card. A decided request answers the same decision again and refuses another. A staff member who is in the org through a grant can never decide one.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the request is to." }, "grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The request, as list_org_grants or the decision card names it." }, "decision": { "type": "string", "enum": [ "approve", "reject" ], "description": "approve or reject." }, "hours": { "type": "integer", "minimum": 1, "maximum": 720, "description": "For an approval: how many hours to approve, when not the hours asked (an edit)." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "grant_id", "decision" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The grant'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 customer org it is a grant to.", "x-data-class": "operational" }, "org_name": { "type": [ "string", "null" ], "description": "That org's name.", "x-data-class": "operational" }, "grantee_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The staff member it lets in.", "x-data-class": "operational" }, "grantee_name": { "type": [ "string", "null" ], "description": "Their name, or their address when they have none.", "x-data-class": "operational" }, "grantee_email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their address.", "x-data-class": "personal" }, "level": { "type": "string", "enum": [ "read", "act" ], "description": "read: what the Read-only template carries. act: what the Admin template carries.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "request", "break_glass" ], "description": "request: asked of the org's admins. break_glass: entered at once by Sage or Sonja, the admins told.", "x-data-class": "operational" }, "reason": { "type": "string", "description": "Why, in the requester's words.", "x-data-class": "operational" }, "requested_hours": { "type": "integer", "description": "How long it was asked for.", "x-data-class": "operational" }, "requested_at": { "type": "string", "format": "date-time", "description": "When it was asked for.", "x-data-class": "operational" }, "exception_id": { "type": [ "string", "null" ], "description": "The decision card the org's admins decide a request on.", "x-data-class": "operational" }, "decision": { "type": [ "string", "null" ], "enum": [ "approved", "rejected", null ], "description": "What the admin decided; null while it waits.", "x-data-class": "operational" }, "decided_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who decided it.", "x-data-class": "operational" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When.", "x-data-class": "operational" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it became active.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops being active.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked, if it was.", "x-data-class": "operational" }, "revoked_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who revoked it.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "active", "rejected", "revoked", "expired" ], "description": "pending, active, rejected, revoked or expired, as of now.", "x-data-class": "operational" }, "notified": { "type": "integer", "description": "How many of the org's admins a break-glass notice was written to.", "x-data-class": "operational" } }, "required": [ "grant_id", "org_id", "org_name", "grantee_user_id", "grantee_name", "grantee_email", "level", "kind", "reason", "requested_hours", "requested_at", "exception_id", "decision", "decided_by", "decided_at", "approved_at", "expires_at", "revoked_at", "revoked_by", "status", "notified" ], "additionalProperties": false }, "annotations": { "title": "Decide a staff access request", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "break_glass_access", "title": "Break glass into a customer org", "description": "Sage or Sonja enters a customer org at once, without asking, at a level (act unless said) for a few hours (four unless said, at most twenty-four). Every admin of the org is mailed a notice in the same call, and sees the access in their Members table, where they can revoke it. For emergencies only: everyone else asks with request_staff_grant.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The customer org to enter." }, "level": { "type": "string", "enum": [ "read", "act" ], "default": "act", "description": "act (the default) or read." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why, in a sentence the org's admins will read in the notice." }, "hours": { "type": "integer", "minimum": 1, "maximum": 24, "default": 4, "description": "How long, in hours: four unless said, at most twenty-four." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "reason" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The grant'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 customer org it is a grant to.", "x-data-class": "operational" }, "org_name": { "type": [ "string", "null" ], "description": "That org's name.", "x-data-class": "operational" }, "grantee_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The staff member it lets in.", "x-data-class": "operational" }, "grantee_name": { "type": [ "string", "null" ], "description": "Their name, or their address when they have none.", "x-data-class": "operational" }, "grantee_email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their address.", "x-data-class": "personal" }, "level": { "type": "string", "enum": [ "read", "act" ], "description": "read: what the Read-only template carries. act: what the Admin template carries.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "request", "break_glass" ], "description": "request: asked of the org's admins. break_glass: entered at once by Sage or Sonja, the admins told.", "x-data-class": "operational" }, "reason": { "type": "string", "description": "Why, in the requester's words.", "x-data-class": "operational" }, "requested_hours": { "type": "integer", "description": "How long it was asked for.", "x-data-class": "operational" }, "requested_at": { "type": "string", "format": "date-time", "description": "When it was asked for.", "x-data-class": "operational" }, "exception_id": { "type": [ "string", "null" ], "description": "The decision card the org's admins decide a request on.", "x-data-class": "operational" }, "decision": { "type": [ "string", "null" ], "enum": [ "approved", "rejected", null ], "description": "What the admin decided; null while it waits.", "x-data-class": "operational" }, "decided_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who decided it.", "x-data-class": "operational" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When.", "x-data-class": "operational" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it became active.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops being active.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked, if it was.", "x-data-class": "operational" }, "revoked_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who revoked it.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "active", "rejected", "revoked", "expired" ], "description": "pending, active, rejected, revoked or expired, as of now.", "x-data-class": "operational" }, "notified": { "type": "integer", "description": "How many of the org's admins a break-glass notice was written to.", "x-data-class": "operational" } }, "required": [ "grant_id", "org_id", "org_name", "grantee_user_id", "grantee_name", "grantee_email", "level", "kind", "reason", "requested_hours", "requested_at", "exception_id", "decision", "decided_by", "decided_at", "approved_at", "expires_at", "revoked_at", "revoked_by", "status", "notified" ], "additionalProperties": false }, "annotations": { "title": "Break glass into a customer org", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "cancel_org_deletion", "title": "Cancel an org's deletion", "description": "Stops an org's deletion countdown and returns the org to the state it was in when the deletion was scheduled: live, or suspended. Calling it on an org with no deletion scheduled changes nothing. A test twin, an org the repository declares and a purged org are refused.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose deletion to cancel." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "active", "suspended" ], "description": "The state the org is in now.", "x-data-class": "operational" }, "purge_after": { "type": [ "string", "null" ], "format": "date-time", "description": "Always null: no deletion is scheduled.", "x-data-class": "operational" } }, "required": [ "org_id", "state", "purge_after" ], "additionalProperties": false }, "annotations": { "title": "Cancel an org's deletion", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "check_ip_allowlist", "title": "Check my address against an org's IP allowlist", "description": "Answers the address this request came from, as the org's IP allowlist reads it, whether the allowlist allows it and which range does, the allowlist's mode and who it applies to, and whether enforce mode is available on this deployment.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose IP allowlist to check this request's address against." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "address": { "type": [ "string", "null" ], "description": "This request's client address, IPv4-mapped IPv6 read as IPv4; null when none could be read.", "x-data-class": "operational" }, "via": { "type": "string", "enum": [ "cloudflare", "edge" ], "description": "cloudflare: Cloudflare's CF-Connecting-IP, from Cloudflare with the origin-auth header. edge: the address the request reached front-door from.", "x-data-class": "operational" }, "in_list": { "type": "boolean", "description": "Whether a range of the allowlist covers the address.", "x-data-class": "operational" }, "entry": { "type": [ "object", "null" ], "description": "The range that covers the address, {cidr, label}; null when none does.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "off", "monitor", "enforce" ], "description": "The allowlist's mode.", "x-data-class": "operational" }, "applies_to": { "type": "string", "enum": [ "members", "api_keys", "both" ], "description": "Who the allowlist checks.", "x-data-class": "operational" }, "enforce_available": { "type": "boolean", "description": "Whether enforce mode can be set on this deployment: front-door's ingress self-check.", "x-data-class": "operational" }, "ingress": { "type": "object", "description": "The self-check's parts: ingress_authenticated, origin_auth_configured, generated_domain (unknown, absent, refuses or serves) and cloudflare_seen.", "x-data-class": "operational" } }, "required": [ "org_id", "address", "via", "in_list", "entry", "mode", "applies_to", "enforce_available", "ingress" ], "additionalProperties": false }, "annotations": { "title": "Check my address against an org's IP allowlist", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "claim_depot", "title": "Claim a depot's BFC", "description": "Claims a depot's BIC Facility Code (BFC) in the depot registry for the org that runs the yard, and sets it on the org's depot unit. A BFC not in the registry is added, named as given or after the unit. A unit carries one BFC and a BFC is on one unit of an org. A BFC another org has already claimed is not claimed: the call answers 202 and raises a staff exception, and staff decide. An org admin, or an admin of the unit or a unit above it, may claim. The same claim again changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that runs the yard." }, "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The org's depot unit the BFC is set on." }, "bfc": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}[A-Z0-9]{4}$", "format": "bic-facility-code", "description": "The depot's BIC Facility Code." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The depot's name, used only when the BFC is not in the registry yet. Absent, the unit's name." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "unit_id", "bfc" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The claiming org.", "x-data-class": "operational" }, "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The depot unit.", "x-data-class": "operational" }, "bfc": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}[A-Z0-9]{4}$", "format": "bic-facility-code", "description": "The BFC.", "x-data-class": "operational" }, "claimed": { "type": "boolean", "description": "True when the org holds the BFC and the unit carries it; false when another org holds it and a staff exception was raised.", "x-data-class": "operational" }, "exception_id": { "type": [ "string", "null" ], "description": "The staff exception a conflicting claim raised; null when the claim landed.", "x-data-class": "operational" } }, "required": [ "org_id", "unit_id", "bfc", "claimed", "exception_id" ], "additionalProperties": false }, "annotations": { "title": "Claim a depot's BFC", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "claim_party", "title": "Claim an org's party", "description": "Claims a party in the party directory as an org's own, which joins the org to the trade graph: the documents that seat that party are then the org's to read as a counterparty. Name the party by party_id and by name. For a party in the directory the name must be its name; a party that is not there yet is added under that id and name, unless the directory holds the name under another id, which is refused with that id. An org claims one party. A party another org has already claimed is not claimed: the call answers 202 and raises a staff exception, and staff decide. The same claim again changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that claims the party." }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The party to claim: one from search_party_directory, or a new party's id." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "x-normalized": "trimmed, each run of whitespace one space", "description": "The party's name: for a party in the directory, its name there (without regard to case or spacing); for a new party, the name it is added under. Trimmed, with each run of whitespace one space." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "party_id", "name" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The claiming org.", "x-data-class": "operational" }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The party.", "x-data-class": "operational" }, "name": { "type": "string", "description": "The party's name in the directory.", "x-data-class": "operational" }, "claimed": { "type": "boolean", "description": "True when the org now claims the party; false when another org holds it and a staff exception was raised.", "x-data-class": "operational" }, "exception_id": { "type": [ "string", "null" ], "description": "The staff exception a conflicting claim raised; null when the claim landed.", "x-data-class": "operational" } }, "required": [ "org_id", "party_id", "name", "claimed", "exception_id" ], "additionalProperties": false }, "annotations": { "title": "Claim an org's party", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "clone_role_template", "title": "Clone a role template", "description": "Makes the org's own copy of a role template, shipped or one of the org's clones, under a new title, adding the permissions in `grant` and removing those in `revoke`. The copy can carry only permissions your own role in the org carries. Shipped templates never change. Send an Idempotency-Key header: a retry with the same key and inputs returns the same copy and creates nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the copy belongs to." }, "source": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The template to copy: a shipped id such as read_only, or one of the org's clone ids." }, "title": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The copy's name, unique within the org." }, "description": { "type": "string", "minLength": 1, "maxLength": 400, "description": "What the copy is for. Defaults to the source's description." }, "grant": { "type": "array", "items": { "type": "string", "enum": [ "org.admin", "org.member", "org.guest", "role.read", "role.manage", "api_key.read" ] }, "uniqueItems": true, "description": "Permissions to add to the source's." }, "revoke": { "type": "array", "items": { "type": "string", "enum": [ "org.admin", "org.member", "org.guest", "role.read", "role.manage", "api_key.read" ] }, "uniqueItems": true, "description": "Permissions to remove from the source's." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "source", "title" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "role_id": { "type": "string", "description": "The copy'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 belongs to.", "x-data-class": "operational" }, "title": { "type": "string", "description": "Its name.", "x-data-class": "operational" }, "cloned_from": { "type": "string", "description": "The source template.", "x-data-class": "operational" }, "modules": { "type": "array", "items": { "type": "string" }, "description": "The module tags, the source's.", "x-data-class": "operational" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "The permissions the copy carries.", "x-data-class": "operational" }, "clerk_role": { "type": "string", "description": "The Clerk built-in role its members hold: org:admin when the copy carries org.admin, else org:member (TRA-963).", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who made it.", "x-data-class": "operational" } }, "required": [ "role_id", "org_id", "title", "cloned_from", "modules", "permissions", "clerk_role", "created_by" ], "additionalProperties": false }, "annotations": { "title": "Clone a role template", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "close_access_review", "title": "Close an access review", "description": "Closes an access review once every item is decided, and writes its evidence document: who decided what, and when. A review with an item left to decide is refused, with how many. Closing one already closed changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the review is of." }, "review_id": { "type": "string", "minLength": 1, "maxLength": 14, "description": "The review to close." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "review_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "review_id": { "type": "string", "description": "The review'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 whose access it reviews.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What it is called.", "x-data-class": "operational" }, "covers": { "type": "array", "items": { "type": "string" }, "description": "What it covers, of members, guests, service_accounts, api_keys and staff_grants, in that order.", "x-data-class": "operational" }, "due_at": { "type": "string", "format": "date-time", "description": "When it is due: the end (UTC) of its due date.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "open", "overdue", "closed" ], "description": "open; overdue, an open review past due; or closed.", "x-data-class": "operational" }, "total": { "type": "integer", "minimum": 0, "description": "How many items it asks about.", "x-data-class": "operational" }, "decided": { "type": "integer", "minimum": 0, "description": "How many of them are decided.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who started it.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was started.", "x-data-class": "operational" }, "closed_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who closed it.", "x-data-class": "operational" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was closed.", "x-data-class": "operational" }, "evidence_document_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The evidence document closing it wrote: who decided what, and when.", "x-data-class": "operational" }, "items": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "item_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The item's id.", "x-data-class": "operational" }, "review_id": { "type": "string", "description": "The review it belongs to.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "member", "guest", "service_account", "api_key", "staff_grant" ], "description": "member, guest, service_account, api_key or staff_grant.", "x-data-class": "operational" }, "subject_id": { "type": "string", "description": "Whose access: a user id, a service account id, a key id or a staff grant's id.", "x-data-class": "operational" }, "subject_label": { "anyOf": [ { "type": "string" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "What a reviewer reads for it: an email, or a service account's or key's name.", "x-data-class": "personal" }, "role": { "type": [ "string", "null" ], "description": "The access it held when the review began: a role template, a key's service account, or a staff grant's level.", "x-data-class": "operational" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was last seen acting before the review began, where known.", "x-data-class": "operational" }, "decision": { "type": [ "string", "null" ], "enum": [ "keep", "change_role", "revoke", null ], "description": "keep, change_role or revoke; null until decided.", "x-data-class": "operational" }, "new_role_template_id": { "type": [ "string", "null" ], "description": "The role template a change_role decision gave the member.", "x-data-class": "operational" }, "decided_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who decided it.", "x-data-class": "operational" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was decided.", "x-data-class": "operational" }, "own": { "type": "boolean", "description": "Whether it is the caller's own row, which another admin decides.", "x-data-class": "operational" } }, "required": [ "item_id", "review_id", "kind", "subject_id", "subject_label", "own" ], "additionalProperties": false }, "description": "Its items, when one review is asked for (review_id); null otherwise.", "x-data-class": "operational" } }, "required": [ "review_id", "org_id", "name", "covers", "due_at", "status", "total", "decided", "created_by", "created_at", "closed_by", "closed_at", "evidence_document_id", "items" ], "additionalProperties": false }, "annotations": { "title": "Close an access review", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "confirm_purchase_order", "title": "Confirm a purchase order as its supplier", "description": "For the supplier of an org's purchase order (a guest of the org in the seller seat, or a member of the supplier's own Trade HQ org): confirms the purchase order with the lines you will supply, and optionally your pro forma number and the date the units will be ready. The confirmation lands in the buyer's PO ingest exactly as an emailed confirmation PDF does, as staged rows the buyer previews and applies. A purchase order is confirmed once: the same confirmation again changes nothing, and a different one is refused.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that owns the purchase order: the buyer." }, "document_kind": { "type": "string", "enum": [ "asset_intake", "order" ], "description": "asset_intake: a purchase order. An order is refused." }, "document_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The purchase order's id." }, "lines": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "properties": { "size": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The container size, as the org's size list spells it, e.g. 40." }, "type": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The container type, as the org's type list spells it, e.g. HC." }, "condition": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The condition, as the org's condition list spells it." }, "color": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The colour, as the org's colour list spells it; optional." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 500, "description": "How many units of this line." }, "unit_price": { "type": "string", "pattern": "^[0-9]{1,12}(\\.[0-9]{1,12})?$", "format": "positive-decimal", "description": "The price of one unit, as digits; optional." } }, "required": [ "size", "type", "condition", "quantity" ], "additionalProperties": false }, "description": "What you will supply: each line a size, type, condition and optional colour from the estate's lists, a quantity, and optionally a unit price." }, "vendor_pro_forma_id": { "type": "string", "minLength": 1, "maxLength": 199, "description": "Your pro forma number for this purchase order." }, "vendor_eta": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "When the units will be ready for the in-gate, YYYY-MM-DD." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "document_kind", "document_id", "lines" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "post_id": { "type": "string", "description": "The confirmation.", "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 buyer.", "x-data-class": "operational" }, "document_id": { "type": "string", "description": "The purchase order.", "x-data-class": "operational" }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The supplier party that confirmed it.", "x-data-class": "operational" }, "ingest_document_id": { "type": "string", "description": "The ingest document the confirmation was staged as: what the buyer's PO ingest preview and apply take.", "x-data-class": "operational" }, "ingest_batch_id": { "type": "string", "description": "Its ingest_po_batch.", "x-data-class": "operational" }, "line_count": { "type": "integer", "minimum": 0, "description": "Lines confirmed.", "x-data-class": "operational" }, "unit_count": { "type": "integer", "minimum": 0, "description": "Units confirmed.", "x-data-class": "operational" }, "vendor_eta": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The ready date given, if any.", "x-data-class": "operational" }, "posted_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" } }, "required": [ "post_id", "org_id", "document_id", "party_id", "ingest_document_id", "ingest_batch_id", "line_count", "unit_count", "vendor_eta", "posted_at" ], "additionalProperties": false }, "annotations": { "title": "Confirm a purchase order as its supplier", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "confirm_report", "title": "Confirm a report works now", "description": "Tells Trade HQ support that a Fixed or Answered report of your org works now for you. It shows on the report's timeline and on support's ticket, naming you. Confirming a report you already confirmed changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the report is of: yours." }, "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The Fixed or Answered report that works now." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "report_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report.", "x-data-class": "operational" }, "ticket": { "type": "string", "description": "The report's reference (CUS-n).", "x-data-class": "operational" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "When you confirmed it: the first time, on every later call.", "x-data-class": "operational" } }, "required": [ "report_id", "ticket", "confirmed_at" ], "additionalProperties": false }, "annotations": { "title": "Confirm a report works now", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "convert_sandbox", "title": "Convert a sandbox to a customer", "description": "Turns a public sandbox into a paying customer's organization, after the deal is signed. The sandbox keeps its id and becomes a customer org in an account (an existing one, or a new one named here), on a plan, with a first admin who is invited by magic link or passkey. Its test data and its test API key stay in test mode, and the key stops expiring; live mode starts empty. The account and org steps are done at once and the rest of the onboarding (sign-in organization, invite, entitlements, welcome mail) finishes as for a provisioned account; get_onboarding_status reports it. Accepts the sandbox's org id or its test twin's. Send an Idempotency-Key header. Staff who provision accounts only.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The sandbox: its org, or its test twin, answered the same." }, "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "An existing account the customer org joins. Send this or account_name, not both." }, "account_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "A new account to make for the customer: the commercial relationship's name. Send this or account_id, not both." }, "org_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The customer org's name, the legal entity's. Its test twin becomes \"{org_name} (test)\"." }, "admin_email": { "type": "string", "minLength": 3, "maxLength": 254, "description": "The first admin's email address. They are invited, and sign in with it by magic link or passkey." }, "admin_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The first admin's name, for the welcome mail." }, "plan": { "type": "string", "enum": [ "base" ], "description": "The plan the customer org is on: base (the one tier today, and the default)." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "org_name", "admin_email" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The customer org: the sandbox's own id, unchanged, now of type customer.", "x-data-class": "operational" }, "twin_org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "Its test twin, which kept the sandbox's data and test key.", "x-data-class": "operational" }, "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account the customer org is in.", "x-data-class": "operational" }, "account_created": { "type": "boolean", "description": "Whether this call made the account.", "x-data-class": "operational" }, "provisioning_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The onboarding's ledger row, which get_onboarding_status reads.", "x-data-class": "operational" }, "plan": { "type": "string", "enum": [ "base" ], "description": "The plan the customer org is on.", "x-data-class": "operational" }, "key_id": { "type": "string", "description": "The sandbox's test API key, kept, which no longer expires. Never the secret.", "x-data-class": "operational" }, "converted_at": { "type": "string", "format": "date-time", "description": "When the sandbox was converted.", "x-data-class": "operational" } }, "required": [ "org_id", "twin_org_id", "account_id", "account_created", "provisioning_id", "plan", "key_id", "converted_at" ], "additionalProperties": false }, "annotations": { "title": "Convert a sandbox to a customer", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "create_access_review", "title": "Start an access review", "description": "Starts an access review of an org: a list of everyone and everything that holds access to it now, of the kinds chosen (members, guests, service_accounts, api_keys, staff_grants), for its admins to decide one by one with decide_access_review_item: keep it, change a member's role, or revoke it. The review is due at the end of due_on (UTC); an open review past due is raised to the account owner. It closes with close_access_review once every item is decided.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose access to review." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What the review is called, such as Q4 2026 access review." }, "due_on": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The day the review is due (YYYY-MM-DD); it is due at that day's end, UTC." }, "members": { "type": "boolean", "description": "Review the org's members. False by default." }, "guests": { "type": "boolean", "description": "Review the org's guests. False by default." }, "service_accounts": { "type": "boolean", "description": "Review the org's service accounts. False by default." }, "api_keys": { "type": "boolean", "description": "Review the org's API keys. False by default." }, "staff_grants": { "type": "boolean", "description": "Review the Trade HQ staff grants active in the org. False by default." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "name", "due_on" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "review_id": { "type": "string", "description": "The review'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 whose access it reviews.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What it is called.", "x-data-class": "operational" }, "covers": { "type": "array", "items": { "type": "string" }, "description": "What it covers, of members, guests, service_accounts, api_keys and staff_grants, in that order.", "x-data-class": "operational" }, "due_at": { "type": "string", "format": "date-time", "description": "When it is due: the end (UTC) of its due date.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "open", "overdue", "closed" ], "description": "open; overdue, an open review past due; or closed.", "x-data-class": "operational" }, "total": { "type": "integer", "minimum": 0, "description": "How many items it asks about.", "x-data-class": "operational" }, "decided": { "type": "integer", "minimum": 0, "description": "How many of them are decided.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who started it.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was started.", "x-data-class": "operational" }, "closed_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who closed it.", "x-data-class": "operational" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was closed.", "x-data-class": "operational" }, "evidence_document_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The evidence document closing it wrote: who decided what, and when.", "x-data-class": "operational" }, "items": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "item_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The item's id.", "x-data-class": "operational" }, "review_id": { "type": "string", "description": "The review it belongs to.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "member", "guest", "service_account", "api_key", "staff_grant" ], "description": "member, guest, service_account, api_key or staff_grant.", "x-data-class": "operational" }, "subject_id": { "type": "string", "description": "Whose access: a user id, a service account id, a key id or a staff grant's id.", "x-data-class": "operational" }, "subject_label": { "anyOf": [ { "type": "string" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "What a reviewer reads for it: an email, or a service account's or key's name.", "x-data-class": "personal" }, "role": { "type": [ "string", "null" ], "description": "The access it held when the review began: a role template, a key's service account, or a staff grant's level.", "x-data-class": "operational" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was last seen acting before the review began, where known.", "x-data-class": "operational" }, "decision": { "type": [ "string", "null" ], "enum": [ "keep", "change_role", "revoke", null ], "description": "keep, change_role or revoke; null until decided.", "x-data-class": "operational" }, "new_role_template_id": { "type": [ "string", "null" ], "description": "The role template a change_role decision gave the member.", "x-data-class": "operational" }, "decided_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who decided it.", "x-data-class": "operational" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was decided.", "x-data-class": "operational" }, "own": { "type": "boolean", "description": "Whether it is the caller's own row, which another admin decides.", "x-data-class": "operational" } }, "required": [ "item_id", "review_id", "kind", "subject_id", "subject_label", "own" ], "additionalProperties": false }, "description": "Its items, when one review is asked for (review_id); null otherwise.", "x-data-class": "operational" } }, "required": [ "review_id", "org_id", "name", "covers", "due_at", "status", "total", "decided", "created_by", "created_at", "closed_by", "closed_at", "evidence_document_id", "items" ], "additionalProperties": false }, "annotations": { "title": "Start an access review", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "create_account", "title": "Create an account", "description": "Creates an account: the commercial relationship a customer's orgs belong to. It holds no business data. Optionally names its first owner, who may then create orgs and portfolios in it. Send an Idempotency-Key header: a retry with the same key and inputs returns the same account and creates nothing.", "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The account's name: the commercial relationship's, as staff know it." }, "owner_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The account's first owner: an existing user who is not deactivated." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "name" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The new account's id.", "x-data-class": "operational" }, "name": { "type": "string", "description": "The account's name.", "x-data-class": "operational" }, "owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Its first owner, or null.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who created it.", "x-data-class": "operational" } }, "required": [ "account_id", "name", "owner_user_id", "created_by" ], "additionalProperties": false }, "annotations": { "title": "Create an account", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "create_data_share", "title": "Share data with a counterparty", "description": "Shares one saved query of the org's data with a counterparty party, delivered to the recipients by email on a daily or hourly digest. The counterparty already sees the documents on which it holds a seat; a share adds to that. Call preview_data_share first to see exactly what the counterparty will receive. A share stays until revoke_data_share revokes it.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org sharing its data." }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The counterparty, from the shared party directory." }, "query": { "type": "string", "enum": [ "vendor_bill_request", "vendor_forecast", "vendor_sell_through" ], "description": "The saved query: vendor_forecast (the org's open purchase orders with the vendor, with ETAs and units), vendor_sell_through (units bought from the vendor, sold and on hand, by size, type and condition) or vendor_bill_request (one bill request's units, as the cash flow audit's vendor export lists them)." }, "contact_id": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^CT[0-9A-Za-z]{1,18}$", "format": "tradehq-contact-id", "description": "For vendor_forecast and vendor_sell_through: the vendor, one of the org's own contacts. The party must hold the seller seat on at least one of the org's purchase orders with it, and only those purchase orders are shared. When the vendor is itself a Trade HQ org, the party must be the one that org has claimed." }, "request_id": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^VR[0-9A-Za-z]{1,18}$", "format": "tradehq-vendor-bill-request-id", "description": "For vendor_bill_request: the cash flow audit's vendor bill request. Its units' one vendor is the vendor, and the party must hold the seller seat on every purchase order the units came in on." }, "recipients": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\\.)+([A-Za-z]{2,}|[Xx][Nn]--[A-Za-z0-9-]*[A-Za-z0-9])$", "maxLength": 254 }, "description": "The counterparty's addresses the share is emailed to, 1 to 10." }, "cadence": { "type": "string", "enum": [ "daily", "hourly" ], "default": "daily", "description": "daily (the default) or hourly." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "party_id", "query", "recipients" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "data_share_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The share, derived from the Idempotency-Key.", "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 sharing.", "x-data-class": "operational" }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The counterparty.", "x-data-class": "operational" }, "party_name": { "type": "string", "description": "The counterparty's name in the directory.", "x-data-class": "operational" }, "query": { "type": "string", "enum": [ "vendor_bill_request", "vendor_forecast", "vendor_sell_through" ], "description": "The saved query shared.", "x-data-class": "operational" }, "title": { "type": "string", "description": "The saved query's title, as the counterparty reads it.", "x-data-class": "operational" }, "recipients": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\\.)+([A-Za-z]{2,}|[Xx][Nn]--[A-Za-z0-9-]*[A-Za-z0-9])$", "maxLength": 254 }, "uniqueItems": true }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Who it is emailed to, sorted.", "x-data-class": "personal" }, "cadence": { "type": "string", "enum": [ "daily", "hourly" ], "description": "How often it is emailed.", "x-data-class": "operational" }, "row_total": { "type": "integer", "minimum": 0, "description": "How many rows it renders now.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Null; set on a replay of a share revoked since.", "x-data-class": "operational" } }, "required": [ "data_share_id", "org_id", "party_id", "party_name", "query", "title", "recipients", "cadence", "row_total", "created_at", "revoked_at" ], "additionalProperties": false }, "annotations": { "title": "Share data with a counterparty", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "create_invite_link", "title": "Create an invite link", "description": "Creates a link that invites whoever opens it into an org, optionally with a role template, valid for 1 to 30 days (7 by default). The link is shown once, in this answer; only its hash is kept. Send an Idempotency-Key header: a retry with the same key and inputs returns the same link id with url null, and creates nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the link invites into." }, "role_template_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The role template a person joining by the link will hold: shipped or this org's own, and carrying nothing your role does not." }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 30, "default": 7, "description": "How many days the link works." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "link_id": { "type": "string", "description": "The link's id, for revoking it.", "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.", "x-data-class": "operational" }, "role_template_id": { "type": [ "string", "null" ], "description": "The role template, if any.", "x-data-class": "operational" }, "expires_at": { "type": "string", "format": "date-time", "description": "When it stops working.", "x-data-class": "operational" }, "url": { "type": [ "string", "null" ], "description": "The link. Only in the creating call's answer; null on a replay, because only its hash is stored.", "x-data-class": "operational" } }, "required": [ "link_id", "org_id", "role_template_id", "expires_at", "url" ], "additionalProperties": false }, "annotations": { "title": "Create an invite link", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "create_org", "title": "Create an org", "description": "Creates an org with a name and a type (internal, demo or customer), optionally in an account, and returns its id. An account owner creates only into an account they own. The org starts with no members. Send an Idempotency-Key header: a retry with the same key and inputs returns the same org and creates nothing.", "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The org's name: the legal entity's, as customers know it." }, "org_type": { "type": "string", "enum": [ "internal", "demo", "customer" ], "description": "internal (staff dogfood and QA), demo (a sales demo) or customer (a tenant)." }, "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account the org belongs to. Required of an account owner, and one they own." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "name", "org_type" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The new org's id.", "x-data-class": "operational" }, "name": { "type": "string", "description": "The org's name.", "x-data-class": "operational" }, "org_type": { "type": "string", "enum": [ "internal", "demo", "customer" ], "description": "The org's type.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who created it.", "x-data-class": "operational" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "Its account, or null.", "x-data-class": "operational" } }, "required": [ "org_id", "name", "org_type", "created_by", "account_id" ], "additionalProperties": false }, "annotations": { "title": "Create an org", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "create_portfolio", "title": "Create a portfolio", "description": "Creates an empty portfolio, a named set of orgs, in an account or, for staff, in no account. An account owner creates only into an account they own. Send an Idempotency-Key header: a retry with the same key and inputs returns the same portfolio and creates nothing.", "inputSchema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The portfolio's name." }, "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The owning account. Required of an account owner, and one they own; staff may leave it out." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "name" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "portfolio_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-portfolio-id", "description": "The new portfolio's id.", "x-data-class": "operational" }, "name": { "type": "string", "description": "Its name.", "x-data-class": "operational" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "Its account; null for a staff portfolio.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who created it.", "x-data-class": "operational" } }, "required": [ "portfolio_id", "name", "account_id", "created_by" ], "additionalProperties": false }, "annotations": { "title": "Create a portfolio", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "create_service_account", "title": "Create a service account", "description": "Makes a service account on an org: a non-human principal that owns API keys and acts under its own role template. It has a primary and a backup owner, two different active members of the org; when the primary is deactivated the backup takes over, and when the last owner is deactivated the account is suspended until an admin reassigns it. Its role template is never Owner or Admin. It expires after expires_in_days (at most 365) unless renewed, and its mode, live or test, is the mode of every key it holds. Issue its keys with create_api_key.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The live org the account belongs to." }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "What the account is for, such as the integration that holds its keys." }, "owner_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The primary owner: an active member of the org." }, "backup_owner_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The backup owner: another active member of the org, who takes over when the primary is deactivated." }, "role_template_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The role template the account acts under: a shipped one or the org's own, never owner or admin." }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "default": 365, "description": "Days until the account and every key of it stop working, at most 365 (the default). update_service_account renews it." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live (the default) or test. Its keys are sk_live_ or sk_test_ to match; it never changes." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "name", "owner_user_id", "backup_owner_user_id", "role_template_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "service_account_id": { "type": "string", "description": "The account'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 live org it belongs to.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What it is for.", "x-data-class": "operational" }, "owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Its primary owner; null only while it is suspended for want of one.", "x-data-class": "operational" }, "backup_owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Its backup owner, who takes over when the primary is deactivated; null once that has happened.", "x-data-class": "operational" }, "role_template_id": { "type": "string", "description": "The role template it acts under: never Owner or Admin.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live or test; its keys are sk_live_ or sk_test_ to match.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "suspended", "disabled", "expired" ], "description": "active; suspended when its last owner was deactivated, until an admin reassigns it; disabled, which is final; or expired.", "x-data-class": "operational" }, "expires_at": { "type": "string", "format": "date-time", "description": "When it and every key of it stop working, unless renewed.", "x-data-class": "operational" }, "keys": { "type": "integer", "description": "How many working keys it holds.", "x-data-class": "operational" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The start of the last minute any key of it was served a request; null if never.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was made.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who made it.", "x-data-class": "operational" } }, "required": [ "service_account_id", "org_id", "name", "owner_user_id", "backup_owner_user_id", "role_template_id", "mode", "status", "expires_at", "keys", "last_used_at", "created_at", "created_by" ], "additionalProperties": false }, "annotations": { "title": "Create a service account", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "create_sso_connection", "title": "Add a single sign-on connection", "description": "Adds a single sign-on connection (SAML or OIDC) for one email domain this org has verified. The connection is created in Clerk shortly after, inactive; list_sso_connections then shows the ACS URL and entity id to give the IdP admin. Save the IdP's metadata and activate it with update_sso_connection, then require it with set_sso_policy.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What the org's admins call it, such as the IdP's name." }, "protocol": { "type": "string", "enum": [ "saml", "oidc" ], "description": "saml or oidc." }, "domain": { "type": "string", "minLength": 3, "maxLength": 253, "description": "The email domain it serves: one this org has verified." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "name", "protocol", "domain" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "connection_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "Trade HQ's id for the connection.", "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 belongs to.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What the org's admins call it.", "x-data-class": "operational" }, "protocol": { "type": "string", "enum": [ "saml", "oidc" ], "description": "saml or oidc.", "x-data-class": "operational" }, "domain": { "type": "string", "description": "The verified email domain it serves.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "creating", "awaiting_metadata", "ready_to_test", "active", "deleting", "deleted" ], "description": "creating (Clerk has not answered yet), awaiting_metadata, ready_to_test, active, deleting or deleted.", "x-data-class": "operational" }, "active": { "type": "boolean", "description": "Whether people sign in through it.", "x-data-class": "operational" }, "acs_url": { "type": [ "string", "null" ], "description": "The service provider's ACS URL, for the IdP admin; null until Clerk has answered.", "x-data-class": "operational" }, "sp_entity_id": { "type": [ "string", "null" ], "description": "The service provider's entity id, for the IdP admin; null until Clerk has answered.", "x-data-class": "operational" }, "sp_metadata_url": { "type": [ "string", "null" ], "description": "The service provider's metadata URL; null until Clerk has answered.", "x-data-class": "operational" }, "idp_metadata_url": { "type": [ "string", "null" ], "description": "The IdP metadata URL saved, if a URL was.", "x-data-class": "operational" }, "has_idp_metadata": { "type": "boolean", "description": "Whether IdP metadata is saved, as a URL or as uploaded XML.", "x-data-class": "operational" }, "required": { "type": "boolean", "description": "Whether members at its domain must sign in through it.", "x-data-class": "operational" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time", "description": "While the outage lever holds, when it ends; null otherwise.", "x-data-class": "operational" }, "jit": { "type": "boolean", "description": "Whether a first sign-in through it makes the person a member.", "x-data-class": "operational" }, "default_role_template": { "type": [ "string", "null" ], "description": "The role template a just-in-time member gets.", "x-data-class": "operational" }, "idp_mfa_trusted": { "type": "boolean", "description": "Whether the IdP's MFA counts toward the org's MFA settings.", "x-data-class": "operational" }, "allow_manual_additions": { "type": "boolean", "description": "Whether invites stay allowed for its domain while a directory manages it (TRA-486).", "x-data-class": "operational" }, "last_sign_in_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The last sign-in through it.", "x-data-class": "operational" }, "idp_certificate_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the IdP's signing certificate expires, once known.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was added.", "x-data-class": "operational" }, "caller_may_bypass": { "type": "boolean", "description": "Whether the caller may pull the outage lever: the account owner, or the Owner role template in the org.", "x-data-class": "operational" } }, "required": [ "connection_id", "org_id", "name", "protocol", "domain", "status", "active", "acs_url", "sp_entity_id", "sp_metadata_url", "idp_metadata_url", "has_idp_metadata", "required", "bypass_until", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions", "last_sign_in_at", "idp_certificate_expires_at", "created_at", "caller_may_bypass" ], "additionalProperties": false }, "annotations": { "title": "Add a single sign-on connection", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "create_unit", "title": "Create a unit", "description": "Creates a unit (a division, region, depot or office) in an org's unit tree, beneath a parent unit or as a root, and returns its id. A depot is a leaf: nothing can be created beneath one. An org admin can create anywhere in the tree; a member who holds admin on a unit can create beneath that unit. A role held on a unit reaches every unit beneath it. Send an Idempotency-Key header: a retry with the same key and inputs returns the same unit and creates nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose tree the unit joins." }, "parent_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The unit it goes beneath, in the same org. Absent, the unit is a root." }, "kind": { "type": "string", "enum": [ "division", "region", "depot", "office" ], "description": "division, region, depot (a yard, always a leaf) or office." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The unit's name, as the org's people know it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "kind", "name" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The new unit'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": "Its org.", "x-data-class": "operational" }, "parent_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "Its parent; null for a root.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "division", "region", "depot", "office" ], "description": "Its kind.", "x-data-class": "operational" }, "name": { "type": "string", "description": "Its name.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who created it.", "x-data-class": "operational" } }, "required": [ "unit_id", "org_id", "parent_id", "kind", "name", "created_by" ], "additionalProperties": false }, "annotations": { "title": "Create a unit", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "deactivate_user", "title": "Deactivate a user", "description": "Marks a user deactivated: this is what the admin console's Delete button does. Their Clerk sessions are revoked and they cannot sign in; their memberships and records are kept, and their records keep their name. It is reversible with reinstate_user. A deactivated user can call no capability. Calling it again on a deactivated user changes nothing. An org admin can deactivate only a user whose every org they administer; staff can deactivate anyone but themselves.", "inputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The user to deactivate." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "user_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The user.", "x-data-class": "operational" }, "deactivated_at": { "type": "string", "format": "date-time", "description": "When they were deactivated: the first call's time on a replay.", "x-data-class": "operational" }, "orgs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id" }, "description": "The orgs the user belongs to, whose admins the event reaches.", "x-data-class": "operational" } }, "required": [ "user_id", "deactivated_at", "orgs" ], "additionalProperties": false }, "annotations": { "title": "Deactivate a user", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "decide_access_review_item", "title": "Decide an access review item", "description": "Decides one item of an open access review, and does what the decision says: keep leaves it as it is; change_role gives a member the role template role_template_id; revoke deactivates a member, revokes a guest, disables a service account (and every key of it), revokes an API key or ends a staff grant. A decision is final. You cannot decide your own row, or a service account or key you own; another admin does.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the review is of." }, "review_id": { "type": "string", "minLength": 1, "maxLength": 14, "description": "The review." }, "item_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The item to decide." }, "decision": { "type": "string", "enum": [ "keep", "change_role", "revoke" ], "description": "keep, change_role (a member's alone) or revoke." }, "role_template_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The member's new role template, for change_role." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "review_id", "item_id", "decision" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "item_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The item's id.", "x-data-class": "operational" }, "review_id": { "type": "string", "description": "The review it belongs to.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "member", "guest", "service_account", "api_key", "staff_grant" ], "description": "member, guest, service_account, api_key or staff_grant.", "x-data-class": "operational" }, "subject_id": { "type": "string", "description": "Whose access: a user id, a service account id, a key id or a staff grant's id.", "x-data-class": "operational" }, "subject_label": { "anyOf": [ { "type": "string" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "What a reviewer reads for it: an email, or a service account's or key's name.", "x-data-class": "personal" }, "role": { "type": [ "string", "null" ], "description": "The access it held when the review began: a role template, a key's service account, or a staff grant's level.", "x-data-class": "operational" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was last seen acting before the review began, where known.", "x-data-class": "operational" }, "decision": { "type": [ "string", "null" ], "enum": [ "keep", "change_role", "revoke", null ], "description": "keep, change_role or revoke; null until decided.", "x-data-class": "operational" }, "new_role_template_id": { "type": [ "string", "null" ], "description": "The role template a change_role decision gave the member.", "x-data-class": "operational" }, "decided_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who decided it.", "x-data-class": "operational" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was decided.", "x-data-class": "operational" }, "own": { "type": "boolean", "description": "Whether it is the caller's own row, which another admin decides.", "x-data-class": "operational" } }, "required": [ "item_id", "review_id", "kind", "subject_id", "subject_label", "role", "last_active_at", "decision", "new_role_template_id", "decided_by", "decided_at", "own" ], "additionalProperties": false }, "annotations": { "title": "Decide an access review item", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "decline_data_share", "title": "Stop receiving a data share", "description": "Stops a data share another org made with this org: nothing more is sent to its addresses, and the org that made it sees that this org declined it. Only that org can share it again, as a new share. Documents this org holds a seat on are not affected. Declining a declined share changes nothing; a revoked share is refused.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The receiving org: the one that has claimed the share's party." }, "data_share_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The share, as list_received_data_shares names it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "data_share_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "data_share_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The share.", "x-data-class": "operational" }, "from_org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that made it.", "x-data-class": "operational" }, "declined_at": { "type": "string", "format": "date-time", "description": "When it was declined.", "x-data-class": "operational" }, "declined_by": { "type": "string", "description": "Who declined it.", "x-data-class": "operational" } }, "required": [ "data_share_id", "from_org_id", "declined_at", "declined_by" ], "additionalProperties": false }, "annotations": { "title": "Stop receiving a data share", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "delete_file", "title": "Delete a file", "description": "Deletes one of the org's files. It stops being listed or read at once, and its bytes are kept aside for 30 days before they are gone.", "inputSchema": { "type": "object", "properties": { "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 filed in." }, "file_id": { "type": "string", "minLength": 26, "maxLength": 26, "description": "The file's id." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "file_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "file_id": { "type": "string", "description": "The file.", "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 was filed in.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "deleted" ], "description": "deleted.", "x-data-class": "operational" }, "deleted_at": { "type": "string", "format": "date-time", "description": "When it was deleted.", "x-data-class": "operational" } }, "required": [ "file_id", "org_id", "state", "deleted_at" ], "additionalProperties": false }, "annotations": { "title": "Delete a file", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "delete_role_template", "title": "Delete a role template", "description": "Deletes one of the org's own role templates. A template a member holds, a pending invite will give, or an active invite link hands out is not deleted: give those people another role first. Shipped templates cannot be deleted. You can delete only a template that carries nothing your own role in the org does not. An id the org does not have is refused.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the template belongs to." }, "role_id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The org's own template to delete: a clone id (RT and twelve characters)." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "role_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "role_id": { "type": "string", "description": "The template'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 belonged to.", "x-data-class": "operational" }, "deleted": { "type": "boolean", "description": "True: the org has no template with this id.", "x-data-class": "operational" } }, "required": [ "role_id", "org_id", "deleted" ], "additionalProperties": false }, "annotations": { "title": "Delete a role template", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "delete_sso_connection", "title": "Delete a single sign-on connection", "description": "Deletes a single sign-on connection. Nobody signs in through it from this call, its domain no longer requires SSO (members there use magic link or passkey again), its just-in-time settings go with it, and the Clerk connection is deleted shortly after.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org." }, "connection_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The connection, as list_sso_connections names it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "connection_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "connection_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The connection.", "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.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "deleting", "deleted" ], "description": "deleting until Clerk has deleted it, then deleted.", "x-data-class": "operational" } }, "required": [ "connection_id", "org_id", "status" ], "additionalProperties": false }, "annotations": { "title": "Delete a single sign-on connection", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "delete_view", "title": "Delete a saved view", "description": "Deletes a saved view: the caller's own, or one shared org-write. It is no longer listed. A view shared org-read by another member, or a system view, is refused (view_read_only). Repeating the same call answers the first deletion, replayed.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the view is in." }, "view_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The view to delete." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "view_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "view_id": { "type": "string", "description": "The view deleted.", "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 was in.", "x-data-class": "operational" }, "title": { "type": "string", "description": "What it was called.", "x-data-class": "operational" }, "deleted_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who deleted it.", "x-data-class": "operational" } }, "required": [ "view_id", "org_id", "title", "deleted_by" ], "additionalProperties": false }, "annotations": { "title": "Delete a saved view", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "disable_service_account", "title": "Disable a service account", "description": "Disables a service account for good and revokes every API key it holds, in one step: its keys stop working at once. A disabled account cannot be re-enabled or changed; make another. Disabling one already disabled changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the account belongs to." }, "service_account_id": { "type": "string", "minLength": 1, "maxLength": 14, "description": "The account to disable." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "service_account_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "service_account_id": { "type": "string", "description": "The account'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 live org it belongs to.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What it is for.", "x-data-class": "operational" }, "owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Its primary owner; null only while it is suspended for want of one.", "x-data-class": "operational" }, "backup_owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Its backup owner, who takes over when the primary is deactivated; null once that has happened.", "x-data-class": "operational" }, "role_template_id": { "type": "string", "description": "The role template it acts under: never Owner or Admin.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live or test; its keys are sk_live_ or sk_test_ to match.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "suspended", "disabled", "expired" ], "description": "active; suspended when its last owner was deactivated, until an admin reassigns it; disabled, which is final; or expired.", "x-data-class": "operational" }, "expires_at": { "type": "string", "format": "date-time", "description": "When it and every key of it stop working, unless renewed.", "x-data-class": "operational" }, "keys": { "type": "integer", "description": "How many working keys it holds.", "x-data-class": "operational" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The start of the last minute any key of it was served a request; null if never.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was made.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who made it.", "x-data-class": "operational" } }, "required": [ "service_account_id", "org_id", "name", "owner_user_id", "backup_owner_user_id", "role_template_id", "mode", "status", "expires_at", "keys", "last_used_at", "created_at", "created_by" ], "additionalProperties": false }, "annotations": { "title": "Disable a service account", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "export_audit_events", "title": "Export an org's audit log", "description": "Exports the audit log of one org, with the filters list_audit_events takes (event, actor, impersonation, admin alerts, a UTC date range; staff may add the acts on no org), to a CSV and a JSON file. Answers 202 with the export's id while it is built; list_audit_exports says when it is ready and answers a download link for each file, signed and good for 24 hours. The files hold exactly what list_audit_events shows the caller: staff read each row whole; an account owner or an org admin gets before and after as the keys the act changed only, redacted. More than 50,000 events fail the export rather than cut it short. One export of an org runs at a time.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose audit log is exported." }, "event": { "type": "string", "minLength": 3, "maxLength": 64, "pattern": "^[a-z_]+\\.[a-z_]+$", "format": "tradehq-event-name", "description": "Only this event, by name (org.settings_changed)." }, "actor_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Only acts by this user." }, "impersonated": { "type": "boolean", "description": "true: only acts staff took inside the org on platform authority; false: only the others." }, "alerts_only": { "type": "boolean", "description": "Only the admin activity alerts: a new admin, an SSO change, an API key created." }, "since": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "Only acts on or after this UTC day." }, "until": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "Only acts on or before this UTC day." }, "include_platform": { "type": "boolean", "description": "Staff only: also export acts that touched no org (accounts, portfolios, platform FX overrides)." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "export_id": { "type": "string", "description": "The export: ae and eighteen characters, derived from the Idempotency-Key.", "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.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "running", "ready", "failed" ], "description": "running when first answered (202); a replay answers where it is now.", "x-data-class": "operational" }, "filters": { "type": "object", "description": "The filters as asked, by their input names; the export holds exactly the rows they list.", "x-data-class": "operational" } }, "required": [ "export_id", "org_id", "status", "filters" ], "additionalProperties": false }, "annotations": { "title": "Export an org's audit log", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "follow_report", "title": "Follow a customer report", "description": "Follows a customer report: it then shows unread to the caller when it changes, and its updates reach them. Open to anyone who may get the report: a member of its org or the owner of the org's account. A private report is its reporter's alone. Following writes a followed event on the report's timeline; following a report you follow already changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the report is in." }, "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report: its CUS ticket's Linear id, as list_reports and get_report answer it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "report_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report.", "x-data-class": "operational" }, "following": { "type": "boolean", "description": "Whether the caller follows the report now.", "x-data-class": "operational" } }, "required": [ "report_id", "following" ], "additionalProperties": false }, "annotations": { "title": "Follow a customer report", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "get_acting_scope", "title": "Get where my session acts", "description": "Answers where the signed-in user's session acts: at an account, an org or a unit, with each one's name. At account scope it names the entity acts land in (null until one is chosen). It says whether the session is a device pinned to its unit, whether it is in live or test mode, and whether the caller may enter test mode. Changing it is set_acting_scope.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "account", "org", "unit" ], "description": "Where the session acts: account, org or unit.", "x-data-class": "operational" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account: the scope's at account scope, else the session org's own; null when the org is in none.", "x-data-class": "operational" }, "account_name": { "type": [ "string", "null" ], "description": "That account's name.", "x-data-class": "operational" }, "account_member": { "type": "boolean", "description": "The caller is a member of that account, so the session can act at account scope.", "x-data-class": "operational" }, "org_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The session's org: the entity.", "x-data-class": "operational" }, "org_name": { "type": [ "string", "null" ], "description": "The entity's name.", "x-data-class": "operational" }, "landing_org_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "At account scope, the entity acts land in; null until one is chosen, and at any other level.", "x-data-class": "operational" }, "landing_org_name": { "type": [ "string", "null" ], "description": "That entity's name.", "x-data-class": "operational" }, "unit_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "At unit scope, the unit.", "x-data-class": "operational" }, "unit_name": { "type": [ "string", "null" ], "description": "The unit's name.", "x-data-class": "operational" }, "device": { "type": "boolean", "description": "The session is a device pinned to its unit: it acts only there and cannot change scope.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "The session's mode: live, or test, where it acts in the org's test twin.", "x-data-class": "operational" }, "test_mode_allowed": { "type": "boolean", "description": "The caller may enter test mode: their role in the session's live org carries org.admin or api_key.read. Leaving test is open to anyone in it.", "x-data-class": "operational" } }, "required": [ "level", "account_id", "account_name", "account_member", "org_id", "org_name", "landing_org_id", "landing_org_name", "unit_id", "unit_name", "device", "mode", "test_mode_allowed" ], "additionalProperties": false }, "annotations": { "title": "Get where my session acts", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_api_usage", "title": "Get API usage", "description": "Counts the requests the org's API keys made, per key per UTC day, newest day first: how many were served and how many were refused for passing a key's limits. Live and test keys are kept apart: each row names its mode, and mode narrows to one. One key with key_id, or all of them. The window is since to until, both UTC days and both included: the last 30 days by default, at most 92. BK_ keys are not metered and have no usage.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose keys they are." }, "key_id": { "type": "string", "minLength": 1, "maxLength": 12, "description": "One key's usage. Absent, every key's." }, "since": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first UTC day, included. Defaults to 29 days before until." }, "until": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last UTC day, included. Defaults to today." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live or test: only the keys of that mode. Absent, both, each row naming its mode." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The UTC day.", "x-data-class": "operational" }, "key_id": { "type": "string", "description": "The key.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "The key's mode.", "x-data-class": "operational" }, "requests": { "type": "integer", "description": "Requests served that day.", "x-data-class": "operational" }, "refused": { "type": "integer", "description": "Requests refused that day for passing a limit.", "x-data-class": "operational" } }, "required": [ "day", "key_id", "mode", "requests", "refused" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "Get API usage", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_data_policy", "title": "Get a role template's data policy", "description": "Returns one role template's data policy: which records its members reach (record_scope) and, for commercial, financial and personal fields, whether they read them (allowed, masked or denied) and export them (allowed or denied). A shipped template's data policy is read-only; a clone answers its own, or its source's until it has one. Operational fields are always read and exported.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose role template it is." }, "role_id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The role template: a shipped id or one of the org's clone ids." } }, "required": [ "org_id", "role_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "role_id": { "type": "string", "description": "The role template: a shipped id such as read_only, or a clone's RT id.", "x-data-class": "operational" }, "source": { "type": "string", "enum": [ "shipped", "own", "inherited" ], "description": "shipped: the template's own, read-only; own: the clone's own row; inherited: a clone with no row, answered its source's.", "x-data-class": "operational" }, "version": { "type": "integer", "description": "The clone's own data policy's version; 0 for a shipped or inherited one.", "x-data-class": "operational" }, "record_scope": { "type": "string", "enum": [ "whole_org", "unit_subtree", "portfolio", "party_seat" ], "description": "Which records its members reach: whole_org, unit_subtree, portfolio or party_seat.", "x-data-class": "operational" }, "record_scope_locked": { "type": "boolean", "description": "A Counterparty template, or a clone of one, is locked to its party's seat.", "x-data-class": "operational" }, "commercial_read": { "type": "string", "enum": [ "allowed", "masked", "denied" ], "description": "Commercial fields (acquisition cost, margin, supplier price, FX override): allowed, masked or denied.", "x-data-class": "operational" }, "commercial_export": { "type": "string", "enum": [ "allowed", "denied" ], "description": "Whether an export carries commercial fields: allowed or denied.", "x-data-class": "operational" }, "financial_read": { "type": "string", "enum": [ "allowed", "masked", "denied" ], "description": "Financial fields (invoice totals, credit terms): allowed, masked or denied.", "x-data-class": "operational" }, "financial_export": { "type": "string", "enum": [ "allowed", "denied" ], "description": "Whether an export carries financial fields: allowed or denied.", "x-data-class": "operational" }, "personal_read": { "type": "string", "enum": [ "allowed", "masked", "denied" ], "description": "Personal fields (member emails, phone numbers): allowed, masked or denied.", "x-data-class": "operational" }, "personal_export": { "type": "string", "enum": [ "allowed", "denied" ], "description": "Whether an export carries personal fields: allowed or denied.", "x-data-class": "operational" } }, "required": [ "org_id", "role_id", "source", "version", "record_scope", "record_scope_locked", "commercial_read", "commercial_export", "financial_read", "financial_export", "personal_read", "personal_export" ], "additionalProperties": false }, "annotations": { "title": "Get a role template's data policy", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_file", "title": "Get a file", "description": "Reads one of the org's files: its record and, up to 180,000 bytes and where the caller's data policy reads its class, its bytes (base64). Never a link.", "inputSchema": { "type": "object", "properties": { "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 filed in." }, "file_id": { "type": "string", "minLength": 26, "maxLength": 26, "description": "The file's id." } }, "required": [ "org_id", "file_id" ], "additionalProperties": false }, "outputSchema": { "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 }, "annotations": { "title": "Get a file", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_identity_sync", "title": "Get an org's Clerk sync state", "description": "Answers how an org's Clerk sync stands: when the reconcile last finished for it (nightly at 02:00 PT), how many role differences, memberships Trade HQ did not decide and missing memberships are open, what the org's drift setting does with them (quarantined or alerted), and how many of Clerk's events for it are waiting or failed, the failed ones named.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose Clerk sync to read." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the newest reconcile covering the org finished; null before the first.", "x-data-class": "operational" }, "last_run_trigger": { "type": [ "string", "null" ], "enum": [ "nightly", "manual", null ], "description": "Whether it was the nightly run or a manual one.", "x-data-class": "operational" }, "role_differences": { "type": "integer", "description": "Open role_mismatch findings.", "x-data-class": "operational" }, "unexpected_memberships": { "type": "integer", "description": "Open membership_unexpected findings.", "x-data-class": "operational" }, "missing_memberships": { "type": "integer", "description": "Open membership_missing findings.", "x-data-class": "operational" }, "drift_policy": { "type": "string", "enum": [ "quarantined", "alerted" ], "description": "What the org's drift setting does with a difference: quarantined (refused here and put back in Clerk) or alerted (raised only).", "x-data-class": "operational" }, "events_waiting": { "type": "integer", "description": "Clerk's events for the org not yet processed.", "x-data-class": "operational" }, "events_failed": { "type": "integer", "description": "Clerk's events for the org that failed five times and wait for a person.", "x-data-class": "operational" }, "failed_events": { "type": "array", "items": { "type": "string" }, "description": "The newest failed events, at most twenty, each as ` `.", "x-data-class": "operational" } }, "required": [ "org_id", "last_run_at", "last_run_trigger", "role_differences", "unexpected_memberships", "missing_memberships", "drift_policy", "events_waiting", "events_failed", "failed_events" ], "additionalProperties": false }, "annotations": { "title": "Get an org's Clerk sync state", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_my_settings", "title": "Get my settings", "description": "Reads the caller's own effective settings in the org: every key with its value, the level it came from (platform, account, org or user) and the level that locks it, if any. Includes shell_last_tab, the header tab they last chose.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the caller is a member of, whose levels above the caller apply." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "settings": { "type": "object", "properties": { "base_currency": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "The ISO 4217 currency the books are kept in. An org decides it; its units and people do not." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "date_format": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "YYYY-MM-DD", "DD/MM/YYYY", "MM/DD/YYYY" ], "description": "How dates are shown." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "fiscal_year_start": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "The first day of the fiscal year, MM-DD. An org decides it; its units and people do not." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "locale": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "en-US", "en-GB", "de-DE", "fr-FR", "es-ES", "nl-NL" ], "description": "The language and regional format of the interface." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_booking": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How bookings are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_invoice": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How invoices are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_order": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How sales orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_purchase_order": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How purchase orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_release": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How releases are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. A yard may number its own." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_vendor_bill": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How vendor bills are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "shell_last_tab": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "depots", "sell", "source", "intel" ], "description": "The tab of the app's header a person last chose, which they land on when they sign in." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "timezone": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(UTC|[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+)+)$", "description": "The IANA time zone times are shown in." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "units_of_measure": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "metric", "imperial" ], "description": "Metric or imperial weights and dimensions. An org decides it for everyone in it." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "week_starts_on": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "monday", "sunday" ], "description": "The first day of a week in calendars and weekly reports." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false } }, "required": [ "base_currency", "date_format", "fiscal_year_start", "locale", "numbering_series_booking", "numbering_series_invoice", "numbering_series_order", "numbering_series_purchase_order", "numbering_series_release", "numbering_series_vendor_bill", "shell_last_tab", "timezone", "units_of_measure", "week_starts_on" ], "additionalProperties": false, "description": "Every key's effective value for the caller in the org, where it came from, and where it is locked.", "x-data-class": "operational" } }, "required": [ "org_id", "settings" ], "additionalProperties": false }, "annotations": { "title": "Get my settings", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_notification_policy", "title": "Read an org's notification settings", "description": "Lists the org's six notice kinds in order: the audit log digest, admin activity alerts, staff access requests, break-glass access, deletion notices and announcements. Each carries its fixed recipients, which nothing removes (org_admins: every admin of the org; deleted_user: the user a user deletion is about), the members, outside email addresses and Slack channels the org also requires, and for the digest its cadence. A Slack channel is its name and id, never its webhook URL.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose notification settings to read." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "audit_digest", "admin_alerts", "access_request", "break_glass", "deletion", "announcement" ], "description": "The notice kind.", "x-data-class": "operational" }, "title": { "type": "string", "description": "Its name, as the page shows it.", "x-data-class": "operational" }, "sent": { "type": "string", "description": "When it is sent.", "x-data-class": "operational" }, "fixed": { "type": "array", "items": { "type": "string" }, "description": "The recipients fixed in code, which nothing removes: org_admins (every admin of the org) and, for a deletion, deleted_user (the user a user deletion is about).", "x-data-class": "operational" }, "recipients": { "anyOf": [ { "type": "object" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Who the org also requires: {members: [{user_id, name}], outside: [email], slack: [{id, channel_name}]}. A Slack channel is its name and id, never its webhook URL.", "x-data-class": "personal" }, "cadence": { "type": [ "string", "null" ], "enum": [ "hourly", "daily", null ], "description": "The audit digest's cadence, hourly or daily; null for every other kind.", "x-data-class": "operational" } }, "required": [ "kind", "title", "sent", "fixed", "recipients", "cadence" ], "additionalProperties": false }, "maxItems": 6 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "Read an org's notification settings", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_onboarding_status", "title": "Get an org's onboarding checklist", "description": "Returns the org's onboarding checklist: each provisioning step (account, org, Clerk organization, admin invite, entitlements, welcome mail) with its state, then whether the org has an admin and a first unit, whether all of it is complete, and the first item that is not. Staff, the account's owner and an admin of the org read the same document. Changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose onboarding to read." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "provisioning_id": { "type": [ "string", "null" ], "description": "The provision_account ledger row; null for an org no provisioning made.", "x-data-class": "operational" }, "account_id": { "type": [ "string", "null" ], "description": "The account the org belongs to.", "x-data-class": "operational" }, "account": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The account step.", "x-data-class": "operational" }, "org": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The org step.", "x-data-class": "operational" }, "clerk_org": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The Clerk Organization.", "x-data-class": "operational" }, "admin_invite": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The first admin's invite.", "x-data-class": "operational" }, "entitlements": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The plan's entitlements.", "x-data-class": "operational" }, "welcome_mail": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The welcome mail.", "x-data-class": "operational" }, "first_admin": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "done once the org has an active member whose role template carries org.admin.", "x-data-class": "operational" }, "first_unit": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "done once the org has a unit.", "x-data-class": "operational" }, "complete": { "type": "boolean", "description": "Every item is done and the welcome is sent.", "x-data-class": "operational" }, "waiting_on": { "type": [ "string", "null" ], "description": "The first item that is not done, its state and what it waits for; null when complete.", "x-data-class": "operational" } }, "required": [ "org_id", "provisioning_id", "account_id", "account", "org", "clerk_org", "admin_invite", "entitlements", "welcome_mail", "first_admin", "first_unit", "complete", "waiting_on" ], "additionalProperties": false }, "annotations": { "title": "Get an org's onboarding checklist", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_purchase_order_suggestions", "title": "Get purchase order suggestions", "description": "From the org's own past purchase orders: for a supplier, the origin market and yard its purchase orders were most often picked up at, with how many name that yard; for a lane (an origin market and a destination market), the median days from P/U Date to the first gate-in at a depot in the destination market, with how many purchase orders had both. Each is null below 3 purchase orders, or when its inputs are not sent.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose purchase orders are read." }, "supplier_id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The supplier's contact id, as a purchase order names its supplier. Absent, supplier is null." }, "origin_market": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The lane's origin market. Absent, lane is null." }, "destination_market": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The lane's destination market. Absent, lane is null." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "supplier": { "type": [ "object", "null" ], "description": "{origin_market, origin_yard_id, origin_yard_name, purchase_orders}: the supplier's most frequent origin yard, its market and name, and how many of the org's purchase orders from the supplier name it. Null with no supplier_id or fewer than 3.", "x-data-class": "operational" }, "lane": { "type": [ "object", "null" ], "description": "{median_days, purchase_orders}: the median whole days from P/U Date to the first gate-in at a depot in the destination market, and how many purchase orders on the lane had both. Null without both markets or fewer than 3.", "x-data-class": "operational" } }, "required": [ "supplier", "lane" ], "additionalProperties": false }, "annotations": { "title": "Get purchase order suggestions", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_purge_readiness", "title": "Read whether an org's purge is ready", "description": "For an org whose deletion is scheduled: whether its purge may be approved and run, as a checklist of three lines, Countdown ended, Dry run and Approvals, each pass, fail or pending with one line of evidence. Answers the countdown, the current dry run (the newest; a newer one supersedes it) with what it counted, the approvals of that dry run, ready, and the codes that block. Refused for an org with no deletion scheduled. Trade HQ staff only.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose deletion is scheduled." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "active", "suspended", "deletion_scheduled", "purged" ], "description": "Where the org is in its life: deletion_scheduled whenever this answers.", "x-data-class": "operational" }, "countdown": { "type": "object", "description": "{purge_after, ended}: when the 30 day countdown ends, and whether it has.", "x-data-class": "operational" }, "dry_run": { "type": [ "object", "null" ], "properties": { "dry_run_id": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "ready", "failed", "stopped", "purged" ] }, "requested_at": { "type": "string", "format": "date-time" }, "requested_by": { "type": "string" }, "requested_by_name": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "counts": { "type": [ "object", "null" ] }, "failure": { "type": [ "string", "null" ] }, "stopped": { "type": [ "object", "null" ], "properties": { "at": { "type": "string", "format": "date-time" }, "code": { "type": "string", "enum": [ "purge_counts_changed" ] }, "detail": { "type": "string" } }, "required": [ "at", "code", "detail" ], "additionalProperties": false } }, "required": [ "dry_run_id", "status", "requested_at", "requested_by", "requested_by_name", "finished_at", "counts", "failure", "stopped" ], "additionalProperties": false, "description": "The round's current dry run, the newest: running, ready (counts written), failed, stopped (the purge job's recount differed; stopped says how) or purged. A dry run running past ten minutes reads failed. Null when none has been run.", "x-data-class": "operational" }, "approvals": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "needed": { "type": "integer", "enum": [ 1, 2 ] }, "principal": { "type": "boolean" }, "approvers": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "principal": { "type": "boolean" }, "approved_at": { "type": "string", "format": "date-time" } }, "required": [ "user_id", "name", "principal", "approved_at" ], "additionalProperties": false } } }, "required": [ "count", "needed", "principal", "approvers" ], "additionalProperties": false, "description": "The approvals of the current dry run while it is ready: one principal's is the quorum (needed 1), else two different staff's. Empty otherwise: approvals of a superseded or stopped dry run no longer count.", "x-data-class": "operational" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "countdown", "dry_run", "approvals" ] }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pass", "fail", "pending" ] }, "evidence": { "type": "string" } }, "required": [ "key", "label", "status", "evidence" ], "additionalProperties": false }, "description": "The checklist, in order: Countdown ended, Dry run, Approvals.", "x-data-class": "operational" }, "ready": { "type": "boolean", "description": "Every line passes: the purge job may run.", "x-data-class": "operational" }, "blocking": { "type": "array", "items": { "type": "string" }, "description": "What stands in the way, once each, in line order: countdown_running, purge_dry_run_required, purge_dry_run_running or purge_approvals_needed. Empty when ready.", "x-data-class": "operational" } }, "required": [ "org_id", "state", "countdown", "dry_run", "approvals", "checks", "ready", "blocking" ], "additionalProperties": false }, "annotations": { "title": "Read whether an org's purge is ready", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_report", "title": "Get a customer report", "description": "One customer report: everything list_reports answers for it, the reporter's own words, the page and record it was filed from, the report it reopens, who follows it, its timeline oldest first (each status and window change, note, reply, confirmation, reopen and follow, with its time) and the newest event the caller has seen. A private report is got only by its reporter and by staff; for anyone else it is report_not_found, as a report that does not exist is.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that filed the report." }, "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report's id, as list_reports answers it." } }, "required": [ "org_id", "report_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report's id: its ticket's id in the support tracker.", "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 that filed it.", "x-data-class": "operational" }, "ticket": { "type": "string", "description": "Its reference, CUS-n, as the customer quotes it.", "x-data-class": "operational" }, "org_name": { "type": [ "string", "null" ], "description": "That org's name.", "x-data-class": "operational" }, "title": { "type": "string", "description": "The first line of the reporter's own words.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "feedback", "problem", "question" ], "description": "Feedback, a problem or a question.", "x-data-class": "operational" }, "filed_via": { "type": "string", "enum": [ "app", "email", "staff" ], "description": "How it was filed: in the app, by email, or by staff for the customer.", "x-data-class": "operational" }, "reporter": { "anyOf": [ { "type": [ "object", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The member who filed it in the app, {user_id, name}; null when it was filed by email or by staff.", "x-data-class": "personal" }, "reporter_email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The sender's address, for a report filed by email.", "x-data-class": "personal" }, "impact": { "type": [ "string", "null" ], "enum": [ "blocking", "slowing", "suggestion", null ], "description": "How much it hurts, in the reporter's estimate.", "x-data-class": "operational" }, "private": { "type": "boolean", "description": "Whether only its reporter and staff see it.", "x-data-class": "operational" }, "reported_at": { "type": "string", "format": "date-time", "description": "When it was filed.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "received", "waiting_on_you", "planned", "fixed", "answered", "wont_fix", "duplicate" ], "description": "Where it stands.", "x-data-class": "operational" }, "status_at": { "type": "string", "format": "date-time", "description": "When it reached that status.", "x-data-class": "operational" }, "window": { "type": [ "string", "null" ], "enum": [ "next_release", "this_month", "later", null ], "description": "When a planned report is expected: next release, this month or later; null unless planned.", "x-data-class": "operational" }, "note": { "type": [ "string", "null" ], "description": "The latest note written for the customer.", "x-data-class": "operational" }, "release_note_url": { "type": [ "string", "null" ], "description": "The customer-facing release note of the fix, when it has one.", "x-data-class": "operational" }, "duplicate_of": { "type": [ "string", "null" ], "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report this one duplicates, when that report is this org's and the person asking may see it.", "x-data-class": "operational" }, "duplicate_status": { "type": [ "string", "null" ], "enum": [ "received", "waiting_on_you", "planned", "fixed", "answered", "wont_fix", "duplicate", null ], "description": "The status of the report this one duplicates.", "x-data-class": "operational" }, "fixed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the fix went live for the org.", "x-data-class": "operational" }, "days_to_fix": { "type": [ "integer", "null" ], "description": "Calendar days, Pacific time, from the day reported to the day fixed.", "x-data-class": "operational" }, "last_event_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When its timeline last changed.", "x-data-class": "operational" }, "following": { "type": "boolean", "description": "Whether the person asking follows it.", "x-data-class": "operational" }, "unread": { "type": "boolean", "description": "Whether it changed since the person asking last saw it.", "x-data-class": "operational" }, "text": { "type": "string", "description": "The reporter's own words, masked as filed; shown only inside the org.", "x-data-class": "operational" }, "page": { "type": [ "string", "null" ], "description": "The app page it was filed from.", "x-data-class": "operational" }, "record": { "type": [ "object", "null" ], "description": "The record the reporter was on, {kind, id}.", "x-data-class": "operational" }, "reopened_from": { "type": [ "string", "null" ], "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The fixed or answered report this one reports again as still broken.", "x-data-class": "operational" }, "followers": { "anyOf": [ { "type": "array", "items": { "type": "object" } }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Who follows it, [{user_id, name}], longest-standing first.", "x-data-class": "personal" }, "timeline": { "type": "array", "items": { "type": "object" }, "description": "Every event, oldest first: {event_id, at, kind} and, by kind, from and to (status, window), text (note), from, user_id, name and text (reply), user_id and name (confirmed, followed, unfollowed), report_id and ticket (reopened).", "x-data-class": "operational" }, "seen_through": { "type": [ "string", "null" ], "format": "date-time", "description": "The newest event the person asking has seen.", "x-data-class": "operational" } }, "required": [ "report_id", "org_id", "ticket", "org_name", "title", "kind", "filed_via", "reporter", "reporter_email", "impact", "private", "reported_at", "status", "status_at", "window", "note", "release_note_url", "duplicate_of", "duplicate_status", "fixed_at", "days_to_fix", "last_event_at", "following", "unread", "text", "page", "record", "reopened_from", "followers", "timeline", "seen_through" ], "additionalProperties": false }, "annotations": { "title": "Get a customer report", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_security_policy", "title": "Get an org's security settings", "description": "Answers the org's security settings, every section: sso, mfa, session, network and drift. Each carries its value, whether that is the section's default, and the version, who changed it and when (null for a section still at its default and never written). Every org holds the defaults until an admin changes a section.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose security settings to read." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "sections": { "type": "object", "properties": { "sso": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "sso", "mfa", "session", "network", "drift" ] }, "policy": { "oneOf": [ { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "required": { "type": "boolean" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "domain", "required", "bypass_until" ], "additionalProperties": false } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string" }, "jit": { "type": "boolean" }, "default_role_template": { "type": [ "string", "null" ] }, "idp_mfa_trusted": { "type": "boolean" }, "allow_manual_additions": { "type": "boolean" } }, "required": [ "connection_id", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions" ], "additionalProperties": false } } }, "required": [ "domains", "connections" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "required", "required_for_templates" ] }, "templates": { "type": "array", "items": { "type": "string" } }, "grace_days": { "type": "integer", "minimum": 0, "maximum": 30 }, "accept_idp_mfa": { "type": "boolean" } }, "required": [ "mode", "templates", "grace_days", "accept_idp_mfa" ], "additionalProperties": false }, { "type": "object", "properties": { "idle_minutes": { "type": "integer", "minimum": 15, "maximum": 1440 }, "absolute_hours": { "type": "integer", "minimum": 1, "maximum": 168 }, "reauth_on_role_change": { "type": "boolean" }, "single_session": { "type": "boolean" } }, "required": [ "idle_minutes", "absolute_hours", "reauth_on_role_change", "single_session" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "monitor", "enforce" ] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "cidr": { "type": "string" }, "label": { "type": "string" } }, "required": [ "cidr", "label" ], "additionalProperties": false } }, "applies_to": { "type": "string", "enum": [ "members", "api_keys", "both" ] } }, "required": [ "mode", "entries", "applies_to" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "quarantine", "alert_only" ] } }, "required": [ "action" ], "additionalProperties": false } ] }, "is_default": { "type": "boolean" }, "version": { "type": [ "integer", "null" ], "minimum": 1 }, "changed_by": { "type": [ "string", "null" ] }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "section", "policy", "is_default", "version", "changed_by", "changed_at" ], "additionalProperties": false }, "mfa": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "sso", "mfa", "session", "network", "drift" ] }, "policy": { "oneOf": [ { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "required": { "type": "boolean" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "domain", "required", "bypass_until" ], "additionalProperties": false } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string" }, "jit": { "type": "boolean" }, "default_role_template": { "type": [ "string", "null" ] }, "idp_mfa_trusted": { "type": "boolean" }, "allow_manual_additions": { "type": "boolean" } }, "required": [ "connection_id", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions" ], "additionalProperties": false } } }, "required": [ "domains", "connections" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "required", "required_for_templates" ] }, "templates": { "type": "array", "items": { "type": "string" } }, "grace_days": { "type": "integer", "minimum": 0, "maximum": 30 }, "accept_idp_mfa": { "type": "boolean" } }, "required": [ "mode", "templates", "grace_days", "accept_idp_mfa" ], "additionalProperties": false }, { "type": "object", "properties": { "idle_minutes": { "type": "integer", "minimum": 15, "maximum": 1440 }, "absolute_hours": { "type": "integer", "minimum": 1, "maximum": 168 }, "reauth_on_role_change": { "type": "boolean" }, "single_session": { "type": "boolean" } }, "required": [ "idle_minutes", "absolute_hours", "reauth_on_role_change", "single_session" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "monitor", "enforce" ] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "cidr": { "type": "string" }, "label": { "type": "string" } }, "required": [ "cidr", "label" ], "additionalProperties": false } }, "applies_to": { "type": "string", "enum": [ "members", "api_keys", "both" ] } }, "required": [ "mode", "entries", "applies_to" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "quarantine", "alert_only" ] } }, "required": [ "action" ], "additionalProperties": false } ] }, "is_default": { "type": "boolean" }, "version": { "type": [ "integer", "null" ], "minimum": 1 }, "changed_by": { "type": [ "string", "null" ] }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "section", "policy", "is_default", "version", "changed_by", "changed_at" ], "additionalProperties": false }, "session": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "sso", "mfa", "session", "network", "drift" ] }, "policy": { "oneOf": [ { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "required": { "type": "boolean" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "domain", "required", "bypass_until" ], "additionalProperties": false } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string" }, "jit": { "type": "boolean" }, "default_role_template": { "type": [ "string", "null" ] }, "idp_mfa_trusted": { "type": "boolean" }, "allow_manual_additions": { "type": "boolean" } }, "required": [ "connection_id", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions" ], "additionalProperties": false } } }, "required": [ "domains", "connections" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "required", "required_for_templates" ] }, "templates": { "type": "array", "items": { "type": "string" } }, "grace_days": { "type": "integer", "minimum": 0, "maximum": 30 }, "accept_idp_mfa": { "type": "boolean" } }, "required": [ "mode", "templates", "grace_days", "accept_idp_mfa" ], "additionalProperties": false }, { "type": "object", "properties": { "idle_minutes": { "type": "integer", "minimum": 15, "maximum": 1440 }, "absolute_hours": { "type": "integer", "minimum": 1, "maximum": 168 }, "reauth_on_role_change": { "type": "boolean" }, "single_session": { "type": "boolean" } }, "required": [ "idle_minutes", "absolute_hours", "reauth_on_role_change", "single_session" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "monitor", "enforce" ] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "cidr": { "type": "string" }, "label": { "type": "string" } }, "required": [ "cidr", "label" ], "additionalProperties": false } }, "applies_to": { "type": "string", "enum": [ "members", "api_keys", "both" ] } }, "required": [ "mode", "entries", "applies_to" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "quarantine", "alert_only" ] } }, "required": [ "action" ], "additionalProperties": false } ] }, "is_default": { "type": "boolean" }, "version": { "type": [ "integer", "null" ], "minimum": 1 }, "changed_by": { "type": [ "string", "null" ] }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "section", "policy", "is_default", "version", "changed_by", "changed_at" ], "additionalProperties": false }, "network": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "sso", "mfa", "session", "network", "drift" ] }, "policy": { "oneOf": [ { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "required": { "type": "boolean" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "domain", "required", "bypass_until" ], "additionalProperties": false } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string" }, "jit": { "type": "boolean" }, "default_role_template": { "type": [ "string", "null" ] }, "idp_mfa_trusted": { "type": "boolean" }, "allow_manual_additions": { "type": "boolean" } }, "required": [ "connection_id", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions" ], "additionalProperties": false } } }, "required": [ "domains", "connections" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "required", "required_for_templates" ] }, "templates": { "type": "array", "items": { "type": "string" } }, "grace_days": { "type": "integer", "minimum": 0, "maximum": 30 }, "accept_idp_mfa": { "type": "boolean" } }, "required": [ "mode", "templates", "grace_days", "accept_idp_mfa" ], "additionalProperties": false }, { "type": "object", "properties": { "idle_minutes": { "type": "integer", "minimum": 15, "maximum": 1440 }, "absolute_hours": { "type": "integer", "minimum": 1, "maximum": 168 }, "reauth_on_role_change": { "type": "boolean" }, "single_session": { "type": "boolean" } }, "required": [ "idle_minutes", "absolute_hours", "reauth_on_role_change", "single_session" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "monitor", "enforce" ] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "cidr": { "type": "string" }, "label": { "type": "string" } }, "required": [ "cidr", "label" ], "additionalProperties": false } }, "applies_to": { "type": "string", "enum": [ "members", "api_keys", "both" ] } }, "required": [ "mode", "entries", "applies_to" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "quarantine", "alert_only" ] } }, "required": [ "action" ], "additionalProperties": false } ] }, "is_default": { "type": "boolean" }, "version": { "type": [ "integer", "null" ], "minimum": 1 }, "changed_by": { "type": [ "string", "null" ] }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "section", "policy", "is_default", "version", "changed_by", "changed_at" ], "additionalProperties": false }, "drift": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "sso", "mfa", "session", "network", "drift" ] }, "policy": { "oneOf": [ { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "required": { "type": "boolean" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "domain", "required", "bypass_until" ], "additionalProperties": false } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string" }, "jit": { "type": "boolean" }, "default_role_template": { "type": [ "string", "null" ] }, "idp_mfa_trusted": { "type": "boolean" }, "allow_manual_additions": { "type": "boolean" } }, "required": [ "connection_id", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions" ], "additionalProperties": false } } }, "required": [ "domains", "connections" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "required", "required_for_templates" ] }, "templates": { "type": "array", "items": { "type": "string" } }, "grace_days": { "type": "integer", "minimum": 0, "maximum": 30 }, "accept_idp_mfa": { "type": "boolean" } }, "required": [ "mode", "templates", "grace_days", "accept_idp_mfa" ], "additionalProperties": false }, { "type": "object", "properties": { "idle_minutes": { "type": "integer", "minimum": 15, "maximum": 1440 }, "absolute_hours": { "type": "integer", "minimum": 1, "maximum": 168 }, "reauth_on_role_change": { "type": "boolean" }, "single_session": { "type": "boolean" } }, "required": [ "idle_minutes", "absolute_hours", "reauth_on_role_change", "single_session" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "monitor", "enforce" ] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "cidr": { "type": "string" }, "label": { "type": "string" } }, "required": [ "cidr", "label" ], "additionalProperties": false } }, "applies_to": { "type": "string", "enum": [ "members", "api_keys", "both" ] } }, "required": [ "mode", "entries", "applies_to" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "quarantine", "alert_only" ] } }, "required": [ "action" ], "additionalProperties": false } ] }, "is_default": { "type": "boolean" }, "version": { "type": [ "integer", "null" ], "minimum": 1 }, "changed_by": { "type": [ "string", "null" ] }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "section", "policy", "is_default", "version", "changed_by", "changed_at" ], "additionalProperties": false } }, "required": [ "sso", "mfa", "session", "network", "drift" ], "additionalProperties": false, "description": "Every section, keyed by its name.", "x-data-class": "operational" } }, "required": [ "org_id", "sections" ], "additionalProperties": false }, "annotations": { "title": "Get an org's security settings", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_supplier_purchase_order", "title": "Get a purchase order as its supplier", "description": "For the supplier of an org's purchase order (a guest of the org in the seller seat, or a member of the supplier's own Trade HQ org): the purchase order as sent, with the buyer's name, when it was placed, the depot it is delivered to and the lines ordered with their unit prices; the confirmation, if posted, with every line that differs from the order; every update posted; the units confirmed and the unit numbers submitted; and what to do next. Anyone else is refused as if the purchase order did not exist.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that owns the purchase order: the buyer." }, "document_kind": { "type": "string", "enum": [ "asset_intake", "order" ], "description": "asset_intake: a purchase order. An order is refused." }, "document_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The purchase order's id." } }, "required": [ "org_id", "document_kind", "document_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The buyer.", "x-data-class": "operational" }, "document_id": { "type": "string", "description": "The purchase order.", "x-data-class": "operational" }, "reference": { "type": "string", "description": "The purchase order's PO number, else its booking number, else its id.", "x-data-class": "operational" }, "status": { "type": "string", "description": "pending, in_progress, completed or cancelled.", "x-data-class": "operational" }, "buyer_name": { "type": "string", "description": "The buyer org's name.", "x-data-class": "operational" }, "placed_at": { "type": "string", "format": "date-time", "description": "When the buyer placed it.", "x-data-class": "operational" }, "delivery_depot": { "type": [ "string", "null" ], "description": "The depot the units are delivered to, by name; null when none is set.", "x-data-class": "operational" }, "purchase_order_type": { "type": [ "string", "null" ], "description": "The purchase order's type.", "x-data-class": "operational" }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The supplier party the caller reads as.", "x-data-class": "operational" }, "party_name": { "type": "string", "description": "Its name.", "x-data-class": "operational" }, "ordered_lines": { "type": "array", "items": { "type": "object" }, "description": "The lines as the buyer ordered them, in order: {size, type, condition, color, quantity, unit_price, currency}, unit_price a decimal string or null.", "x-data-class": "operational" }, "confirmation": { "type": [ "object", "null" ], "description": "The confirmation the party posted, or null: {post_id, lines (each {size, type, condition, color, quantity, unit_price}), changes (each {line, fields, ordered, confirmed}: a confirmed line that differs from the ordered line at its position, fields naming what changed), pro_forma, vendor_eta, posted_at, posted_by_name, applied, ingest_document_id}. applied is whether the buyer has taken it up.", "x-data-class": "operational" }, "posts": { "type": "array", "items": { "type": "object" }, "description": "Every post the party made on the purchase order, newest first: {post_id, kind (confirmation, production_status or serial_batch), status (a production status, else null), vendor_eta, note, unit_count, posted_at}.", "x-data-class": "operational" }, "units": { "type": "object", "description": "{confirmed, submitted, numbers}: the units confirmed, how many have a unit number, and each number as {unit_number, line, size, type, condition, color, submitted_at}, in the order submitted.", "x-data-class": "operational" }, "next_step": { "type": "string", "enum": [ "confirm_purchase_order", "submit_serial_batch", "post_production_status", "nothing" ], "description": "What the supplier does next: the capability that does it, or nothing once the purchase order is closed or the buyer has applied the confirmation.", "x-data-class": "operational" }, "vocabulary": { "type": "object", "description": "The values a confirmed line's size, type, condition and color are held to: {size, type, condition, color}, each a list of {value, label}.", "x-data-class": "operational" } }, "required": [ "org_id", "document_id", "reference", "status", "buyer_name", "placed_at", "delivery_depot", "purchase_order_type", "party_id", "party_name", "ordered_lines", "confirmation", "posts", "units", "next_step", "vocabulary" ], "additionalProperties": false }, "annotations": { "title": "Get a purchase order as its supplier", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_tenant_health", "title": "Get tenant health", "description": "Reads one org's health over the last 30 days: when a member last signed in, how many members were active, how many documents it ingested and what share of them failed, its plan tier and member count, and how many exceptions are open. The error rate is the ingest error rate, and it is null when nothing was ingested. Open exceptions are null until the exception store exists. Staff only.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org to read." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "name": { "type": "string", "description": "The org's name.", "x-data-class": "operational" }, "org_type": { "type": [ "string", "null" ], "enum": [ "internal", "demo", "customer", "synthetic", "system", null ], "description": "The org's type (TRA-234); null for a ported org nothing has typed yet.", "x-data-class": "operational" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account the org belongs to (a twin reads its live org's); null when it has none.", "x-data-class": "operational" }, "window_days": { "type": "integer", "description": "The window every 30-day figure covers.", "x-data-class": "operational" }, "last_login_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The newest sign-in by any member of the org; null when none has signed in.", "x-data-class": "operational" }, "member_count": { "type": "integer", "description": "The org's members.", "x-data-class": "operational" }, "active_users_30d": { "type": "integer", "description": "Members with a session seen in the window.", "x-data-class": "operational" }, "ingest_documents_30d": { "type": "integer", "description": "Documents the org ingested in the window, failed ones included.", "x-data-class": "operational" }, "ingest_failed_30d": { "type": "integer", "description": "Of those, the documents whose ingest failed.", "x-data-class": "operational" }, "error_rate": { "type": [ "number", "null" ], "description": "ingest_failed_30d over ingest_documents_30d, from 0 to 1; null when nothing was ingested.", "x-data-class": "operational" }, "plan_tier": { "type": [ "string", "null" ], "description": "The org's plan tier; null until TRA-238 sets one.", "x-data-class": "operational" }, "entitlements_defined": { "type": "boolean", "description": "Whether tier-to-capability data exists to measure use against. False until TRA-238.", "x-data-class": "operational" }, "open_exceptions": { "type": [ "integer", "null" ], "description": "Exceptions for the org that are open, waiting or escalated; null until TRA-294's store exists.", "x-data-class": "operational" } }, "required": [ "org_id", "name", "org_type", "account_id", "window_days", "last_login_at", "member_count", "active_users_30d", "ingest_documents_30d", "ingest_failed_30d", "error_rate", "plan_tier", "entitlements_defined", "open_exceptions" ], "additionalProperties": false }, "annotations": { "title": "Get tenant health", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_test_twin", "title": "Get an org's test twin", "description": "Returns the test twin of an org: the org of its own that test mode acts in, whose members, roles, units and settings mirror the live org and whose business data is its own. Accepts the live org's id or the twin's and answers the same. Says whether the twin is in line with the live org now, and which of those four it differs in if not. Changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org, or its twin." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The live org.", "x-data-class": "operational" }, "twin_org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "Its test twin, the org test mode and sk_test_ keys act in.", "x-data-class": "operational" }, "twin_name": { "type": "string", "description": "The twin's name.", "x-data-class": "operational" }, "org_type": { "type": "string", "enum": [ "internal", "demo", "customer", "synthetic", "system" ], "description": "The type the twin shares with its live org.", "x-data-class": "operational" }, "in_sync": { "type": "boolean", "description": "Whether the twin's members, roles, units and settings equal the live org's now.", "x-data-class": "operational" }, "drift": { "type": [ "string", "null" ], "description": "The classes the twin differs in, comma separated (roles, members, units, settings); null when in sync.", "x-data-class": "operational" } }, "required": [ "org_id", "twin_org_id", "twin_name", "org_type", "in_sync", "drift" ], "additionalProperties": false }, "annotations": { "title": "Get an org's test twin", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_view", "title": "Open a saved view", "description": "Opens a saved view the caller may read: re-runs its stored call (capability and args) as the caller, now, under the caller's own permissions and data policy, never the owner's, and answers the view and the call's first page. A view stores no rows, so nothing it answers is older than the open. A view the caller may not read is unknown_view; a stored call the caller may not make is view_call_refused.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the view is in." }, "view_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The view to open: a UUID, or system: for a system view." } }, "required": [ "org_id", "view_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "view": { "type": "object", "description": "The view, as list_saved_views answers it.", "x-data-class": "operational" }, "result": { "type": "object", "description": "What the view's capability answers the caller for its stored call, now: its first page, masked by the caller's data policy.", "x-data-class": "operational" } }, "required": [ "view", "result" ], "additionalProperties": false }, "annotations": { "title": "Open a saved view", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "get_view_default", "title": "Get the view in force", "description": "Answers which saved view a screen opens with for the caller (mode sales: the Sales catalog), and why: the view they opened (view_id), else their own default, else the org default an org admin set, else none, the four fixed keys (market, size, type, condition) with nothing split. It answers the view's capability and args, ready to call, and both defaults while the caller may open them. A default whose view the caller can no longer open is passed over.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose views they are." }, "mode": { "type": "string", "enum": [ "sales" ], "description": "Which screen's default: sales, the Sales catalog." }, "view_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The saved view the caller opened, which is in force over any default." } }, "required": [ "org_id", "mode" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sales" ], "description": "The mode: sales, the Sales catalog.", "x-data-class": "operational" }, "in_force": { "type": "string", "enum": [ "opened", "mine", "org", "fixed" ], "description": "Which view applies: opened (the saved view the caller opened), mine (their own default), org (the org default an org admin set) or fixed (none: the four fixed keys alone).", "x-data-class": "operational" }, "view_id": { "type": [ "string", "null" ], "description": "The view in force; null when fixed.", "x-data-class": "operational" }, "title": { "type": [ "string", "null" ], "description": "Its title; null when fixed.", "x-data-class": "operational" }, "capability": { "type": "string", "enum": [ "list_inventory", "summarize_catalog", "list_catalog" ], "description": "The capability the screen calls: the view's, or the mode's own when fixed.", "x-data-class": "operational" }, "args": { "type": "object", "properties": { "filters": { "type": "object", "description": "The list's filters input, as the capability declares it." }, "q": { "type": "string", "description": "The list's q input." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "One of the called capability's sort keys." }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "description": "The list's sort input: one key and its direction." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The list's fields input." }, "limit": { "type": "integer", "description": "The list's limit input." }, "split_by": { "type": "array", "items": { "type": "string" }, "description": "A Sales catalog view's split_by, in the order the attributes were switched on (summarize_catalog's input)." }, "slice": { "type": "string", "enum": [ "owned", "partner", "supplier", "all" ], "description": "A Sales catalog view's source slice: owned, partner, supplier or all." }, "layout": { "type": "string", "enum": [ "cards", "rows" ], "description": "A Sales catalog view's layout: cards or rows." } }, "additionalProperties": false, "description": "The arguments in force: the view's, or when fixed nothing split, every source and cards.", "x-data-class": "operational" }, "grouped_by": { "type": "array", "items": { "type": "string" }, "description": "The keys every group is grouped by, whatever view is in force: market, size, type and condition.", "x-data-class": "operational" }, "default_id": { "type": [ "string", "null" ], "description": "The default in force, when it is mine or org; null when opened or fixed.", "x-data-class": "operational" }, "user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Whose default is in force: the caller's when mine; null when org, opened or fixed.", "x-data-class": "operational" }, "set_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who set the default in force (the org admin, for the org's); null when opened or fixed.", "x-data-class": "operational" }, "set_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the default in force was set; null when opened or fixed.", "x-data-class": "operational" }, "my_default_view_id": { "type": [ "string", "null" ], "description": "The caller's own default, while they may open it; null when none (reset to the org default).", "x-data-class": "operational" }, "org_default_view_id": { "type": [ "string", "null" ], "description": "The org default, while the caller may open it; null when none (reset to the fixed keys).", "x-data-class": "operational" } }, "required": [ "mode", "in_force", "view_id", "title", "capability", "args", "grouped_by", "default_id", "user_id", "set_by", "set_at", "my_default_view_id", "org_default_view_id" ], "additionalProperties": false }, "annotations": { "title": "Get the view in force", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "grant_capability", "title": "Grant a capability to an org", "description": "Gives one org one capability outside its plan tier: as a grant (any capability, for a design partner or a deal) or as an add-on (bought on top; only a capability sold as one). The grant records who gave it, how, when and why, and may expire on a date. From then the org and its test twin have the capability, and no other org does. A grant is permanent; it ends by revoke_capability_grant or its expiry. A test twin, a retired capability and an unknown name are refused. Send an Idempotency-Key header: a retry with the same key and inputs returns the same grant and records nothing new.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The live org to give it to." }, "capability_id": { "type": "string", "minLength": 1, "maxLength": 63, "description": "The capability, by its registry name (as list_permissions and capabilities.json name it)." }, "kind": { "type": "string", "enum": [ "grant", "add_on" ], "description": "grant: given outside the tier. add_on: bought on top, only a capability sold as an add-on." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why it is given: the deal, the partner, the ticket. Kept with the grant." }, "expires_on": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The day it stops counting, from 00:00 UTC: YYYY-MM-DD, after today's date in UTC. Absent: it does not expire." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "capability_id", "kind", "reason" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The grant'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 was given to.", "x-data-class": "operational" }, "capability_id": { "type": "string", "description": "The capability, by its registry name.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "grant", "add_on" ], "description": "grant, given outside the tier, or add_on, bought on top.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ], "description": "active while it counts; expired past expires_at; revoked once revoked.", "x-data-class": "operational" }, "reason": { "type": "string", "description": "Why it was given.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops counting; null for never.", "x-data-class": "operational" }, "granted_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who gave it.", "x-data-class": "operational" }, "granted_via": { "type": "string", "description": "The principal kind it came through: clerk_user, or mcp_subject for an agent.", "x-data-class": "operational" }, "granted_client": { "type": [ "string", "null" ], "description": "The OAuth client an agent acted through; null otherwise.", "x-data-class": "operational" }, "granted_at": { "type": "string", "format": "date-time", "description": "When it was given.", "x-data-class": "operational" }, "revoked_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who revoked it; null while it is not revoked.", "x-data-class": "operational" }, "revoked_via": { "type": [ "string", "null" ], "description": "The principal kind the revocation came through.", "x-data-class": "operational" }, "revoked_client": { "type": [ "string", "null" ], "description": "The OAuth client an agent revoked it through.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked.", "x-data-class": "operational" }, "revoke_reason": { "type": [ "string", "null" ], "description": "Why it was revoked.", "x-data-class": "operational" } }, "required": [ "org_grant_id", "org_id", "capability_id", "kind", "status", "reason", "expires_at", "granted_by", "granted_via", "granted_client", "granted_at", "revoked_by", "revoked_via", "revoked_client", "revoked_at", "revoke_reason" ], "additionalProperties": false }, "annotations": { "title": "Grant a capability to an org", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "grant_staff_role", "title": "Grant a staff role", "description": "Gives a member of Trade HQ's Internal org one of the four staff roles: staff_read, staff_ops, staff_provision or staff_finance. Someone who is not a member of the Internal org is refused: invite them into it first. A deactivated or anonymized user is refused. Granting a role they already hold changes nothing. Staff with staff.ops only.", "inputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The member of the Internal org to make staff." }, "role_id": { "type": "string", "enum": [ "staff_read", "staff_ops", "staff_provision", "staff_finance" ], "description": "The staff role to grant." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "user_id", "role_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The staff member.", "x-data-class": "operational" }, "role_id": { "type": "string", "enum": [ "staff_read", "staff_ops", "staff_provision", "staff_finance" ], "description": "The staff role they hold.", "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 Internal org it is held in.", "x-data-class": "operational" }, "granted_by": { "type": "string", "description": "Who granted it.", "x-data-class": "operational" }, "granted_at": { "type": "string", "format": "date-time", "description": "When it was granted.", "x-data-class": "operational" } }, "required": [ "user_id", "role_id", "org_id", "granted_by", "granted_at" ], "additionalProperties": false }, "annotations": { "title": "Grant a staff role", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "grant_unit_role", "title": "Give access on a unit", "description": "Gives a member of the org a role template on one unit. It reaches every unit beneath that unit and adds to the member's org role. A member holds one role per unit, so giving another replaces it. You must administer the unit (an org admin, or admin on it or a unit above it), you can give only a role whose every permission you hold there, and a role carrying an org-wide permission (role.manage, api_key.read) or a Counterparty role cannot be given on a unit. You cannot change your own access. Giving the role the member already holds there changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose tree the unit is in." }, "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The unit the role is given on." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The member who will hold it." }, "role_template_id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The role template: a shipped id (admin, ops, ...) or one of the org's own (RT...)." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "unit_id", "user_id", "role_template_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The unit it is held on.", "x-data-class": "operational" }, "unit_name": { "type": "string", "description": "The unit's name.", "x-data-class": "operational" }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who holds it.", "x-data-class": "operational" }, "name": { "anyOf": [ { "type": "string" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their name, or their address when they have none.", "x-data-class": "personal" }, "role_template_id": { "type": "string", "description": "The role template it carries.", "x-data-class": "operational" }, "role_title": { "type": "string", "description": "That template's name.", "x-data-class": "operational" }, "role": { "type": "string", "enum": [ "admin", "user" ], "description": "admin when the template carries org.admin, else user.", "x-data-class": "operational" }, "previous_role_template_id": { "type": [ "string", "null" ], "description": "The template it replaced on this unit; null for a new grant.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who gave it.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" } }, "required": [ "org_id", "unit_id", "unit_name", "user_id", "name", "role_template_id", "role_title", "role", "previous_role_template_id", "created_by", "created_at" ], "additionalProperties": false }, "annotations": { "title": "Give access on a unit", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "hide_catalog_photo", "title": "Hide a catalog photo", "description": "Hides one of the org's unit photos from the sales catalog, or shows it again with hidden false. A hidden photo is never chosen for a catalog group: the next newest photo of a sound unit shows instead, or the drawn outline when there is none. The photo itself is kept. Setting what a photo already is changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose catalog it is." }, "photo_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The photo, as summarize_catalog names it." }, "hidden": { "type": "boolean", "description": "true hides it from the catalog; false shows it again." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "photo_id", "hidden" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "photo_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The photo.", "x-data-class": "operational" }, "container": { "type": "string", "description": "The ISO 6346 container number of the unit it shows.", "x-data-class": "operational" }, "taken_at": { "type": "string", "format": "date-time", "description": "When it was taken.", "x-data-class": "operational" }, "origin": { "type": "string", "enum": [ "depot_report", "gate", "manual" ], "description": "Where it came from: a depot report, gate activity or a person.", "x-data-class": "operational" }, "recorded_by": { "type": "string", "description": "Who recorded it: user:, api_key: or machine:.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When Trade HQ recorded it.", "x-data-class": "operational" }, "hidden": { "type": "boolean", "description": "Whether it is hidden from the catalog.", "x-data-class": "operational" }, "hidden_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was hidden; null while it is shown.", "x-data-class": "operational" }, "hidden_by": { "type": [ "string", "null" ], "description": "The user_id of the org admin who hid it.", "x-data-class": "operational" } }, "required": [ "photo_id", "container", "taken_at", "origin", "recorded_by", "created_at", "hidden", "hidden_at", "hidden_by" ], "additionalProperties": false }, "annotations": { "title": "Hide a catalog photo", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "import_units", "title": "Import units from a CSV", "description": "Creates many units at once from a CSV file, and claims each depot's BIC Facility Code (BFC) in the same pass. The header names the columns: ref, kind and name are required; parent_ref (another row's ref) and bfc are optional. Rows with no parent_ref go beneath parent_id, or become roots when it is absent. A depot is a leaf, and a BFC goes only on a depot. The file is checked whole and written whole: any bad row, or a BFC another org has claimed, refuses it and nothing is created. Send an Idempotency-Key header: under the same key, units already created exactly as the file says are reported and left alone and only the file's new rows are created, so a retry creates nothing and a file that extends an earlier one completes it; a row that differs from what the key created is refused.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose tree the units join." }, "parent_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "Where rows with no parent_ref go. Absent, they become roots." }, "csv": { "type": "string", "minLength": 1, "maxLength": 1000000, "description": "The file: a header row, then one row per unit. Columns ref, kind, name, and optionally parent_ref and bfc." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "csv" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "import_id": { "type": "string", "description": "This import's id, derived from the Idempotency-Key.", "x-data-class": "operational" }, "units_created": { "type": "integer", "description": "The units this call created.", "x-data-class": "operational" }, "units_existing": { "type": "integer", "description": "The file's units this key had already created, exactly as the file says; left alone.", "x-data-class": "operational" }, "depots_claimed": { "type": "integer", "description": "The BFCs this call claimed for the org in the registry, one per depot.claimed event.", "x-data-class": "operational" }, "bfcs_set": { "type": "integer", "description": "The units this call created carrying a BFC, the org's own claims included.", "x-data-class": "operational" }, "unit_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id" }, "description": "Every unit of the file, created now or before, in the file's row order.", "x-data-class": "operational" } }, "required": [ "import_id", "units_created", "units_existing", "depots_claimed", "bfcs_set", "unit_ids" ], "additionalProperties": false }, "annotations": { "title": "Import units from a CSV", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "import_users", "title": "Import users", "description": "Invites a list of up to 500 people into an org in one step, each exactly as invite_user would, optionally all with one role template. The whole list is invited or none of it is. Answers how many were invited, already invited or already members, and which addresses were refused because they belong to a deactivated user. Send an Idempotency-Key header: a retry with the same key and list returns the first answer and invites nobody again.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org to invite them into." }, "invitees": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "properties": { "email": { "type": "string", "minLength": 3, "maxLength": 254, "pattern": "^[\\t\\n\\u000b\\f\\r \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]*[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+(\\.[A-Za-z]{2,})+[\\t\\n\\u000b\\f\\r \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]*$", "format": "email" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "email" ], "additionalProperties": false }, "description": "The people: each an email address and, optionally, a full name." }, "role_template_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The role template every new invitee will hold once they join: shipped or this org's own, and carrying nothing your role does not." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "invitees" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "import_id": { "type": "string", "description": "The import.", "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.", "x-data-class": "operational" }, "invited": { "type": "integer", "description": "New invites, each with its invite email.", "x-data-class": "operational" }, "already_invited": { "type": "integer", "description": "Addresses with a pending invite already; nothing written.", "x-data-class": "operational" }, "already_members": { "type": "integer", "description": "Addresses that are members already.", "x-data-class": "operational" }, "refused": { "type": "array", "items": { "type": "string" }, "description": "Addresses of deactivated users, not invited.", "x-data-class": "operational" } }, "required": [ "import_id", "org_id", "invited", "already_invited", "already_members", "refused" ], "additionalProperties": false }, "annotations": { "title": "Import users", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "invite_guest", "title": "Invite a guest from a document", "description": "Invites the person behind one of a document's parties, by email address, as a guest of the org that owns the document. A guest signs in with their own login and reads the documents their party holds a seat on in that org, and nothing else of it: a lessee (a forwarder) reads its leases, a seller (a supplier) its purchase orders. Inviting the same person again for the same party changes nothing. A current member of the org, a guest of it for another party, a deactivated user, and a party that is already a Trade HQ org are refused. An optional expires_on, from today to 365 days out, is the guest's last day of access; from the next day they are refused as a revoked guest is.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that owns the document, and that the guest becomes a guest of." }, "document_kind": { "type": "string", "enum": [ "asset_intake", "order" ], "description": "The document the invitation is made from: an order (a lease) for a lessee, an asset_intake (a purchase order) for a seller." }, "document_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The document's id in that table." }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The party on the document the guest is, from the shared directory." }, "seat": { "type": "string", "enum": [ "lessee", "seller" ], "description": "The seat that party holds on the document: lessee or seller." }, "email": { "type": "string", "minLength": 3, "maxLength": 254, "pattern": "^[\\t\\n\\u000b\\f\\r \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]*[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+(\\.[A-Za-z]{2,})+[\\t\\n\\u000b\\f\\r \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]*$", "format": "email", "description": "The guest's email address. It becomes their sign-in." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Their full name, set only if they have none yet." }, "expires_on": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The guest's last day of access, a UTC date from today to 365 days out. Absent, their access does not expire." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "document_kind", "document_id", "party_id", "seat", "email" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The guest.", "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 they are a guest of.", "x-data-class": "operational" }, "email": { "anyOf": [ { "type": "string" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The address, cleaned.", "x-data-class": "personal" }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The party they are.", "x-data-class": "operational" }, "seat": { "type": "string", "enum": [ "lessee", "seller" ], "description": "Their seat.", "x-data-class": "operational" }, "role_id": { "type": "string", "description": "The Counterparty template they hold: counterparty_.", "x-data-class": "operational" }, "shape": { "type": "string", "enum": [ "forwarder", "supplier" ], "description": "What their view shows: forwarder (leases) or supplier (purchase orders).", "x-data-class": "operational" }, "expires_on": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "Their last day of access, or null for none. A repeat invitation answers the expiry the guest holds.", "x-data-class": "operational" } }, "required": [ "user_id", "org_id", "email", "party_id", "seat", "role_id", "shape", "expires_on" ], "additionalProperties": false }, "annotations": { "title": "Invite a guest from a document", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "invite_user", "title": "Invite a user", "description": "Invites a person, by email address, into an org, optionally with a role template. Records the invite and the invite email as an outbound document; the person gets a login (no password) and the email once identity-provisioner has run. Inviting an address that already has a pending invite into the org changes nothing. A current member, or a deactivated user, is refused.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org to invite them into." }, "email": { "type": "string", "minLength": 3, "maxLength": 254, "pattern": "^[\\t\\n\\u000b\\f\\r \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]*[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+(\\.[A-Za-z]{2,})+[\\t\\n\\u000b\\f\\r \\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]*$", "format": "email", "description": "Their email address. It becomes their sign-in." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Their full name, used in the email and set only if they have none yet." }, "role_template_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The role template they will hold once they join: a shipped template or this org's own, carrying nothing your role does not. Recorded with the invite; it grants nothing until they are a member." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "email" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The invitee.", "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.", "x-data-class": "operational" }, "email": { "anyOf": [ { "type": "string" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The address, cleaned.", "x-data-class": "personal" }, "document_id": { "type": [ "string", "null" ], "description": "The invite email's outbound document; null only for an invite made before TRA-319, which has none.", "x-data-class": "operational" } }, "required": [ "user_id", "org_id", "email", "document_id" ], "additionalProperties": false }, "annotations": { "title": "Invite a user", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "list_access_reviews", "title": "List access reviews", "description": "Lists the org's access reviews, newest first: each one's name, what it covers, when it is due, its status (open, overdue or closed), how many items it holds and how many are decided, and once closed who closed it and its evidence document. With review_id, answers that one review with its items: who or what holds access, the access it held when the review began, its decision, and whether it is your own row, which another admin decides.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose access reviews to list." }, "review_id": { "type": "string", "minLength": 1, "maxLength": 14, "description": "One review to answer, with its items." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "review_id": { "type": "string", "description": "The review'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 whose access it reviews.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What it is called.", "x-data-class": "operational" }, "covers": { "type": "array", "items": { "type": "string" }, "description": "What it covers, of members, guests, service_accounts, api_keys and staff_grants, in that order.", "x-data-class": "operational" }, "due_at": { "type": "string", "format": "date-time", "description": "When it is due: the end (UTC) of its due date.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "open", "overdue", "closed" ], "description": "open; overdue, an open review past due; or closed.", "x-data-class": "operational" }, "total": { "type": "integer", "minimum": 0, "description": "How many items it asks about.", "x-data-class": "operational" }, "decided": { "type": "integer", "minimum": 0, "description": "How many of them are decided.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who started it.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was started.", "x-data-class": "operational" }, "closed_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who closed it.", "x-data-class": "operational" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was closed.", "x-data-class": "operational" }, "evidence_document_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The evidence document closing it wrote: who decided what, and when.", "x-data-class": "operational" }, "items": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "item_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The item's id.", "x-data-class": "operational" }, "review_id": { "type": "string", "description": "The review it belongs to.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "member", "guest", "service_account", "api_key", "staff_grant" ], "description": "member, guest, service_account, api_key or staff_grant.", "x-data-class": "operational" }, "subject_id": { "type": "string", "description": "Whose access: a user id, a service account id, a key id or a staff grant's id.", "x-data-class": "operational" }, "subject_label": { "anyOf": [ { "type": "string" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "What a reviewer reads for it: an email, or a service account's or key's name.", "x-data-class": "personal" }, "role": { "type": [ "string", "null" ], "description": "The access it held when the review began: a role template, a key's service account, or a staff grant's level.", "x-data-class": "operational" }, "last_active_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was last seen acting before the review began, where known.", "x-data-class": "operational" }, "decision": { "type": [ "string", "null" ], "enum": [ "keep", "change_role", "revoke", null ], "description": "keep, change_role or revoke; null until decided.", "x-data-class": "operational" }, "new_role_template_id": { "type": [ "string", "null" ], "description": "The role template a change_role decision gave the member.", "x-data-class": "operational" }, "decided_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who decided it.", "x-data-class": "operational" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was decided.", "x-data-class": "operational" }, "own": { "type": "boolean", "description": "Whether it is the caller's own row, which another admin decides.", "x-data-class": "operational" } }, "required": [ "item_id", "review_id", "kind", "subject_id", "subject_label", "own" ], "additionalProperties": false }, "description": "Its items, when one review is asked for (review_id); null otherwise.", "x-data-class": "operational" } }, "required": [ "review_id", "org_id", "name", "covers", "due_at", "status", "total", "decided", "created_by", "created_at", "closed_by", "closed_at", "evidence_document_id", "items" ], "additionalProperties": false }, "maxItems": 1000 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List access reviews", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_account_members", "title": "List an account's role holders", "description": "Lists who holds a role in an account, owners first, a page at a time: each person's name, email address, account role, how many of the account's entities they belong to, and who added them when. With candidates (an owner or staff only), lists instead the people an owner may add: members of one of the account's entities who hold no account role. Filters by a case-insensitive substring of the name or address.", "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account whose role holders to list." }, "candidates": { "type": "boolean", "description": "List the people who may be added instead: members of one of the account's entities holding no account role. An owner or staff only." }, "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "A case-insensitive substring of the name or email address." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "minLength": 3, "maxLength": 22, "description": "The previous page's next_after." } }, "required": [ "account_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The person.", "x-data-class": "operational" }, "name": { "type": [ "string", "null" ], "description": "Their name.", "x-data-class": "operational" }, "email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their address; null once anonymized.", "x-data-class": "personal" }, "role": { "type": [ "string", "null" ], "enum": [ "owner", "member", null ], "description": "Their account role; null for a candidate.", "x-data-class": "operational" }, "entity_count": { "type": "integer", "description": "How many of the account's entities they are a member of.", "x-data-class": "operational" }, "entity_total": { "type": "integer", "description": "How many entities the account has.", "x-data-class": "operational" }, "added_by": { "type": [ "string", "null" ], "description": "Who gave them the role: a user id, or declaration:. Null for a candidate.", "x-data-class": "operational" }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When they were given it. Null for a candidate.", "x-data-class": "operational" } }, "required": [ "user_id", "name", "email", "role", "entity_count", "entity_total", "added_by", "added_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 }, "annotations": { "title": "List an account's role holders", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_accounts", "title": "List accounts", "description": "Lists accounts, ordered by account id, a page at a time. Filters by a case-insensitive substring of the name. Each account carries its id, name, when it was created and how many orgs belong to it. Staff see every account; naming an org narrows the list to the account that holds it. An org admin reads only the account that holds its own org, named by org id, and is refused any other org and any list that names no org.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "A case-insensitive substring of the account's name." }, "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "Only the account that holds this org; an org in no account is an empty page. An org admin names its own org here, and is refused without it." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The previous page's next_after." } }, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account's id.", "x-data-class": "operational" }, "name": { "type": "string", "description": "The account's name.", "x-data-class": "operational" }, "org_count": { "type": "integer", "description": "How many orgs belong to it.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created.", "x-data-class": "operational" } }, "required": [ "account_id", "name", "org_count", "created_at" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List accounts", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_agent_reads", "title": "List agent reads", "description": "Lists what Trade HQ's agents read of the org's business content, newest first: each read's agent, the records it read (purchase orders, invoices, orders), the kinds of fields it was answered, those masked and those your own data policies deny, how many records, and the purpose it stated, a ticket when there is one. Bank and card numbers are only ever shown to an agent as their last four.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose agent reads to list." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "How many of the newest reads to answer." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "read_id": { "type": "string", "description": "The read's id.", "x-data-class": "operational" }, "at": { "type": "string", "format": "date-time", "description": "When it was read.", "x-data-class": "operational" }, "actor": { "type": "string", "description": "The agent that read it: its broker role, @.", "x-data-class": "operational" }, "family": { "type": "string", "description": "What it read: purchase_orders, sales_orders, order_line_items, invoices, inbound_documents and so on.", "x-data-class": "operational" }, "relation": { "type": "string", "description": "The table it read.", "x-data-class": "operational" }, "classes_read": { "type": "array", "items": { "type": "string" }, "description": "The kinds of field it was answered: commercial, financial, personal, operational.", "x-data-class": "operational" }, "classes_masked": { "type": "array", "items": { "type": "string" }, "description": "The kinds answered masked, because one of the org's own data policies masks them.", "x-data-class": "operational" }, "classes_denied": { "type": "array", "items": { "type": "string" }, "description": "The kinds never read, because one of the org's own data policies denies them.", "x-data-class": "operational" }, "filter_columns": { "type": "array", "items": { "type": "string" }, "description": "The fields it filtered on, never their values.", "x-data-class": "operational" }, "record_count": { "type": "integer", "minimum": 0, "description": "How many records it was answered.", "x-data-class": "operational" }, "purpose": { "type": "string", "description": "Why it read them, as the agent stated it: a ticket when there is one.", "x-data-class": "operational" }, "refused": { "type": [ "string", "null" ], "description": "Why the read was refused, when it was: it filtered on a kind of field your own data policies mask (filter_on_masked_class) or deny (class_restricted_by_customer). Nothing was read.", "x-data-class": "operational" } }, "required": [ "read_id", "at", "actor", "family", "relation", "classes_read", "classes_masked", "classes_denied", "filter_columns", "record_count", "purpose", "refused" ], "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 }, "annotations": { "title": "List agent reads", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_announcements", "title": "List what is showing to an org", "description": "Lists what is showing now to the members of one org: the maintenance banner, if it is on, and then the announcements published to the org's account that have not ended, newest first. An org sees only its own account's announcements. Any member of the org may call it, and so may staff.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose members are looking: usually the caller's current org." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "maintenance", "announcement" ], "description": "maintenance for the platform banner, announcement for one published to the account.", "x-data-class": "operational" }, "id": { "type": "string", "description": "The banner's or the announcement's id.", "x-data-class": "operational" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ], "description": "info, warning or critical.", "x-data-class": "operational" }, "title": { "type": [ "string", "null" ], "description": "The headline; null on the banner.", "x-data-class": "operational" }, "body": { "type": "string", "description": "The message.", "x-data-class": "operational" }, "starts_at": { "type": "string", "format": "date-time", "description": "When it started showing.", "x-data-class": "operational" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops; null when it has no end, and it shows until something ends it.", "x-data-class": "operational" } }, "required": [ "kind", "id", "severity", "title", "body", "starts_at", "ends_at" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List what is showing to an org", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_api_keys", "title": "List API keys", "description": "Lists the org's API keys, newest first, a page at a time: each key's id and public prefix, name, mode (live or test), status (active, expiring, expired or revoked), the API version it is pinned to, its limits, and the key it was rotated from or into. Never a key's secret: Trade HQ does not keep it. Revoked keys only with include_revoked.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose keys they are." }, "include_revoked": { "type": "boolean", "description": "Also list revoked keys. False by default." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "minLength": 1, "maxLength": 12, "description": "The previous page's next_after." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "key_id": { "type": "string", "description": "The key's id, its public part.", "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 live org it was issued on.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What it is for.", "x-data-class": "operational" }, "service_account_id": { "type": [ "string", "null" ], "description": "The service account that owns the key and that it acts as (TRA-493); null only for a BK_ key the core issued.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "sk", "legacy" ], "description": "sk for a key this plane issued, legacy for a BK_ key.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live, or test for a key that reaches the test twin.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "expiring", "expired", "revoked" ], "description": "active; expiring when it has an expiry still ahead, as a rotated key does in its overlap; expired; or revoked.", "x-data-class": "operational" }, "display": { "type": "string", "description": "The key's prefix and id, safe to show anywhere. Never the secret.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was issued.", "x-data-class": "operational" }, "created_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who issued it.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops working, if it does.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked.", "x-data-class": "operational" }, "api_version": { "type": [ "string", "null" ], "description": "The API version it is pinned to; null for a BK_ key, which follows the current version.", "x-data-class": "operational" }, "requests_per_minute": { "type": [ "integer", "null" ], "description": "Its per-minute limit, or null for none.", "x-data-class": "operational" }, "requests_per_day": { "type": [ "integer", "null" ], "description": "Its per-day limit, or null for none.", "x-data-class": "operational" }, "rotated_from": { "type": [ "string", "null" ], "description": "The key it succeeded.", "x-data-class": "operational" }, "rotated_to": { "type": [ "string", "null" ], "description": "The key that succeeded it.", "x-data-class": "operational" }, "grants": { "type": "array", "items": { "type": "string" }, "description": "What the key was granted (TRA-619), in name order: the permissions it may use, each only while its service account's role template carries it. Empty for a key granted nothing and for a BK_ key.", "x-data-class": "operational" } }, "required": [ "key_id", "org_id", "name", "service_account_id", "kind", "mode", "status", "display", "created_at", "created_by", "expires_at", "revoked_at", "api_version", "requests_per_minute", "requests_per_day", "rotated_from", "rotated_to", "grants" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List API keys", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_audit_events", "title": "List an org's audit events", "description": "Lists the audit log of one org, newest first, a page at a time: every act on the org through the capability plane, with the actor, the scope the call acted in, the state before and after, and whether staff acted inside the org on platform authority. Filters by event, actor, impersonation, admin alerts and a UTC date range. Staff read each row whole and may also list the acts that touched no org; an account owner or an org admin gets before and after as the keys the act changed only, redacted of secrets, emails and tokens, never whole. Read only: no surface edits or deletes an audit row.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose audit log is listed." }, "event": { "type": "string", "minLength": 3, "maxLength": 64, "pattern": "^[a-z_]+\\.[a-z_]+$", "format": "tradehq-event-name", "description": "Only this event, by name (org.settings_changed)." }, "actor_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Only acts by this user." }, "impersonated": { "type": "boolean", "description": "true: only acts staff took inside the org on platform authority; false: only the others." }, "alerts_only": { "type": "boolean", "description": "Only the admin activity alerts: a new admin, an SSO change, an API key created." }, "since": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "Only acts on or after this UTC day." }, "until": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "Only acts on or before this UTC day." }, "include_platform": { "type": "boolean", "description": "Staff only: also list acts that touched no org (accounts, portfolios, platform FX overrides)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The previous page's next_after." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "audit_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The row's id: the outbox row it was recorded from.", "x-data-class": "operational" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the act committed.", "x-data-class": "operational" }, "event": { "type": "string", "description": "The event, noun.past_verb.", "x-data-class": "operational" }, "capability": { "type": "string", "description": "The capability that acted.", "x-data-class": "operational" }, "target_org_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the act was about. For anyone but staff, always the listed org: an act on several orgs is listed to each as its own. For staff, null when it touched no org or several.", "x-data-class": "operational" }, "actor_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who acted: null when nobody was signed in to the act, which is only an act anybody may call (provision_sandbox).", "x-data-class": "operational" }, "actor_staff": { "type": "boolean", "description": "Whether they were staff.", "x-data-class": "operational" }, "acting_scope": { "type": "object", "properties": { "target": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "via": { "type": [ "string", "null" ] }, "org_ids": { "type": "array", "items": { "type": "string" } }, "accounts": { "type": "array", "items": { "type": "string" } } }, "required": [ "target", "id", "via", "org_ids", "accounts" ], "additionalProperties": false, "description": "{target, id, via, org_ids, accounts}: the target kind, its id, the permission that admitted the call and what it reached. org_ids and accounts are cut to this org for anyone but staff.", "x-data-class": "operational" }, "impersonated": { "type": "boolean", "description": "Staff acting inside the org on platform authority rather than on a role the org gave them.", "x-data-class": "operational" }, "before": { "type": [ "object", "null" ], "description": "What the act replaced; null for a creation. For anyone but staff, only the keys the act changed, redacted.", "x-data-class": "operational" }, "after": { "type": [ "object", "null" ], "description": "What the act left. For anyone but staff, only the keys the act changed, redacted.", "x-data-class": "operational" }, "alert": { "type": [ "string", "null" ], "enum": [ "new_admin", "sso_changed", "key_created", null ], "description": "The admin activity alert this act is, if any.", "x-data-class": "operational" } }, "required": [ "audit_id", "occurred_at", "event", "capability", "target_org_id", "actor_user_id", "actor_staff", "acting_scope", "impersonated", "before", "after", "alert" ], "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 }, "annotations": { "title": "List an org's audit events", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_audit_exports", "title": "List an org's audit log exports", "description": "Lists the exports of one org's audit log, newest first: whether each is running, ready or failed, the filters it was asked with, how many events it holds, why it failed, and, while a ready export's links last (24 hours from when it finished), a signed download link for its CSV and its JSON file. Staff list the org's exports; an account owner or an org admin lists the ones they asked for themselves. Read only.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose exports are listed." }, "export_id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Only this export, as export_audit_events answered it." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "The page size." }, "after": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The previous page's next_after." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "export_id": { "type": "string", "description": "The export.", "x-data-class": "operational" }, "requested_at": { "type": "string", "format": "date-time", "description": "When it was asked for.", "x-data-class": "operational" }, "requested_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who asked for it.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "running", "ready", "failed" ], "description": "running while it is built; ready once both files are written; failed when they could not be.", "x-data-class": "operational" }, "filters": { "type": "object", "description": "The filters it was asked with, by list_audit_events' input names.", "x-data-class": "operational" }, "row_count": { "type": [ "integer", "null" ], "description": "How many events the files hold, once ready.", "x-data-class": "operational" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it landed or failed.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When its links stop working: 24 hours after it finished, fixed.", "x-data-class": "operational" }, "failure": { "type": [ "string", "null" ], "description": "Why a failed export failed.", "x-data-class": "operational" }, "links": { "type": [ "object", "null" ], "description": "{csv, json}: a signed download link for each file, while a ready export's links last; null otherwise.", "x-data-class": "operational" } }, "required": [ "export_id", "requested_at", "requested_by", "status", "filters", "row_count", "finished_at", "expires_at", "failure", "links" ], "additionalProperties": false }, "maxItems": 50 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List an org's audit log exports", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_beta_lists", "title": "Beta lists", "description": "Lists the beta lists flags can target: each list's name, what it is for, the person property that is the list in PostHog, and where it is declared. Who is on each is list_beta_members. Staff only.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The list's name, as flags and members name it.", "x-data-class": "operational" }, "purpose": { "type": [ "string", "null" ], "description": "What the list is for.", "x-data-class": "operational" }, "property": { "type": "string", "description": "The person property that is the list.", "x-data-class": "operational" }, "source": { "type": "string", "enum": [ "declared" ], "description": "declared: in src/beta_lists.json, changed by pull request.", "x-data-class": "operational" } }, "required": [ "name", "purpose", "property", "source" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "Beta lists", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_beta_members", "title": "Beta testers and who agreed", "description": "Lists every org and user on each beta list, with who at the customer agreed to test early and when, who on staff added them, and whether they were added here or declared in the repository. Staff only.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "list": { "type": "string", "description": "The beta list.", "x-data-class": "operational" }, "member_kind": { "type": "string", "enum": [ "org", "user" ], "description": "org or user.", "x-data-class": "operational" }, "member_id": { "type": "string", "description": "The org's or the user's id.", "x-data-class": "operational" }, "member_name": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The org's name, or the user's name (their address when they have none); null when it no longer exists.", "x-data-class": "personal" }, "member_email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "A user member's address (TRA-1461); null for an org, and once the user is anonymized.", "x-data-class": "personal" }, "agreed_by": { "type": "string", "description": "Who at the customer agreed to test early.", "x-data-class": "operational" }, "agreed_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "When they agreed.", "x-data-class": "operational" }, "source": { "type": "string", "enum": [ "declared", "page" ], "description": "page: added here, removable here; declared: in src/beta_lists.json, removed by pull request.", "x-data-class": "operational" }, "added_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who on staff added it; null when declared.", "x-data-class": "operational" }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When; null when declared.", "x-data-class": "operational" } }, "required": [ "list", "member_kind", "member_id", "member_name", "member_email", "agreed_by", "agreed_at", "source", "added_by", "added_at" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "Beta testers and who agreed", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_capability_events", "title": "List capability events and their delivery", "description": "Lists every capability event, newest first, a page at a time, each with its delivery to the consumers: whether it was delivered, how many tries and replays, and when and by whom it was last replayed. Waiting events are listed oldest first. Filters by event type, org, delivery state and a UTC date range. Each row says whether the caller may replay its delivery now. Staff only.", "inputSchema": { "type": "object", "properties": { "event_type": { "type": "string", "minLength": 3, "maxLength": 64, "pattern": "^[a-z_]+\\.[a-z_]+$", "format": "tradehq-event-name", "description": "Only events of this type (org.settings_changed)." }, "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "Only events about this org." }, "delivery": { "type": "string", "enum": [ "any", "waiting", "delivered", "replayed" ], "default": "any", "description": "any; waiting (not yet delivered, oldest first); delivered; or replayed (replayed at least once)." }, "since": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "Only events recorded on or after this UTC day." }, "until": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "Only events recorded on or before this UTC day." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The previous page's next_after." } }, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The event.", "x-data-class": "operational" }, "event_type": { "type": "string", "description": "What the event is, noun.past_verb, as the capability that emitted it declares it.", "x-data-class": "operational" }, "tenant_org_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the event is about; null for a platform event (an account, an announcement).", "x-data-class": "operational" }, "tenant_org_name": { "type": [ "string", "null" ], "description": "That org's name; null for a platform event.", "x-data-class": "operational" }, "producer_capability": { "type": "string", "description": "The capability that emitted it: its id on contract 2, its name on contract 1.", "x-data-class": "operational" }, "subject_type": { "type": "string", "description": "What the event is about: its type's noun.", "x-data-class": "operational" }, "subject_id": { "type": [ "string", "null" ], "description": "The subject's id, when the event's data names one.", "x-data-class": "operational" }, "actor_chain": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" } }, "required": [ "kind", "id" ] }, "description": "Who acted, outermost first: the principal, then the OAuth client and the counterparty it acted through or for.", "x-data-class": "operational" }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the side effect happened.", "x-data-class": "operational" }, "recorded_at": { "type": "string", "format": "date-time", "description": "When the event was recorded; the list's order.", "x-data-class": "operational" }, "trace_id": { "type": [ "string", "null" ], "description": "The call's trace.", "x-data-class": "operational" }, "correlation_id": { "type": [ "string", "null" ], "description": "What the event belongs with.", "x-data-class": "operational" }, "data": { "type": "object", "description": "The event's data: ids and names, as the capability declares it. Never a secret.", "x-data-class": "operational" }, "delivery": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "tries": { "type": "integer", "minimum": 0 }, "replays": { "type": "integer", "minimum": 0 }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "replayed_at": { "type": [ "string", "null" ], "format": "date-time" }, "replayed_by": { "type": [ "string", "null" ] } }, "required": [ "delivered", "tries", "replays", "delivered_at", "replayed_at", "replayed_by" ], "additionalProperties": false, "description": "{delivered, tries, replays, delivered_at, replayed_at, replayed_by}: the relay's state for the event.", "x-data-class": "operational" }, "replayable": { "type": "boolean", "description": "Whether the caller may replay this delivery now: it is delivered, they hold staff.ops, and replaying is enabled for them.", "x-data-class": "operational" } }, "required": [ "event_id", "event_type", "tenant_org_id", "tenant_org_name", "producer_capability", "subject_type", "subject_id", "actor_chain", "occurred_at", "recorded_at", "trace_id", "correlation_id", "data", "delivery", "replayable" ], "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 }, "annotations": { "title": "List capability events and their delivery", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_catalog", "title": "List catalog", "description": "Lists an org's sales catalog a line at a time: one line per market, depot, size, type, condition, colour and hardware, with its unit counts. Filtered by market, depot, size, type, condition and availability (available: the line counts an available unit), colour, forklift pockets, lockbox, vents, handles, repair state (the line's damage) and a Wholesale price range, all ANDed. Sorted by one key, paged by its cursor; fields chooses the columns from the field groups. A page holds at most 500 lines and one walk of the cursor at most 10,000 (walk_ceiling_reached). summarize_catalog counts the same lines.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose catalog it is." }, "filters": { "type": "object", "properties": { "market": { "type": "string", "minLength": 1, "maxLength": 128, "format": "tradehq-market", "x-filter-kind": "id_reference", "description": "A place equipment sits at, is priced from, or moves between. Availability and price are location-qualified everywhere in the trade (\"what's available where at what cost\"), which makes Location a first-class dimension of every sub-domain rather than an attribute of any one of them. A Depot is a facility at a Location; cities, regions, and ports are Locations without being facilities." }, "depot": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^Y[0-9A-Za-z]{1,18}$", "format": "tradehq-depot-id", "x-filter-kind": "id_reference", "description": "A facility that stores, handles, inspects, and repairs containers: the physical node of the operations clearinghouse. Carries fee schedules and rates, generates gate-in and gate-out events, and holds inventory whose states the depot sub-domain defines. Trade HQ's schema calls this a yard; the industry says depot; both names are attested and kept. Industry-wide, a depot is identified by a BIC Facility Code, a nine-character child code of the UN/LOCODE." }, "size": { "type": "array", "items": { "type": "string", "enum": [ "10", "20", "40", "45", "53" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Nominal container lengths in feet as traded: 10, 20, 40, 45, 53. A convention: the set differs by market (53ft is North American domestic), and TEU arithmetic is derived from it, not stored on it." }, "type": { "type": "array", "items": { "type": "string", "enum": [ "std", "hc", "stddd", "hcdd", "stdos", "hcos", "hcos2dr", "hcos4dr", "stdot", "hcot", "stdrf", "hcrf", "fr", "duocon" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The construction-type vocabulary for containers: standard, high cube, open top, open side, double door, flat rack, reefer, and combinations. These are Trade HQ's internal codes with practitioner definitions; they are not ISO 6346 size-type codes, and the mapping to ISO is an open question (OQ-003)." }, "condition": { "type": "array", "items": { "type": "string", "enum": [ "new", "cw", "wwt", "asis", "iicl", "reefer-pti", "reefer-nopti", "reefer-broken", "twotrip" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The condition ladder used to grade a container's state for sale or lease. A convention, not an axiom: the ladder and its labels vary by sub-market and era, so the ontology records the attested set without hard-coding order." }, "availability": { "type": "array", "items": { "type": "string", "enum": [ "available" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The commercial-availability half of inventory state: whether the holder will offer a unit right now. Seat-relative by nature, a lessor's available and a trader's available are different judgments over the same box, which is why availability is the holder's tenant-private call expressed in this canonical vocabulary rather than a physical fact." }, "color": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 50, "uniqueItems": true, "x-filter-kind": "text_set", "description": "The container's colour, as recorded: any of the values given." }, "forklift_pockets": { "type": "array", "items": { "type": "boolean" }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "x-filter-kind": "boolean_set", "description": "Whether the containers have forklift pockets: true, false, or both for any line that records it." }, "lockbox": { "type": "array", "items": { "type": "boolean" }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "x-filter-kind": "boolean_set", "description": "Whether the containers have a lockbox: true, false, or both for any line that records it." }, "vents": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 50, "uniqueItems": true, "x-filter-kind": "text_set", "description": "The containers' vents, as recorded: any of the values given." }, "handles": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 50, "uniqueItems": true, "x-filter-kind": "text_set", "description": "The containers' door handles, as recorded: any of the values given." }, "repair_state": { "type": "array", "items": { "type": "string", "enum": [ "undamaged", "awaiting-estimate", "pending-approval", "pending-repair", "repaired", "unrepairable", "damaged-not-repaired" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Where a unit stands in maintenance and repair: undamaged, damaged and waiting on an estimate, an estimate waiting on approval, approved and waiting on the repair, repaired, or damaged and not to be repaired. A dimension apart from ConditionGrade: a grade names the criteria a unit meets, a repair state names the work outstanding against it. The filter term repair_state in the list capabilities." }, "wholesale_price": { "type": "object", "properties": { "min": { "type": "string", "pattern": "^\\s*[0-9]{1,11}(\\.[0-9]{1,4})?\\s*$", "description": "The least value included, a decimal of at most four places." }, "max": { "type": "string", "pattern": "^\\s*[0-9]{1,11}(\\.[0-9]{1,4})?\\s*$", "description": "The greatest value included, a decimal of at most four places." } }, "minProperties": 1, "additionalProperties": false, "x-filter-kind": "decimal_range", "description": "The line's Wholesale (suggested) price, between min and max inclusive; a line with no Wholesale is not selected." } }, "additionalProperties": false, "minProperties": 1, "x-combine": "and", "description": "Lines matching every term given." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "market", "depot", "size", "type", "condition", "available_count" ], "x-enum-descriptions": [ "By market.", "By the depot's name.", "By container size.", "By container type.", "By condition grade.", "Most available units first." ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "default": [ { "key": "market", "dir": "asc" } ], "x-keyset": [ "sort key", "catalog_id" ], "description": "One sort key and its direction. By market when left out." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "market", "depot", "depot_name", "size", "type", "condition", "color", "sku_code", "lockbox", "forklift_pockets", "vents", "handles", "total_count", "available_count", "reserved_count", "secured_count", "pending_count", "available_secured_count", "available_pending_count", "suggested_price", "retail_price", "damage", "purchase_order_type" ] }, "minItems": 1, "uniqueItems": true, "default": [ "market", "depot", "depot_name", "size", "type", "condition", "color", "sku_code", "lockbox", "forklift_pockets", "vents", "handles", "total_count", "available_count", "reserved_count", "secured_count", "pending_count", "available_secured_count", "available_pending_count" ], "x-field-groups": [ { "name": "line", "fields": [ "market", "depot", "depot_name", "size", "type", "condition", "color", "sku_code" ], "default": true, "description": "What the line groups its units by." }, { "name": "hardware", "fields": [ "lockbox", "forklift_pockets", "vents", "handles" ], "default": true, "description": "The container hardware the line groups by." }, { "name": "counts", "fields": [ "total_count", "available_count", "reserved_count", "secured_count", "pending_count", "available_secured_count", "available_pending_count" ], "default": true, "description": "How many of the line's units are in each state." }, { "name": "prices", "fields": [ "suggested_price", "retail_price" ], "default": false, "description": "The line's suggested and retail prices." }, { "name": "source", "fields": [ "damage", "purchase_order_type" ], "default": false, "description": "The damage and purchase order type the line groups by, as recorded." } ], "description": "The fields to answer, from the field groups. The line, hardware and counts groups when left out." }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100, "description": "The page size." }, "after": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 1024, "format": "tradehq-keyset-cursor", "description": "The previous page's next_after." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "catalog_id": { "type": "string", "description": "The line's catalog id.", "x-data-class": "operational" }, "line": { "type": "integer", "description": "The line's ordinal under its catalog id (1 unless today's catalog emits two rows under one id).", "x-data-class": "operational" }, "market": { "type": [ "string", "null" ], "description": "The line's market.", "x-data-class": "operational" }, "depot": { "type": [ "string", "null" ], "description": "The depot the line's units are in.", "x-data-class": "operational" }, "depot_name": { "type": [ "string", "null" ], "description": "That depot's name.", "x-data-class": "operational" }, "size": { "type": [ "string", "null" ], "description": "The container size, as recorded.", "x-data-class": "operational" }, "type": { "type": [ "string", "null" ], "description": "The container type, as recorded.", "x-data-class": "operational" }, "condition": { "type": [ "string", "null" ], "description": "The condition grade, as recorded.", "x-data-class": "operational" }, "color": { "type": [ "string", "null" ], "description": "The colour.", "x-data-class": "operational" }, "sku_code": { "type": [ "string", "null" ], "description": "The line's SKU code.", "x-data-class": "operational" }, "lockbox": { "type": [ "boolean", "null" ], "description": "Whether the containers have a lockbox.", "x-data-class": "operational" }, "forklift_pockets": { "type": [ "boolean", "null" ], "description": "Whether they have forklift pockets.", "x-data-class": "operational" }, "vents": { "type": [ "string", "null" ], "description": "Their vents.", "x-data-class": "operational" }, "handles": { "type": [ "string", "null" ], "description": "Their door handles.", "x-data-class": "operational" }, "total_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "The line's units.", "x-data-class": "operational" }, "available_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Its units available to sell.", "x-data-class": "operational" }, "reserved_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Its units reserved.", "x-data-class": "operational" }, "secured_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Its units secured.", "x-data-class": "operational" }, "pending_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Its units pending.", "x-data-class": "operational" }, "available_secured_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Its units available and secured.", "x-data-class": "operational" }, "available_pending_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Its units available and pending.", "x-data-class": "operational" }, "suggested_price": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The line's suggested price, as a decimal string.", "x-data-class": "commercial" }, "retail_price": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The line's retail price, as a decimal string.", "x-data-class": "commercial" }, "damage": { "type": [ "string", "null" ], "description": "The damage the line groups by, as recorded.", "x-data-class": "operational" }, "purchase_order_type": { "type": [ "string", "null" ], "description": "The purchase order type the line groups by, as recorded.", "x-data-class": "operational" } }, "required": [ "catalog_id", "line" ], "additionalProperties": false }, "maxItems": 500 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List catalog", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_data_fields", "title": "List the data field classes", "description": "Lists the four field classes a role template's data policy is written in (commercial, financial, personal, operational), each with examples, the capability fields and database columns it covers, and how many. Operational is everything else and is counted, not listed.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose role templates are being read." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "class": { "type": "string", "enum": [ "commercial", "financial", "personal", "operational" ], "description": "commercial, financial, personal or operational.", "x-data-class": "operational" }, "title": { "type": "string", "description": "Its name.", "x-data-class": "operational" }, "examples": { "type": "string", "description": "What it covers, in plain words.", "x-data-class": "operational" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The capability fields of this class, as capability.field; empty for operational.", "x-data-class": "operational" }, "columns": { "type": "array", "items": { "type": "string" }, "description": "The database columns of this class the GraphQL surface serves, as schema.relation.column; empty for operational.", "x-data-class": "operational" }, "field_count": { "type": "integer", "minimum": 0, "description": "How many capability fields are of this class.", "x-data-class": "operational" }, "column_count": { "type": "integer", "minimum": 0, "description": "How many database columns are of this class, served on GraphQL or not.", "x-data-class": "operational" } }, "required": [ "class", "title", "examples", "fields", "columns", "field_count", "column_count" ], "additionalProperties": false }, "maxItems": 4 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List the data field classes", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_data_shares", "title": "List data shares", "description": "Lists what an org shares with its counterparties: for each party holding a seat on the org's documents, that floor (which is derived and cannot be revoked), and each explicit share of a saved query. An admin of the org sees every party's. A member of an org that is one of those counterparties sees its own and nothing else, and never a revoked share. A share the receiving org declined is listed with when it declined and who, and cannot be revoked.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org sharing." }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "Only this counterparty's." }, "include_revoked": { "type": "boolean", "description": "For an admin: also the revoked shares. A counterparty is never shown one." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "explicit", "floor" ], "description": "floor (the documents the party holds a seat on) or explicit (a share).", "x-data-class": "operational" }, "data_share_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The share; null for the floor, which has no row.", "x-data-class": "operational" }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The counterparty.", "x-data-class": "operational" }, "party_name": { "type": "string", "description": "The counterparty's name in the directory.", "x-data-class": "operational" }, "query": { "type": [ "string", "null" ], "enum": [ "vendor_bill_request", "vendor_forecast", "vendor_sell_through", null ], "description": "The saved query; null for the floor.", "x-data-class": "operational" }, "title": { "type": "string", "description": "What it is called.", "x-data-class": "operational" }, "recipients": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\\.)+([A-Za-z]{2,}|[Xx][Nn]--[A-Za-z0-9-]*[A-Za-z0-9])$", "maxLength": 254 }, "uniqueItems": true }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Who a share is emailed to; empty for the floor.", "x-data-class": "personal" }, "cadence": { "type": [ "string", "null" ], "enum": [ "daily", "hourly", null ], "description": "How often a share is emailed; null for the floor.", "x-data-class": "operational" }, "documents": { "type": [ "integer", "null" ], "minimum": 0, "description": "For the floor, how many documents; null for a share.", "x-data-class": "operational" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a share was created; null for the floor.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a share was revoked, or null.", "x-data-class": "operational" }, "declined_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the receiving org stopped receiving it (decline_data_share), or null.", "x-data-class": "operational" }, "declined_by_org_name": { "type": [ "string", "null" ], "description": "The org that declined it: the one that has claimed the counterparty; null unless declined.", "x-data-class": "operational" }, "revocable": { "type": "boolean", "description": "Whether revoke_data_share can revoke it: a live share can; the floor and a revoked or declined share never.", "x-data-class": "operational" } }, "required": [ "kind", "data_share_id", "party_id", "party_name", "query", "title", "recipients", "cadence", "documents", "created_at", "revoked_at", "declined_at", "declined_by_org_name", "revocable" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List data shares", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_depot_references", "title": "List an org's depot links", "description": "Lists the org's own links to depots it uses (reference_depot): its name and code for each yard, the yard's BIC Facility Code (BFC) and its name in the registry, and who made the link and when. Ordered by the org's name for the depot, a page at a time. The query matches a substring of the name or the code, or the start of a BFC; bfc limits the list to those BFCs, such as a page of list_depot_registry. Only the org's members see its links.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose links to list." }, "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "A case-insensitive substring of the org's name or code for the depot, or the start of a BFC." }, "bfc": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}[A-Z0-9]{4}$", "format": "bic-facility-code" }, "maxItems": 200, "uniqueItems": true, "description": "Only the links to these BFCs: a page of list_depot_registry, to join to it. A set: in any order, each code once (a repeat is refused). An empty list matches none." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The previous page's next_after. An id that is not one of this org's links ends the listing: an empty page." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "depot_reference_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The link's id: what remove_depot_reference names.", "x-data-class": "operational" }, "bfc": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}[A-Z0-9]{4}$", "format": "bic-facility-code", "description": "The depot's BIC Facility Code.", "x-data-class": "operational" }, "depot_name": { "type": "string", "description": "The depot's name in the registry.", "x-data-class": "operational" }, "alias": { "type": "string", "description": "The org's name for the depot.", "x-data-class": "operational" }, "private_code": { "type": "string", "description": "The org's code for the depot; its name when it gave none.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The member who made the link.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When the link was made.", "x-data-class": "operational" } }, "required": [ "depot_reference_id", "bfc", "depot_name", "alias", "private_code", "created_by", "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 }, "annotations": { "title": "List an org's depot links", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_depot_registry", "title": "List the depot registry", "description": "Lists the depot registry, the one register of container depots every Trade HQ tenant sees the same, keyed on the BIC Facility Code (BFC) and ordered by it, a page at a time. The query matches the start of a BFC or a case-insensitive substring of the depot's name. Each depot carries its BFC, its name, whether an org has claimed it, and the party that operates it when that is known. Any signed-in user may list it. With org_id, an org the caller is a member of, each depot also says whether that org claims it (yours).", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The start of a BFC, or a case-insensitive substring of the depot's name." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}[A-Z0-9]{4}$", "format": "bic-facility-code", "description": "The previous page's next_after." }, "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "An org the caller is a member of, for yours. Absent, yours is null." } }, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "bfc": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}[A-Z0-9]{4}$", "format": "bic-facility-code", "description": "The depot's BIC Facility Code.", "x-data-class": "operational" }, "name": { "type": "string", "description": "The depot's name in the registry.", "x-data-class": "operational" }, "claimed": { "type": "boolean", "description": "Whether an org has claimed the depot (claim_depot). Which org is not said.", "x-data-class": "operational" }, "operator_party_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The party that runs the yard, from the party directory; null when not known.", "x-data-class": "operational" }, "operator_name": { "type": [ "string", "null" ], "description": "That party's name; null when not known.", "x-data-class": "operational" }, "yours": { "type": [ "boolean", "null" ], "description": "Whether the org named by org_id claims the depot; null when no org_id is given.", "x-data-class": "operational" } }, "required": [ "bfc", "name", "claimed", "operator_party_id", "operator_name", "yours" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List the depot registry", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_devices", "title": "List my devices", "description": "Lists the caller's own devices, newest first, revoked ones included: each with its platform, app version, the org it was bound in, whether it is a managed (shared) device, whether it receives push, when it was bound and revoked, and whether it is the device making this call. Never a key or a push token.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "binding_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The binding: what revoke_device takes.", "x-data-class": "operational" }, "installation_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The installation.", "x-data-class": "operational" }, "platform": { "type": "string", "enum": [ "ios", "android" ], "description": "Its platform.", "x-data-class": "operational" }, "app_version": { "type": "string", "description": "The app version it registered with.", "x-data-class": "operational" }, "bound_org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org it was bound in.", "x-data-class": "operational" }, "managed": { "type": "boolean", "description": "A managed (shared) device, which reads only.", "x-data-class": "operational" }, "push": { "type": "boolean", "description": "Whether it has a live push destination.", "x-data-class": "operational" }, "bound_at": { "type": "string", "format": "date-time", "description": "When it was bound.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked; null while it stands.", "x-data-class": "operational" }, "this_device": { "type": "boolean", "description": "Whether it is the device making this call.", "x-data-class": "operational" } }, "required": [ "binding_id", "installation_id", "platform", "app_version", "bound_org_id", "managed", "push", "bound_at", "revoked_at", "this_device" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List my devices", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_document_parties", "title": "List a document's parties", "description": "Lists the parties on one commercial document (a purchase order is an asset_intake, a lease or sale is an order) and the seat each holds. A member of the org that owns the document sees every seat. A member of an org whose party holds a seat on it sees that org's own seat and no other party.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that owns the document." }, "document_kind": { "type": "string", "enum": [ "asset_intake", "order" ], "description": "The table the document is in: asset_intake (a purchase order) or order." }, "document_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The document's id in that table." } }, "required": [ "org_id", "document_kind", "document_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The party, in the shared directory.", "x-data-class": "operational" }, "party_name": { "type": "string", "description": "The party's name in the directory.", "x-data-class": "operational" }, "seat": { "type": "string", "enum": [ "buyer", "lessee", "lessor", "seller" ], "description": "The seat it holds on this document.", "x-data-class": "operational" }, "party_org_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The Trade HQ org that has claimed the party; null when none has.", "x-data-class": "operational" } }, "required": [ "party_id", "party_name", "seat", "party_org_id" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List a document's parties", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_domains", "title": "List an org's email domains", "description": "Lists every email domain the org has claimed with verify_domain, pending or verified, ordered by domain. Each carries its status, the DNS TXT record to publish (record_name, record_value), its join_policy, and verified_at and verified_by once it is verified.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose domains to list." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org claiming it.", "x-data-class": "operational" }, "domain": { "type": "string", "description": "The domain, lower case.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "verified" ], "description": "pending until the TXT record is found, then verified.", "x-data-class": "operational" }, "record_name": { "type": "string", "description": "Where to publish the TXT record.", "x-data-class": "operational" }, "record_value": { "type": "string", "description": "What the TXT record carries.", "x-data-class": "operational" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was verified.", "x-data-class": "operational" }, "verified_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who verified it.", "x-data-class": "operational" }, "join_policy": { "type": "string", "enum": [ "invite_only", "request" ], "description": "invite_only, or request: a person signing up at the domain is put to the org's admins as a join request.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who claimed it.", "x-data-class": "operational" } }, "required": [ "org_id", "domain", "status", "record_name", "record_value", "verified_at", "verified_by", "join_policy", "created_by" ], "additionalProperties": false }, "maxItems": 1000 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List an org's email domains", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_files", "title": "List files", "description": "Lists the org's files, newest first, a page at a time, optionally one kind. Each carries its record; a name is the mask where the caller's data policy masks the file's class.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose files they are." }, "kind": { "type": "string", "enum": [ "doc", "img", "att", "msg", "gen" ], "description": "Only files of this kind." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "minLength": 26, "maxLength": 26, "description": "The previous page's next_after." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "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 }, "annotations": { "title": "List files", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_flag_actions", "title": "List the flag changes made from the Flags page", "description": "Lists the changes made from the Flags page, newest first: who made each one, which flag or beta list, from what to what, when, and whether PostHog took it. Optionally for one flag. Staff only.", "inputSchema": { "type": "object", "properties": { "flag_key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Only this flag's changes." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "How many, newest first." } }, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "action_id": { "type": "string", "description": "The change's id.", "x-data-class": "operational" }, "action": { "type": "string", "enum": [ "advance", "roll_back", "beta_add", "beta_remove", "set_lists" ], "description": "advance, roll_back, beta_add, beta_remove, or set_lists (TRA-1461: the beta lists a flag reaches, before and after in detail).", "x-data-class": "operational" }, "flag_key": { "type": [ "string", "null" ], "description": "The flag moved; null for a beta list change.", "x-data-class": "operational" }, "beta_list": { "type": [ "string", "null" ], "description": "The list changed; null for a flag move.", "x-data-class": "operational" }, "member_kind": { "type": [ "string", "null" ], "description": "org or user, for a beta list change.", "x-data-class": "operational" }, "member_id": { "type": [ "string", "null" ], "description": "The org or user, for a beta list change.", "x-data-class": "operational" }, "from_state": { "type": "string", "description": "The wave before (or absent/member for a list).", "x-data-class": "operational" }, "to_state": { "type": "string", "description": "The wave after (or member/absent for a list).", "x-data-class": "operational" }, "agreed_by": { "type": [ "string", "null" ], "description": "Who at the customer agreed, for an add.", "x-data-class": "operational" }, "agreed_at": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "When they agreed, for an add.", "x-data-class": "operational" }, "actor": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who made the change.", "x-data-class": "operational" }, "acted_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" }, "outcome": { "type": "string", "enum": [ "pending", "applied", "failed" ], "description": "applied, failed (PostHog refused it), or pending (still in flight).", "x-data-class": "operational" }, "detail": { "type": [ "string", "null" ], "description": "Why it failed.", "x-data-class": "operational" } }, "required": [ "action_id", "action", "flag_key", "beta_list", "member_kind", "member_id", "from_state", "to_state", "agreed_by", "agreed_at", "actor", "acted_at", "outcome", "detail" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List the flag changes made from the Flags page", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_flag_staff", "title": "Staff by name, for the Flags page", "description": "Lists every person holding a Trade HQ staff role, once each, with their name and status (active, deactivated or anonymized), ordered by person: the names the Flags page shows for who made a move and offers for who agreed. No address; their addresses and roles are list_staff's. Staff only.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The staff member.", "x-data-class": "operational" }, "name": { "type": [ "string", "null" ], "description": "Their name; the tombstone once anonymized.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "deactivated", "anonymized" ], "description": "active, deactivated or anonymized.", "x-data-class": "operational" } }, "required": [ "user_id", "name", "status" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "Staff by name, for the Flags page", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_flags", "title": "List the feature flags", "description": "Lists every feature flag in the registry with its state in PostHog: kind, owner, purpose, decide-by date, failure default, the wave it is on (staff, beta, a percentage of customer orgs, everyone, off, absent from PostHog, or a custom rule), the next wave up, its age and a link to it in PostHog, and the drift check's findings. Flags PostHog has that the registry does not are listed too. Staff only.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The flag's PostHog key.", "x-data-class": "operational" }, "registered": { "type": "boolean", "description": "Whether the registry carries it; false for a flag only PostHog has.", "x-data-class": "operational" }, "kind": { "type": [ "string", "null" ], "enum": [ "release", "experiment", "prototype", "kill", null ], "description": "release, experiment, prototype or kill; null when unregistered.", "x-data-class": "operational" }, "owner": { "type": [ "string", "null" ], "description": "Who owns the flag; null when unregistered.", "x-data-class": "operational" }, "purpose": { "type": [ "string", "null" ], "description": "What it is for, in one line; null when unregistered.", "x-data-class": "operational" }, "capability": { "type": [ "string", "null" ], "description": "The capability id it gates; null when unregistered.", "x-data-class": "operational" }, "decide_by": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "When the flag is removed or made permanent; null when unregistered.", "x-data-class": "operational" }, "failure_default": { "type": [ "string", "null" ], "enum": [ "on", "off", null ], "description": "What every caller reads when PostHog cannot answer; null when unregistered.", "x-data-class": "operational" }, "wave": { "type": "string", "enum": [ "absent", "off", "staff", "beta", "orgs_10", "orgs_25", "orgs_50", "everyone", "custom", "unknown" ], "description": "Where PostHog has it: absent, off, staff, beta, orgs_ (n percent of customer orgs), everyone, custom (a rule this page did not write), or unknown when PostHog could not be read.", "x-data-class": "operational" }, "percentage": { "type": [ "integer", "null" ], "description": "The percentage of customer orgs on an orgs wave; null on any other.", "x-data-class": "operational" }, "beta_lists": { "type": "array", "items": { "type": "string" }, "description": "The beta lists it targets, by name; empty below the beta wave.", "x-data-class": "operational" }, "next_wave": { "type": [ "string", "null" ], "description": "The wave advancing moves it to; null when it cannot be advanced here (everyone, custom, unknown, unregistered).", "x-data-class": "operational" }, "age_days": { "type": [ "integer", "null" ], "description": "Days since PostHog created it; null when PostHog does not have it.", "x-data-class": "operational" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When PostHog created it.", "x-data-class": "operational" }, "posthog_url": { "type": [ "string", "null" ], "description": "The flag in PostHog; null when PostHog does not have it or could not be read.", "x-data-class": "operational" }, "drift": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "TRA-247's drift statuses for it, empty when in sync: in_code_not_registry, in_registry_not_code, in_registry_not_posthog, in_posthog_not_registry, in_code_not_posthog, past_decide_by, everyone. Null when PostHog could not be read.", "x-data-class": "operational" } }, "required": [ "key", "registered", "kind", "owner", "purpose", "capability", "decide_by", "failure_default", "wave", "percentage", "beta_lists", "next_wave", "age_days", "created_at", "posthog_url", "drift" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List the feature flags", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_fx_rates", "title": "List FX rates", "description": "Lists the FX rates an org converts with on one day, as units of each currency per one `per` (EUR unless given). Rates are ECB's daily reference rates; an override set by finance for the org's account, or platform-wide, takes precedence on its day. Every row states its source (ecb or override), its date, whether it is overridden, and the fetched ECB rate for the same day. A day without an ECB publication uses the latest rate from the seven days before it; a currency with none in that window is absent.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose rates to list. Its account's overrides apply." }, "on": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The day, YYYY-MM-DD. Today in UTC when absent." }, "per": { "type": "string", "pattern": "^[A-Z]{3}$", "format": "iso4217", "description": "Express every rate per one unit of this currency, e.g. the account's reporting currency. EUR when absent. Nothing is listed when it has no rate; a code ISO 4217 does not assign is refused (currency_not_iso4217)." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "format": "iso4217", "description": "The currency the rate is in.", "x-data-class": "operational" }, "per": { "type": "string", "pattern": "^[A-Z]{3}$", "format": "iso4217", "description": "One unit of this currency buys `rate` of `currency`.", "x-data-class": "operational" }, "rate": { "anyOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "format": "positive-decimal" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The effective rate, to ten decimal places at most.", "x-data-class": "commercial" }, "rate_date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The day the rate is for (the older leg's, for a cross rate).", "x-data-class": "operational" }, "source": { "type": "string", "enum": [ "ecb", "override" ], "description": "ecb, or override when an override made either leg.", "x-data-class": "operational" }, "overridden": { "type": "boolean", "description": "Whether an override made the rate.", "x-data-class": "operational" }, "fetched_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+(\\.[0-9]+)?$", "format": "positive-decimal", "description": "What ECB's rates alone give for the same day; null when ECB published none for a leg.", "x-data-class": "operational" } }, "required": [ "currency", "per", "rate", "rate_date", "source", "overridden", "fetched_rate" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List FX rates", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_granted_capabilities", "title": "List an org's capability grants", "description": "Lists the capabilities an org was given outside its plan tier, newest first, a page at a time: each grant or add-on, who gave it, how, when, why, its expiry, and its status (active, expired or revoked) with who revoked it and why. Ended grants only with include_ended.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose grants they are." }, "include_ended": { "type": "boolean", "description": "Also list revoked and expired grants. False by default." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The previous page's next_after." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "org_grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The grant'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 was given to.", "x-data-class": "operational" }, "capability_id": { "type": "string", "description": "The capability, by its registry name.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "grant", "add_on" ], "description": "grant, given outside the tier, or add_on, bought on top.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ], "description": "active while it counts; expired past expires_at; revoked once revoked.", "x-data-class": "operational" }, "reason": { "type": "string", "description": "Why it was given.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops counting; null for never.", "x-data-class": "operational" }, "granted_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who gave it.", "x-data-class": "operational" }, "granted_via": { "type": "string", "description": "The principal kind it came through: clerk_user, or mcp_subject for an agent.", "x-data-class": "operational" }, "granted_client": { "type": [ "string", "null" ], "description": "The OAuth client an agent acted through; null otherwise.", "x-data-class": "operational" }, "granted_at": { "type": "string", "format": "date-time", "description": "When it was given.", "x-data-class": "operational" }, "revoked_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who revoked it; null while it is not revoked.", "x-data-class": "operational" }, "revoked_via": { "type": [ "string", "null" ], "description": "The principal kind the revocation came through.", "x-data-class": "operational" }, "revoked_client": { "type": [ "string", "null" ], "description": "The OAuth client an agent revoked it through.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked.", "x-data-class": "operational" }, "revoke_reason": { "type": [ "string", "null" ], "description": "Why it was revoked.", "x-data-class": "operational" } }, "required": [ "org_grant_id", "org_id", "capability_id", "kind", "status", "reason", "expires_at", "granted_by", "granted_via", "granted_client", "granted_at", "revoked_by", "revoked_via", "revoked_client", "revoked_at", "revoke_reason" ], "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 }, "annotations": { "title": "List an org's capability grants", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_guest_documents", "title": "List my documents as a guest", "description": "For a guest of an org: the documents their party holds a seat on in that org, at their seat, and nothing else of the org. A forwarder reads its leases and a supplier its purchase orders. Each says whether it is an offer still waiting on them. A member of the org is refused; this is the guest's view.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the caller is a guest of." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "document_kind": { "type": "string", "enum": [ "asset_intake", "order" ], "description": "order (a lease) or asset_intake (a purchase order).", "x-data-class": "operational" }, "document_id": { "type": "string", "description": "The document's id.", "x-data-class": "operational" }, "seat": { "type": "string", "enum": [ "lessee", "seller" ], "description": "The guest's seat on it.", "x-data-class": "operational" }, "shape": { "type": "string", "enum": [ "forwarder", "supplier" ], "description": "The guest's view: forwarder or supplier.", "x-data-class": "operational" }, "reference": { "type": "string", "description": "What the document is called: an order's invoice number, a purchase order's PO number or booking number, else its id.", "x-data-class": "operational" }, "document_type": { "type": [ "string", "null" ], "description": "The order's sales order type or the purchase order's type.", "x-data-class": "operational" }, "status": { "type": "string", "description": "The document's status.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was made.", "x-data-class": "operational" }, "offer": { "type": "boolean", "description": "An offer still waiting on the guest: a purchase order still pending.", "x-data-class": "operational" } }, "required": [ "document_kind", "document_id", "seat", "shape", "reference", "document_type", "status", "created_at", "offer" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List my documents as a guest", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_guests", "title": "List an org's guests", "description": "Lists the guests of an org: the people invited from its documents to read the documents their party holds a seat on. Each carries the party they are, their seat, what their view shows (forwarder or supplier), the document they were invited from, how many documents their party holds that seat on, whether they have signed in yet, their expiry, and their status: active, expired (past their last day) or revoked. A revoked guest stays listed as the record.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose guests to list." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Only guests whose user_id sorts strictly after this one: pass the previous page's next_after, which is the last user_id that page returned. Absent, the first page." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The guest.", "x-data-class": "operational" }, "email": { "anyOf": [ { "type": "string" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their sign-in address.", "x-data-class": "personal" }, "name": { "type": [ "string", "null" ], "description": "Their name, when they have one.", "x-data-class": "operational" }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The party they are.", "x-data-class": "operational" }, "party_name": { "type": "string", "description": "The party's name in the directory.", "x-data-class": "operational" }, "seat": { "type": "string", "enum": [ "lessee", "seller" ], "description": "Their seat.", "x-data-class": "operational" }, "role_id": { "type": [ "string", "null" ], "description": "The Counterparty template they hold; null once revoked.", "x-data-class": "operational" }, "shape": { "type": "string", "enum": [ "forwarder", "supplier" ], "description": "What their view shows.", "x-data-class": "operational" }, "invited_from_kind": { "type": "string", "enum": [ "asset_intake", "order" ], "description": "The kind of the document they were invited from.", "x-data-class": "operational" }, "invited_from_id": { "type": "string", "description": "That document's id.", "x-data-class": "operational" }, "invited_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who invited them.", "x-data-class": "operational" }, "invited_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" }, "expires_on": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "Their last day of access, a UTC date, or null when it does not expire.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ], "description": "active; expired once past expires_on, when they are refused in the org as a revoked guest is; revoked once revoke_guest has ended their access.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When their access was revoked, or null.", "x-data-class": "operational" }, "signed_in": { "type": "boolean", "description": "Whether they have signed in to the org.", "x-data-class": "operational" }, "document_count": { "type": "integer", "minimum": 0, "description": "How many of the org's documents their party holds their seat on: what their view lists while their access stands.", "x-data-class": "operational" } }, "required": [ "user_id", "email", "name", "party_id", "party_name", "seat", "role_id", "shape", "invited_from_kind", "invited_from_id", "invited_by", "invited_at", "expires_on", "status", "revoked_at", "signed_in", "document_count" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List an org's guests", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_identity_findings", "title": "List an org's Clerk drift findings", "description": "Lists the differences the drift detector found between Clerk and Trade HQ in an org: a Clerk membership Trade HQ did not decide (quarantined: refused here and removed from Clerk), a Clerk role that is not the member's role template's (put back), or an active member Clerk holds no membership for. Open findings first, newest first; each names the decisions resolve_identity_finding offers on it. state chooses open (the default), resolved or all.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose findings to list." }, "state": { "type": "string", "enum": [ "open", "resolved", "all" ], "default": "open", "description": "open (the default), resolved, or all." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "finding_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The finding.", "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.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "membership_unexpected", "role_mismatch", "membership_missing" ], "description": "membership_unexpected: Clerk holds a membership Trade HQ did not decide. role_mismatch: Clerk's role is not the member's role template's. membership_missing: an active member Clerk holds no membership for.", "x-data-class": "operational" }, "source": { "type": "string", "enum": [ "webhook", "reconcile" ], "description": "What saw it: Clerk's event, or the reconcile.", "x-data-class": "operational" }, "user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The Trade HQ user, when the Clerk user is one.", "x-data-class": "operational" }, "name": { "type": [ "string", "null" ], "description": "The Trade HQ user's profile name, when they have one.", "x-data-class": "operational" }, "clerk_user_id": { "type": [ "string", "null" ], "description": "The Clerk user.", "x-data-class": "operational" }, "email_domain": { "type": [ "string", "null" ], "description": "The domain of the Clerk member's address; never the address.", "x-data-class": "operational" }, "observed_role": { "type": [ "string", "null" ], "description": "The Clerk role Clerk holds.", "x-data-class": "operational" }, "expected_role": { "type": [ "string", "null" ], "description": "The Clerk role the member's role template carries.", "x-data-class": "operational" }, "role_template_id": { "type": [ "string", "null" ], "description": "The member's role template when the finding was raised.", "x-data-class": "operational" }, "action_taken": { "type": "string", "enum": [ "quarantined", "restored", "alerted", "fused", "none" ], "description": "quarantined: refused here and queued for removal from Clerk; restored: the template's role queued back to Clerk; alerted: the org's drift setting is alert only; fused: the run found more than it may act on at once; none: nothing to do but decide.", "x-data-class": "operational" }, "command_outcome": { "type": [ "string", "null" ], "description": "What Clerk answered the finding's last command (applied, no_clerk_membership, withdrawn); null while it waits or when there is none.", "x-data-class": "operational" }, "raised_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" }, "decisions": { "type": "array", "items": { "type": "string" }, "description": "What resolve_identity_finding offers on it while it is open: remove, admit, ignore. Empty once resolved. Staff may only remove.", "x-data-class": "operational" }, "resolution": { "type": [ "string", "null" ], "enum": [ "removed", "admitted", "ignored", null ], "description": "How it was resolved; null while open.", "x-data-class": "operational" }, "admitted_role_template_id": { "type": [ "string", "null" ], "description": "The role template an Admit gave.", "x-data-class": "operational" }, "resolved_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who resolved it.", "x-data-class": "operational" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was resolved.", "x-data-class": "operational" } }, "required": [ "finding_id", "org_id", "kind", "source", "user_id", "name", "clerk_user_id", "email_domain", "observed_role", "expected_role", "role_template_id", "action_taken", "command_outcome", "raised_at", "decisions", "resolution", "admitted_role_template_id", "resolved_by", "resolved_at" ], "additionalProperties": false }, "maxItems": 500 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List an org's Clerk drift findings", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_inventory", "title": "List inventory", "description": "Lists an org's units a page at a time: filtered by acquisition, availability, custody, depot, size, type, condition, in_depot_since, gated_out, acquisition_channel, holding_basis, vendor_bill_paid, vendor_eta, repair_state, customer, vendor and tag, all of them ANDed, and by q, the start of an identifier. With no acquisition filter it lists units pending or acquired. Sorted by one key, paged by its cursor; fields chooses the columns from the field groups. A page holds at most 500 units and one walk of the cursor at most 10,000 (walk_ceiling_reached). summarize_inventory counts the same units.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose inventory it is." }, "filters": { "type": "object", "properties": { "acquisition": { "type": "array", "items": { "type": "string", "enum": [ "pending", "acquired", "cancelled" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The acquisition half of inventory state: whether the holder is still buying a unit, has it, or will not get it. The third dimension of InventoryState beside availability and custody, by Sage's decision of 2026-10-05, so that units being bought sit in the same lists as units held. Cancelled is terminal and leaves no holder state: a cancelled unit has no availability and no custody." }, "availability": { "type": "array", "items": { "type": "string", "enum": [ "available", "committed", "withdrawn" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The commercial-availability half of inventory state: whether the holder will offer a unit right now. Seat-relative by nature, a lessor's available and a trader's available are different judgments over the same box, which is why availability is the holder's tenant-private call expressed in this canonical vocabulary rather than a physical fact." }, "custody": { "type": "array", "items": { "type": "string", "enum": [ "in-depot", "on-hire", "disposed", "in-transit" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The physical-and-contractual half of inventory state: where a unit sits and under whose control. Closer to fact than judgment: in-depot is derivable from gate-event pairs, on-hire from lease commitments, disposed from exits. Every seat reads these the same way, which is what separates custody from availability." }, "depot": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^Y[0-9A-Za-z]{1,18}$", "format": "tradehq-depot-id", "x-filter-kind": "id_reference", "description": "A facility that stores, handles, inspects, and repairs containers: the physical node of the operations clearinghouse. Carries fee schedules and rates, generates gate-in and gate-out events, and holds inventory whose states the depot sub-domain defines. Trade HQ's schema calls this a yard; the industry says depot; both names are attested and kept. Industry-wide, a depot is identified by a BIC Facility Code, a nine-character child code of the UN/LOCODE." }, "size": { "type": "array", "items": { "type": "string", "enum": [ "10", "20", "40", "45", "53" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Nominal container lengths in feet as traded: 10, 20, 40, 45, 53. A convention: the set differs by market (53ft is North American domestic), and TEU arithmetic is derived from it, not stored on it." }, "type": { "type": "array", "items": { "type": "string", "enum": [ "std", "hc", "stddd", "hcdd", "stdos", "hcos", "hcos2dr", "hcos4dr", "stdot", "hcot", "stdrf", "hcrf", "fr", "duocon" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The construction-type vocabulary for containers: standard, high cube, open top, open side, double door, flat rack, reefer, and combinations. These are Trade HQ's internal codes with practitioner definitions; they are not ISO 6346 size-type codes, and the mapping to ISO is an open question (OQ-003)." }, "condition": { "type": "array", "items": { "type": "string", "enum": [ "new", "cw", "wwt", "asis", "iicl", "reefer-pti", "reefer-nopti", "reefer-broken", "twotrip" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The condition ladder used to grade a container's state for sale or lease. A convention, not an axiom: the ladder and its labels vary by sub-market and era, so the ontology records the attested set without hard-coding order." }, "in_depot_since": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "The day the unit's most recent residency began: a range of days, or true for a unit that has been gated in and false for one that never has." }, "gated_out": { "type": "boolean", "x-filter-kind": "presence", "description": "True: the unit's most recent residency has ended. False: it has not, so the unit is still in the depot or has never been gated in." }, "acquisition_channel": { "type": "array", "items": { "type": "string", "enum": [ "direct", "gate-buy", "yard-buy", "consignment", "factory-direct", "inland-transfer", "open-inventory" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "How a holder sources a unit: bought direct, bought in transit to a customer (gate buy), bought where it sits in a supplier's yard (yard buy), taken on consignment, bought from the factory, transferred in from a supplier's depot account, or listed as open inventory before any unit lands. One half of today's purchase_order_type, split by Sage's decision of 2026-10-05; the other half is HoldingBasis." }, "holding_basis": { "type": "array", "items": { "type": "string", "enum": [ "owned", "leased-in", "subleased" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The basis on which a holder holds an acquired unit: it owns it, it leases it in from a supplier, or it leases it in and lets it on to a customer. The other half of today's purchase_order_type, split by Sage's decision of 2026-10-05, read together with steward_type. Instrument's two forms as they apply to the holder's own stock: ownership follows a sale, leased-in and subleased follow a lease." }, "vendor_bill_paid": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "When the holder paid the vendor's bill for the unit: a range of days, or true for paid and false for not paid." }, "vendor_eta": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "The day the vendor expects to deliver the unit: a range of days, or true for a unit with an ETA and false for one without." }, "origin_market": { "type": "string", "minLength": 1, "maxLength": 128, "format": "tradehq-market", "x-filter-kind": "id_reference", "description": "The market the unit's most recent purchase order picks it up in, its origin, as the purchase order names it (for example Charlotte, NC): matched exactly." }, "origin_depot": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^Y[0-9A-Za-z]{1,18}$", "format": "tradehq-depot-id", "x-filter-kind": "id_reference", "description": "The depot the unit's most recent purchase order picks it up at, its origin depot." }, "pickup_date": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "The day the unit's most recent purchase order picks it up at its origin, the P/U Date: a range of days, or true for a unit with one and false for one without." }, "transit_days": { "type": "object", "properties": { "from": { "type": "integer", "minimum": -3650, "maximum": 3650, "description": "The lowest value included." }, "to": { "type": "integer", "minimum": -3650, "maximum": 3650, "description": "The highest value included." } }, "minProperties": 1, "additionalProperties": false, "x-filter-kind": "int_range", "description": "Days from the unit's P/U Date to its vendor ETA: a range of whole days, inclusive. A unit missing either date has no transit days and matches no range; a negative number is an ETA before the P/U Date." }, "repair_state": { "type": "array", "items": { "type": "string", "enum": [ "undamaged", "awaiting-estimate", "pending-approval", "pending-repair", "repaired", "unrepairable", "damaged-not-repaired" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Where a unit stands in maintenance and repair: undamaged, damaged and waiting on an estimate, an estimate waiting on approval, approved and waiting on the repair, repaired, or damaged and not to be repaired. A dimension apart from ConditionGrade: a grade names the criteria a unit meets, a repair state names the work outstanding against it. The filter term repair_state in the list capabilities." }, "customer": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^CT[0-9A-Za-z]{1,18}$", "format": "tradehq-contact-id", "x-filter-kind": "id_reference", "description": "The customer contact on the unit's most recent order." }, "vendor": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^CT[0-9A-Za-z]{1,18}$", "format": "tradehq-contact-id", "x-filter-kind": "id_reference", "description": "The vendor contact the holder acquired the unit from." }, "tag": { "type": "string", "minLength": 1, "maxLength": 64, "format": "tradehq-org-tag", "x-filter-kind": "id_reference", "description": "One of the org's tags: units carrying it." } }, "additionalProperties": false, "minProperties": 1, "x-combine": "and", "description": "Units matching every term given. With no acquisition term, units pending or acquired." }, "q": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The start of a BIC number, booking number, release booking number, intake id, vendor bill id or invoice number." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "availability", "depot", "size", "type", "condition", "in_depot_since", "vendor_eta", "pickup_date", "transit_days", "total_cost", "updated_at" ], "x-enum-descriptions": [ "By availability state.", "By the depot of the most recent residency.", "By container size.", "By container type.", "By condition grade.", "Longest in the depot first.", "Soonest vendor ETA first.", "Soonest P/U Date first.", "Shortest transit first.", "Highest total cost first.", "Most recently changed first." ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "default": [ { "key": "updated_at", "dir": "desc" } ], "x-keyset": [ "sort key", "asset_id" ], "description": "One sort key and its direction. Most recently changed first when left out." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "bic", "acquisition", "availability", "custody", "repair_state", "tags", "internal_notes", "created_at", "updated_at", "size", "type", "condition", "color", "color_ral", "year_of_make", "forklift_pockets", "handles", "lockbox", "vents", "intake_id", "acquisition_channel", "pickup_date", "vendor_eta", "transit_days", "booking_number", "intake_depot", "origin_market", "origin_depot", "nearest_metro", "fee_responsibility", "depot", "in_depot_since", "gated_out_at", "duration_days", "release_booking_number", "holding_basis", "vendor", "vendor_bill_id", "vendor_bill_paid_at", "purchase_price", "lease_price", "lease_term", "order_id", "customer", "invoice_number", "sales_order_type", "reserved_price", "listed", "list_price", "lease_base_price", "lease_base_duration", "purchase_terms", "total_cost", "available", "repair_cost", "transport_cost", "other_cost", "fee_currency", "fee_gate_in", "fee_gate_out", "fee_lift", "fee_storage", "fee_total" ] }, "minItems": 1, "uniqueItems": true, "default": [ "bic", "acquisition", "availability", "custody", "repair_state", "tags", "internal_notes", "created_at", "updated_at", "size", "type", "condition", "color", "color_ral", "year_of_make", "forklift_pockets", "handles", "lockbox", "vents", "depot", "in_depot_since", "gated_out_at", "duration_days", "release_booking_number" ], "x-field-groups": [ { "name": "unit", "fields": [ "bic", "acquisition", "availability", "custody", "repair_state", "tags", "internal_notes", "created_at", "updated_at" ], "default": true, "description": "The unit itself and its state." }, { "name": "container", "fields": [ "size", "type", "condition", "color", "color_ral", "year_of_make", "forklift_pockets", "handles", "lockbox", "vents" ], "default": true, "description": "The container's physical description." }, { "name": "intake", "fields": [ "intake_id", "acquisition_channel", "pickup_date", "vendor_eta", "transit_days", "booking_number", "intake_depot", "origin_market", "origin_depot", "nearest_metro", "fee_responsibility" ], "default": false, "description": "The unit's most recent intake: its purchase order, the route it travels (origin, P/U Date, ETA and the days between) and its destination market." }, { "name": "residency", "fields": [ "depot", "in_depot_since", "gated_out_at", "duration_days", "release_booking_number" ], "default": true, "description": "The unit's most recent residency." }, { "name": "stewardship", "fields": [ "holding_basis", "vendor", "vendor_bill_id", "vendor_bill_paid_at", "purchase_price", "lease_price", "lease_term" ], "default": false, "description": "How the holder came to hold the unit." }, { "name": "order", "fields": [ "order_id", "customer", "invoice_number", "sales_order_type", "reserved_price" ], "default": false, "description": "The unit's most recent order and its active reservation." }, { "name": "sales", "fields": [ "listed", "list_price", "lease_base_price", "lease_base_duration", "purchase_terms" ], "default": false, "description": "The unit's sales availability." }, { "name": "costs", "fields": [ "total_cost", "available", "repair_cost", "transport_cost", "other_cost" ], "default": false, "description": "The unit's cost rollup." }, { "name": "fees", "fields": [ "fee_currency", "fee_gate_in", "fee_gate_out", "fee_lift", "fee_storage", "fee_total" ], "default": false, "description": "The yard fees the most recent residency is projected to cost." } ], "description": "The fields to answer, from the field groups. The unit, container and residency groups when left out." }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100, "description": "The page size." }, "after": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 1024, "format": "tradehq-keyset-cursor", "description": "The previous page's next_after." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "asset_id": { "type": "string", "description": "The unit's id.", "x-data-class": "operational" }, "bic": { "type": [ "string", "null" ], "description": "The container's BIC number.", "x-data-class": "operational" }, "acquisition": { "type": [ "string", "null" ], "enum": [ "pending", "acquired", "cancelled", null ], "description": "Its acquisition state.", "x-data-class": "operational" }, "availability": { "type": [ "string", "null" ], "enum": [ "available", "committed", "withdrawn", null ], "description": "Its availability state; null once cancelled.", "x-data-class": "operational" }, "custody": { "type": [ "string", "null" ], "enum": [ "in-depot", "on-hire", "disposed", "in-transit", null ], "description": "Its custody state; null while pending and once cancelled.", "x-data-class": "operational" }, "repair_state": { "type": "string", "enum": [ "undamaged", "awaiting-estimate", "pending-approval", "pending-repair", "repaired", "unrepairable", "damaged-not-repaired" ], "description": "Its repair state.", "x-data-class": "operational" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "The org's tags on it.", "x-data-class": "operational" }, "internal_notes": { "type": [ "string", "null" ], "description": "The org's notes on it.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was recorded.", "x-data-class": "operational" }, "updated_at": { "type": "string", "format": "date-time", "description": "When it last changed.", "x-data-class": "operational" }, "size": { "type": [ "string", "null" ], "description": "Its size as recorded.", "x-data-class": "operational" }, "type": { "type": [ "string", "null" ], "description": "Its type as recorded.", "x-data-class": "operational" }, "condition": { "type": [ "string", "null" ], "description": "Its condition grade as recorded.", "x-data-class": "operational" }, "color": { "type": [ "string", "null" ], "description": "Its colour.", "x-data-class": "operational" }, "color_ral": { "type": [ "integer", "null" ], "description": "Its RAL colour number.", "x-data-class": "operational" }, "year_of_make": { "type": [ "integer", "null" ], "description": "The year it was built.", "x-data-class": "operational" }, "forklift_pockets": { "type": [ "boolean", "null" ], "description": "Whether it has forklift pockets.", "x-data-class": "operational" }, "handles": { "type": [ "string", "null" ], "description": "Its door handles.", "x-data-class": "operational" }, "lockbox": { "type": [ "boolean", "null" ], "description": "Whether it has a lockbox.", "x-data-class": "operational" }, "vents": { "type": [ "string", "null" ], "description": "Its vents.", "x-data-class": "operational" }, "intake_id": { "type": [ "string", "null" ], "description": "Its most recent intake.", "x-data-class": "operational" }, "acquisition_channel": { "type": [ "string", "null" ], "enum": [ "direct", "gate-buy", "yard-buy", "consignment", "factory-direct", "inland-transfer", "open-inventory", null ], "description": "How the holder sourced it.", "x-data-class": "operational" }, "pickup_date": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "When its purchase order picks it up at the origin, the P/U Date.", "x-data-class": "operational" }, "vendor_eta": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "When the vendor expects to deliver it.", "x-data-class": "operational" }, "transit_days": { "type": [ "integer", "null" ], "description": "Days from its P/U Date to its vendor ETA; null when either is missing, negative when the ETA is first.", "x-data-class": "operational" }, "booking_number": { "type": [ "string", "null" ], "description": "The intake's booking number.", "x-data-class": "operational" }, "intake_depot": { "type": [ "string", "null" ], "description": "The depot the intake names.", "x-data-class": "operational" }, "origin_market": { "type": [ "string", "null" ], "description": "The market its purchase order picks it up in, its origin.", "x-data-class": "operational" }, "origin_depot": { "type": [ "string", "null" ], "description": "The depot its purchase order picks it up at, its origin depot.", "x-data-class": "operational" }, "nearest_metro": { "type": [ "string", "null" ], "description": "The intake's nearest metro.", "x-data-class": "operational" }, "fee_responsibility": { "type": [ "string", "null" ], "description": "Who pays the yard fees.", "x-data-class": "operational" }, "depot": { "type": [ "string", "null" ], "description": "The depot of its most recent residency.", "x-data-class": "operational" }, "in_depot_since": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "When that residency began.", "x-data-class": "operational" }, "gated_out_at": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "When that residency ended.", "x-data-class": "operational" }, "duration_days": { "type": [ "integer", "null" ], "description": "Days in that residency.", "x-data-class": "operational" }, "release_booking_number": { "type": [ "string", "null" ], "description": "Its release's booking number.", "x-data-class": "operational" }, "holding_basis": { "type": [ "string", "null" ], "enum": [ "owned", "leased-in", "subleased", null ], "description": "The basis on which the holder holds it.", "x-data-class": "operational" }, "vendor": { "type": [ "string", "null" ], "description": "The vendor contact.", "x-data-class": "operational" }, "vendor_bill_id": { "type": [ "string", "null" ], "description": "The vendor's bill.", "x-data-class": "operational" }, "vendor_bill_paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the vendor's bill was paid.", "x-data-class": "operational" }, "purchase_price": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its purchase price, as a decimal string.", "x-data-class": "commercial" }, "lease_price": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its lease price, as a decimal string.", "x-data-class": "commercial" }, "lease_term": { "type": [ "string", "null" ], "description": "Its lease term.", "x-data-class": "operational" }, "order_id": { "type": [ "string", "null" ], "description": "Its most recent order.", "x-data-class": "operational" }, "customer": { "type": [ "string", "null" ], "description": "That order's customer contact.", "x-data-class": "operational" }, "invoice_number": { "type": [ "string", "null" ], "description": "That order's invoice number.", "x-data-class": "operational" }, "sales_order_type": { "type": [ "string", "null" ], "description": "That order's type.", "x-data-class": "operational" }, "reserved_price": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its active reservation's price, as a decimal string.", "x-data-class": "commercial" }, "listed": { "type": [ "boolean", "null" ], "description": "Whether it is listed for sale.", "x-data-class": "operational" }, "list_price": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its list price, as a decimal string.", "x-data-class": "commercial" }, "lease_base_price": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its lease base price, as a decimal string.", "x-data-class": "commercial" }, "lease_base_duration": { "type": [ "integer", "null" ], "description": "Its lease base duration.", "x-data-class": "operational" }, "purchase_terms": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its purchase terms.", "x-data-class": "financial" }, "total_cost": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its total cost in USD, as a decimal string.", "x-data-class": "commercial" }, "available": { "type": "boolean", "description": "Whether it is available to sell.", "x-data-class": "operational" }, "repair_cost": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its repair costs in USD, as a decimal string.", "x-data-class": "commercial" }, "transport_cost": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its transport costs in USD, as a decimal string.", "x-data-class": "commercial" }, "other_cost": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its other costs in USD, as a decimal string.", "x-data-class": "commercial" }, "fee_currency": { "type": [ "string", "null" ], "description": "The currency of its projected fees.", "x-data-class": "operational" }, "fee_gate_in": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its projected gate-in fee, as a decimal string.", "x-data-class": "commercial" }, "fee_gate_out": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its projected gate-out fee, as a decimal string.", "x-data-class": "commercial" }, "fee_lift": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its projected lift fees, as a decimal string.", "x-data-class": "commercial" }, "fee_storage": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its projected storage fees, as a decimal string.", "x-data-class": "commercial" }, "fee_total": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Its projected fees in total, as a decimal string.", "x-data-class": "commercial" } }, "required": [ "asset_id" ], "additionalProperties": false }, "maxItems": 500 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List inventory", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_my_notifications", "title": "List my notifications", "description": "Lists the notice kinds the caller's role can already see in the org, in the page's order, each with its state: fixed (sent to them by code, as an org admin), required (the org's notification settings names them), opted_in (they added it themselves), on (Report updates, sent by default until they turn it off) or available (they may add it with set_my_notification). Carries the audit digest's and Report updates' cadence and the sign-in address notices are emailed to.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the caller is a member of." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "audit_digest", "admin_alerts", "access_request", "break_glass", "deletion", "announcement", "report_updates" ], "description": "The notice kind.", "x-data-class": "operational" }, "title": { "type": "string", "description": "Its name, as the page shows it.", "x-data-class": "operational" }, "sent": { "type": "string", "description": "When it is sent.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "fixed", "required", "opted_in", "on", "available" ], "description": "fixed: sent to the caller by code (an org admin's notices). required: the org's notification settings names them. opted_in: they added it themselves. on: sent to them by default until they turn it off (Report updates). available: they may add it, or turn it back on.", "x-data-class": "operational" }, "cadence": { "type": [ "string", "null" ], "enum": [ "hourly", "daily", "immediately", "weekly", null ], "description": "How often the caller receives it: the audit digest hourly or daily (hourly until they choose); Report updates immediately, daily or weekly (immediately until they choose); null for every other kind.", "x-data-class": "operational" }, "email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The sign-in address a notice is emailed to.", "x-data-class": "personal" } }, "required": [ "kind", "title", "sent", "state", "cadence", "email" ], "additionalProperties": false }, "maxItems": 7 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List my notifications", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_org_grants", "title": "List the staff access grants to an org", "description": "Lists every Trade HQ staff access grant to the org, newest first: who, at which level, why, until when, and whether it is waiting, active, rejected, revoked or expired. Break-glass entries say how many of the org's admins were told. Staff are never members; this is where an admin sees them and revokes them. A staff caller is answered only their own grants to the org.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org." }, "current": { "type": "boolean", "description": "true for only the grants waiting or active now." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The grant'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 customer org it is a grant to.", "x-data-class": "operational" }, "org_name": { "type": [ "string", "null" ], "description": "That org's name.", "x-data-class": "operational" }, "grantee_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The staff member it lets in.", "x-data-class": "operational" }, "grantee_name": { "type": [ "string", "null" ], "description": "Their name, or their address when they have none.", "x-data-class": "operational" }, "grantee_email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their address.", "x-data-class": "personal" }, "level": { "type": "string", "enum": [ "read", "act" ], "description": "read: what the Read-only template carries. act: what the Admin template carries.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "request", "break_glass" ], "description": "request: asked of the org's admins. break_glass: entered at once by Sage or Sonja, the admins told.", "x-data-class": "operational" }, "reason": { "type": "string", "description": "Why, in the requester's words.", "x-data-class": "operational" }, "requested_hours": { "type": "integer", "description": "How long it was asked for.", "x-data-class": "operational" }, "requested_at": { "type": "string", "format": "date-time", "description": "When it was asked for.", "x-data-class": "operational" }, "exception_id": { "type": [ "string", "null" ], "description": "The decision card the org's admins decide a request on.", "x-data-class": "operational" }, "decision": { "type": [ "string", "null" ], "enum": [ "approved", "rejected", null ], "description": "What the admin decided; null while it waits.", "x-data-class": "operational" }, "decided_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who decided it.", "x-data-class": "operational" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When.", "x-data-class": "operational" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it became active.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops being active.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked, if it was.", "x-data-class": "operational" }, "revoked_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who revoked it.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "active", "rejected", "revoked", "expired" ], "description": "pending, active, rejected, revoked or expired, as of now.", "x-data-class": "operational" }, "notified": { "type": "integer", "description": "How many of the org's admins a break-glass notice was written to.", "x-data-class": "operational" } }, "required": [ "grant_id", "org_id", "org_name", "grantee_user_id", "grantee_name", "grantee_email", "level", "kind", "reason", "requested_hours", "requested_at", "exception_id", "decision", "decided_by", "decided_at", "approved_at", "expires_at", "revoked_at", "revoked_by", "status", "notified" ], "additionalProperties": false }, "maxItems": 1000 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List the staff access grants to an org", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_orgs", "title": "List orgs", "description": "Lists orgs, ordered by org id, a page at a time. Filters by a case-insensitive substring of the name, by org type and by account. Each org carries its id, name, type and account, where it is in its life, when a suspended org was suspended and by whom, and the end of a scheduled deletion's countdown. Why it was suspended is answered to staff only. Filters by one org id too, within the same scope. Staff also see whether an org is or was a public sandbox: its dates, its test key's display, when a running one expires, and when and by whom it was converted. A member of an account sees that account's orgs, and naming an account that is not theirs is refused; staff see every org. An org admin who is neither reads only its own org, named by org id, and is refused any other org and any list that names no org. An org with no account never matches an account filter. In live mode test twins are not listed; in test mode each twin is listed in place of its org, with its org's account. Staff also see each purged org by its id and kept name, with when it was purged, the dry run its purge was approved on, who approved it and what was deleted.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "A case-insensitive substring of the org's name." }, "org_type": { "type": "string", "enum": [ "internal", "demo", "customer", "synthetic", "system" ], "description": "Only orgs of this type." }, "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "Only orgs of this account; an org with no account never matches. A member may name only an account of theirs." }, "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "Only this org; in test mode, the twin listed in place of it. An org outside the caller's scope is an empty page. An org admin names its own org here, and is refused without it." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The previous page's next_after." } }, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org's id.", "x-data-class": "operational" }, "name": { "type": "string", "description": "The org's name.", "x-data-class": "operational" }, "org_type": { "type": [ "string", "null" ], "enum": [ "internal", "demo", "customer", "synthetic", "system", null ], "description": "The org's type (TRA-234); null for a ported org nothing has typed yet.", "x-data-class": "operational" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account the org belongs to; null when it has none yet.", "x-data-class": "operational" }, "state": { "type": [ "string", "null" ], "enum": [ "active", "suspended", "deletion_scheduled", "purged", null ], "description": "Where the org is in its life (TRA-316); null for an org with no lifecycle row.", "x-data-class": "operational" }, "purge_after": { "type": [ "string", "null" ], "format": "date-time", "description": "The end of a scheduled deletion's 30 day countdown; null when none is scheduled.", "x-data-class": "operational" }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a suspended org was suspended, as suspend_org recorded it; null in every other state, and for a suspension recorded before the field existed.", "x-data-class": "operational" }, "suspended_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who suspended a suspended org, as suspend_org recorded it; null in every other state, and for a suspension recorded before the field existed.", "x-data-class": "operational" }, "suspended_by_name": { "type": [ "string", "null" ], "description": "That user's name; null when suspended_by is, when they have no name, and once they are anonymized.", "x-data-class": "operational" }, "suspend_reason": { "type": [ "string", "null" ], "description": "Why a suspended org was suspended, as suspend_org recorded it. Answered to staff only: null to an account member, in every other state, and when no reason was given.", "x-data-class": "operational" }, "sandbox": { "type": [ "object", "null" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "key_display": { "type": "string" }, "converted_at": { "type": [ "string", "null" ], "format": "date-time" }, "converted_by": { "type": [ "string", "null" ] } }, "required": [ "created_at", "expires_at", "key_display", "converted_at", "converted_by" ], "additionalProperties": false, "description": "For an org that is or was a public sandbox (TRA-474): when it was made, when it expires, its one test key's display (never the secret), and when and by whom staff converted it, both null until then. Null for every other org, and for any caller who is not staff.", "x-data-class": "operational" }, "purged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a purged org was purged (TRA-467); null for every other org, and for any caller who is not staff.", "x-data-class": "operational" }, "purge": { "type": [ "object", "null" ], "properties": { "dry_run_id": { "type": "string" }, "approvers": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "principal": { "type": "boolean" }, "approved_at": { "type": "string", "format": "date-time" } }, "required": [ "user_id", "name", "principal", "approved_at" ], "additionalProperties": false } }, "counts": { "type": [ "object", "null" ] }, "deleted": { "type": [ "object", "null" ] } }, "required": [ "dry_run_id", "approvers", "counts", "deleted" ], "additionalProperties": false, "description": "A purged org's purge (TRA-467): the dry run it was approved on, who approved it (oldest first), what that dry run counted, which the purge job's recount found unchanged, and what the job deleted ({rows, tables}). Null for every other org, for a purge recorded before dry runs existed, and for any caller who is not staff.", "x-data-class": "operational" }, "customer_stage": { "type": [ "string", "null" ], "enum": [ "prospect", "pilot", "customer", null ], "description": "Where a customer org is in Trade HQ's sales cycle (TRA-1273): prospect, pilot, or customer when it has no stage; a twin answers its live org's. Null for an org that is not a customer org, and for any caller who is not staff.", "x-data-class": "operational" }, "sandbox_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a running public sandbox and its key are deleted; null once it is converted or purged, for every other org, and for any caller who is not staff.", "x-data-class": "operational" } }, "required": [ "org_id", "name", "org_type", "account_id", "state", "purge_after", "suspended_at", "suspended_by", "suspended_by_name", "suspend_reason", "sandbox", "purged_at", "purge", "customer_stage", "sandbox_expires_at" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List orgs", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_permissions", "title": "List permissions", "description": "Lists the permission catalog: every permission a capability declares, with what it lets someone do, where it is held, whether a role template may carry it and whether such a role may be given on a unit or only on the whole org, the capabilities it admits to, and whether your role in the given org carries it.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org to read `held` against." }, "scope": { "type": "string", "enum": [ "staff", "account", "org", "self", "seat", "share", "signed_in", "public" ], "description": "Only permissions held at this scope: staff, account, org, self, seat, signed_in or public." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The permission, e.g. org.admin.", "x-data-class": "operational" }, "description": { "type": "string", "description": "What holding it lets someone do.", "x-data-class": "operational" }, "scope": { "type": "string", "enum": [ "staff", "account", "org", "self", "seat", "share", "signed_in", "public" ], "description": "Where it is held.", "x-data-class": "operational" }, "role_bindable": { "type": "boolean", "description": "Whether a role template may carry it. Staff and account permissions are not.", "x-data-class": "operational" }, "given_on": { "type": [ "string", "null" ], "enum": [ "unit", "org", null ], "description": "Where a role carrying it may be given (TRA-473): unit, on a unit and everything beneath it, or org, on the whole organization only. A role with any org permission cannot be given on a unit. Null when no role carries it.", "x-data-class": "operational" }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "The capabilities it admits to, by name.", "x-data-class": "operational" }, "capability_titles": { "type": "array", "items": { "type": "string" }, "description": "Each admitted capability's title, in plain words, in the same order as capabilities.", "x-data-class": "operational" }, "held": { "type": "boolean", "description": "Whether your role template in the org carries it.", "x-data-class": "operational" } }, "required": [ "name", "description", "scope", "role_bindable", "given_on", "capabilities", "capability_titles", "held" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List permissions", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_portfolios", "title": "List portfolios", "description": "Lists portfolios, ordered by portfolio id, a page at a time. Each carries its id, name and account, and its orgs by id and name. An account owner names an account they own and sees that account's portfolios and no others; staff may name any account, or none to see every portfolio, staff portfolios included.", "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "Only this account's portfolios. Required of an account owner, and one they own; staff may leave it out." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-portfolio-id", "description": "The previous page's next_after." } }, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "portfolio_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-portfolio-id", "description": "The portfolio's id.", "x-data-class": "operational" }, "name": { "type": "string", "description": "Its name.", "x-data-class": "operational" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "Its account; null for a staff portfolio.", "x-data-class": "operational" }, "org_count": { "type": "integer", "minimum": 0, "description": "How many orgs it holds.", "x-data-class": "operational" }, "orgs": { "type": "array", "items": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id" }, "name": { "type": "string" } }, "required": [ "org_id", "name" ], "additionalProperties": false }, "description": "Its orgs, by org id, each with its name.", "x-data-class": "operational" } }, "required": [ "portfolio_id", "name", "account_id", "org_count", "orgs" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List portfolios", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_purchase_orders", "title": "List purchase orders", "description": "Lists an org's purchase orders a page at a time, those with no containers yet included: each with its number, supplier, type and status, its origin (origin market, origin depot, P/U Date), its destination (destination market, destination depot, ETA), the transit days between P/U Date and ETA, and how many of its containers have landed. Filtered by vendor, origin_market, destination_market, pickup_date, vendor_eta, acquisition_channel, inventory_type and purchase_order_status, all ANDed, and by q, the start of a purchase order number, unit number or supplier bill. Sorted by one key, paged by its cursor; fields chooses the columns from the field groups. A page holds at most 500 purchase orders and one walk of the cursor at most 10,000 (walk_ceiling_reached). summarize_purchase_orders counts the same ones.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose purchase orders they are." }, "filters": { "type": "object", "properties": { "vendor": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^CT[0-9A-Za-z]{1,18}$", "format": "tradehq-contact-id", "x-filter-kind": "id_reference", "description": "The supplier contact the purchase order buys from." }, "origin_market": { "type": "string", "minLength": 1, "maxLength": 128, "format": "tradehq-market", "x-filter-kind": "id_reference", "description": "The market the purchase order's containers come from: the supplier's nearest port or metro, as recorded." }, "destination_market": { "type": "string", "minLength": 1, "maxLength": 128, "format": "tradehq-market", "x-filter-kind": "id_reference", "description": "The market the purchase order's containers are delivered to, as recorded." }, "pickup_date": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "The day the containers are picked up at the origin (P/U Date): a range of days, or true for a purchase order with one and false for one without." }, "vendor_eta": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "The day the supplier expects the containers to arrive for gate-in at the destination: a range of days, or true for a purchase order with an ETA and false for one without." }, "acquisition_channel": { "type": "array", "items": { "type": "string", "enum": [ "direct", "gate-buy", "yard-buy", "consignment", "factory-direct", "inland-transfer", "open-inventory" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "How a holder sources a unit: bought direct, bought in transit to a customer (gate buy), bought where it sits in a supplier's yard (yard buy), taken on consignment, bought from the factory, transferred in from a supplier's depot account, or listed as open inventory before any unit lands. One half of today's purchase_order_type, split by Sage's decision of 2026-10-05; the other half is HoldingBasis." }, "inventory_type": { "type": "array", "items": { "type": "string", "enum": [ "direct", "factory-direct-purchase", "yard-buy", "inland-yard-transfer", "gate-buy", "consignment", "lease", "sublease", "open-inventory", "open-inventory-landed" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The purchase order's type as recorded, the Procure list's Inventory Type: direct, factory direct purchase, yard buy, inland yard transfer, gate buy, consignment, lease, sublease, open inventory, or open inventory landed." }, "purchase_order_status": { "type": "array", "items": { "type": "string", "enum": [ "pending", "in-progress", "completed", "cancelled" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Where the purchase order stands: pending, in progress (partly filled), completed or cancelled (voided)." } }, "additionalProperties": false, "minProperties": 1, "x-combine": "and", "description": "Purchase orders matching every term given." }, "q": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The start of a purchase order number, a unit number on it or a supplier bill on it, case ignored." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "created_at", "updated_at", "booking_number", "pickup_date", "vendor_eta", "transit_days", "origin_market", "destination_market", "container_count" ], "x-enum-descriptions": [ "Newest purchase order first.", "Most recently changed first.", "By purchase order number.", "Earliest P/U Date first.", "Earliest ETA first.", "Shortest transit first.", "By origin market.", "By destination market.", "Most containers first." ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "default": [ { "key": "created_at", "dir": "desc" } ], "x-keyset": [ "sort key", "intake_id" ], "description": "One sort key and its direction. Newest purchase order first when left out." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "booking_number", "vendor", "purchase_order_type", "acquisition_channel", "status", "expires_at", "created_at", "updated_at", "origin_market", "origin_depot", "origin_depot_name", "pickup_date", "destination_market", "destination_depot", "destination_depot_name", "vendor_eta", "transit_days", "container_count", "landed_count" ] }, "minItems": 1, "uniqueItems": true, "default": [ "booking_number", "vendor", "purchase_order_type", "acquisition_channel", "status", "expires_at", "created_at", "updated_at", "origin_market", "origin_depot", "origin_depot_name", "pickup_date", "destination_market", "destination_depot", "destination_depot_name", "vendor_eta", "transit_days", "container_count", "landed_count" ], "x-field-groups": [ { "name": "order", "fields": [ "booking_number", "vendor", "purchase_order_type", "acquisition_channel", "status", "expires_at", "created_at", "updated_at" ], "default": true, "description": "The purchase order itself: its number, supplier, type, status and dates." }, { "name": "route", "fields": [ "origin_market", "origin_depot", "origin_depot_name", "pickup_date", "destination_market", "destination_depot", "destination_depot_name", "vendor_eta", "transit_days" ], "default": true, "description": "Where the containers come from and when, where they go and when, and the days between." }, { "name": "units", "fields": [ "container_count", "landed_count" ], "default": true, "description": "How many containers the purchase order carries and how many have landed." } ], "description": "The fields to answer, from the field groups. All three groups when left out." }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100, "description": "The page size." }, "after": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 1024, "format": "tradehq-keyset-cursor", "description": "The previous page's next_after." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "intake_id": { "type": "string", "description": "The purchase order's id.", "x-data-class": "operational" }, "booking_number": { "type": "string", "description": "The purchase order number.", "x-data-class": "operational" }, "vendor": { "type": [ "string", "null" ], "description": "The supplier contact.", "x-data-class": "operational" }, "purchase_order_type": { "type": "string", "description": "The inventory type, as recorded.", "x-data-class": "operational" }, "acquisition_channel": { "type": [ "string", "null" ], "enum": [ "direct", "gate-buy", "yard-buy", "consignment", "factory-direct", "inland-transfer", "open-inventory", null ], "description": "How it sources its units; null for a lease or sublease.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "in-progress", "completed", "cancelled" ], "description": "Where it stands.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When its still-pending units are discarded as cancelled.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created.", "x-data-class": "operational" }, "updated_at": { "type": "string", "format": "date-time", "description": "When it last changed.", "x-data-class": "operational" }, "origin_market": { "type": [ "string", "null" ], "description": "The market its containers come from.", "x-data-class": "operational" }, "origin_depot": { "type": [ "string", "null" ], "description": "The depot they are picked up at.", "x-data-class": "operational" }, "origin_depot_name": { "type": [ "string", "null" ], "description": "That depot's name.", "x-data-class": "operational" }, "pickup_date": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The day they are picked up (P/U Date).", "x-data-class": "operational" }, "destination_market": { "type": [ "string", "null" ], "description": "The market they are delivered to.", "x-data-class": "operational" }, "destination_depot": { "type": [ "string", "null" ], "description": "The depot they are delivered to.", "x-data-class": "operational" }, "destination_depot_name": { "type": [ "string", "null" ], "description": "That depot's name.", "x-data-class": "operational" }, "vendor_eta": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The day the supplier expects them at the destination (ETA).", "x-data-class": "operational" }, "transit_days": { "type": [ "integer", "null" ], "description": "Days from P/U Date to ETA; null unless both are known.", "x-data-class": "operational" }, "container_count": { "type": "integer", "minimum": 0, "description": "Its containers, not counting cancelled ones.", "x-data-class": "operational" }, "landed_count": { "type": "integer", "minimum": 0, "description": "Of those, the ones no longer pending.", "x-data-class": "operational" } }, "required": [ "intake_id" ], "additionalProperties": false }, "maxItems": 500 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List purchase orders", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_received_data_shares", "title": "List data shares received", "description": "Lists the data shares other orgs have made with an org: every share made to the party the org has claimed, from whom, what, to which addresses and how often. A revoked share is never listed; a declined one is, with when it was declined. Any member of the org may read it. An org that has claimed no party receives nothing and is refused org_party_unclaimed.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The receiving org." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "data_share_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The share.", "x-data-class": "operational" }, "from_org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that made it.", "x-data-class": "operational" }, "from_org_name": { "type": "string", "description": "That org's name.", "x-data-class": "operational" }, "query": { "type": "string", "enum": [ "vendor_bill_request", "vendor_forecast", "vendor_sell_through" ], "description": "The saved query it shares.", "x-data-class": "operational" }, "title": { "type": "string", "description": "What it is called.", "x-data-class": "operational" }, "recipients": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\\.)+([A-Za-z]{2,}|[Xx][Nn]--[A-Za-z0-9-]*[A-Za-z0-9])$", "maxLength": 254 }, "uniqueItems": true }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The addresses it is emailed to.", "x-data-class": "personal" }, "cadence": { "type": [ "string", "null" ], "enum": [ "daily", "hourly", null ], "description": "How often it is emailed.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was made.", "x-data-class": "operational" }, "declined_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the org stopped receiving it, or null.", "x-data-class": "operational" }, "declinable": { "type": "boolean", "description": "Whether decline_data_share can still decline it: a live share can.", "x-data-class": "operational" } }, "required": [ "data_share_id", "from_org_id", "from_org_name", "query", "title", "recipients", "cadence", "created_at", "declined_at", "declinable" ], "additionalProperties": false }, "maxItems": 1000 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List data shares received", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_report_opens", "title": "List my report opens", "description": "Lists how often the caller opened each report in an org over the last 90 days, most opened first, then by report name: one item per report opened, with its count and when it was last opened. Only the caller's own opens (record_report_open), never anyone else's. The Reports list is ordered by it, after the reports of the tab the person is on.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the reports were opened in." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "report": { "type": "string", "enum": [ "available_to_promise", "yard_fees_by_unit", "yard_monthly_fees", "sourced_overall", "sourced_by_supplier", "orders_overall", "orders_by_customer", "activity_log", "inventory_audit", "failed_comms", "depot_inventory", "asset_inventory", "cash_flow_audit" ], "description": "The report.", "x-data-class": "operational" }, "opens": { "type": "integer", "description": "How many times the caller opened it in the last 90 days, at least one.", "x-data-class": "operational" }, "last_opened_at": { "type": "string", "format": "date-time", "description": "When the caller last opened it.", "x-data-class": "operational" } }, "required": [ "report", "opens", "last_opened_at" ], "additionalProperties": false }, "maxItems": 13 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List my report opens", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_reports", "title": "List customer reports", "description": "Lists the reports an org filed with Trade HQ support (feedback, problems and questions), newest first, a page at a time: each with its reference (CUS-n), title, kind, how and by whom it was filed, its status in plain words (received, waiting on you, planned, fixed, answered, won't fix, duplicate) and when it got there, a planned report's window, the note written for the customer, and whether the person asking follows it and has seen its latest change. A member reads their own org's reports; an account owner every org of their account; staff every org; org_id and account_id narrow. A private report is listed only to its reporter and to staff. Filtered by status, kind, filed_via, impact, reported (a range of days), reporter (a user id or me), following, unread and private, all ANDed, and by q, words in the title or text. A page holds at most 200 reports and one walk of the cursor at most 10,000 (walk_ceiling_reached). summarize_reports counts the same ones.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "One org's reports. A member names their own org; staff and an account owner may leave it out for every org they reach." }, "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "One account's orgs. An account owner may name only an account they own." }, "filters": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": [ "received", "waiting_on_you", "planned", "fixed", "answered", "wont_fix", "duplicate" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Where the report stands in plain words: received, waiting on you, planned, fixed, answered, won't fix or duplicate, derived from its ticket in the support tracker and never set by hand." }, "kind": { "type": "array", "items": { "type": "string", "enum": [ "feedback", "problem", "question" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "What the report is about: feedback on the product, a problem that stops or slows the reporter, or a question about how to do something." }, "filed_via": { "type": "array", "items": { "type": "string", "enum": [ "app", "email", "staff" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "How the report reached the support team: in the app, by email to the support address, or filed by staff for the customer." }, "impact": { "type": "array", "items": { "type": "string", "enum": [ "blocking", "slowing", "suggestion" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "How much the reported problem hurts, in the reporter's own estimate: blocking, slowing or a suggestion. Absent when the reporter gave none." }, "reported": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false, "x-filter-kind": "date_range", "description": "When the report was filed: the moment its ticket was created, read by day (Pacific time) when a list filters on a date range." }, "reporter": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]+$", "x-filter-kind": "id_reference", "description": "The member who filed the report in the app: a user id, or me for the caller. An email-filed report has a sender's address instead, and a report staff filed for the customer has neither." }, "following": { "type": "boolean", "x-filter-kind": "presence", "description": "Whether the person asking follows the report: true for the reports they follow (their own from the day each was filed, and any they chose to follow), false for the rest." }, "unread": { "type": "boolean", "x-filter-kind": "presence", "description": "Whether the report changed since the person asking last saw it: true for a report with a change newer than the last one they saw, or that they have never opened." }, "private": { "type": "boolean", "x-filter-kind": "presence", "description": "Whether the reporter marked the report private: then only the reporter and Trade HQ staff see it. true lists the private reports the person asking may see." } }, "additionalProperties": false, "minProperties": 1, "x-combine": "and", "description": "Reports matching every term given." }, "q": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Words in a report's title or text, case ignored: \"already reported?\"." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "reported_at", "status_at", "waiting_first" ], "x-enum-descriptions": [ "Newest report first.", "Most recent status change first.", "Reports waiting on the customer first, then newest report first." ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "default": [ { "key": "reported_at", "dir": "desc" } ], "x-keyset": [ "sort key", "report_id" ], "description": "One sort key and its direction. Newest report first when left out." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "ticket", "org_name", "title", "kind", "filed_via", "reporter", "reporter_email", "impact", "private", "reported_at", "status", "status_at", "window", "note", "release_note_url", "duplicate_of", "duplicate_status", "fixed_at", "days_to_fix", "last_event_at", "following", "unread" ] }, "minItems": 1, "uniqueItems": true, "default": [ "ticket", "org_name", "title", "kind", "filed_via", "reporter", "reporter_email", "impact", "private", "reported_at", "status", "status_at", "window", "note", "release_note_url", "duplicate_of", "duplicate_status", "fixed_at", "days_to_fix", "last_event_at", "following", "unread" ], "x-field-groups": [ { "name": "report", "fields": [ "ticket", "org_name", "title", "kind", "filed_via", "reporter", "reporter_email", "impact", "private", "reported_at" ], "default": true, "description": "The report itself: its reference, org, title, kind, how and by whom it was filed, and when." }, { "name": "status", "fields": [ "status", "status_at", "window", "note", "release_note_url", "duplicate_of", "duplicate_status", "fixed_at", "days_to_fix" ], "default": true, "description": "Where it stands: its status and since when, its window, the note for the customer, and the fix." }, { "name": "activity", "fields": [ "last_event_at", "following", "unread" ], "default": true, "description": "Its newest change, and whether the person asking follows it and has seen that change." } ], "description": "The fields to answer, from the field groups. All three groups when left out." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 1024, "format": "tradehq-keyset-cursor", "description": "The previous page's next_after." } }, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report's id: its ticket's id in the support tracker.", "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 that filed it.", "x-data-class": "operational" }, "ticket": { "type": "string", "description": "Its reference, CUS-n, as the customer quotes it.", "x-data-class": "operational" }, "org_name": { "type": [ "string", "null" ], "description": "That org's name.", "x-data-class": "operational" }, "title": { "type": "string", "description": "The first line of the reporter's own words.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "feedback", "problem", "question" ], "description": "Feedback, a problem or a question.", "x-data-class": "operational" }, "filed_via": { "type": "string", "enum": [ "app", "email", "staff" ], "description": "How it was filed: in the app, by email, or by staff for the customer.", "x-data-class": "operational" }, "reporter": { "anyOf": [ { "type": [ "object", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The member who filed it in the app, {user_id, name}; null when it was filed by email or by staff.", "x-data-class": "personal" }, "reporter_email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The sender's address, for a report filed by email.", "x-data-class": "personal" }, "impact": { "type": [ "string", "null" ], "enum": [ "blocking", "slowing", "suggestion", null ], "description": "How much it hurts, in the reporter's estimate.", "x-data-class": "operational" }, "private": { "type": "boolean", "description": "Whether only its reporter and staff see it.", "x-data-class": "operational" }, "reported_at": { "type": "string", "format": "date-time", "description": "When it was filed.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "received", "waiting_on_you", "planned", "fixed", "answered", "wont_fix", "duplicate" ], "description": "Where it stands.", "x-data-class": "operational" }, "status_at": { "type": "string", "format": "date-time", "description": "When it reached that status.", "x-data-class": "operational" }, "window": { "type": [ "string", "null" ], "enum": [ "next_release", "this_month", "later", null ], "description": "When a planned report is expected: next release, this month or later; null unless planned.", "x-data-class": "operational" }, "note": { "type": [ "string", "null" ], "description": "The latest note written for the customer.", "x-data-class": "operational" }, "release_note_url": { "type": [ "string", "null" ], "description": "The customer-facing release note of the fix, when it has one.", "x-data-class": "operational" }, "duplicate_of": { "type": [ "string", "null" ], "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report this one duplicates, when that report is this org's and the person asking may see it.", "x-data-class": "operational" }, "duplicate_status": { "type": [ "string", "null" ], "enum": [ "received", "waiting_on_you", "planned", "fixed", "answered", "wont_fix", "duplicate", null ], "description": "The status of the report this one duplicates.", "x-data-class": "operational" }, "fixed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the fix went live for the org.", "x-data-class": "operational" }, "days_to_fix": { "type": [ "integer", "null" ], "description": "Calendar days, Pacific time, from the day reported to the day fixed.", "x-data-class": "operational" }, "last_event_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When its timeline last changed.", "x-data-class": "operational" }, "following": { "type": "boolean", "description": "Whether the person asking follows it.", "x-data-class": "operational" }, "unread": { "type": "boolean", "description": "Whether it changed since the person asking last saw it.", "x-data-class": "operational" } }, "required": [ "report_id", "org_id" ], "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 }, "annotations": { "title": "List customer reports", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_role_templates", "title": "List role templates", "description": "Lists the role templates an org can assign: the shipped bundles (Owner, Admin, Ops, Sales, Finance, Read-only, Developer and one Counterparty per seat), which cannot be changed, and the org's own clones. Each carries its permissions, its module tags, the Clerk role it maps to, and how many of the org's members hold it. Filters by module and by kind.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose templates to list." }, "module": { "type": "string", "enum": [ "leasing", "trading", "depot", "forwarding" ], "description": "Only templates tagged with this module." }, "kind": { "type": "string", "enum": [ "shipped", "clone" ], "description": "shipped (read-only bundles) or clone (the org's own)." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "role_id": { "type": "string", "description": "The template's id: a shipped id such as admin, or a clone's RT id.", "x-data-class": "operational" }, "title": { "type": "string", "description": "Its name.", "x-data-class": "operational" }, "description": { "type": [ "string", "null" ], "description": "What it is for.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "shipped", "clone" ], "description": "shipped or clone.", "x-data-class": "operational" }, "read_only": { "type": "boolean", "description": "True for a shipped template: clone it to change it.", "x-data-class": "operational" }, "family": { "type": [ "string", "null" ], "description": "The family it belongs to, such as counterparty.", "x-data-class": "operational" }, "seat": { "type": [ "string", "null" ], "description": "Its seat in the family, such as depot.", "x-data-class": "operational" }, "modules": { "type": "array", "items": { "type": "string" }, "description": "The modules it is tagged with.", "x-data-class": "operational" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "The permissions it carries.", "x-data-class": "operational" }, "clerk_role": { "type": "string", "description": "The Clerk built-in role its members hold: org:admin when it carries org.admin, else org:member (TRA-963).", "x-data-class": "operational" }, "cloned_from": { "type": [ "string", "null" ], "description": "The template a clone was made from; null for a shipped one.", "x-data-class": "operational" }, "members": { "type": "integer", "description": "How many of the org's members hold it.", "x-data-class": "operational" }, "units": { "type": "integer", "description": "How many grants on the org's units name it (TRA-473): it is held on that many units.", "x-data-class": "operational" } }, "required": [ "role_id", "title", "description", "kind", "read_only", "family", "seat", "modules", "permissions", "clerk_role", "cloned_from", "members", "units" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List role templates", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_saved_views", "title": "List saved views", "description": "Lists the saved views a member may open in an org: the system views every org has, then the member's own views and the ones shared with the org, pinned first and then most recently changed. A saved view is a stored call of a list capability: its capability, contract and args, which can be sent to that capability as they are. Give capability to list one list's views, or mode (inventory or sales) to list one screen's, and tab for that tab's Home: the views pinned there for the member, by themselves or by an org admin for everyone. Each view says who it is shared with by name and where it is pinned. At most 200; more is refused (too_many_views).", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose views they are." }, "capability": { "type": "string", "enum": [ "list_inventory", "summarize_catalog", "list_catalog" ], "description": "Only the views of this list capability. Every list's when left out." }, "tab": { "type": "string", "enum": [ "depots", "sell", "source", "intel" ], "description": "Only the views pinned to this tab's Home for the caller (theirs, or an org admin's for everyone), and no system view. Every view when left out." }, "mode": { "type": "string", "enum": [ "inventory", "sales", "sales_lines" ], "description": "Only the views of this mode: inventory, or sales (the Sales catalog's). Every mode's when left out." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "view_id": { "type": "string", "description": "The view: a UUID, or system: for a system view.", "x-data-class": "operational" }, "capability": { "type": "string", "enum": [ "list_inventory", "summarize_catalog", "list_catalog" ], "description": "The list capability it calls.", "x-data-class": "operational" }, "mode": { "type": [ "string", "null" ], "enum": [ "inventory", "sales", "sales_lines", null ], "description": "inventory: a grid of units. sales: a Sales catalog view, the grouped read with its split_by, source slice and layout. sales_lines: the sales grid's line table, a list_catalog call. Null only for a capability in no mode, which every_savable_capability_is_in_exactly_one_mode holds never happens.", "x-data-class": "operational" }, "contract": { "type": "string", "description": "The capability's contract and the stored call's version, @.", "x-data-class": "operational" }, "args": { "type": "object", "properties": { "filters": { "type": "object", "description": "The list's filters input, as the capability declares it." }, "q": { "type": "string", "description": "The list's q input." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "One of the called capability's sort keys." }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "description": "The list's sort input: one key and its direction." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The list's fields input." }, "limit": { "type": "integer", "description": "The list's limit input." }, "split_by": { "type": "array", "items": { "type": "string" }, "description": "A Sales catalog view's split_by, in the order the attributes were switched on (summarize_catalog's input)." }, "slice": { "type": "string", "enum": [ "owned", "partner", "supplier", "all" ], "description": "A Sales catalog view's source slice: owned, partner, supplier or all." }, "layout": { "type": "string", "enum": [ "cards", "rows" ], "description": "A Sales catalog view's layout: cards or rows." } }, "additionalProperties": false, "description": "The call's arguments: filters, q, sort, fields and limit, as given.", "x-data-class": "operational" }, "title": { "type": "string", "description": "What it is called.", "x-data-class": "operational" }, "pinned": { "type": "boolean", "description": "Whether it is pinned to the top.", "x-data-class": "operational" }, "visibility": { "type": "string", "enum": [ "private", "org-read", "org-write" ], "description": "private: its owner alone. org-read: every member reads it. org-write: every member reads, changes and deletes it. A system view is org-read.", "x-data-class": "operational" }, "system": { "type": "boolean", "description": "A system view: declared for every org, never changed.", "x-data-class": "operational" }, "owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who saved it; null for a system view and for a moved view whose owner is gone.", "x-data-class": "operational" }, "writable": { "type": "boolean", "description": "Whether the caller may change or delete it.", "x-data-class": "operational" }, "unmapped": { "type": "array", "items": { "type": "string" }, "description": "What of an older saved search the call could not carry, each as field: why. Empty for a view saved as a call.", "x-data-class": "operational" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it last changed; null for a system view.", "x-data-class": "operational" }, "shared_with": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "format": "tradehq-user-id", "description": "The teammate it is shared with." }, "shared_by": { "type": "string", "format": "tradehq-user-id", "description": "Who shared it: its owner." }, "created_at": { "type": "string", "format": "date-time", "description": "When." } }, "required": [ "user_id", "shared_by", "created_at" ], "additionalProperties": false }, "description": "The teammates its owner shared it with by name, each {user_id, shared_by, created_at}, by user id. Empty for a system view.", "x-data-class": "operational" }, "pins": { "type": "array", "items": { "type": "object", "properties": { "tab": { "type": "string", "enum": [ "depots", "sell", "source", "intel" ], "description": "The tab whose Home shows it." }, "for": { "type": "string", "enum": [ "me", "everyone" ], "description": "me: the caller's own pin. everyone: an org admin's, on every member's Home." }, "user_id": { "type": [ "string", "null" ], "format": "tradehq-user-id", "description": "The caller, on their own pin; null on the org's." }, "pinned_by": { "type": "string", "format": "tradehq-user-id", "description": "Who pinned it: the caller, or the org admin who pinned it for everyone." }, "created_at": { "type": "string", "format": "date-time", "description": "When." } }, "required": [ "tab", "for", "user_id", "pinned_by", "created_at" ], "additionalProperties": false }, "description": "Where it is pinned for the caller, by tab: their own pins (for me) and the org's (for everyone, an org admin's). Empty for a system view.", "x-data-class": "operational" } }, "required": [ "view_id", "capability", "mode", "contract", "args", "title", "pinned", "visibility", "system", "owner_user_id", "writable", "unmapped", "updated_at", "shared_with", "pins" ], "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 }, "annotations": { "title": "List saved views", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_service_accounts", "title": "List service accounts", "description": "Lists the org's service accounts, newest first: each one's org, primary and backup owner, role template, mode (live or test), status (active, suspended, disabled or expired), how many working API keys it holds, when it expires, and when a key of it was last used. Disabled accounts only with include_disabled.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose service accounts to list." }, "include_disabled": { "type": "boolean", "description": "Also list disabled accounts. False by default." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "service_account_id": { "type": "string", "description": "The account'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 live org it belongs to.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What it is for.", "x-data-class": "operational" }, "owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Its primary owner; null only while it is suspended for want of one.", "x-data-class": "operational" }, "backup_owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Its backup owner, who takes over when the primary is deactivated; null once that has happened.", "x-data-class": "operational" }, "role_template_id": { "type": "string", "description": "The role template it acts under: never Owner or Admin.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live or test; its keys are sk_live_ or sk_test_ to match.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "suspended", "disabled", "expired" ], "description": "active; suspended when its last owner was deactivated, until an admin reassigns it; disabled, which is final; or expired.", "x-data-class": "operational" }, "expires_at": { "type": "string", "format": "date-time", "description": "When it and every key of it stop working, unless renewed.", "x-data-class": "operational" }, "keys": { "type": "integer", "description": "How many working keys it holds.", "x-data-class": "operational" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The start of the last minute any key of it was served a request; null if never.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was made.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who made it.", "x-data-class": "operational" } }, "required": [ "service_account_id", "org_id", "name", "owner_user_id", "backup_owner_user_id", "role_template_id", "mode", "status", "expires_at", "keys", "last_used_at", "created_at", "created_by" ], "additionalProperties": false }, "maxItems": 1000 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List service accounts", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_sessions", "title": "List an org's active sessions", "description": "Lists the org's active sessions, most recently active first: each with the person, whether it is a sign-in or an MCP connection, when it started and was last seen, where (a masked address and the browser), how the person signed in, and whether it is the session making this call. Give user_id to list one person's; a member who is not an admin lists only their own.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose sessions to list." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Only this person's sessions. A member who is not an admin gives their own." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "session_id": { "type": "string", "description": "The session: what revoke_sessions takes.", "x-data-class": "operational" }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The person.", "x-data-class": "operational" }, "email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The person's email address.", "x-data-class": "personal" }, "surface": { "type": "string", "enum": [ "clerk", "mcp" ], "description": "clerk: a sign-in. mcp: an MCP connection.", "x-data-class": "operational" }, "started_at": { "type": "string", "format": "date-time", "description": "When the session was first seen.", "x-data-class": "operational" }, "last_seen_at": { "type": "string", "format": "date-time", "description": "Its last request, to the minute.", "x-data-class": "operational" }, "ip_masked": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Where from, masked.", "x-data-class": "personal" }, "user_agent": { "type": [ "string", "null" ], "description": "The browser or client it last named.", "x-data-class": "operational" }, "factors": { "type": "string", "enum": [ "sso_idp_mfa", "sso", "totp", "passkey", "magic_link", "unknown" ], "description": "How the person signed in.", "x-data-class": "operational" }, "current": { "type": "boolean", "description": "Whether it is the session making this call.", "x-data-class": "operational" } }, "required": [ "session_id", "user_id", "email", "surface", "started_at", "last_seen_at", "ip_masked", "user_agent", "factors", "current" ], "additionalProperties": false }, "maxItems": 1000 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List an org's active sessions", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_shared_catalog", "title": "List a shared catalog", "description": "Lists the catalog lines of a share another org sent you, a line at a time: one line per market, depot, size, type, condition, colour and hardware, with its available units. Only the lines the share holds, and only its recipients may read it. Filtered by market, depot, size, type, condition and availability, all ANDed. Sorted by one key, paged by its cursor; fields chooses the columns, and a price is answered only where the share shows it (field_not_granted otherwise). A page holds at most 500 lines and one walk of the cursor at most 10,000 (walk_ceiling_reached).", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that made the share." }, "share_inbound_id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The received share, by its recipient row: the share_inbound_id the received shares list names." }, "filters": { "type": "object", "properties": { "market": { "type": "string", "minLength": 1, "maxLength": 128, "format": "tradehq-market", "x-filter-kind": "id_reference", "description": "A place equipment sits at, is priced from, or moves between. Availability and price are location-qualified everywhere in the trade (\"what's available where at what cost\"), which makes Location a first-class dimension of every sub-domain rather than an attribute of any one of them. A Depot is a facility at a Location; cities, regions, and ports are Locations without being facilities." }, "depot": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^Y[0-9A-Za-z]{1,18}$", "format": "tradehq-depot-id", "x-filter-kind": "id_reference", "description": "A facility that stores, handles, inspects, and repairs containers: the physical node of the operations clearinghouse. Carries fee schedules and rates, generates gate-in and gate-out events, and holds inventory whose states the depot sub-domain defines. Trade HQ's schema calls this a yard; the industry says depot; both names are attested and kept. Industry-wide, a depot is identified by a BIC Facility Code, a nine-character child code of the UN/LOCODE." }, "size": { "type": "array", "items": { "type": "string", "enum": [ "10", "20", "40", "45", "53" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Nominal container lengths in feet as traded: 10, 20, 40, 45, 53. A convention: the set differs by market (53ft is North American domestic), and TEU arithmetic is derived from it, not stored on it." }, "type": { "type": "array", "items": { "type": "string", "enum": [ "std", "hc", "stddd", "hcdd", "stdos", "hcos", "hcos2dr", "hcos4dr", "stdot", "hcot", "stdrf", "hcrf", "fr", "duocon" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The construction-type vocabulary for containers: standard, high cube, open top, open side, double door, flat rack, reefer, and combinations. These are Trade HQ's internal codes with practitioner definitions; they are not ISO 6346 size-type codes, and the mapping to ISO is an open question (OQ-003)." }, "condition": { "type": "array", "items": { "type": "string", "enum": [ "new", "cw", "wwt", "asis", "iicl", "reefer-pti", "reefer-nopti", "reefer-broken", "twotrip" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The condition ladder used to grade a container's state for sale or lease. A convention, not an axiom: the ladder and its labels vary by sub-market and era, so the ontology records the attested set without hard-coding order." }, "availability": { "type": "array", "items": { "type": "string", "enum": [ "available" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The commercial-availability half of inventory state: whether the holder will offer a unit right now. Seat-relative by nature, a lessor's available and a trader's available are different judgments over the same box, which is why availability is the holder's tenant-private call expressed in this canonical vocabulary rather than a physical fact." }, "color": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 50, "uniqueItems": true, "x-filter-kind": "text_set", "description": "The container's colour, as recorded: any of the values given." }, "forklift_pockets": { "type": "array", "items": { "type": "boolean" }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "x-filter-kind": "boolean_set", "description": "Whether the containers have forklift pockets: true, false, or both for any line that records it." }, "lockbox": { "type": "array", "items": { "type": "boolean" }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "x-filter-kind": "boolean_set", "description": "Whether the containers have a lockbox: true, false, or both for any line that records it." }, "vents": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 50, "uniqueItems": true, "x-filter-kind": "text_set", "description": "The containers' vents, as recorded: any of the values given." }, "handles": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 50, "uniqueItems": true, "x-filter-kind": "text_set", "description": "The containers' door handles, as recorded: any of the values given." }, "repair_state": { "type": "array", "items": { "type": "string", "enum": [ "undamaged", "awaiting-estimate", "pending-approval", "pending-repair", "repaired", "unrepairable", "damaged-not-repaired" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Where a unit stands in maintenance and repair: undamaged, damaged and waiting on an estimate, an estimate waiting on approval, approved and waiting on the repair, repaired, or damaged and not to be repaired. A dimension apart from ConditionGrade: a grade names the criteria a unit meets, a repair state names the work outstanding against it. The filter term repair_state in the list capabilities." }, "wholesale_price": { "type": "object", "properties": { "min": { "type": "string", "pattern": "^\\s*[0-9]{1,11}(\\.[0-9]{1,4})?\\s*$", "description": "The least value included, a decimal of at most four places." }, "max": { "type": "string", "pattern": "^\\s*[0-9]{1,11}(\\.[0-9]{1,4})?\\s*$", "description": "The greatest value included, a decimal of at most four places." } }, "minProperties": 1, "additionalProperties": false, "x-filter-kind": "decimal_range", "description": "The line's Wholesale (suggested) price, between min and max inclusive; a line with no Wholesale is not selected." } }, "additionalProperties": false, "minProperties": 1, "x-combine": "and", "description": "Lines matching every term given." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "market", "depot", "size", "type", "condition", "available_count" ], "x-enum-descriptions": [ "By market.", "By the depot's name.", "By container size.", "By container type.", "By condition grade.", "Most available units first." ] }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "default": [ { "key": "market", "dir": "asc" } ], "x-keyset": [ "sort key", "catalog_id" ], "description": "One sort key and its direction. By market when left out." }, "fields": { "type": "array", "items": { "type": "string", "enum": [ "market", "depot", "depot_name", "size", "type", "condition", "color", "sku_code", "lockbox", "forklift_pockets", "vents", "handles", "available_count", "available_secured_count", "available_pending_count", "suggested_price", "retail_price", "damage" ] }, "minItems": 1, "uniqueItems": true, "default": [ "market", "depot", "depot_name", "size", "type", "condition", "color", "sku_code", "lockbox", "forklift_pockets", "vents", "handles", "available_count", "available_secured_count", "available_pending_count" ], "x-field-groups": [ { "name": "line", "fields": [ "market", "depot", "depot_name", "size", "type", "condition", "color", "sku_code" ], "default": true, "description": "What the line groups its units by." }, { "name": "hardware", "fields": [ "lockbox", "forklift_pockets", "vents", "handles" ], "default": true, "description": "The container hardware the line groups by." }, { "name": "counts", "fields": [ "available_count", "available_secured_count", "available_pending_count" ], "default": true, "description": "How many of the line's units are available, and of those how many secured and pending." }, { "name": "prices", "fields": [ "suggested_price", "retail_price" ], "default": false, "description": "The line's suggested and retail prices, each only where the share shows it; asking for one it does not is refused field_not_granted." }, { "name": "damage", "fields": [ "damage" ], "default": false, "description": "The damage the line groups by, as recorded." } ], "description": "The fields to answer, from the field groups. The line, hardware and counts groups when left out; a price only where the share shows it." }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100, "description": "The page size." }, "after": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "maxLength": 1024, "format": "tradehq-keyset-cursor", "description": "The previous page's next_after." } }, "required": [ "org_id", "share_inbound_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "catalog_id": { "type": "string", "description": "The line's catalog id.", "x-data-class": "operational" }, "line": { "type": "integer", "description": "The line's ordinal under its catalog id (1 unless today's catalog emits two rows under one id).", "x-data-class": "operational" }, "market": { "type": [ "string", "null" ], "description": "The line's market.", "x-data-class": "operational" }, "depot": { "type": [ "string", "null" ], "description": "The depot the line's units are in.", "x-data-class": "operational" }, "depot_name": { "type": [ "string", "null" ], "description": "That depot's name.", "x-data-class": "operational" }, "size": { "type": [ "string", "null" ], "description": "The container size, as recorded.", "x-data-class": "operational" }, "type": { "type": [ "string", "null" ], "description": "The container type, as recorded.", "x-data-class": "operational" }, "condition": { "type": [ "string", "null" ], "description": "The condition grade, as recorded.", "x-data-class": "operational" }, "color": { "type": [ "string", "null" ], "description": "The colour.", "x-data-class": "operational" }, "sku_code": { "type": [ "string", "null" ], "description": "The line's SKU code.", "x-data-class": "operational" }, "lockbox": { "type": [ "boolean", "null" ], "description": "Whether the containers have a lockbox.", "x-data-class": "operational" }, "forklift_pockets": { "type": [ "boolean", "null" ], "description": "Whether they have forklift pockets.", "x-data-class": "operational" }, "vents": { "type": [ "string", "null" ], "description": "Their vents.", "x-data-class": "operational" }, "handles": { "type": [ "string", "null" ], "description": "Their door handles.", "x-data-class": "operational" }, "available_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Its units available to sell.", "x-data-class": "operational" }, "available_secured_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Its units available and secured.", "x-data-class": "operational" }, "available_pending_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Its units available and pending.", "x-data-class": "operational" }, "suggested_price": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The line's suggested price, as a decimal string.", "x-data-class": "commercial" }, "retail_price": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The line's retail price, as a decimal string.", "x-data-class": "commercial" }, "damage": { "type": [ "string", "null" ], "description": "The damage the line groups by, as recorded.", "x-data-class": "operational" } }, "required": [ "catalog_id", "line" ], "additionalProperties": false }, "maxItems": 500 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List a shared catalog", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_sso_connections", "title": "List an org's single sign-on connections", "description": "Lists the org's single sign-on connections (SAML or OIDC through Clerk), ordered by name. Each carries its domain and status, the service provider values to give the IdP admin, and the org's settings for it: whether SSO is required at its domain, the outage bypass while it holds, just-in-time membership and its default role template, and IdP MFA trust.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose connections to list." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "Trade HQ's id for the connection.", "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 belongs to.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What the org's admins call it.", "x-data-class": "operational" }, "protocol": { "type": "string", "enum": [ "saml", "oidc" ], "description": "saml or oidc.", "x-data-class": "operational" }, "domain": { "type": "string", "description": "The verified email domain it serves.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "creating", "awaiting_metadata", "ready_to_test", "active", "deleting", "deleted" ], "description": "creating (Clerk has not answered yet), awaiting_metadata, ready_to_test, active, deleting or deleted.", "x-data-class": "operational" }, "active": { "type": "boolean", "description": "Whether people sign in through it.", "x-data-class": "operational" }, "acs_url": { "type": [ "string", "null" ], "description": "The service provider's ACS URL, for the IdP admin; null until Clerk has answered.", "x-data-class": "operational" }, "sp_entity_id": { "type": [ "string", "null" ], "description": "The service provider's entity id, for the IdP admin; null until Clerk has answered.", "x-data-class": "operational" }, "sp_metadata_url": { "type": [ "string", "null" ], "description": "The service provider's metadata URL; null until Clerk has answered.", "x-data-class": "operational" }, "idp_metadata_url": { "type": [ "string", "null" ], "description": "The IdP metadata URL saved, if a URL was.", "x-data-class": "operational" }, "has_idp_metadata": { "type": "boolean", "description": "Whether IdP metadata is saved, as a URL or as uploaded XML.", "x-data-class": "operational" }, "required": { "type": "boolean", "description": "Whether members at its domain must sign in through it.", "x-data-class": "operational" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time", "description": "While the outage lever holds, when it ends; null otherwise.", "x-data-class": "operational" }, "jit": { "type": "boolean", "description": "Whether a first sign-in through it makes the person a member.", "x-data-class": "operational" }, "default_role_template": { "type": [ "string", "null" ], "description": "The role template a just-in-time member gets.", "x-data-class": "operational" }, "idp_mfa_trusted": { "type": "boolean", "description": "Whether the IdP's MFA counts toward the org's MFA settings.", "x-data-class": "operational" }, "allow_manual_additions": { "type": "boolean", "description": "Whether invites stay allowed for its domain while a directory manages it (TRA-486).", "x-data-class": "operational" }, "last_sign_in_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The last sign-in through it.", "x-data-class": "operational" }, "idp_certificate_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the IdP's signing certificate expires, once known.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was added.", "x-data-class": "operational" }, "caller_may_bypass": { "type": "boolean", "description": "Whether the caller may pull the outage lever: the account owner, or the Owner role template in the org.", "x-data-class": "operational" } }, "required": [ "connection_id", "org_id", "name", "protocol", "domain", "status", "active", "acs_url", "sp_entity_id", "sp_metadata_url", "idp_metadata_url", "has_idp_metadata", "required", "bypass_until", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions", "last_sign_in_at", "idp_certificate_expires_at", "created_at", "caller_may_bypass" ], "additionalProperties": false }, "maxItems": 100 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List an org's single sign-on connections", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_staff", "title": "List Trade HQ staff", "description": "Lists every staff role held in Trade HQ's Internal org: one item per person and role, with their name, email address, status (active, deactivated or anonymized), the role, who granted it and when. Ordered by person, then role. Staff only.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The staff member.", "x-data-class": "operational" }, "name": { "type": [ "string", "null" ], "description": "Their name; the tombstone once anonymized.", "x-data-class": "operational" }, "email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their address; null once anonymized.", "x-data-class": "personal" }, "status": { "type": "string", "enum": [ "active", "deactivated", "anonymized" ], "description": "active, deactivated or anonymized.", "x-data-class": "operational" }, "role_id": { "type": "string", "enum": [ "staff_read", "staff_ops", "staff_provision", "staff_finance", "staff_adjudicate" ], "description": "The staff role held.", "x-data-class": "operational" }, "granted_by": { "type": "string", "description": "Who granted it: a user id, or rolemigrate:TRA-318 for the one-shot adoption.", "x-data-class": "operational" }, "granted_at": { "type": "string", "format": "date-time", "description": "When it was granted.", "x-data-class": "operational" } }, "required": [ "user_id", "name", "email", "status", "role_id", "granted_by", "granted_at" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List Trade HQ staff", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_staff_grants", "title": "List staff access grants", "description": "Lists Trade HQ staff access grants, newest first. Every staff member sees their own; a holder of staff.read sees everyone's unless `mine` is true. Narrow it to one org with `org_id` or one status with `status` (pending, active, rejected, revoked, expired).", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "Only the grants to this org." }, "status": { "type": "string", "enum": [ "pending", "active", "rejected", "revoked", "expired" ], "description": "Only the grants in this status now." }, "mine": { "type": "boolean", "description": "true for only the caller's own grants." } }, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The grant'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 customer org it is a grant to.", "x-data-class": "operational" }, "org_name": { "type": [ "string", "null" ], "description": "That org's name.", "x-data-class": "operational" }, "grantee_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The staff member it lets in.", "x-data-class": "operational" }, "grantee_name": { "type": [ "string", "null" ], "description": "Their name, or their address when they have none.", "x-data-class": "operational" }, "grantee_email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their address.", "x-data-class": "personal" }, "level": { "type": "string", "enum": [ "read", "act" ], "description": "read: what the Read-only template carries. act: what the Admin template carries.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "request", "break_glass" ], "description": "request: asked of the org's admins. break_glass: entered at once by Sage or Sonja, the admins told.", "x-data-class": "operational" }, "reason": { "type": "string", "description": "Why, in the requester's words.", "x-data-class": "operational" }, "requested_hours": { "type": "integer", "description": "How long it was asked for.", "x-data-class": "operational" }, "requested_at": { "type": "string", "format": "date-time", "description": "When it was asked for.", "x-data-class": "operational" }, "exception_id": { "type": [ "string", "null" ], "description": "The decision card the org's admins decide a request on.", "x-data-class": "operational" }, "decision": { "type": [ "string", "null" ], "enum": [ "approved", "rejected", null ], "description": "What the admin decided; null while it waits.", "x-data-class": "operational" }, "decided_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who decided it.", "x-data-class": "operational" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When.", "x-data-class": "operational" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it became active.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops being active.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked, if it was.", "x-data-class": "operational" }, "revoked_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who revoked it.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "active", "rejected", "revoked", "expired" ], "description": "pending, active, rejected, revoked or expired, as of now.", "x-data-class": "operational" }, "notified": { "type": "integer", "description": "How many of the org's admins a break-glass notice was written to.", "x-data-class": "operational" } }, "required": [ "grant_id", "org_id", "org_name", "grantee_user_id", "grantee_name", "grantee_email", "level", "kind", "reason", "requested_hours", "requested_at", "exception_id", "decision", "decided_by", "decided_at", "approved_at", "expires_at", "revoked_at", "revoked_by", "status", "notified" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List staff access grants", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_supplier_posts", "title": "List a purchase order's supplier updates", "description": "For the buyer: what the supplier of one of the org's purchase orders has posted on it, newest first: its confirmation (with every line that differs from the line ordered, and whether it has been applied), its production updates with their ready dates and notes, and the batches of unit numbers it submitted. Each names the supplier party and, when a guest posted it, the guest. Any member of the org reads it.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that owns the purchase order." }, "document_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The purchase order's id (an asset_intake). One of another org, or none, lists nothing." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "The page size." }, "after": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The previous page's next_after. A post id that is not one of this purchase order's ends the listing: an empty page." } }, "required": [ "org_id", "document_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "post_id": { "type": "string", "description": "The post.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "confirmation", "production_status", "serial_batch" ], "description": "confirmation, production_status or serial_batch.", "x-data-class": "operational" }, "party_name": { "type": "string", "description": "The supplier party that posted it.", "x-data-class": "operational" }, "guest_name": { "type": [ "string", "null" ], "description": "The guest who posted it, when a guest did; null for a member of the supplier's own org.", "x-data-class": "operational" }, "status": { "type": [ "string", "null" ], "description": "A production status's status (scheduled, in_production, produced, ready_for_pickup, delayed); null for the other kinds.", "x-data-class": "operational" }, "vendor_eta": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The ready date given, if any.", "x-data-class": "operational" }, "note": { "type": [ "string", "null" ], "description": "A production status's note, if any.", "x-data-class": "operational" }, "unit_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Units confirmed, or unit numbers submitted; null for a production status.", "x-data-class": "operational" }, "posted_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" }, "ingest_document_id": { "type": [ "string", "null" ], "description": "The confirmation's ingest document, which the PO ingest apply takes; null for a production status.", "x-data-class": "operational" }, "applied": { "type": [ "boolean", "null" ], "description": "For a confirmation or serial batch, whether the buyer has applied the confirmation; null for a production status.", "x-data-class": "operational" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the buyer applied the confirmation, for a confirmation or serial batch it has applied; null otherwise.", "x-data-class": "operational" }, "pro_forma": { "type": [ "string", "null" ], "description": "A confirmation's pro forma number, if the supplier gave one; null for the other kinds.", "x-data-class": "operational" }, "changes": { "type": "array", "items": { "type": "object" }, "description": "For a confirmation, every confirmed line that differs from the ordered line at its position: {line, fields, ordered, confirmed}, fields naming what changed of size, type, condition, color, quantity and unit_price. Empty for the other kinds.", "x-data-class": "operational" } }, "required": [ "post_id", "kind", "party_name", "guest_name", "status", "vendor_eta", "note", "unit_count", "posted_at", "ingest_document_id", "applied", "applied_at", "pro_forma", "changes" ], "additionalProperties": false }, "maxItems": 100 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List a purchase order's supplier updates", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_switchable_orgs", "title": "List the orgs I can switch to", "description": "Lists the orgs the signed-in user can switch to, ordered by name. Everyone gets the orgs they are a member of. Staff also get the orgs they hold an active grant to and the orgs in staff portfolios; an internal org is listed only for a membership or a grant. Each org says which of these put it on the list. In live mode test twins are not listed; in test mode each twin is listed in place of its org. Switching is switch_org; staff search every org with list_orgs. A system org (the template new orgs are cloned from) is never listed.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org's id: what switch_org takes.", "x-data-class": "operational" }, "name": { "type": "string", "description": "The org's name.", "x-data-class": "operational" }, "org_type": { "type": [ "string", "null" ], "enum": [ "internal", "demo", "customer", "synthetic", "system", null ], "description": "The org's type (TRA-234); null for a ported org nothing has typed yet.", "x-data-class": "operational" }, "member": { "type": "boolean", "description": "The caller is a member of the org.", "x-data-class": "operational" }, "granted": { "type": "boolean", "description": "The caller holds an active staff grant to the org.", "x-data-class": "operational" }, "grant_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the latest-expiring active grant ends; null when there is none.", "x-data-class": "operational" }, "portfolio_id": { "type": [ "string", "null" ], "description": "The staff portfolio the org is in (the first by name when it is in several); null when none.", "x-data-class": "operational" }, "portfolio_name": { "type": [ "string", "null" ], "description": "That portfolio's name.", "x-data-class": "operational" } }, "required": [ "org_id", "name", "org_type", "member", "granted", "grant_expires_at", "portfolio_id", "portfolio_name" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List the orgs I can switch to", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_unit_access", "title": "List access by unit", "description": "Lists who holds a role on a unit (the unit's own grants first, then those inherited from the units above it), or, given a member instead, the units that member holds a role on. Each grant carries its role, the unit it is held on, who gave it and when, and whether you could remove it, with the reason when you could not. Name exactly one of unit_id or user_id. You must administer the unit; for a member, you see only grants on units you administer unless you are an org admin.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org." }, "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The unit whose access to list. Name this or user_id." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The member whose grants to list. Name this or unit_id." }, "include_inherited": { "type": "boolean", "description": "With unit_id, whether to include the grants on the units above it, which reach it. Default true." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "minLength": 1, "maxLength": 80, "description": "The previous page's next_after." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who holds it.", "x-data-class": "operational" }, "name": { "anyOf": [ { "type": "string" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their name, or their address when they have none.", "x-data-class": "personal" }, "email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their address; null once anonymized.", "x-data-class": "personal" }, "role_template_id": { "type": "string", "description": "The role template the grant carries.", "x-data-class": "operational" }, "role_title": { "type": "string", "description": "That template's name.", "x-data-class": "operational" }, "role": { "type": "string", "enum": [ "admin", "user" ], "description": "admin when the template carries org.admin, else user.", "x-data-class": "operational" }, "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The unit it is held on.", "x-data-class": "operational" }, "unit_name": { "type": "string", "description": "That unit's name.", "x-data-class": "operational" }, "beneath": { "type": "integer", "minimum": 0, "description": "How many units are beneath that unit, which the grant also reaches.", "x-data-class": "operational" }, "inherited": { "type": "boolean", "description": "True when it is held on a unit above the one asked about.", "x-data-class": "operational" }, "created_by": { "type": "string", "description": "Who gave it: a user id, or a declaration or backfill marker.", "x-data-class": "operational" }, "created_by_name": { "type": [ "string", "null" ], "description": "That person's name; null when it was not a person.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" }, "removable": { "type": "boolean", "description": "Whether revoke_unit_role would remove it for you.", "x-data-class": "operational" }, "remove_refusal_code": { "type": [ "string", "null" ], "enum": [ "own_access", "unit_outside_caller", "holder_above_caller", null ], "description": "When it would not, the code it would answer.", "x-data-class": "operational" }, "remove_refusal": { "type": [ "string", "null" ], "description": "When it would not, the sentence it would answer.", "x-data-class": "operational" } }, "required": [ "user_id", "name", "email", "role_template_id", "role_title", "role", "unit_id", "unit_name", "beneath", "inherited", "created_by", "created_by_name", "created_at", "removable", "remove_refusal_code", "remove_refusal" ], "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 }, "annotations": { "title": "List access by unit", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_units", "title": "List units", "description": "Lists an org's unit tree depth first, siblings by name, a page at a time, or only the subtree beneath one unit. Each unit carries its parent, kind, name, BFC (for a claimed depot), depth, and the caller's role there: what their role template in the org amounts to (admin if it carries org.admin, user if org.member) or a role held on that unit or any unit above it, whichever is higher. A tree of more than 10,000 units is refused (tree_too_large).", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose tree it is." }, "root_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "Only this unit and what is beneath it." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500, "description": "The page size." }, "after": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The previous page's next_after." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The unit's id.", "x-data-class": "operational" }, "parent_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "Its parent; null for a root.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "division", "region", "depot", "office" ], "description": "Its kind.", "x-data-class": "operational" }, "name": { "type": "string", "description": "Its name.", "x-data-class": "operational" }, "bfc": { "type": [ "string", "null" ], "description": "The BIC Facility Code of a claimed depot; null otherwise.", "x-data-class": "operational" }, "depth": { "type": "integer", "description": "Its distance from its root: 0 for a root.", "x-data-class": "operational" }, "my_role": { "type": [ "string", "null" ], "enum": [ "admin", "user", null ], "description": "The caller's role at this unit, inherited downward; null for none.", "x-data-class": "operational" } }, "required": [ "unit_id", "parent_id", "kind", "name", "bfc", "depth", "my_role" ], "additionalProperties": false }, "maxItems": 1000 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List units", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_user_factors", "title": "List the second factors of an org's members", "description": "Lists every member of the org with the kinds of factor they have enrolled (totp, sms, backup_code, passkey), whether one is a second factor that meets an MFA requirement, whether the org's MFA requirement reaches them, and when their grace ends. Ordered by user id. Never a phone number, a code or a credential.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose members to list." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The member.", "x-data-class": "operational" }, "factors": { "type": "array", "items": { "type": "string" }, "description": "The factor kinds they have enrolled: totp, sms, backup_code, passkey.", "x-data-class": "operational" }, "second_factor": { "type": "boolean", "description": "Whether one of them is a second factor that meets an MFA requirement (totp or sms).", "x-data-class": "operational" }, "policy_applies": { "type": "boolean", "description": "Whether the org's MFA requirement reaches this member.", "x-data-class": "operational" }, "only_org": { "type": "boolean", "description": "Whether this org is the member's only org: the one case an org admin may reset their MFA (reset_user_mfa), which the Members row menu reads to offer it.", "x-data-class": "operational" }, "grace_ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When their grace ends, for a member the requirement reaches; null otherwise.", "x-data-class": "operational" } }, "required": [ "user_id", "factors", "second_factor", "policy_applies", "only_org", "grace_ends_at" ], "additionalProperties": false }, "maxItems": 5000 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List the second factors of an org's members", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "list_users", "title": "List users", "description": "Lists an org's members and pending invitees, ordered by user id, a page at a time. Each carries a name, an email address (null once anonymized), a status (invited, active, deactivated or anonymized), their membership role and their role template. Filters by status and by a case-insensitive substring of the name or address. An org admin reads it, and so does a member who administers a unit (delegated administration), read-only.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose users to list." }, "status": { "type": "string", "enum": [ "invited", "active", "deactivated", "anonymized" ], "description": "Only users with this status." }, "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "A case-insensitive substring of the name or email address." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The previous page's next_after." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The user.", "x-data-class": "operational" }, "name": { "type": [ "string", "null" ], "description": "Their name; the tombstone once anonymized.", "x-data-class": "operational" }, "email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their address; null once anonymized.", "x-data-class": "personal" }, "status": { "type": "string", "enum": [ "invited", "active", "deactivated", "anonymized" ], "description": "Where they are in their lifecycle.", "x-data-class": "operational" }, "role_template_id": { "type": [ "string", "null" ], "description": "A member's assigned role template, which decides what they may call; an invitee's, the one they will hold. Null: none.", "x-data-class": "operational" }, "unit_grants": { "type": "integer", "description": "How many roles they hold on units of the org that the caller may see: every one for an org admin or staff, only those on units a delegate administers for a delegate (TRA-473).", "x-data-class": "operational" } }, "required": [ "user_id", "name", "email", "status", "role_template_id", "unit_grants" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "List users", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "mark_report_seen", "title": "Mark a customer report seen", "description": "Marks a customer report seen by the caller, through one event of its timeline (through, an event's at) or, left out, its newest: it then shows unread to them only once something newer happens. It never moves back, and writes no event. Open to anyone who may get the report.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the report is in." }, "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report: its CUS ticket's Linear id, as list_reports and get_report answer it." }, "through": { "type": "string", "format": "date-time", "description": "The newest event the caller has seen, by its at on the report's timeline. Absent, the newest event." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "report_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report.", "x-data-class": "operational" }, "seen_through": { "type": "string", "format": "date-time", "description": "How far the caller has seen the report's timeline now: the at of the newest event seen.", "x-data-class": "operational" } }, "required": [ "report_id", "seen_through" ], "additionalProperties": false }, "annotations": { "title": "Mark a customer report seen", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "move_unit", "title": "Move a unit", "description": "Moves a unit, with everything beneath it, to a new parent unit in the same org, or to the root. Roles held on units inside the moved subtree move with it; roles held above its old place stop reaching it, and roles above its new place start to. The caller needs admin on the unit and at the destination (the org role for the root). A unit cannot move beneath itself, its own descendants or a depot. Moving a unit to where it already is changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose tree it is." }, "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The unit to move. Everything beneath it moves with it." }, "new_parent_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The unit it goes beneath, in the same org. Absent, it becomes a root." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "unit_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The unit moved.", "x-data-class": "operational" }, "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "Its org.", "x-data-class": "operational" }, "parent_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "Its parent now; null for a root.", "x-data-class": "operational" }, "units_moved": { "type": "integer", "description": "The units in the moved subtree, the unit itself included.", "x-data-class": "operational" }, "grants_moved": { "type": "integer", "description": "The roles held on units inside the subtree, which moved with it.", "x-data-class": "operational" } }, "required": [ "unit_id", "org_id", "parent_id", "units_moved", "grants_moved" ], "additionalProperties": false }, "annotations": { "title": "Move a unit", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "pin_view", "title": "Pin a saved view to a tab's Home", "description": "Pins a saved view to a tab's Home (depots, sell, source or intel) as a card, or with pinned false takes the pin down. for me (the default) pins it for the caller alone, of any view they may read. for everyone pins it on every member's Home: only an org admin may (org_pin_admin_only), and only a view shared with the org (view_not_shared_with_org). A pin never shows a view to anyone who may not read it.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the view is in." }, "view_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The view to pin." }, "tab": { "type": "string", "enum": [ "depots", "sell", "source", "intel" ], "description": "The tab whose Home shows it." }, "for": { "type": "string", "enum": [ "me", "everyone" ], "default": "me", "description": "me (the default): the caller's own Home. everyone: every member's, an org admin's to pin." }, "pinned": { "type": "boolean", "description": "false takes the pin down. Pinned when left out." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "view_id", "tab" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "view_id": { "type": "string", "description": "The view: a UUID, or system: for a system view.", "x-data-class": "operational" }, "capability": { "type": "string", "enum": [ "list_inventory", "summarize_catalog", "list_catalog" ], "description": "The list capability it calls.", "x-data-class": "operational" }, "mode": { "type": [ "string", "null" ], "enum": [ "inventory", "sales", "sales_lines", null ], "description": "inventory: a grid of units. sales: a Sales catalog view, the grouped read with its split_by, source slice and layout. sales_lines: the sales grid's line table, a list_catalog call. Null only for a capability in no mode, which every_savable_capability_is_in_exactly_one_mode holds never happens.", "x-data-class": "operational" }, "contract": { "type": "string", "description": "The capability's contract and the stored call's version, @.", "x-data-class": "operational" }, "args": { "type": "object", "properties": { "filters": { "type": "object", "description": "The list's filters input, as the capability declares it." }, "q": { "type": "string", "description": "The list's q input." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "One of the called capability's sort keys." }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "description": "The list's sort input: one key and its direction." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The list's fields input." }, "limit": { "type": "integer", "description": "The list's limit input." }, "split_by": { "type": "array", "items": { "type": "string" }, "description": "A Sales catalog view's split_by, in the order the attributes were switched on (summarize_catalog's input)." }, "slice": { "type": "string", "enum": [ "owned", "partner", "supplier", "all" ], "description": "A Sales catalog view's source slice: owned, partner, supplier or all." }, "layout": { "type": "string", "enum": [ "cards", "rows" ], "description": "A Sales catalog view's layout: cards or rows." } }, "additionalProperties": false, "description": "The call's arguments: filters, q, sort, fields and limit, as given.", "x-data-class": "operational" }, "title": { "type": "string", "description": "What it is called.", "x-data-class": "operational" }, "pinned": { "type": "boolean", "description": "Whether it is pinned to the top.", "x-data-class": "operational" }, "visibility": { "type": "string", "enum": [ "private", "org-read", "org-write" ], "description": "private: its owner alone. org-read: every member reads it. org-write: every member reads, changes and deletes it. A system view is org-read.", "x-data-class": "operational" }, "system": { "type": "boolean", "description": "A system view: declared for every org, never changed.", "x-data-class": "operational" }, "owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who saved it; null for a system view and for a moved view whose owner is gone.", "x-data-class": "operational" }, "writable": { "type": "boolean", "description": "Whether the caller may change or delete it.", "x-data-class": "operational" }, "unmapped": { "type": "array", "items": { "type": "string" }, "description": "What of an older saved search the call could not carry, each as field: why. Empty for a view saved as a call.", "x-data-class": "operational" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it last changed; null for a system view.", "x-data-class": "operational" }, "shared_with": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "format": "tradehq-user-id", "description": "The teammate it is shared with." }, "shared_by": { "type": "string", "format": "tradehq-user-id", "description": "Who shared it: its owner." }, "created_at": { "type": "string", "format": "date-time", "description": "When." } }, "required": [ "user_id", "shared_by", "created_at" ], "additionalProperties": false }, "description": "The teammates its owner shared it with by name, each {user_id, shared_by, created_at}, by user id. Empty for a system view.", "x-data-class": "operational" }, "pins": { "type": "array", "items": { "type": "object", "properties": { "tab": { "type": "string", "enum": [ "depots", "sell", "source", "intel" ], "description": "The tab whose Home shows it." }, "for": { "type": "string", "enum": [ "me", "everyone" ], "description": "me: the caller's own pin. everyone: an org admin's, on every member's Home." }, "user_id": { "type": [ "string", "null" ], "format": "tradehq-user-id", "description": "The caller, on their own pin; null on the org's." }, "pinned_by": { "type": "string", "format": "tradehq-user-id", "description": "Who pinned it: the caller, or the org admin who pinned it for everyone." }, "created_at": { "type": "string", "format": "date-time", "description": "When." } }, "required": [ "tab", "for", "user_id", "pinned_by", "created_at" ], "additionalProperties": false }, "description": "Where it is pinned for the caller, by tab: their own pins (for me) and the org's (for everyone, an org admin's). Empty for a system view.", "x-data-class": "operational" } }, "required": [ "view_id", "capability", "mode", "contract", "args", "title", "pinned", "visibility", "system", "owner_user_id", "writable", "unmapped", "updated_at", "shared_with", "pins" ], "additionalProperties": false }, "annotations": { "title": "Pin a saved view to a tab's Home", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "post_production_status", "title": "Post a purchase order's production status", "description": "For the supplier of an org's purchase order: says where its units are in production (scheduled, in production, produced, ready for pickup, delayed), optionally with the date they will be ready and a note. While the purchase order's confirmation is still waiting in the buyer's PO ingest, the date is written onto it, so the buyer's apply carries it. Each post is kept; sending the same post again with the same Idempotency-Key changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that owns the purchase order: the buyer." }, "document_kind": { "type": "string", "enum": [ "asset_intake", "order" ], "description": "asset_intake: a purchase order. An order is refused." }, "document_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The purchase order's id." }, "status": { "type": "string", "enum": [ "scheduled", "in_production", "produced", "ready_for_pickup", "delayed" ], "description": "Where the units are: scheduled, in_production, produced, ready_for_pickup or delayed." }, "vendor_eta": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "When the units will be ready for the in-gate, YYYY-MM-DD." }, "note": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Anything the buyer should read with it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "document_kind", "document_id", "status" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "post_id": { "type": "string", "description": "The post.", "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 buyer.", "x-data-class": "operational" }, "document_id": { "type": "string", "description": "The purchase order.", "x-data-class": "operational" }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The supplier party.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "scheduled", "in_production", "produced", "ready_for_pickup", "delayed" ], "description": "The status posted.", "x-data-class": "operational" }, "vendor_eta": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The ready date, if given.", "x-data-class": "operational" }, "note": { "type": [ "string", "null" ], "description": "The note, if given.", "x-data-class": "operational" }, "staged_rows": { "type": "integer", "minimum": 0, "description": "How many of the confirmation's staged rows took the date: zero with no date, no confirmation, or one the buyer has applied.", "x-data-class": "operational" }, "posted_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" } }, "required": [ "post_id", "org_id", "document_id", "party_id", "status", "vendor_eta", "note", "staged_rows", "posted_at" ], "additionalProperties": false }, "annotations": { "title": "Post a purchase order's production status", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "preview_data_share", "title": "Preview a data share", "description": "Renders exactly what a counterparty sees of a data share: the saved query's rows and the documents on which the party holds a seat. Name a stored share by data_share_id, or a proposed one by party_id, query and the query's param. Nothing is stored or sent. A member of the org a stored share is made to may preview that share, by its id, while it lasts.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org sharing its data." }, "data_share_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "A stored share to preview. Leave out to preview a proposed one." }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "For a proposed share: the counterparty." }, "query": { "type": "string", "enum": [ "vendor_bill_request", "vendor_forecast", "vendor_sell_through" ], "description": "The saved query: vendor_forecast (the org's open purchase orders with the vendor, with ETAs and units), vendor_sell_through (units bought from the vendor, sold and on hand, by size, type and condition) or vendor_bill_request (one bill request's units, as the cash flow audit's vendor export lists them)." }, "contact_id": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^CT[0-9A-Za-z]{1,18}$", "format": "tradehq-contact-id", "description": "For vendor_forecast and vendor_sell_through: the vendor, one of the org's own contacts. The party must hold the seller seat on at least one of the org's purchase orders with it, and only those purchase orders are shared. When the vendor is itself a Trade HQ org, the party must be the one that org has claimed." }, "request_id": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^VR[0-9A-Za-z]{1,18}$", "format": "tradehq-vendor-bill-request-id", "description": "For vendor_bill_request: the cash flow audit's vendor bill request. Its units' one vendor is the vendor, and the party must hold the seller seat on every purchase order the units came in on." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "data_share_id": { "type": [ "string", "null" ], "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The stored share; null for a proposed one.", "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 sharing.", "x-data-class": "operational" }, "org_name": { "type": [ "string", "null" ], "description": "The org's name, as the counterparty reads it.", "x-data-class": "operational" }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The counterparty.", "x-data-class": "operational" }, "party_name": { "type": "string", "description": "The counterparty's name in the directory.", "x-data-class": "operational" }, "query": { "type": "string", "enum": [ "vendor_bill_request", "vendor_forecast", "vendor_sell_through" ], "description": "The saved query.", "x-data-class": "operational" }, "title": { "type": "string", "description": "The saved query's title.", "x-data-class": "operational" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" } }, "required": [ "name", "title" ], "additionalProperties": false }, "description": "The columns, in the order of every row's cells.", "x-data-class": "operational" }, "rows": { "anyOf": [ { "type": "array", "items": { "type": "array", "items": { "type": [ "string", "null" ] } } }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The rows the counterparty receives, at most 1000.", "x-data-class": "commercial" }, "row_total": { "type": "integer", "minimum": 0, "description": "How many rows there are in all.", "x-data-class": "operational" }, "truncated": { "type": "boolean", "description": "Whether rows holds fewer than row_total.", "x-data-class": "operational" }, "floor": { "type": "array", "items": { "type": "object", "properties": { "document_kind": { "type": "string", "enum": [ "asset_intake", "order" ] }, "document_id": { "type": "string" }, "seat": { "type": "string", "enum": [ "buyer", "lessee", "lessor", "seller" ] } }, "required": [ "document_kind", "document_id", "seat" ], "additionalProperties": false }, "description": "The party's seats on the purchase orders this share's rows come from, at most 1000. The party's whole floor is list_data_shares', inside Trade HQ; a share never sends more of it than its own rows stand on.", "x-data-class": "operational" }, "floor_total": { "type": "integer", "minimum": 0, "description": "How many such seats there are in all.", "x-data-class": "operational" }, "recipients": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\\.)+([A-Za-z]{2,}|[Xx][Nn]--[A-Za-z0-9-]*[A-Za-z0-9])$", "maxLength": 254 }, "uniqueItems": true }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "A stored share's recipients; empty for a proposed one.", "x-data-class": "personal" }, "cadence": { "type": [ "string", "null" ], "enum": [ "daily", "hourly", null ], "description": "A stored share's cadence; null for a proposed one.", "x-data-class": "operational" } }, "required": [ "data_share_id", "org_id", "org_name", "party_id", "party_name", "query", "title", "columns", "rows", "row_total", "truncated", "floor", "floor_total", "recipients", "cadence" ], "additionalProperties": false }, "annotations": { "title": "Preview a data share", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "provision_account", "title": "Provision an account", "description": "Creates an account, its first org, the org's Clerk Organization, the first admin's invite, the plan's entitlements and a welcome mail, and reports each step. Idempotent on account_name plus admin_email, ignoring case and extra whitespace: calling again with the same inputs creates nothing new and resumes any step that did not finish. The same name and email with different other inputs is refused. Staff only. The admin invite and the entitlements are reported as stubbed until invite_user (TRA-319) and entitlements (TRA-238) exist.", "inputSchema": { "type": "object", "properties": { "account_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The account's name: the commercial relationship, as the customer knows it. Half of the idempotency key." }, "admin_email": { "type": "string", "minLength": 3, "maxLength": 254, "description": "The first admin's email address. They sign in with it, by magic link or passkey. The other half of the idempotency key. A string checked by the server; it becomes a typed email input when the shared input types can take one." }, "admin_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The first admin's name, for the welcome mail." }, "org_name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The first org's name: the legal entity's. The account's name when absent." }, "org_type": { "type": "string", "enum": [ "internal", "demo", "customer" ], "description": "The first org's type: internal, demo or customer (the default)." }, "plan": { "type": "string", "enum": [ "base" ], "description": "The plan whose entitlements the account gets: base (the one tier today, and the default)." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "account_name", "admin_email" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "provisioning_id": { "type": "string", "description": "The ledger row: derived from the normalised account name and admin email.", "x-data-class": "operational" }, "account_name": { "type": "string", "description": "The account's name as the first call spelled it.", "x-data-class": "operational" }, "account_id": { "type": [ "string", "null" ], "description": "The account, once the account step is done.", "x-data-class": "operational" }, "org_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The first org, once the org step is done.", "x-data-class": "operational" }, "account": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The account step.", "x-data-class": "operational" }, "org": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The org step (create_org).", "x-data-class": "operational" }, "clerk_org": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The Clerk Organization: waiting until the provision-account job has made it.", "x-data-class": "operational" }, "admin_invite": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The first admin's invite (invite_user).", "x-data-class": "operational" }, "entitlements": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The plan's entitlements.", "x-data-class": "operational" }, "welcome_mail": { "type": "string", "enum": [ "pending", "done", "waiting", "stubbed", "held", "queued", "sent", "refused", "failed" ], "description": "The welcome mail: held, queued, sent or refused.", "x-data-class": "operational" }, "complete": { "type": "boolean", "description": "Every step is done and the welcome is sent.", "x-data-class": "operational" }, "waiting_on": { "type": [ "string", "null" ], "description": "The first step that is not done, and what it waits for; null when complete.", "x-data-class": "operational" } }, "required": [ "provisioning_id", "account_name", "account_id", "org_id", "account", "org", "clerk_org", "admin_invite", "entitlements", "welcome_mail", "complete", "waiting_on" ], "additionalProperties": false }, "annotations": { "title": "Provision an account", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "publish_announcement", "title": "Publish an announcement to one account", "description": "Publishes a titled message to one account. It shows to the members of that account's orgs, and to no other account, from now until it ends after the given number of days (14 unless set). Send an Idempotency-Key header: a retry with the same key and inputs returns the same announcement and publishes nothing new. Staff only.", "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The one account it shows in." }, "title": { "type": "string", "minLength": 1, "maxLength": 120, "description": "A short headline." }, "body": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The message, as plain text." }, "severity": { "type": "string", "enum": [ "info", "warning" ], "description": "info, or warning for something the account must act on." }, "days": { "type": "integer", "minimum": 1, "maximum": 90, "default": 14, "description": "How many days it shows for." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "account_id", "title", "body", "severity" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "announcement_id": { "type": "string", "description": "The announcement's id.", "x-data-class": "operational" }, "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account it shows in.", "x-data-class": "operational" }, "title": { "type": "string", "description": "The headline.", "x-data-class": "operational" }, "body": { "type": "string", "description": "The message.", "x-data-class": "operational" }, "severity": { "type": "string", "enum": [ "info", "warning" ], "description": "info or warning.", "x-data-class": "operational" }, "starts_at": { "type": "string", "format": "date-time", "description": "When it started showing.", "x-data-class": "operational" }, "ends_at": { "type": "string", "format": "date-time", "description": "When it stops showing.", "x-data-class": "operational" }, "published_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who published it.", "x-data-class": "operational" } }, "required": [ "announcement_id", "account_id", "title", "body", "severity", "starts_at", "ends_at", "published_by" ], "additionalProperties": false }, "annotations": { "title": "Publish an announcement to one account", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "purge_org", "title": "Approve an org's purge", "description": "Approves purging an org whose 30 day deletion countdown has ended, on one dry run: dry_run_id names the org's current dry run, which must have counted. The purge runs as a backend job once two different staff, or one principal, have approved the same dry run; the job counts again, stops and deletes nothing if any count differs, and otherwise deletes the org's data and its test twin's and keeps a tombstone. Refused while the countdown runs, when no deletion is scheduled, without a finished dry run, for a dry run a newer one superseded, and for one the purge stopped on. The same person approving again changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org to purge." }, "dry_run_id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The dry run approved: the org's current one, as get_purge_readiness names it, once it has counted." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "dry_run_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "deletion_scheduled" ], "description": "deletion_scheduled: the purge is the job's, and a purged org is no target.", "x-data-class": "operational" }, "purge_after": { "type": [ "string", "null" ], "format": "date-time", "description": "When the countdown ended.", "x-data-class": "operational" }, "dry_run_id": { "type": "string", "description": "The dry run approved.", "x-data-class": "operational" }, "approvals": { "type": "integer", "description": "How many staff have approved this dry run.", "x-data-class": "operational" }, "queued": { "type": "boolean", "description": "The approvals are a quorum and the purge job may run.", "x-data-class": "operational" } }, "required": [ "org_id", "state", "purge_after", "dry_run_id", "approvals", "queued" ], "additionalProperties": false }, "annotations": { "title": "Approve an org's purge", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "record_gate_event", "title": "Record a gate event", "description": "Records that a container crossed a depot's gate, in or out: when it happened, when Trade HQ learned it, where the report came from and its EIR if any. The first report of a movement records it. A later report of the same movement is linked to it and records nothing new, and one that disagrees with it is linked and raises an exception for a person to decide; nothing is overwritten. Send an Idempotency-Key: the same key and report again returns the first answer.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose depot ledger the movement is in." }, "kind": { "type": "string", "enum": [ "gate-in", "gate-out" ], "description": "gate-in: the container entered the depot. gate-out: it left." }, "container": { "type": "string", "pattern": "^[A-Z]{3}[UJZ][0-9]{7}$", "format": "iso6346", "description": "The container's ISO 6346 number, upper case, with its check digit." }, "depot": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The depot's yard id: a yard of this org, or a shared one." }, "occurred_at": { "type": "string", "format": "date-time", "description": "When the container crossed the gate, with its offset. The movement's day (gated_at) is this instant's UTC calendar day." }, "observed_at": { "type": "string", "format": "date-time", "description": "When Trade HQ learned of it, with its offset. Leave out for now." }, "source": { "type": "string", "enum": [ "eir", "email_report", "carrier_feed", "depot_system", "manual" ], "description": "Where the report came from: an EIR, an emailed depot report, a carrier's feed, a depot's own system, or a person." }, "eir_ref": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The equipment interchange receipt's reference, if the report carries one." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "kind", "container", "depot", "occurred_at", "source" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "observation_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "This report's observation.", "x-data-class": "operational" }, "relation": { "type": "string", "enum": [ "original", "duplicate", "conflict" ], "description": "original: this report recorded the movement. duplicate: it agrees with an earlier report and was linked to it. conflict: it disagrees, was linked, and raised an exception.", "x-data-class": "operational" }, "gate_event_id": { "type": "string", "description": "The movement: its gate-in or gate-out id.", "x-data-class": "operational" }, "duplicate_of": { "type": [ "string", "null" ], "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The earlier observation this one is linked to; null for an original.", "x-data-class": "operational" }, "exception_id": { "type": [ "string", "null" ], "description": "The exception a conflict raised; null otherwise.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "gate-in", "gate-out" ], "description": "The movement's kind.", "x-data-class": "operational" }, "container": { "type": "string", "description": "The container's ISO 6346 number.", "x-data-class": "operational" } }, "required": [ "observation_id", "relation", "gate_event_id", "duplicate_of", "exception_id", "kind", "container" ], "additionalProperties": false }, "annotations": { "title": "Record a gate event", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "record_report_open", "title": "Record a report open", "description": "Records that the caller opened a report in an org, as one event of its own: each open is a row, never a counter, and list_report_opens counts them over the last 90 days to order the Reports list by how often the person opens each report. Send an Idempotency-Key per open: the same key again is that open, never a second one.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the report was opened in." }, "report": { "type": "string", "enum": [ "available_to_promise", "yard_fees_by_unit", "yard_monthly_fees", "sourced_overall", "sourced_by_supplier", "orders_overall", "orders_by_customer", "activity_log", "inventory_audit", "failed_comms", "depot_inventory", "asset_inventory", "cash_flow_audit" ], "description": "The report opened, by name." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "report" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "open_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The open, derived from the call's Idempotency-Key.", "x-data-class": "operational" }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who opened it: the caller.", "x-data-class": "operational" }, "report": { "type": "string", "enum": [ "available_to_promise", "yard_fees_by_unit", "yard_monthly_fees", "sourced_overall", "sourced_by_supplier", "orders_overall", "orders_by_customer", "activity_log", "inventory_audit", "failed_comms", "depot_inventory", "asset_inventory", "cash_flow_audit" ], "description": "The report opened.", "x-data-class": "operational" }, "opened_at": { "type": "string", "format": "date-time", "description": "When it was opened.", "x-data-class": "operational" } }, "required": [ "open_id", "user_id", "report", "opened_at" ], "additionalProperties": false }, "annotations": { "title": "Record a report open", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "reference_depot", "title": "Reference a third-party depot", "description": "Maps an org's own name and code for a depot it uses but does not run to the depot's BIC Facility Code (BFC) in the registry, so the org's documents can name the yard its own way and still mean the canonical one. The depot must be in the registry (list_depot_registry). With no private code, the alias is the code. An org maps a depot once, and a code to one depot; the same mapping again changes nothing. The mapping is the org's own: no other tenant sees it. Any member of the org may make it.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that uses the depot." }, "bfc": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}[A-Z0-9]{4}$", "format": "bic-facility-code", "description": "The depot's BIC Facility Code, from list_depot_registry." }, "alias": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The org's own name for the depot." }, "private_code": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The org's own code for the depot, as its systems write it. Absent, the alias." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "bfc", "alias" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "depot_reference_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The mapping'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.", "x-data-class": "operational" }, "bfc": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}[A-Z0-9]{4}$", "format": "bic-facility-code", "description": "The canonical BFC.", "x-data-class": "operational" }, "alias": { "type": "string", "description": "The org's name for it.", "x-data-class": "operational" }, "private_code": { "type": "string", "description": "The org's code for it.", "x-data-class": "operational" } }, "required": [ "depot_reference_id", "org_id", "bfc", "alias", "private_code" ], "additionalProperties": false }, "annotations": { "title": "Reference a third-party depot", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "reinstate_user", "title": "Reinstate a user", "description": "Undoes a deactivation: the user can sign in again, with their memberships and records as they were. Calling it on an active user changes nothing. An anonymized user cannot be reinstated. An org admin can reinstate only a user whose every org they administer.", "inputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The user to reinstate." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "user_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The user.", "x-data-class": "operational" }, "orgs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id" }, "description": "The orgs the user belongs to, whose admins the event reaches.", "x-data-class": "operational" } }, "required": [ "user_id", "orgs" ], "additionalProperties": false }, "annotations": { "title": "Reinstate a user", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "remove_account_member", "title": "Remove a person from an account", "description": "Takes a person's account role away. Their roles in each entity they belong to are kept, and so are their records. The account's only owner cannot be removed, and someone who holds no role in the account is not found.", "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The person whose account role to take away." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "account_id", "user_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account.", "x-data-class": "operational" }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The person.", "x-data-class": "operational" }, "previous_role": { "type": "string", "enum": [ "owner", "member" ], "description": "The role they held.", "x-data-class": "operational" } }, "required": [ "account_id", "user_id", "previous_role" ], "additionalProperties": false }, "annotations": { "title": "Remove a person from an account", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "remove_depot_reference", "title": "Remove a depot link", "description": "Removes one of the org's own links to a depot (reference_depot), so its documents that use the org's name or code for the yard stop resolving to that BIC Facility Code until it is linked again. The registry record is not touched. An org admin, or the member who made the link, may remove it. A link that is already gone answers the same, and changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose link it is." }, "depot_reference_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The link, from list_depot_references." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "depot_reference_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "depot_reference_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The link.", "x-data-class": "operational" }, "removed": { "type": "boolean", "description": "True: the link is gone.", "x-data-class": "operational" } }, "required": [ "depot_reference_id", "removed" ], "additionalProperties": false }, "annotations": { "title": "Remove a depot link", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "remove_domain", "title": "Remove an email domain", "description": "Removes an email domain the org claimed with verify_domain, pending or verified. People signing up at it are no longer matched to the org. To move a domain to another org, remove it here and claim it there with verify_domain, which proves the DNS TXT record again. Repeating the same call answers the first removal, replayed. A domain the org neither has nor removed is refused unknown_domain; a domain an SSO connection or Directory Sync directory still uses is refused domain_in_use, naming which.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org removing the domain." }, "domain": { "type": "string", "minLength": 3, "maxLength": 253, "description": "The domain, such as example.com." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "domain" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org it was removed from.", "x-data-class": "operational" }, "domain": { "type": "string", "description": "The domain, lower case.", "x-data-class": "operational" }, "was": { "type": "string", "enum": [ "pending", "verified" ], "description": "Whether it was pending or verified when it was removed.", "x-data-class": "operational" }, "removed_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who removed it.", "x-data-class": "operational" } }, "required": [ "org_id", "domain", "was", "removed_by" ], "additionalProperties": false }, "annotations": { "title": "Remove an email domain", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "reopen_report", "title": "Report it again: still broken", "description": "Says a Fixed or Answered report of your org is still broken. Trade HQ support gets a new report linked to the original, with its page, the record it was about and how much it hurts, and your words. Answers the new report, which shows that it reopened the original. Send it again with the same Idempotency-Key and it is the same new report.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the report is of: yours." }, "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The Fixed or Answered report that is still broken." }, "body": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "What is still wrong." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "report_id", "body" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "reopen_id": { "type": "string", "description": "The reopen: ro and thirty characters, derived from the Idempotency-Key.", "x-data-class": "operational" }, "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The new report.", "x-data-class": "operational" }, "ticket": { "type": "string", "description": "The new report's reference (CUS-n).", "x-data-class": "operational" }, "reopened_from": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report it reopens.", "x-data-class": "operational" }, "at": { "type": "string", "format": "date-time", "description": "When the original's timeline recorded it.", "x-data-class": "operational" } }, "required": [ "reopen_id", "report_id", "ticket", "reopened_from", "at" ], "additionalProperties": false }, "annotations": { "title": "Report it again: still broken", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "replay_event_delivery", "title": "Replay an event's delivery", "description": "Puts one capability event's delivery back to pending, so every consumer of it hears it again. The event itself is not changed and no new event is written. A delivery that is already pending is left as it is. Requires a reason, which is kept on the replay's audit record. Staff only.", "inputSchema": { "type": "object", "properties": { "event_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The event whose delivery is replayed." }, "reason": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Why the delivery is replayed, kept on the replay's audit record: every consumer, customers' webhooks, Slack and digests among them, hears the event again." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "event_id", "reason" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "event_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The event.", "x-data-class": "operational" }, "event_type": { "type": "string", "description": "What the event is, as the capability that emitted it declares it.", "x-data-class": "operational" }, "replays": { "type": "integer", "description": "How many times the event's delivery has been replayed.", "x-data-class": "operational" } }, "required": [ "event_id", "event_type", "replays" ], "additionalProperties": false }, "annotations": { "title": "Replay an event's delivery", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "reply_to_report", "title": "Reply to a report", "description": "Replies to Trade HQ support on one of your org's reports (a problem or feedback you or a colleague sent): your words reach the support team on the report's ticket, and, when the report came in by email, its email thread too. A report waiting on you goes back to support. The reply shows on the report's timeline. Send it again with the same Idempotency-Key and it is the same reply.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the report is of." }, "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report, as list_reports and get_report name it." }, "body": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Your reply." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "report_id", "body" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "reply_id": { "type": "string", "description": "The reply: rr and thirty characters, derived from the Idempotency-Key.", "x-data-class": "operational" }, "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report.", "x-data-class": "operational" }, "ticket": { "type": "string", "description": "The report's reference (CUS-n).", "x-data-class": "operational" }, "at": { "type": "string", "format": "date-time", "description": "When the reply was recorded on the report's timeline.", "x-data-class": "operational" }, "text": { "type": "string", "description": "The reply as the timeline shows it: your words, with anything that looks like a password, card or account number masked.", "x-data-class": "operational" }, "emailed": { "type": "boolean", "description": "Whether it also went to the report's email thread (a report filed by email).", "x-data-class": "operational" } }, "required": [ "reply_id", "report_id", "ticket", "at", "text", "emailed" ], "additionalProperties": false }, "annotations": { "title": "Reply to a report", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "request_staff_grant", "title": "Ask a customer org for staff access", "description": "A Trade HQ staff member asks a customer org's admins for access to it, at a level (read: what the Read-only role carries; act: what the Admin role carries) and for a number of hours (fourteen days unless said, at most thirty). Nothing is granted until one of the org's admins approves it with approve_grant, on a decision card raised to them by this call; staff never become members. Refused for an org the caller is a member of, for an org that is not a customer or demo org, and while the caller has a request waiting or a grant active there.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The customer org to ask." }, "level": { "type": "string", "enum": [ "read", "act" ], "default": "read", "description": "read (the default) or act." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why, in a sentence the admins will read, such as the ticket it is for." }, "hours": { "type": "integer", "minimum": 1, "maximum": 720, "default": 336, "description": "How long the access is asked for, in hours: 336 (fourteen days) unless said, at most 720." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "reason" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The grant'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 customer org it is a grant to.", "x-data-class": "operational" }, "org_name": { "type": [ "string", "null" ], "description": "That org's name.", "x-data-class": "operational" }, "grantee_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The staff member it lets in.", "x-data-class": "operational" }, "grantee_name": { "type": [ "string", "null" ], "description": "Their name, or their address when they have none.", "x-data-class": "operational" }, "grantee_email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their address.", "x-data-class": "personal" }, "level": { "type": "string", "enum": [ "read", "act" ], "description": "read: what the Read-only template carries. act: what the Admin template carries.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "request", "break_glass" ], "description": "request: asked of the org's admins. break_glass: entered at once by Sage or Sonja, the admins told.", "x-data-class": "operational" }, "reason": { "type": "string", "description": "Why, in the requester's words.", "x-data-class": "operational" }, "requested_hours": { "type": "integer", "description": "How long it was asked for.", "x-data-class": "operational" }, "requested_at": { "type": "string", "format": "date-time", "description": "When it was asked for.", "x-data-class": "operational" }, "exception_id": { "type": [ "string", "null" ], "description": "The decision card the org's admins decide a request on.", "x-data-class": "operational" }, "decision": { "type": [ "string", "null" ], "enum": [ "approved", "rejected", null ], "description": "What the admin decided; null while it waits.", "x-data-class": "operational" }, "decided_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who decided it.", "x-data-class": "operational" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When.", "x-data-class": "operational" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it became active.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops being active.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked, if it was.", "x-data-class": "operational" }, "revoked_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who revoked it.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "active", "rejected", "revoked", "expired" ], "description": "pending, active, rejected, revoked or expired, as of now.", "x-data-class": "operational" }, "notified": { "type": "integer", "description": "How many of the org's admins a break-glass notice was written to.", "x-data-class": "operational" } }, "required": [ "grant_id", "org_id", "org_name", "grantee_user_id", "grantee_name", "grantee_email", "level", "kind", "reason", "requested_hours", "requested_at", "exception_id", "decision", "decided_by", "decided_at", "approved_at", "expires_at", "revoked_at", "revoked_by", "status", "notified" ], "additionalProperties": false }, "annotations": { "title": "Ask a customer org for staff access", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "reset_user_mfa", "title": "Reset a user's multi-factor authentication", "description": "Removes every second factor of a user (authenticator app, text message, backup codes) and signs them out everywhere, so they set one up again at their next sign-in. A user is one person across every org they belong to, so the reset is too: an org admin can reset only a user whose every org they administer, and an account owner only a user whose every org is in an account they own. Needs a second factor verified in the last 10 minutes. While a reset is still being carried out, calling it again changes nothing.", "inputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The user whose second factors to remove." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "user_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The user.", "x-data-class": "operational" }, "factors_removed": { "type": "array", "items": { "type": "string" }, "description": "The factor kinds Trade HQ held for them and removed: totp, sms, backup_code, passkey.", "x-data-class": "operational" }, "queued": { "type": "boolean", "description": "Whether this call queued the reset in Clerk; false when one was already queued.", "x-data-class": "operational" } }, "required": [ "user_id", "factors_removed", "queued" ], "additionalProperties": false }, "annotations": { "title": "Reset a user's multi-factor authentication", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "resolve_identity_finding", "title": "Resolve a Clerk drift finding", "description": "Decides a finding list_identity_findings shows. remove takes the Clerk membership away (a membership Trade HQ did not decide). admit, with a role_template_id, makes the person a member with that role, or gives a member whose Clerk role changed that role, and puts Clerk's role to match: never Owner, never a role carrying more than yours, never a membership a directory manages. ignore closes the finding once and changes nothing. Staff may only remove. The same decision again changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the finding is in." }, "finding_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The finding, from list_identity_findings." }, "decision": { "type": "string", "enum": [ "remove", "admit", "ignore" ], "description": "remove, admit or ignore: one the finding's decisions name." }, "role_template_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "For admit: a shipped role template's id or one of the org's own, never owner." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "finding_id", "decision" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "finding_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The finding.", "x-data-class": "operational" }, "resolution": { "type": "string", "enum": [ "removed", "admitted", "ignored" ], "description": "How it is resolved.", "x-data-class": "operational" }, "admitted_role_template_id": { "type": [ "string", "null" ], "description": "The role template an admit gave.", "x-data-class": "operational" }, "command": { "type": [ "string", "null" ], "enum": [ "membership_remove", "role_set", null ], "description": "The Clerk command the decision queued, if any.", "x-data-class": "operational" } }, "required": [ "org_id", "finding_id", "resolution", "admitted_role_template_id", "command" ], "additionalProperties": false }, "annotations": { "title": "Resolve a Clerk drift finding", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "restore_security_policy", "title": "Restore a section of an org's security settings", "description": "Puts one section of the org's security settings (sso, mfa, session, network or drift) back to an earlier version, by number; version 1 is the section's default. The restore is recorded as a new version that names the one it restored, so nothing in the history is lost. Restoring the version already in effect changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose security settings to restore." }, "section": { "type": "string", "enum": [ "sso", "mfa", "session", "network", "drift" ], "description": "The section to restore: sso, mfa, session, network or drift." }, "version": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "The earlier version to restore. 1 is the section's default." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "section", "version" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "restored_from": { "type": "integer", "description": "The version restored.", "x-data-class": "operational" }, "current": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "sso", "mfa", "session", "network", "drift" ] }, "policy": { "oneOf": [ { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "required": { "type": "boolean" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "domain", "required", "bypass_until" ], "additionalProperties": false } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string" }, "jit": { "type": "boolean" }, "default_role_template": { "type": [ "string", "null" ] }, "idp_mfa_trusted": { "type": "boolean" }, "allow_manual_additions": { "type": "boolean" } }, "required": [ "connection_id", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions" ], "additionalProperties": false } } }, "required": [ "domains", "connections" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "required", "required_for_templates" ] }, "templates": { "type": "array", "items": { "type": "string" } }, "grace_days": { "type": "integer", "minimum": 0, "maximum": 30 }, "accept_idp_mfa": { "type": "boolean" } }, "required": [ "mode", "templates", "grace_days", "accept_idp_mfa" ], "additionalProperties": false }, { "type": "object", "properties": { "idle_minutes": { "type": "integer", "minimum": 15, "maximum": 1440 }, "absolute_hours": { "type": "integer", "minimum": 1, "maximum": 168 }, "reauth_on_role_change": { "type": "boolean" }, "single_session": { "type": "boolean" } }, "required": [ "idle_minutes", "absolute_hours", "reauth_on_role_change", "single_session" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "monitor", "enforce" ] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "cidr": { "type": "string" }, "label": { "type": "string" } }, "required": [ "cidr", "label" ], "additionalProperties": false } }, "applies_to": { "type": "string", "enum": [ "members", "api_keys", "both" ] } }, "required": [ "mode", "entries", "applies_to" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "quarantine", "alert_only" ] } }, "required": [ "action" ], "additionalProperties": false } ] }, "is_default": { "type": "boolean" }, "version": { "type": [ "integer", "null" ], "minimum": 1 }, "changed_by": { "type": [ "string", "null" ] }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "section", "policy", "is_default", "version", "changed_by", "changed_at" ], "additionalProperties": false, "description": "The section as it now stands, with its new version.", "x-data-class": "operational" } }, "required": [ "org_id", "restored_from", "current" ], "additionalProperties": false }, "annotations": { "title": "Restore a section of an org's security settings", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "resume_org", "title": "Resume a suspended org", "description": "Brings a suspended org back: its users, and its test twin's, can sign in again. Nothing else changes: its settings, members and data are as they were. Calling it on an org that is already live changes nothing. An org whose deletion is counting down is refused org_deletion_scheduled: cancel the deletion first, which returns it to suspended, then resume it. A test twin, an org the repository declares and a purged org are refused. Trade HQ staff only.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The suspended org to resume." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "active" ], "description": "active: the org is live.", "x-data-class": "operational" }, "purge_after": { "type": [ "string", "null" ], "format": "date-time", "description": "Always null: a live org has no deletion scheduled.", "x-data-class": "operational" } }, "required": [ "org_id", "state", "purge_after" ], "additionalProperties": false }, "annotations": { "title": "Resume a suspended org", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "revoke_api_key", "title": "Revoke an API key", "description": "Stops one of the org's API keys working, at once, including a key still in the overlap window of a rotation. It cannot be undone: a revoked key is never accepted again, so make another. Revoking a revoked key changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the key belongs to." }, "key_id": { "type": "string", "minLength": 1, "maxLength": 12, "description": "The key's id (its public part, as list_api_keys shows it)." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "key_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "key_id": { "type": "string", "description": "The key's id, its public part.", "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 live org it was issued on.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What it is for.", "x-data-class": "operational" }, "service_account_id": { "type": [ "string", "null" ], "description": "The service account that owns the key and that it acts as (TRA-493); null only for a BK_ key the core issued.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "sk", "legacy" ], "description": "sk for a key this plane issued, legacy for a BK_ key.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live, or test for a key that reaches the test twin.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "expiring", "expired", "revoked" ], "description": "active; expiring when it has an expiry still ahead, as a rotated key does in its overlap; expired; or revoked.", "x-data-class": "operational" }, "display": { "type": "string", "description": "The key's prefix and id, safe to show anywhere. Never the secret.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was issued.", "x-data-class": "operational" }, "created_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who issued it.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops working, if it does.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked.", "x-data-class": "operational" }, "api_version": { "type": [ "string", "null" ], "description": "The API version it is pinned to; null for a BK_ key, which follows the current version.", "x-data-class": "operational" }, "requests_per_minute": { "type": [ "integer", "null" ], "description": "Its per-minute limit, or null for none.", "x-data-class": "operational" }, "requests_per_day": { "type": [ "integer", "null" ], "description": "Its per-day limit, or null for none.", "x-data-class": "operational" }, "rotated_from": { "type": [ "string", "null" ], "description": "The key it succeeded.", "x-data-class": "operational" }, "rotated_to": { "type": [ "string", "null" ], "description": "The key that succeeded it.", "x-data-class": "operational" }, "grants": { "type": "array", "items": { "type": "string" }, "description": "What the key was granted (TRA-619), in name order: the permissions it may use, each only while its service account's role template carries it. Empty for a key granted nothing and for a BK_ key.", "x-data-class": "operational" } }, "required": [ "key_id", "org_id", "name", "service_account_id", "kind", "mode", "status", "display", "created_at", "created_by", "expires_at", "revoked_at", "api_version", "requests_per_minute", "requests_per_day", "rotated_from", "rotated_to", "grants" ], "additionalProperties": false }, "annotations": { "title": "Revoke an API key", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "revoke_capability_grant", "title": "Revoke a capability grant", "description": "Ends one grant or add-on an org was given: from then the org has that capability only if its plan tier or another live grant gives it. The grant's record stays, with who revoked it, how, when and why. Revoking a revoked grant changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the grant was given to." }, "org_grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The grant, as list_granted_capabilities names it." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why it ends. Kept with the revocation." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "org_grant_id", "reason" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The grant'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 was given to.", "x-data-class": "operational" }, "capability_id": { "type": "string", "description": "The capability, by its registry name.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "grant", "add_on" ], "description": "grant, given outside the tier, or add_on, bought on top.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ], "description": "active while it counts; expired past expires_at; revoked once revoked.", "x-data-class": "operational" }, "reason": { "type": "string", "description": "Why it was given.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops counting; null for never.", "x-data-class": "operational" }, "granted_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who gave it.", "x-data-class": "operational" }, "granted_via": { "type": "string", "description": "The principal kind it came through: clerk_user, or mcp_subject for an agent.", "x-data-class": "operational" }, "granted_client": { "type": [ "string", "null" ], "description": "The OAuth client an agent acted through; null otherwise.", "x-data-class": "operational" }, "granted_at": { "type": "string", "format": "date-time", "description": "When it was given.", "x-data-class": "operational" }, "revoked_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who revoked it; null while it is not revoked.", "x-data-class": "operational" }, "revoked_via": { "type": [ "string", "null" ], "description": "The principal kind the revocation came through.", "x-data-class": "operational" }, "revoked_client": { "type": [ "string", "null" ], "description": "The OAuth client an agent revoked it through.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked.", "x-data-class": "operational" }, "revoke_reason": { "type": [ "string", "null" ], "description": "Why it was revoked.", "x-data-class": "operational" } }, "required": [ "org_grant_id", "org_id", "capability_id", "kind", "status", "reason", "expires_at", "granted_by", "granted_via", "granted_client", "granted_at", "revoked_by", "revoked_via", "revoked_client", "revoked_at", "revoke_reason" ], "additionalProperties": false }, "annotations": { "title": "Revoke a capability grant", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "revoke_data_share", "title": "Revoke a data share", "description": "Revokes one explicit data share: its counterparty is sent nothing more and no longer sees it. The share's record stays. The documents on which the party holds a seat are not a share and are not revoked here. Revoking a revoked share changes nothing. A share its counterparty declined sends nothing already and is refused.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that made the share." }, "data_share_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The share, as list_data_shares names it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "data_share_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "data_share_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The share.", "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 that made it.", "x-data-class": "operational" }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The counterparty.", "x-data-class": "operational" }, "query": { "type": "string", "enum": [ "vendor_bill_request", "vendor_forecast", "vendor_sell_through" ], "description": "The saved query it shared.", "x-data-class": "operational" }, "revoked_at": { "type": "string", "format": "date-time", "description": "When it was revoked.", "x-data-class": "operational" }, "revoked_by": { "type": "string", "description": "Who revoked it.", "x-data-class": "operational" } }, "required": [ "data_share_id", "org_id", "party_id", "query", "revoked_at", "revoked_by" ], "additionalProperties": false }, "annotations": { "title": "Revoke a data share", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "revoke_device", "title": "Revoke a device", "description": "Revokes one of the caller's devices: from then on it is refused on every call, the session it signed in on included, and it is sent no push. Its binding is kept as history. Revoking a revoked device changes nothing.", "inputSchema": { "type": "object", "properties": { "binding_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The device's binding, as list_devices names it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "binding_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "binding_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The binding revoked.", "x-data-class": "operational" }, "revoked_at": { "type": "string", "format": "date-time", "description": "When it was revoked.", "x-data-class": "operational" }, "destinations_retired": { "type": "integer", "minimum": 0, "description": "Push destinations retired with it.", "x-data-class": "operational" } }, "required": [ "binding_id", "revoked_at", "destinations_retired" ], "additionalProperties": false }, "annotations": { "title": "Revoke a device", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "revoke_grant", "title": "Revoke a staff access grant", "description": "Ends a Trade HQ staff member's access to an org at once, whether it was a request or break-glass, active or still waiting. An admin of the org revokes any grant to it, staff operations any grant, and a staff member their own. A waiting request's decision card is resolved as rejected, and an impersonation made under the grant ends. It cannot be undone; ask again. Revoking a revoked grant changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the grant is to." }, "grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The grant, as list_org_grants or list_staff_grants names it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "grant_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "grant_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The grant'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 customer org it is a grant to.", "x-data-class": "operational" }, "org_name": { "type": [ "string", "null" ], "description": "That org's name.", "x-data-class": "operational" }, "grantee_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The staff member it lets in.", "x-data-class": "operational" }, "grantee_name": { "type": [ "string", "null" ], "description": "Their name, or their address when they have none.", "x-data-class": "operational" }, "grantee_email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Their address.", "x-data-class": "personal" }, "level": { "type": "string", "enum": [ "read", "act" ], "description": "read: what the Read-only template carries. act: what the Admin template carries.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "request", "break_glass" ], "description": "request: asked of the org's admins. break_glass: entered at once by Sage or Sonja, the admins told.", "x-data-class": "operational" }, "reason": { "type": "string", "description": "Why, in the requester's words.", "x-data-class": "operational" }, "requested_hours": { "type": "integer", "description": "How long it was asked for.", "x-data-class": "operational" }, "requested_at": { "type": "string", "format": "date-time", "description": "When it was asked for.", "x-data-class": "operational" }, "exception_id": { "type": [ "string", "null" ], "description": "The decision card the org's admins decide a request on.", "x-data-class": "operational" }, "decision": { "type": [ "string", "null" ], "enum": [ "approved", "rejected", null ], "description": "What the admin decided; null while it waits.", "x-data-class": "operational" }, "decided_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who decided it.", "x-data-class": "operational" }, "decided_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When.", "x-data-class": "operational" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it became active.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops being active.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked, if it was.", "x-data-class": "operational" }, "revoked_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who revoked it.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "active", "rejected", "revoked", "expired" ], "description": "pending, active, rejected, revoked or expired, as of now.", "x-data-class": "operational" }, "notified": { "type": "integer", "description": "How many of the org's admins a break-glass notice was written to.", "x-data-class": "operational" } }, "required": [ "grant_id", "org_id", "org_name", "grantee_user_id", "grantee_name", "grantee_email", "level", "kind", "reason", "requested_hours", "requested_at", "exception_id", "decision", "decided_by", "decided_at", "approved_at", "expires_at", "revoked_at", "revoked_by", "status", "notified" ], "additionalProperties": false }, "annotations": { "title": "Revoke a staff access grant", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "revoke_guest", "title": "Revoke a guest's access", "description": "Ends a guest's access to the org: their guest membership and the Counterparty seat it carried go, so they no longer read any document their party is seated on in the org, and their pending invitation is withdrawn. The guest's record stays, listed as revoked. Revoking a revoked guest answers the first revocation. Someone who is not a guest of the org is refused not_a_guest.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the guest is a guest of." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The guest, as list_guests names them." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "user_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The guest.", "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 they were a guest of.", "x-data-class": "operational" }, "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The party they were.", "x-data-class": "operational" }, "seat": { "type": "string", "enum": [ "lessee", "seller" ], "description": "The seat they held.", "x-data-class": "operational" }, "revoked_at": { "type": "string", "format": "date-time", "description": "When their access ended.", "x-data-class": "operational" }, "revoked_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who ended it.", "x-data-class": "operational" } }, "required": [ "user_id", "org_id", "party_id", "seat", "revoked_at", "revoked_by" ], "additionalProperties": false }, "annotations": { "title": "Revoke a guest's access", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "revoke_sessions", "title": "Sign sessions out", "description": "Signs sessions out of an org at once: one session (session_id), every session of one person (user_id), or every session in the org (all: true) except the one making this call, which the answer names. Give exactly one. The person is asked to sign in again on their next request. A member who is not an admin signs out only their own sessions. A session already signed out changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org to sign sessions out of." }, "session_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "One session, by the id list_sessions answers." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Every session of this person in the org." }, "all": { "type": "boolean", "description": "true: every session in the org except the caller's own." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "revoked": { "type": "array", "items": { "type": "string" }, "description": "The sessions signed out.", "x-data-class": "operational" }, "excluded": { "type": [ "string", "null" ], "description": "For all: the caller's own session, which stays signed in.", "x-data-class": "operational" } }, "required": [ "org_id", "revoked", "excluded" ], "additionalProperties": false }, "annotations": { "title": "Sign sessions out", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "revoke_staff_role", "title": "Revoke a staff role", "description": "Takes one staff role away from a member of Trade HQ's Internal org. The last active holder of staff_ops keeps it: someone else must hold staff_ops first, because staff_ops is what grants staff roles. Revoking a role they do not hold changes nothing. Staff with staff.ops only.", "inputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The staff member." }, "role_id": { "type": "string", "enum": [ "staff_read", "staff_ops", "staff_provision", "staff_finance" ], "description": "The staff role to take away." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "user_id", "role_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The staff member.", "x-data-class": "operational" }, "role_id": { "type": "string", "enum": [ "staff_read", "staff_ops", "staff_provision", "staff_finance" ], "description": "The staff role.", "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 Internal org.", "x-data-class": "operational" }, "revoked": { "type": "boolean", "description": "True: they do not hold the role.", "x-data-class": "operational" } }, "required": [ "user_id", "role_id", "org_id", "revoked" ], "additionalProperties": false }, "annotations": { "title": "Revoke a staff role", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "revoke_unit_role", "title": "Remove access on a unit", "description": "Removes a member's role on one unit, and with it what that role gave them there and on every unit beneath it. Their org role and their roles on other units stay. You must administer the unit, the role must carry nothing you do not hold there, and you cannot remove your own. Removing a role that is already gone changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose tree the unit is in." }, "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The unit the role is held on." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who holds it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "unit_id", "user_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "The unit.", "x-data-class": "operational" }, "unit_name": { "type": "string", "description": "The unit's name.", "x-data-class": "operational" }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who held it.", "x-data-class": "operational" }, "role_template_id": { "type": [ "string", "null" ], "description": "The template the removed grant carried; null when there was none to remove.", "x-data-class": "operational" }, "revoked": { "type": "boolean", "description": "Always true: they hold no role on this unit now.", "x-data-class": "operational" } }, "required": [ "org_id", "unit_id", "unit_name", "user_id", "role_template_id", "revoked" ], "additionalProperties": false }, "annotations": { "title": "Remove access on a unit", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "roll_back_flag", "title": "Roll a flag back to staff only", "description": "Puts one registered feature flag back on the staff list in PostHog, from any wave, so only Trade HQ staff see the feature. Recorded with who did it. Send an Idempotency-Key header. Staff only.", "inputSchema": { "type": "object", "properties": { "flag_key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The flag's key, as the registry has it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "flag_key" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "action_id": { "type": "string", "description": "This move's audit row.", "x-data-class": "operational" }, "flag_key": { "type": "string", "description": "The flag moved.", "x-data-class": "operational" }, "action": { "type": "string", "enum": [ "advance", "roll_back", "set_lists" ], "description": "advance, roll_back, or set_lists (TRA-1461: the beta lists chosen).", "x-data-class": "operational" }, "from_wave": { "type": "string", "description": "The wave PostHog had it on.", "x-data-class": "operational" }, "to_wave": { "type": "string", "description": "The wave it is on now.", "x-data-class": "operational" }, "acted_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who moved it: the staff member or agent, never PostHog's key.", "x-data-class": "operational" }, "acted_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" }, "posthog_url": { "type": [ "string", "null" ], "description": "The flag in PostHog; null on a replay.", "x-data-class": "operational" } }, "required": [ "action_id", "flag_key", "action", "from_wave", "to_wave", "acted_by", "acted_at", "posthog_url" ], "additionalProperties": false }, "annotations": { "title": "Roll a flag back to staff only", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "route_held_file", "title": "Route a held file", "description": "Gives a held file (one that arrived where no org could be told) the org it belongs to, so it is filed there. Staff only.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the file belongs to." }, "upload_id": { "type": "string", "minLength": 26, "maxLength": 26, "description": "The held file's intake id." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "upload_id" ], "additionalProperties": false }, "outputSchema": { "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 it was routed to.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "received", "filed" ], "description": "received when it is waiting to be filed, then filed.", "x-data-class": "operational" } }, "required": [ "upload_id", "org_id", "state" ], "additionalProperties": false }, "annotations": { "title": "Route a held file", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "run_identity_reconcile", "title": "Reconcile an org's Clerk memberships now", "description": "Queues a reconcile of one org's Clerk memberships against Trade HQ, outside the nightly 02:00 PT run: identity-provisioner lists the org's Clerk organization on its next tick and every difference becomes a finding, as at night. Staff only. Send an Idempotency-Key: the same key again answers the same run.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org to reconcile." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "run_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The run.", "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.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "queued" ], "description": "queued: identity-provisioner takes it on its next tick.", "x-data-class": "operational" } }, "required": [ "run_id", "org_id", "status" ], "additionalProperties": false }, "annotations": { "title": "Reconcile an org's Clerk memberships now", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "run_purge_dry_run", "title": "Run a purge dry run", "description": "Counts what purging an org whose deletion is scheduled would delete, and deletes nothing: its rows per table, the R2 objects and bytes its attachments hold, its test twin, its data shares and the members it would leave with no org. Answers 202 with the dry run's id while the count runs; get_purge_readiness says when it lands. A new dry run supersedes the last, and approvals of the last no longer count. The purge job counts again before it deletes and stops if anything differs. Trade HQ staff only.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose deletion is scheduled." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "dry_run_id": { "type": "string", "description": "The dry run: pd and eighteen characters, derived from the Idempotency-Key.", "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.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "running", "ready", "failed", "stopped", "purged" ], "description": "running when first answered (202); a replay answers where it is now.", "x-data-class": "operational" }, "supersedes": { "type": [ "string", "null" ], "description": "The dry run this one replaced as the round's current one, whose approvals no longer count; null for the round's first.", "x-data-class": "operational" } }, "required": [ "dry_run_id", "org_id", "status", "supersedes" ], "additionalProperties": false }, "annotations": { "title": "Run a purge dry run", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "save_view", "title": "Save a view", "description": "Saves a call of a list capability as a view: the capability, its args (filters, q, sort, fields and limit, checked by that capability as a call would be), a title, whether it is pinned, and its visibility. A Sales catalog view is mode sales: capability summarize_catalog, args filters, split_by in order, slice and layout. Its visibility: private, org-read (every member reads it) or org-write (every member may also change or delete it). With view_id it replaces that view, which must be the caller's or shared org-write; a system view is never changed (view_read_only). Send an Idempotency-Key: the same key and view again returns the first answer.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the view is saved in." }, "view_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A view to replace. Leave out to save a new one." }, "mode": { "type": "string", "enum": [ "inventory", "sales", "sales_lines" ], "description": "inventory (a grid of units) or sales (a Sales catalog view). The capability's own when left out; given, it must be the capability's." }, "capability": { "type": "string", "enum": [ "list_inventory", "summarize_catalog", "list_catalog" ], "description": "The capability the view calls: list_inventory for an inventory view, summarize_catalog for a Sales catalog view." }, "args": { "type": "object", "properties": { "filters": { "type": "object", "description": "The list's filters input, as the capability declares it." }, "q": { "type": "string", "description": "The list's q input." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "One of the called capability's sort keys." }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "description": "The list's sort input: one key and its direction." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The list's fields input." }, "limit": { "type": "integer", "description": "The list's limit input." }, "split_by": { "type": "array", "items": { "type": "string" }, "description": "A Sales catalog view's split_by, in the order the attributes were switched on (summarize_catalog's input)." }, "slice": { "type": "string", "enum": [ "owned", "partner", "supplier", "all" ], "description": "A Sales catalog view's source slice: owned, partner, supplier or all." }, "layout": { "type": "string", "enum": [ "cards", "rows" ], "description": "A Sales catalog view's layout: cards or rows." } }, "additionalProperties": false, "description": "The call's arguments, as that capability takes them, each optional and never org_id or after. Inventory: filters, q, sort, fields and limit. Sales: filters and split_by (in the order switched on), and the screen's slice (owned, partner, supplier or all) and layout (cards or rows)." }, "title": { "type": "string", "minLength": 1, "maxLength": 255, "x-normalized": "trimmed, each run of whitespace one space", "description": "What to call it." }, "pinned": { "type": "boolean", "description": "Pin it to the top of the saved views. Not pinned when left out." }, "visibility": { "type": "string", "enum": [ "private", "org-read", "org-write" ], "default": "private", "description": "private (the default), org-read or org-write." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "capability", "args", "title" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "view_id": { "type": "string", "description": "The view: a UUID, or system: for a system view.", "x-data-class": "operational" }, "capability": { "type": "string", "enum": [ "list_inventory", "summarize_catalog", "list_catalog" ], "description": "The list capability it calls.", "x-data-class": "operational" }, "mode": { "type": [ "string", "null" ], "enum": [ "inventory", "sales", "sales_lines", null ], "description": "inventory: a grid of units. sales: a Sales catalog view, the grouped read with its split_by, source slice and layout. sales_lines: the sales grid's line table, a list_catalog call. Null only for a capability in no mode, which every_savable_capability_is_in_exactly_one_mode holds never happens.", "x-data-class": "operational" }, "contract": { "type": "string", "description": "The capability's contract and the stored call's version, @.", "x-data-class": "operational" }, "args": { "type": "object", "properties": { "filters": { "type": "object", "description": "The list's filters input, as the capability declares it." }, "q": { "type": "string", "description": "The list's q input." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "One of the called capability's sort keys." }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "description": "The list's sort input: one key and its direction." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The list's fields input." }, "limit": { "type": "integer", "description": "The list's limit input." }, "split_by": { "type": "array", "items": { "type": "string" }, "description": "A Sales catalog view's split_by, in the order the attributes were switched on (summarize_catalog's input)." }, "slice": { "type": "string", "enum": [ "owned", "partner", "supplier", "all" ], "description": "A Sales catalog view's source slice: owned, partner, supplier or all." }, "layout": { "type": "string", "enum": [ "cards", "rows" ], "description": "A Sales catalog view's layout: cards or rows." } }, "additionalProperties": false, "description": "The call's arguments: filters, q, sort, fields and limit, as given.", "x-data-class": "operational" }, "title": { "type": "string", "description": "What it is called.", "x-data-class": "operational" }, "pinned": { "type": "boolean", "description": "Whether it is pinned to the top.", "x-data-class": "operational" }, "visibility": { "type": "string", "enum": [ "private", "org-read", "org-write" ], "description": "private: its owner alone. org-read: every member reads it. org-write: every member reads, changes and deletes it. A system view is org-read.", "x-data-class": "operational" }, "system": { "type": "boolean", "description": "A system view: declared for every org, never changed.", "x-data-class": "operational" }, "owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who saved it; null for a system view and for a moved view whose owner is gone.", "x-data-class": "operational" }, "writable": { "type": "boolean", "description": "Whether the caller may change or delete it.", "x-data-class": "operational" }, "unmapped": { "type": "array", "items": { "type": "string" }, "description": "What of an older saved search the call could not carry, each as field: why. Empty for a view saved as a call.", "x-data-class": "operational" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it last changed; null for a system view.", "x-data-class": "operational" }, "shared_with": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "format": "tradehq-user-id", "description": "The teammate it is shared with." }, "shared_by": { "type": "string", "format": "tradehq-user-id", "description": "Who shared it: its owner." }, "created_at": { "type": "string", "format": "date-time", "description": "When." } }, "required": [ "user_id", "shared_by", "created_at" ], "additionalProperties": false }, "description": "The teammates its owner shared it with by name, each {user_id, shared_by, created_at}, by user id. Empty for a system view.", "x-data-class": "operational" }, "pins": { "type": "array", "items": { "type": "object", "properties": { "tab": { "type": "string", "enum": [ "depots", "sell", "source", "intel" ], "description": "The tab whose Home shows it." }, "for": { "type": "string", "enum": [ "me", "everyone" ], "description": "me: the caller's own pin. everyone: an org admin's, on every member's Home." }, "user_id": { "type": [ "string", "null" ], "format": "tradehq-user-id", "description": "The caller, on their own pin; null on the org's." }, "pinned_by": { "type": "string", "format": "tradehq-user-id", "description": "Who pinned it: the caller, or the org admin who pinned it for everyone." }, "created_at": { "type": "string", "format": "date-time", "description": "When." } }, "required": [ "tab", "for", "user_id", "pinned_by", "created_at" ], "additionalProperties": false }, "description": "Where it is pinned for the caller, by tab: their own pins (for me) and the org's (for everyone, an org admin's). Empty for a system view.", "x-data-class": "operational" } }, "required": [ "view_id", "capability", "mode", "contract", "args", "title", "pinned", "visibility", "system", "owner_user_id", "writable", "unmapped", "updated_at", "shared_with", "pins" ], "additionalProperties": false }, "annotations": { "title": "Save a view", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "schedule_org_deletion", "title": "Schedule an org's deletion", "description": "Starts a 30 day countdown to an org's deletion and locks its users out for it. Nothing is deleted: after the countdown, purge_org needs two staff or one principal, and a job does the purge. Cancelling returns the org to the state it was in. Calling it again returns the countdown already running. A test twin, an org the repository declares and a purged org are refused.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose deletion to schedule." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "deletion_scheduled" ], "description": "deletion_scheduled.", "x-data-class": "operational" }, "purge_after": { "type": "string", "format": "date-time", "description": "The end of the countdown: when a purge may be approved.", "x-data-class": "operational" }, "scheduled_at": { "type": "string", "format": "date-time", "description": "When the countdown started: the first call's time on a replay.", "x-data-class": "operational" } }, "required": [ "org_id", "state", "purge_after", "scheduled_at" ], "additionalProperties": false }, "annotations": { "title": "Schedule an org's deletion", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "search_party_directory", "title": "Search the party directory", "description": "Searches the party directory, the one registry of trading parties every Trade HQ tenant sees the same, ordered by party id, a page at a time. Filters by a case-insensitive substring of the party's name. Each party carries its id, its name and whether an org has claimed it; it never says which org. Any signed-in user may search it. With org_id, an org the caller is a member of, each party also says whether that org claims it (yours).", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "A case-insensitive substring of the party's name." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "The page size." }, "after": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The previous page's next_after." }, "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "An org the caller is a member of, for yours. Absent, yours is null." } }, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The party's id: what claim_party and set_document_parties name.", "x-data-class": "operational" }, "name": { "type": "string", "description": "The party's name.", "x-data-class": "operational" }, "claimed": { "type": "boolean", "description": "Whether an org has claimed the party (claim_party). Which org is not said.", "x-data-class": "operational" }, "yours": { "type": [ "boolean", "null" ], "description": "Whether the org named by org_id claims the party; null when no org_id is given.", "x-data-class": "operational" } }, "required": [ "party_id", "name", "claimed", "yours" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "Search the party directory", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "search_records", "title": "Search records", "description": "Searches an org's records for what was typed: orders (by invoice number, order id or customer), intake (by booking number), units (by BIC number, full or partial, with or without its check digit, and a wrong check digit still finds the unit), purchase orders (by PO number or supplier), customers and suppliers (by name), and shares (by name or a recipient's address). Each hit carries its kind, a label, a short subtitle, the web route that opens it and whether it matched exactly, as a prefix or inside the text; exact hits come first. kinds narrows the search to the kinds named.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose records to search." }, "q": { "type": "string", "minLength": 2, "maxLength": 100, "description": "What was typed: a number, a name or an address, matched case folded, exactly, as a prefix or inside the text." }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "order", "intake", "unit", "purchase_order", "party", "share" ] }, "minItems": 1, "maxItems": 6, "uniqueItems": true, "description": "Only these kinds of record: order, intake, unit, purchase_order, party, share. Absent, every kind." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "How many of the best hits to answer." } }, "required": [ "org_id", "q" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "order", "intake", "unit", "purchase_order", "party", "share" ], "description": "What kind of record it is.", "x-data-class": "operational" }, "id": { "type": "string", "description": "The record's id: an order, intake, asset, contact or share id.", "x-data-class": "operational" }, "label": { "type": "string", "description": "What the record is called: the invoice number, booking number, BIC number, PO number, name, or the id when it has none.", "x-data-class": "operational" }, "subtitle": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "A short line beside the label: an order's customer, an intake's or purchase order's supplier, a unit's inventory status, a party's role (customer or supplier), or the share recipient whose address matched.", "x-data-class": "personal" }, "route": { "type": "string", "description": "The web route that opens the record.", "x-data-class": "operational" }, "match": { "type": "string", "enum": [ "exact", "prefix", "contains" ], "description": "How it matched: exactly (for a BIC number, its first ten characters whatever the check digit), as a prefix, or inside the text.", "x-data-class": "operational" } }, "required": [ "kind", "id", "label", "subtitle", "route", "match" ], "additionalProperties": false }, "maxItems": 50 }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "Search records", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "send_feedback", "title": "Send feedback or report a problem", "description": "Sends Trade HQ what you think (kind feedback) or what went wrong (kind problem), from the page you are on, for your org. Trade HQ's support team receives it with the page, the build, the browser and the app's recent errors, how much it hurts, the record you were on as a link to it, whether only you and Trade HQ may see it, and the screenshot when you attach one, and answers you when it is resolved. Answers the report's reference. Send it again with the same Idempotency-Key and it is the same report.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org you are sending it for: the one you are signed in to." }, "kind": { "type": "string", "enum": [ "feedback", "problem" ], "description": "feedback (Send feedback) or problem (Report a problem)." }, "message": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "What you think, or what went wrong and what you expected." }, "impact": { "type": "string", "enum": [ "blocking", "slowing", "suggestion" ], "description": "How much it hurts: blocking (Blocking my work), slowing (Slowing me down) or suggestion (Suggestion)." }, "page": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The path of the page you are on, e.g. /orders. A query or fragment is cut off." }, "record": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "order", "intake", "party", "share", "received_share", "release", "gate_in", "gate_out", "audit_schedule", "report" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "kind", "id" ], "additionalProperties": false, "description": "The record the page shows, when it shows one: its kind (order, intake, party, share, received_share, release, gate_in, gate_out, audit_schedule, report) and id. The report links to it and never carries its contents." }, "private": { "type": "boolean", "description": "Only me and Trade HQ: true shows the report to you and to Trade HQ alone, never to the rest of your org. Not given is false: the whole org sees it." }, "build": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The app's build, its commit, when the app knows it." }, "browser": { "type": "string", "minLength": 1, "maxLength": 400, "description": "The browser's user agent." }, "recent_errors": { "type": "array", "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "The last errors the app saw, newest last, at most five." }, "screenshot": { "type": "object", "properties": { "content_type": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp" ] }, "content_base64": { "type": "string", "minLength": 4, "maxLength": 1398168 } }, "required": [ "content_type", "content_base64" ], "additionalProperties": false, "description": "An image to attach (PNG, JPEG or WebP, at most 1 MiB), as base64." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "kind", "message", "impact", "page" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "feedback_id": { "type": "string", "description": "The report: fb and thirty characters, derived from the Idempotency-Key.", "x-data-class": "operational" }, "reference": { "type": "string", "description": "The reference support files it under, to quote when you write to them.", "x-data-class": "operational" }, "screenshot": { "type": "string", "enum": [ "attached", "failed", "none", "skipped" ], "description": "Whether the screenshot was attached: failed means the report was filed without it.", "x-data-class": "operational" } }, "required": [ "feedback_id", "reference", "screenshot" ], "additionalProperties": false }, "annotations": { "title": "Send feedback or report a problem", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_account_role", "title": "Set an account role", "description": "Gives a person a role in an account, owner or member, or changes the one they hold. Only someone already in one of the account's entities can be given one, a deactivated person is neither added nor made an owner, and an account keeps at least one owner. An owner provisions the account's entities and portfolios; a member sees its entities. Org roles are not changed. Setting the role a person already holds changes nothing.", "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The person, a member of one of the account's entities." }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "owner or member." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "account_id", "user_id", "role" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account.", "x-data-class": "operational" }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The person.", "x-data-class": "operational" }, "role": { "type": "string", "enum": [ "owner", "member" ], "description": "The role they now hold.", "x-data-class": "operational" }, "previous_role": { "type": [ "string", "null" ], "enum": [ "owner", "member", null ], "description": "The role they held before; null when they held none.", "x-data-class": "operational" } }, "required": [ "account_id", "user_id", "role", "previous_role" ], "additionalProperties": false }, "annotations": { "title": "Set an account role", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_acting_scope", "title": "Set where my session acts", "description": "Sets where the signed-in user's session acts: at an account they belong to, at the session's org, or at a unit of it. At account scope, landing_org_id names the entity acts land in; until one is chosen, every act is refused. An org admin can pin the session to a unit as a device, after which it acts only in that unit and cannot change scope. Moves no data and grants nothing.", "inputSchema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "account", "org", "unit" ], "description": "account, org or unit." }, "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "At account scope: the account. Required there, refused anywhere else." }, "landing_org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "At account scope: the entity acts land in, one of the account's orgs." }, "unit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "At unit scope: a unit of the session's org. Required there, refused anywhere else." }, "pin_device": { "type": "boolean", "description": "At unit scope: pin this session to the unit as a device. An org admin's act, and permanent for the session." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "scope" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "account", "org", "unit" ], "description": "Where the session acts: account, org or unit.", "x-data-class": "operational" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account: the scope's at account scope, else the session org's own; null when the org is in none.", "x-data-class": "operational" }, "account_name": { "type": [ "string", "null" ], "description": "That account's name.", "x-data-class": "operational" }, "account_member": { "type": "boolean", "description": "The caller is a member of that account, so the session can act at account scope.", "x-data-class": "operational" }, "org_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The session's org: the entity.", "x-data-class": "operational" }, "org_name": { "type": [ "string", "null" ], "description": "The entity's name.", "x-data-class": "operational" }, "landing_org_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "At account scope, the entity acts land in; null until one is chosen, and at any other level.", "x-data-class": "operational" }, "landing_org_name": { "type": [ "string", "null" ], "description": "That entity's name.", "x-data-class": "operational" }, "unit_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-unit-id", "description": "At unit scope, the unit.", "x-data-class": "operational" }, "unit_name": { "type": [ "string", "null" ], "description": "The unit's name.", "x-data-class": "operational" }, "device": { "type": "boolean", "description": "The session is a device pinned to its unit: it acts only there and cannot change scope.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "The session's mode: live, or test, where it acts in the org's test twin.", "x-data-class": "operational" }, "test_mode_allowed": { "type": "boolean", "description": "The caller may enter test mode: their role in the session's live org carries org.admin or api_key.read. Leaving test is open to anyone in it.", "x-data-class": "operational" } }, "required": [ "level", "account_id", "account_name", "account_member", "org_id", "org_name", "landing_org_id", "landing_org_name", "unit_id", "unit_name", "device", "mode", "test_mode_allowed" ], "additionalProperties": false }, "annotations": { "title": "Set where my session acts", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_api_key_limits", "title": "Set an API key's limits", "description": "Sets how many requests one of the org's API keys may make per UTC minute and per UTC day; 0 means no limit. A request past either limit is refused with 429 and counted as refused in get_api_usage. A BK_ key cannot be limited: rotate it into an sk_live_ key first. Setting the limits a key already has changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the key belongs to." }, "key_id": { "type": "string", "minLength": 1, "maxLength": 12, "description": "The key to limit." }, "requests_per_minute": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Requests allowed in one UTC minute; 0 for no limit." }, "requests_per_day": { "type": "integer", "minimum": 0, "maximum": 100000000, "description": "Requests allowed in one UTC day; 0 for no limit." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "key_id", "requests_per_minute", "requests_per_day" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "key_id": { "type": "string", "description": "The key's id, its public part.", "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 live org it was issued on.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What it is for.", "x-data-class": "operational" }, "service_account_id": { "type": [ "string", "null" ], "description": "The service account that owns the key and that it acts as (TRA-493); null only for a BK_ key the core issued.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "sk", "legacy" ], "description": "sk for a key this plane issued, legacy for a BK_ key.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live, or test for a key that reaches the test twin.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "expiring", "expired", "revoked" ], "description": "active; expiring when it has an expiry still ahead, as a rotated key does in its overlap; expired; or revoked.", "x-data-class": "operational" }, "display": { "type": "string", "description": "The key's prefix and id, safe to show anywhere. Never the secret.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was issued.", "x-data-class": "operational" }, "created_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who issued it.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops working, if it does.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked.", "x-data-class": "operational" }, "api_version": { "type": [ "string", "null" ], "description": "The API version it is pinned to; null for a BK_ key, which follows the current version.", "x-data-class": "operational" }, "requests_per_minute": { "type": [ "integer", "null" ], "description": "Its per-minute limit, or null for none.", "x-data-class": "operational" }, "requests_per_day": { "type": [ "integer", "null" ], "description": "Its per-day limit, or null for none.", "x-data-class": "operational" }, "rotated_from": { "type": [ "string", "null" ], "description": "The key it succeeded.", "x-data-class": "operational" }, "rotated_to": { "type": [ "string", "null" ], "description": "The key that succeeded it.", "x-data-class": "operational" }, "grants": { "type": "array", "items": { "type": "string" }, "description": "What the key was granted (TRA-619), in name order: the permissions it may use, each only while its service account's role template carries it. Empty for a key granted nothing and for a BK_ key.", "x-data-class": "operational" } }, "required": [ "key_id", "org_id", "name", "service_account_id", "kind", "mode", "status", "display", "created_at", "created_by", "expires_at", "revoked_at", "api_version", "requests_per_minute", "requests_per_day", "rotated_from", "rotated_to", "grants" ], "additionalProperties": false }, "annotations": { "title": "Set an API key's limits", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_api_key_version", "title": "Set an API key's version", "description": "Pins one of the org's API keys to an API version: a request the key makes without a Trade-HQ-Version header is then served that version. The version is one this API serves, the current one or an older one still supported. A BK_ key has no pin: rotate it into an sk_live_ key first. Pinning a key to the version it already has changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the key belongs to." }, "key_id": { "type": "string", "minLength": 1, "maxLength": 12, "description": "The key to re-pin." }, "api_version": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The version to pin the key to, YYYY-MM-DD: one this API serves." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "key_id", "api_version" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "key_id": { "type": "string", "description": "The key's id, its public part.", "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 live org it was issued on.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What it is for.", "x-data-class": "operational" }, "service_account_id": { "type": [ "string", "null" ], "description": "The service account that owns the key and that it acts as (TRA-493); null only for a BK_ key the core issued.", "x-data-class": "operational" }, "kind": { "type": "string", "enum": [ "sk", "legacy" ], "description": "sk for a key this plane issued, legacy for a BK_ key.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live, or test for a key that reaches the test twin.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "expiring", "expired", "revoked" ], "description": "active; expiring when it has an expiry still ahead, as a rotated key does in its overlap; expired; or revoked.", "x-data-class": "operational" }, "display": { "type": "string", "description": "The key's prefix and id, safe to show anywhere. Never the secret.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was issued.", "x-data-class": "operational" }, "created_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who issued it.", "x-data-class": "operational" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it stops working, if it does.", "x-data-class": "operational" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was revoked.", "x-data-class": "operational" }, "api_version": { "type": [ "string", "null" ], "description": "The API version it is pinned to; null for a BK_ key, which follows the current version.", "x-data-class": "operational" }, "requests_per_minute": { "type": [ "integer", "null" ], "description": "Its per-minute limit, or null for none.", "x-data-class": "operational" }, "requests_per_day": { "type": [ "integer", "null" ], "description": "Its per-day limit, or null for none.", "x-data-class": "operational" }, "rotated_from": { "type": [ "string", "null" ], "description": "The key it succeeded.", "x-data-class": "operational" }, "rotated_to": { "type": [ "string", "null" ], "description": "The key that succeeded it.", "x-data-class": "operational" }, "grants": { "type": "array", "items": { "type": "string" }, "description": "What the key was granted (TRA-619), in name order: the permissions it may use, each only while its service account's role template carries it. Empty for a key granted nothing and for a BK_ key.", "x-data-class": "operational" } }, "required": [ "key_id", "org_id", "name", "service_account_id", "kind", "mode", "status", "display", "created_at", "created_by", "expires_at", "revoked_at", "api_version", "requests_per_minute", "requests_per_day", "rotated_from", "rotated_to", "grants" ], "additionalProperties": false }, "annotations": { "title": "Set an API key's version", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_beta_list_member", "title": "Add or remove an org or user on a beta list", "description": "Adds an org or a user to a named beta list (Loadstar beta, CHS beta), recording who at the customer agreed to test early and on what date, or removes one added here. Flags at the beta wave are then on for them. Members declared in the repository are removed by a pull request, not here. Recorded with who did it. Send an Idempotency-Key header. Staff only.", "inputSchema": { "type": "object", "properties": { "list": { "type": "string", "minLength": 1, "maxLength": 60, "description": "The beta list's name, as src/beta_lists.json has it (not staff)." }, "member_kind": { "type": "string", "enum": [ "org", "user" ], "description": "org or user." }, "member_id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The org's org_id or the user's user_id." }, "state": { "type": "string", "enum": [ "add", "remove" ], "description": "add or remove." }, "agreed_by": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Who at the customer agreed to test early. Required to add; refused to remove." }, "agreed_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The day they agreed, never in the future. Required to add; refused to remove." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "list", "member_kind", "member_id", "state" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "action_id": { "type": "string", "description": "This change's audit row.", "x-data-class": "operational" }, "list": { "type": "string", "description": "The beta list.", "x-data-class": "operational" }, "member_kind": { "type": "string", "enum": [ "org", "user" ], "description": "org or user.", "x-data-class": "operational" }, "member_id": { "type": "string", "description": "The org or user.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "add", "remove" ], "description": "add or remove.", "x-data-class": "operational" }, "agreed_by": { "type": [ "string", "null" ], "description": "Who agreed; null on a remove.", "x-data-class": "operational" }, "agreed_at": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "When they agreed; null on a remove.", "x-data-class": "operational" }, "acted_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who on staff made the change.", "x-data-class": "operational" }, "acted_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" } }, "required": [ "action_id", "list", "member_kind", "member_id", "state", "agreed_by", "agreed_at", "acted_by", "acted_at" ], "additionalProperties": false }, "annotations": { "title": "Add or remove an org or user on a beta list", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_catalog_price", "title": "Set a catalog price", "description": "Sets Wholesale, Retail or both on a sales catalog group or split (market, size, type, condition and any split values, as summarize_catalog answers them), writing every line beneath it, or on one catalog line. A line priced on its own keeps its price when a group is priced, and the answer says how many lines it skipped; with replace, the group price is written to those too. Send an Idempotency-Key header: a retry with the same key and inputs returns the same answer and writes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose catalog it prices." }, "group_key": { "type": "object", "properties": { "market": { "type": [ "string", "null" ], "maxLength": 200 }, "size": { "type": [ "string", "null" ], "maxLength": 200 }, "type": { "type": [ "string", "null" ], "maxLength": 200 }, "condition": { "type": [ "string", "null" ], "maxLength": 200 }, "splits": { "type": "array", "maxItems": 8, "items": { "oneOf": [ { "type": "object", "properties": { "attribute": { "type": "string", "enum": [ "forklift_pockets", "lockbox" ] }, "value": { "type": [ "boolean", "null" ] } }, "required": [ "attribute", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "attribute": { "type": "string", "enum": [ "color", "vents", "handles", "depot", "source", "damage" ] }, "value": { "type": [ "string", "null" ], "maxLength": 200 } }, "required": [ "attribute", "value" ], "additionalProperties": false } ] } } }, "required": [ "market", "size", "type", "condition" ], "additionalProperties": false, "description": "The group or split to price, as summarize_catalog answers it: market, size, type and condition (each null where the group's is), and splits, the split values beneath it as [{attribute, value}]. Every line under it is priced. Give this or catalog_id, not both." }, "catalog_id": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "One catalog line to price. Its price is its own from then on: a later group price skips it unless that call says replace. Give this or group_key, not both." }, "wholesale": { "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "description": "The Wholesale price to set, as a string: up to 11 digits and 4 decimal places. Give this, retail or both." }, "retail": { "type": "string", "pattern": "^[0-9]{1,11}(\\.[0-9]{1,4})?$", "description": "The Retail price to set, as a string: up to 11 digits and 4 decimal places. Give this, wholesale or both." }, "replace": { "type": "boolean", "description": "With group_key: also write lines whose price is their own (set on the line, in the popout, or changed since the last group price). Absent or false, those are kept and counted as skipped." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "price_set_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "This call's id, derived from its Idempotency-Key.", "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 whose catalog it priced.", "x-data-class": "operational" }, "source": { "type": "string", "description": "group (a group or split was priced) or line (one line was).", "x-data-class": "operational" }, "group_key": { "type": [ "object", "null" ], "description": "The group key priced, as read back: {market, size, type, condition, splits}. Null for a line.", "x-data-class": "operational" }, "catalog_id": { "type": [ "string", "null" ], "description": "The line priced. Null for a group.", "x-data-class": "operational" }, "lines": { "type": "integer", "minimum": 0, "description": "The catalog lines the call covered.", "x-data-class": "operational" }, "written": { "type": "integer", "minimum": 0, "description": "Lines at least one price was written to.", "x-data-class": "operational" }, "skipped": { "type": "integer", "minimum": 0, "description": "Lines at least one price was kept on, because the line's price is its own.", "x-data-class": "operational" }, "replaced": { "type": "integer", "minimum": 0, "description": "Lines whose own price was replaced, with replace.", "x-data-class": "operational" }, "prices": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "string", "enum": [ "wholesale", "retail" ] }, "amount": { "type": "string", "pattern": "^[0-9]+\\.[0-9]{4}$" }, "written": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "replaced": { "type": "integer", "minimum": 0 } }, "required": [ "price", "amount", "written", "skipped", "replaced" ], "additionalProperties": false } }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Per price given (wholesale, retail): the amount set, as a 4-place decimal, and the lines written, skipped and replaced.", "x-data-class": "commercial" }, "set_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who set it.", "x-data-class": "operational" }, "set_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" } }, "required": [ "price_set_id", "org_id", "source", "group_key", "catalog_id", "lines", "written", "skipped", "replaced", "prices", "set_by", "set_at" ], "additionalProperties": false }, "annotations": { "title": "Set a catalog price", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_customer_stage", "title": "Set an org's customer stage", "description": "Sets where a customer org is in Trade HQ's sales cycle: prospect, pilot, or customer, which clears the stage (an org with none is a customer). The org's Linear customer shows it as its status after the next customer sync, which this call asks for at once. Setting the stage it already has changes nothing. Only a customer org has a stage; a test twin follows its live org. Trade HQ staff only.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The customer org." }, "stage": { "type": "string", "enum": [ "prospect", "pilot", "customer" ], "description": "prospect, pilot, or customer to clear the stage." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "stage" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "stage": { "type": "string", "enum": [ "prospect", "pilot", "customer" ], "description": "The org's stage now: prospect, pilot, or customer when it has none.", "x-data-class": "operational" }, "previous": { "type": "string", "enum": [ "prospect", "pilot", "customer" ], "description": "The stage it had before the call; the same as stage when nothing changed.", "x-data-class": "operational" } }, "required": [ "org_id", "stage", "previous" ], "additionalProperties": false }, "annotations": { "title": "Set an org's customer stage", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_data_policy", "title": "Set a role template's data policy", "description": "Sets one of the org's own role templates' data policy, whole: which records its members reach (record_scope) and, for commercial, financial and personal fields, whether they read them (allowed, masked or denied) and export them (allowed or denied). A shipped template's data policy is read-only; clone it first. Takes role.manage and a template carrying org.admin. Sending the same data policy again changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose role template it is." }, "role_id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "One of the org's clone ids. A shipped template is refused." }, "record_scope": { "type": "string", "enum": [ "whole_org", "unit_subtree", "portfolio", "party_seat" ], "description": "Which records its members reach: whole_org, or party_seat for a Counterparty clone." }, "commercial_read": { "type": "string", "enum": [ "allowed", "masked", "denied" ], "description": "Commercial fields: allowed, masked or denied." }, "commercial_export": { "type": "string", "enum": [ "allowed", "denied" ], "description": "Commercial fields in an export: allowed or denied." }, "financial_read": { "type": "string", "enum": [ "allowed", "masked", "denied" ], "description": "Financial fields: allowed, masked or denied." }, "financial_export": { "type": "string", "enum": [ "allowed", "denied" ], "description": "Financial fields in an export: allowed or denied." }, "personal_read": { "type": "string", "enum": [ "allowed", "masked", "denied" ], "description": "Personal fields: allowed, masked or denied." }, "personal_export": { "type": "string", "enum": [ "allowed", "denied" ], "description": "Personal fields in an export: allowed or denied." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "role_id", "record_scope", "commercial_read", "commercial_export", "financial_read", "financial_export", "personal_read", "personal_export" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "role_id": { "type": "string", "description": "The role template: a shipped id such as read_only, or a clone's RT id.", "x-data-class": "operational" }, "source": { "type": "string", "enum": [ "shipped", "own", "inherited" ], "description": "shipped: the template's own, read-only; own: the clone's own row; inherited: a clone with no row, answered its source's.", "x-data-class": "operational" }, "version": { "type": "integer", "description": "The clone's own data policy's version; 0 for a shipped or inherited one.", "x-data-class": "operational" }, "record_scope": { "type": "string", "enum": [ "whole_org", "unit_subtree", "portfolio", "party_seat" ], "description": "Which records its members reach: whole_org, unit_subtree, portfolio or party_seat.", "x-data-class": "operational" }, "record_scope_locked": { "type": "boolean", "description": "A Counterparty template, or a clone of one, is locked to its party's seat.", "x-data-class": "operational" }, "commercial_read": { "type": "string", "enum": [ "allowed", "masked", "denied" ], "description": "Commercial fields (acquisition cost, margin, supplier price, FX override): allowed, masked or denied.", "x-data-class": "operational" }, "commercial_export": { "type": "string", "enum": [ "allowed", "denied" ], "description": "Whether an export carries commercial fields: allowed or denied.", "x-data-class": "operational" }, "financial_read": { "type": "string", "enum": [ "allowed", "masked", "denied" ], "description": "Financial fields (invoice totals, credit terms): allowed, masked or denied.", "x-data-class": "operational" }, "financial_export": { "type": "string", "enum": [ "allowed", "denied" ], "description": "Whether an export carries financial fields: allowed or denied.", "x-data-class": "operational" }, "personal_read": { "type": "string", "enum": [ "allowed", "masked", "denied" ], "description": "Personal fields (member emails, phone numbers): allowed, masked or denied.", "x-data-class": "operational" }, "personal_export": { "type": "string", "enum": [ "allowed", "denied" ], "description": "Whether an export carries personal fields: allowed or denied.", "x-data-class": "operational" } }, "required": [ "org_id", "role_id", "source", "version", "record_scope", "record_scope_locked", "commercial_read", "commercial_export", "financial_read", "financial_export", "personal_read", "personal_export" ], "additionalProperties": false }, "annotations": { "title": "Set a role template's data policy", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_document_parties", "title": "Set a document's parties", "description": "Sets the parties on one commercial document (a purchase order is an asset_intake, a lease or sale is an order) and the seat each holds, replacing the seats it had. Each party is from the shared directory. When a Trade HQ org has claimed a party, that org's members can then read their own seat on this document. Sending the same set again changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that owns the document." }, "document_kind": { "type": "string", "enum": [ "asset_intake", "order" ], "description": "The table the document is in: asset_intake (a purchase order) or order." }, "document_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The document's id in that table." }, "parties": { "type": "array", "maxItems": 20, "items": { "type": "object", "properties": { "party_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid" }, "seat": { "type": "string", "enum": [ "buyer", "lessee", "lessor", "seller" ] } }, "required": [ "party_id", "seat" ], "additionalProperties": false }, "description": "Every party on the document and its seat. An asset_intake takes buyer and seller; an order takes buyer, seller, lessor and lessee. An empty list removes every seat." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "document_kind", "document_id", "parties" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that owns the document.", "x-data-class": "operational" }, "document_kind": { "type": "string", "enum": [ "asset_intake", "order" ], "description": "The document's kind.", "x-data-class": "operational" }, "document_id": { "type": "string", "description": "The document's id.", "x-data-class": "operational" }, "seats": { "type": "integer", "description": "How many seats the document now carries.", "x-data-class": "operational" } }, "required": [ "org_id", "document_kind", "document_id", "seats" ], "additionalProperties": false }, "annotations": { "title": "Set a document's parties", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_domain_join_policy", "title": "Set a domain's join_policy", "description": "Decides what a person signing up with an address at one of the org's verified domains may do: invite_only (join only when invited) or request (they are put to the org's admins as a join request to approve or reject; nobody joins without that). The domain must be verified first with verify_domain.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the domain is verified for." }, "domain": { "type": "string", "minLength": 3, "maxLength": 253, "description": "The verified domain." }, "join_policy": { "type": "string", "enum": [ "invite_only", "request" ], "description": "invite_only or request." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "domain", "join_policy" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org claiming it.", "x-data-class": "operational" }, "domain": { "type": "string", "description": "The domain, lower case.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "verified" ], "description": "pending until the TXT record is found, then verified.", "x-data-class": "operational" }, "record_name": { "type": "string", "description": "Where to publish the TXT record.", "x-data-class": "operational" }, "record_value": { "type": "string", "description": "What the TXT record carries.", "x-data-class": "operational" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was verified.", "x-data-class": "operational" }, "verified_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who verified it.", "x-data-class": "operational" }, "join_policy": { "type": "string", "enum": [ "invite_only", "request" ], "description": "invite_only, or request: a person signing up at the domain is put to the org's admins as a join request.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who claimed it.", "x-data-class": "operational" } }, "required": [ "org_id", "domain", "status", "record_name", "record_value", "verified_at", "verified_by", "join_policy", "created_by" ], "additionalProperties": false }, "annotations": { "title": "Set a domain's join_policy", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_flag_lists", "title": "Choose the beta lists a flag reaches", "description": "Sets which beta lists one registered feature flag reaches in PostHog, on the wave you saw: from staff or the beta lists it puts the flag on the lists chosen, and on a percentage of customer orgs it keeps the percentage and takes the lists chosen. Name the wave you saw; if the flag has moved since, nothing changes. Refused for a flag off, not in PostHog, on for everyone or with a rule made in PostHog, and when the lists are the ones it already reaches. Each change is recorded with who made it and the lists before and after. Send an Idempotency-Key header. Staff only.", "inputSchema": { "type": "object", "properties": { "flag_key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The flag's key, as the registry has it." }, "from": { "type": "string", "enum": [ "absent", "off", "staff", "beta", "orgs_10", "orgs_25", "orgs_50", "everyone", "custom" ], "description": "The wave you saw the flag on (list_flags' wave). If PostHog has it anywhere else, nothing changes." }, "lists": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "Loadstar beta", "CHS beta", "Admin walk" ] }, "description": "The beta lists the flag reaches, by name, at least one." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "flag_key", "from", "lists" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "action_id": { "type": "string", "description": "This move's audit row.", "x-data-class": "operational" }, "flag_key": { "type": "string", "description": "The flag moved.", "x-data-class": "operational" }, "action": { "type": "string", "enum": [ "advance", "roll_back", "set_lists" ], "description": "advance, roll_back, or set_lists (TRA-1461: the beta lists chosen).", "x-data-class": "operational" }, "from_wave": { "type": "string", "description": "The wave PostHog had it on.", "x-data-class": "operational" }, "to_wave": { "type": "string", "description": "The wave it is on now.", "x-data-class": "operational" }, "acted_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who moved it: the staff member or agent, never PostHog's key.", "x-data-class": "operational" }, "acted_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" }, "posthog_url": { "type": [ "string", "null" ], "description": "The flag in PostHog; null on a replay.", "x-data-class": "operational" } }, "required": [ "action_id", "flag_key", "action", "from_wave", "to_wave", "acted_by", "acted_at", "posthog_url" ], "additionalProperties": false }, "annotations": { "title": "Choose the beta lists a flag reaches", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_fx_rate_override", "title": "Override an FX rate", "description": "Sets a manual rate for one currency against EUR on one day, for one account or, with no account and only by staff, for every account. The fetched ECB rate is kept, not replaced: the answer states it, and every listed rate says whether an override made it. An override is permanent and carries who set it, when and why; a correction is a new override, and the newest wins. Send an Idempotency-Key header: a retry with the same key and inputs returns the same override and records nothing new.", "inputSchema": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "format": "iso4217", "description": "The currency whose EUR rate is overridden: an ISO 4217 code, not EUR." }, "rate_date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The day the override is for, YYYY-MM-DD. Not in the future." }, "rate": { "type": "string", "pattern": "^[0-9]{1,12}(\\.[0-9]{1,12})?$", "format": "positive-decimal", "description": "Units of the currency per one EUR, as a string of digits." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the fetched rate is not the one to use. Kept with the override." }, "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account it applies to. Absent: every account (staff.finance only)." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "currency", "rate_date", "rate", "reason" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "fx_rate_override_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The override's id.", "x-data-class": "operational" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "The account it applies to; null for every account.", "x-data-class": "operational" }, "rate_date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The day it is for.", "x-data-class": "operational" }, "base_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "format": "iso4217", "description": "Always EUR.", "x-data-class": "operational" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "format": "iso4217", "description": "The currency overridden.", "x-data-class": "operational" }, "rate": { "anyOf": [ { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$", "format": "positive-decimal" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The override's rate.", "x-data-class": "commercial" }, "fetched_rate": { "type": [ "string", "null" ], "pattern": "^[0-9]+(\\.[0-9]+)?$", "format": "positive-decimal", "description": "ECB's rate for the same currency and day, kept; null when ECB published none.", "x-data-class": "operational" }, "reason": { "type": "string", "description": "Why.", "x-data-class": "operational" }, "set_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who set it.", "x-data-class": "operational" }, "set_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" } }, "required": [ "fx_rate_override_id", "account_id", "rate_date", "base_currency", "currency", "rate", "fetched_rate", "reason", "set_by", "set_at" ], "additionalProperties": false }, "annotations": { "title": "Override an FX rate", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_ip_allowlist", "title": "Set an org's IP allowlist", "description": "Sets the org's IP allowlist, whole: its mode (off, monitor, which records the requests it would refuse and refuses none, or enforce), who it checks (members, API keys or both) and its ranges, each an IPv4 or IPv6 range or a single address with a label. Enforce is refused until this deployment can read client addresses safely, and while your own address is not in the list. Break-glass sessions are never refused, and are recorded.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose IP allowlist to set." }, "mode": { "type": "string", "enum": [ "off", "monitor", "enforce" ], "description": "off: no check. monitor: requests from outside the list are recorded and allowed. enforce: they are refused." }, "applies_to": { "type": "string", "enum": [ "members", "api_keys", "both" ], "description": "Who the allowlist checks: members, API keys, or both." }, "entries": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "cidr": { "type": "string", "minLength": 1, "maxLength": 64, "format": "tradehq-ip-range" }, "label": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "cidr", "label" ], "additionalProperties": false }, "description": "The whole list of ranges, each {cidr, label}. A bare address is its /32 (IPv4) or /128 (IPv6)." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "mode", "applies_to", "entries" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "current": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "sso", "mfa", "session", "network", "drift" ] }, "policy": { "oneOf": [ { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "required": { "type": "boolean" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "domain", "required", "bypass_until" ], "additionalProperties": false } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string" }, "jit": { "type": "boolean" }, "default_role_template": { "type": [ "string", "null" ] }, "idp_mfa_trusted": { "type": "boolean" }, "allow_manual_additions": { "type": "boolean" } }, "required": [ "connection_id", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions" ], "additionalProperties": false } } }, "required": [ "domains", "connections" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "required", "required_for_templates" ] }, "templates": { "type": "array", "items": { "type": "string" } }, "grace_days": { "type": "integer", "minimum": 0, "maximum": 30 }, "accept_idp_mfa": { "type": "boolean" } }, "required": [ "mode", "templates", "grace_days", "accept_idp_mfa" ], "additionalProperties": false }, { "type": "object", "properties": { "idle_minutes": { "type": "integer", "minimum": 15, "maximum": 1440 }, "absolute_hours": { "type": "integer", "minimum": 1, "maximum": 168 }, "reauth_on_role_change": { "type": "boolean" }, "single_session": { "type": "boolean" } }, "required": [ "idle_minutes", "absolute_hours", "reauth_on_role_change", "single_session" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "monitor", "enforce" ] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "cidr": { "type": "string" }, "label": { "type": "string" } }, "required": [ "cidr", "label" ], "additionalProperties": false } }, "applies_to": { "type": "string", "enum": [ "members", "api_keys", "both" ] } }, "required": [ "mode", "entries", "applies_to" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "quarantine", "alert_only" ] } }, "required": [ "action" ], "additionalProperties": false } ] }, "is_default": { "type": "boolean" }, "version": { "type": [ "integer", "null" ], "minimum": 1 }, "changed_by": { "type": [ "string", "null" ] }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "section", "policy", "is_default", "version", "changed_by", "changed_at" ], "additionalProperties": false, "description": "The network section as it now stands, with its version.", "x-data-class": "operational" } }, "required": [ "org_id", "current" ], "additionalProperties": false }, "annotations": { "title": "Set an org's IP allowlist", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_maintenance_banner", "title": "Set the maintenance banner", "description": "Turns the platform-wide maintenance banner on with a message, or off. An on banner shows to every signed-in user until it is turned off, or for the given number of hours. Its severity is warning unless set. Each call is kept, so the history says who set what. Send an Idempotency-Key header: a retry with the same key and inputs changes nothing. Staff only.", "inputSchema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "on", "off" ], "description": "on shows the banner; off clears it." }, "message": { "type": "string", "minLength": 1, "maxLength": 280, "description": "What the banner says. Required when on, refused when off." }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ], "description": "info, warning or critical; warning when on and not given. Refused when off." }, "hours": { "type": "integer", "minimum": 1, "maximum": 168, "description": "End an on banner by itself after this many hours. Refused when off." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "state" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "banner_id": { "type": "string", "description": "This setting's id.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "on", "off" ], "description": "on or off.", "x-data-class": "operational" }, "message": { "type": [ "string", "null" ], "description": "What it says; null when off.", "x-data-class": "operational" }, "severity": { "type": [ "string", "null" ], "enum": [ "info", "warning", "critical", null ], "description": "Its severity; null when off.", "x-data-class": "operational" }, "ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it ends by itself; null when it does not.", "x-data-class": "operational" }, "set_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who set it.", "x-data-class": "operational" }, "set_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" } }, "required": [ "banner_id", "state", "message", "severity", "ends_at", "set_by", "set_at" ], "additionalProperties": false }, "annotations": { "title": "Set the maintenance banner", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_member_role", "title": "Set a member's role", "description": "Sets the role template a member holds in an org, which decides what they may call there, or the one a pending invitee will hold once they join. The template is a shipped one or the org's own, and you can give only what your own role carries, to someone whose current role carries nothing yours does not. An account owner holds the Owner role in every org of their account. Setting the template they already hold changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the role is held in." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The member or pending invitee." }, "role_template_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A shipped role template's id, or one of the org's own." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "user_id", "role_template_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The member.", "x-data-class": "operational" }, "role_template_id": { "type": "string", "description": "The template they now hold.", "x-data-class": "operational" } }, "required": [ "org_id", "user_id", "role_template_id" ], "additionalProperties": false }, "annotations": { "title": "Set a member's role", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_mfa_policy", "title": "Set an org's multi-factor authentication requirement", "description": "Sets whether the org's members must use a second factor: off, required for all members, or required for the members whose role template is one of templates. grace_days (0 to 30) is how long a member the requirement newly reaches may go on without one; past it, their requests are refused mfa_required until they set one up. accept_idp_mfa counts a sign-in through the org's SSO, where the identity provider asserted MFA, as enrolled. Needs a second factor verified in the last 10 minutes. Setting what is already in effect changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose MFA settings to set." }, "mode": { "type": "string", "enum": [ "off", "required", "required_for_templates" ], "description": "off, required (every member) or required_for_templates." }, "templates": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-role-template-id" }, "maxItems": 50, "uniqueItems": true, "description": "The role templates whose members must use a second factor: at least one for required_for_templates, and none for any other mode." }, "grace_days": { "type": "integer", "minimum": 0, "maximum": 30, "description": "Days a member the requirement newly reaches may go on without a second factor." }, "accept_idp_mfa": { "type": "boolean", "description": "Whether a sign-in through the org's SSO, where the identity provider asserted MFA, counts as enrolled." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "mode", "templates", "grace_days", "accept_idp_mfa" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "current": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "sso", "mfa", "session", "network", "drift" ] }, "policy": { "oneOf": [ { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "required": { "type": "boolean" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "domain", "required", "bypass_until" ], "additionalProperties": false } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string" }, "jit": { "type": "boolean" }, "default_role_template": { "type": [ "string", "null" ] }, "idp_mfa_trusted": { "type": "boolean" }, "allow_manual_additions": { "type": "boolean" } }, "required": [ "connection_id", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions" ], "additionalProperties": false } } }, "required": [ "domains", "connections" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "required", "required_for_templates" ] }, "templates": { "type": "array", "items": { "type": "string" } }, "grace_days": { "type": "integer", "minimum": 0, "maximum": 30 }, "accept_idp_mfa": { "type": "boolean" } }, "required": [ "mode", "templates", "grace_days", "accept_idp_mfa" ], "additionalProperties": false }, { "type": "object", "properties": { "idle_minutes": { "type": "integer", "minimum": 15, "maximum": 1440 }, "absolute_hours": { "type": "integer", "minimum": 1, "maximum": 168 }, "reauth_on_role_change": { "type": "boolean" }, "single_session": { "type": "boolean" } }, "required": [ "idle_minutes", "absolute_hours", "reauth_on_role_change", "single_session" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "monitor", "enforce" ] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "cidr": { "type": "string" }, "label": { "type": "string" } }, "required": [ "cidr", "label" ], "additionalProperties": false } }, "applies_to": { "type": "string", "enum": [ "members", "api_keys", "both" ] } }, "required": [ "mode", "entries", "applies_to" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "quarantine", "alert_only" ] } }, "required": [ "action" ], "additionalProperties": false } ] }, "is_default": { "type": "boolean" }, "version": { "type": [ "integer", "null" ], "minimum": 1 }, "changed_by": { "type": [ "string", "null" ] }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "section", "policy", "is_default", "version", "changed_by", "changed_at" ], "additionalProperties": false, "description": "The mfa section as it now stands, with its version.", "x-data-class": "operational" } }, "required": [ "org_id", "current" ], "additionalProperties": false }, "annotations": { "title": "Set an org's multi-factor authentication requirement", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_my_notification", "title": "Set one of my notifications", "description": "Adds a notice for the caller alone, or takes back one they added, emailed to their sign-in address. Only a kind their role can already see (notice_not_visible otherwise). A notice fixed in code or required by the org's notification settings cannot be turned off (notice_required). Report updates is on by default: on false turns it off. cadence is the audit log digest's (hourly or daily) and Report updates' (immediately, daily or weekly) alone. The same call again changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the caller is a member of." }, "kind": { "type": "string", "enum": [ "audit_digest", "admin_alerts", "access_request", "break_glass", "deletion", "announcement", "report_updates" ], "description": "The notice kind." }, "on": { "type": "boolean", "description": "true adds it for the caller (or turns Report updates back on); false takes back one they added (or turns Report updates off)." }, "cadence": { "type": "string", "enum": [ "hourly", "daily", "immediately", "weekly" ], "description": "The audit log digest: hourly or daily (hourly at first). Report updates: immediately, daily or weekly (immediately at first). Kept as it is when absent." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "kind", "on" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "audit_digest", "admin_alerts", "access_request", "break_glass", "deletion", "announcement", "report_updates" ], "description": "The notice kind.", "x-data-class": "operational" }, "title": { "type": "string", "description": "Its name, as the page shows it.", "x-data-class": "operational" }, "sent": { "type": "string", "description": "When it is sent.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "fixed", "required", "opted_in", "on", "available" ], "description": "fixed: sent to the caller by code (an org admin's notices). required: the org's notification settings names them. opted_in: they added it themselves. on: sent to them by default until they turn it off (Report updates). available: they may add it, or turn it back on.", "x-data-class": "operational" }, "cadence": { "type": [ "string", "null" ], "enum": [ "hourly", "daily", "immediately", "weekly", null ], "description": "How often the caller receives it: the audit digest hourly or daily (hourly until they choose); Report updates immediately, daily or weekly (immediately until they choose); null for every other kind.", "x-data-class": "operational" }, "email": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The sign-in address a notice is emailed to.", "x-data-class": "personal" } }, "required": [ "kind", "title", "sent", "state", "cadence", "email" ], "additionalProperties": false }, "annotations": { "title": "Set one of my notifications", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_my_settings", "title": "Set my settings", "description": "Sets or clears the caller's own settings (only keys a person may set for themselves, such as shell_last_tab, timezone and locale) and returns their effective settings in the org. A key the platform, the org's account or the org has locked is refused and nothing is applied. Sending the same change again changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the caller is a member of, whose levels above the caller decide what they may set." }, "settings": { "type": "object", "properties": { "date_format": { "anyOf": [ { "type": "string", "enum": [ "YYYY-MM-DD", "DD/MM/YYYY", "MM/DD/YYYY" ], "description": "How dates are shown." }, { "type": "null" } ], "description": "How dates are shown. Null clears the caller's own value." }, "locale": { "anyOf": [ { "type": "string", "enum": [ "en-US", "en-GB", "de-DE", "fr-FR", "es-ES", "nl-NL" ], "description": "The language and regional format of the interface." }, { "type": "null" } ], "description": "The language and regional format of the interface. Null clears the caller's own value." }, "shell_last_tab": { "anyOf": [ { "type": "string", "enum": [ "depots", "sell", "source", "intel" ], "description": "The tab of the app's header a person last chose, which they land on when they sign in." }, { "type": "null" } ], "description": "The tab of the app's header a person last chose, which they land on when they sign in. Null clears the caller's own value." }, "timezone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(UTC|[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+)+)$", "description": "The IANA time zone times are shown in." }, { "type": "null" } ], "description": "The IANA time zone times are shown in. Null clears the caller's own value." }, "week_starts_on": { "anyOf": [ { "type": "string", "enum": [ "monday", "sunday" ], "description": "The first day of a week in calendars and weekly reports." }, { "type": "null" } ], "description": "The first day of a week in calendars and weekly reports. Null clears the caller's own value." } }, "minProperties": 1, "additionalProperties": false, "description": "The keys to change: each to a value, or to null to clear the caller's own value." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "settings" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "settings": { "type": "object", "properties": { "base_currency": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "The ISO 4217 currency the books are kept in. An org decides it; its units and people do not." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "date_format": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "YYYY-MM-DD", "DD/MM/YYYY", "MM/DD/YYYY" ], "description": "How dates are shown." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "fiscal_year_start": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "The first day of the fiscal year, MM-DD. An org decides it; its units and people do not." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "locale": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "en-US", "en-GB", "de-DE", "fr-FR", "es-ES", "nl-NL" ], "description": "The language and regional format of the interface." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_booking": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How bookings are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_invoice": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How invoices are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_order": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How sales orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_purchase_order": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How purchase orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_release": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How releases are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. A yard may number its own." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_vendor_bill": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How vendor bills are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "shell_last_tab": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "depots", "sell", "source", "intel" ], "description": "The tab of the app's header a person last chose, which they land on when they sign in." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "timezone": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(UTC|[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+)+)$", "description": "The IANA time zone times are shown in." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "units_of_measure": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "metric", "imperial" ], "description": "Metric or imperial weights and dimensions. An org decides it for everyone in it." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "week_starts_on": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "monday", "sunday" ], "description": "The first day of a week in calendars and weekly reports." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false } }, "required": [ "base_currency", "date_format", "fiscal_year_start", "locale", "numbering_series_booking", "numbering_series_invoice", "numbering_series_order", "numbering_series_purchase_order", "numbering_series_release", "numbering_series_vendor_bill", "shell_last_tab", "timezone", "units_of_measure", "week_starts_on" ], "additionalProperties": false, "description": "Every key's effective value for the caller in the org, where it came from, and where it is locked.", "x-data-class": "operational" } }, "required": [ "org_id", "settings" ], "additionalProperties": false }, "annotations": { "title": "Set my settings", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_my_view_default", "title": "Set my default view", "description": "Sets the caller's own default view for a screen (mode sales: the Sales catalog): the saved view it opens with, over the org default. Leave out view_id to reset to the org default. The view must be one the caller may open, of the mode. Answers the view now in force, as get_view_default does.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose views they are." }, "mode": { "type": "string", "enum": [ "sales" ], "description": "Which screen's default: sales, the Sales catalog." }, "view_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The saved view to open with. Leave out to reset to the org default." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "mode" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sales" ], "description": "The mode: sales, the Sales catalog.", "x-data-class": "operational" }, "in_force": { "type": "string", "enum": [ "opened", "mine", "org", "fixed" ], "description": "Which view applies: opened (the saved view the caller opened), mine (their own default), org (the org default an org admin set) or fixed (none: the four fixed keys alone).", "x-data-class": "operational" }, "view_id": { "type": [ "string", "null" ], "description": "The view in force; null when fixed.", "x-data-class": "operational" }, "title": { "type": [ "string", "null" ], "description": "Its title; null when fixed.", "x-data-class": "operational" }, "capability": { "type": "string", "enum": [ "list_inventory", "summarize_catalog", "list_catalog" ], "description": "The capability the screen calls: the view's, or the mode's own when fixed.", "x-data-class": "operational" }, "args": { "type": "object", "properties": { "filters": { "type": "object", "description": "The list's filters input, as the capability declares it." }, "q": { "type": "string", "description": "The list's q input." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "One of the called capability's sort keys." }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "description": "The list's sort input: one key and its direction." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The list's fields input." }, "limit": { "type": "integer", "description": "The list's limit input." }, "split_by": { "type": "array", "items": { "type": "string" }, "description": "A Sales catalog view's split_by, in the order the attributes were switched on (summarize_catalog's input)." }, "slice": { "type": "string", "enum": [ "owned", "partner", "supplier", "all" ], "description": "A Sales catalog view's source slice: owned, partner, supplier or all." }, "layout": { "type": "string", "enum": [ "cards", "rows" ], "description": "A Sales catalog view's layout: cards or rows." } }, "additionalProperties": false, "description": "The arguments in force: the view's, or when fixed nothing split, every source and cards.", "x-data-class": "operational" }, "grouped_by": { "type": "array", "items": { "type": "string" }, "description": "The keys every group is grouped by, whatever view is in force: market, size, type and condition.", "x-data-class": "operational" }, "default_id": { "type": [ "string", "null" ], "description": "The default in force, when it is mine or org; null when opened or fixed.", "x-data-class": "operational" }, "user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Whose default is in force: the caller's when mine; null when org, opened or fixed.", "x-data-class": "operational" }, "set_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who set the default in force (the org admin, for the org's); null when opened or fixed.", "x-data-class": "operational" }, "set_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the default in force was set; null when opened or fixed.", "x-data-class": "operational" }, "my_default_view_id": { "type": [ "string", "null" ], "description": "The caller's own default, while they may open it; null when none (reset to the org default).", "x-data-class": "operational" }, "org_default_view_id": { "type": [ "string", "null" ], "description": "The org default, while the caller may open it; null when none (reset to the fixed keys).", "x-data-class": "operational" } }, "required": [ "mode", "in_force", "view_id", "title", "capability", "args", "grouped_by", "default_id", "user_id", "set_by", "set_at", "my_default_view_id", "org_default_view_id" ], "additionalProperties": false }, "annotations": { "title": "Set my default view", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_notification_policy", "title": "Set who must receive a notice", "description": "Sets, for one notice kind of the org, the whole set of recipients it must also reach beside its fixed ones, which nothing removes: members (by user_id), outside email addresses, and Slack channels (a new one by channel_name and webhook_url, one the org already holds by its id). cadence, hourly or daily, is the audit log digest's alone. The audit digest and admin activity alerts are written as subscribe_audit's subscriptions. Every outside address added or removed is audited. The same call again changes nothing. A Slack webhook URL is never returned.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose notification settings are set." }, "kind": { "type": "string", "enum": [ "audit_digest", "admin_alerts", "access_request", "break_glass", "deletion", "announcement" ], "description": "The notice kind: audit_digest, admin_alerts, access_request, break_glass, deletion or announcement." }, "recipients": { "type": "array", "maxItems": 50, "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "member", "outside", "slack" ] }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$" }, "email": { "type": "string", "minLength": 1, "maxLength": 320 }, "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9]{1,64}$" }, "channel_name": { "type": "string", "minLength": 1, "maxLength": 80 }, "webhook_url": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "type" ], "additionalProperties": false, "oneOf": [ { "properties": { "type": { "const": "member" }, "user_id": {} }, "required": [ "type", "user_id" ], "additionalProperties": false }, { "properties": { "type": { "const": "outside" }, "email": {} }, "required": [ "type", "email" ], "additionalProperties": false }, { "properties": { "type": { "const": "slack" }, "id": {} }, "required": [ "type", "id" ], "additionalProperties": false }, { "properties": { "type": { "const": "slack" }, "channel_name": {}, "webhook_url": {} }, "required": [ "type", "channel_name", "webhook_url" ], "additionalProperties": false } ] }, "description": "The whole set the org requires, each {type: member, user_id}, {type: outside, email}, {type: slack, id} (a channel the org already holds) or {type: slack, channel_name, webhook_url} (a new one). An empty list requires nobody beyond the fixed recipients." }, "cadence": { "type": "string", "enum": [ "hourly", "daily" ], "description": "The audit log digest only: hourly or daily (kept as it is when absent)." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "kind", "recipients" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "audit_digest", "admin_alerts", "access_request", "break_glass", "deletion", "announcement" ], "description": "The notice kind.", "x-data-class": "operational" }, "title": { "type": "string", "description": "Its name, as the page shows it.", "x-data-class": "operational" }, "sent": { "type": "string", "description": "When it is sent.", "x-data-class": "operational" }, "fixed": { "type": "array", "items": { "type": "string" }, "description": "The recipients fixed in code, which nothing removes: org_admins (every admin of the org) and, for a deletion, deleted_user (the user a user deletion is about).", "x-data-class": "operational" }, "recipients": { "anyOf": [ { "type": "object" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "Who the org also requires: {members: [{user_id, name}], outside: [email], slack: [{id, channel_name}]}. A Slack channel is its name and id, never its webhook URL.", "x-data-class": "personal" }, "cadence": { "type": [ "string", "null" ], "enum": [ "hourly", "daily", null ], "description": "The audit digest's cadence, hourly or daily; null for every other kind.", "x-data-class": "operational" } }, "required": [ "kind", "title", "sent", "fixed", "recipients", "cadence" ], "additionalProperties": false }, "annotations": { "title": "Set who must receive a notice", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_org_view_default", "title": "Set the org default view", "description": "Sets the org's default view for a screen (mode sales: the Sales catalog), which every member opens with unless they set their own. Org admins only. Leave out view_id to reset to the four fixed keys. The view must be shared org-read or org-write (view_not_shared otherwise). Answers the view now in force for the caller, as get_view_default does.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose views they are." }, "mode": { "type": "string", "enum": [ "sales" ], "description": "Which screen's default: sales, the Sales catalog." }, "view_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The shared saved view every member opens with. Leave out to reset to the four fixed keys." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "mode" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sales" ], "description": "The mode: sales, the Sales catalog.", "x-data-class": "operational" }, "in_force": { "type": "string", "enum": [ "opened", "mine", "org", "fixed" ], "description": "Which view applies: opened (the saved view the caller opened), mine (their own default), org (the org default an org admin set) or fixed (none: the four fixed keys alone).", "x-data-class": "operational" }, "view_id": { "type": [ "string", "null" ], "description": "The view in force; null when fixed.", "x-data-class": "operational" }, "title": { "type": [ "string", "null" ], "description": "Its title; null when fixed.", "x-data-class": "operational" }, "capability": { "type": "string", "enum": [ "list_inventory", "summarize_catalog", "list_catalog" ], "description": "The capability the screen calls: the view's, or the mode's own when fixed.", "x-data-class": "operational" }, "args": { "type": "object", "properties": { "filters": { "type": "object", "description": "The list's filters input, as the capability declares it." }, "q": { "type": "string", "description": "The list's q input." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "One of the called capability's sort keys." }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "description": "The list's sort input: one key and its direction." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The list's fields input." }, "limit": { "type": "integer", "description": "The list's limit input." }, "split_by": { "type": "array", "items": { "type": "string" }, "description": "A Sales catalog view's split_by, in the order the attributes were switched on (summarize_catalog's input)." }, "slice": { "type": "string", "enum": [ "owned", "partner", "supplier", "all" ], "description": "A Sales catalog view's source slice: owned, partner, supplier or all." }, "layout": { "type": "string", "enum": [ "cards", "rows" ], "description": "A Sales catalog view's layout: cards or rows." } }, "additionalProperties": false, "description": "The arguments in force: the view's, or when fixed nothing split, every source and cards.", "x-data-class": "operational" }, "grouped_by": { "type": "array", "items": { "type": "string" }, "description": "The keys every group is grouped by, whatever view is in force: market, size, type and condition.", "x-data-class": "operational" }, "default_id": { "type": [ "string", "null" ], "description": "The default in force, when it is mine or org; null when opened or fixed.", "x-data-class": "operational" }, "user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Whose default is in force: the caller's when mine; null when org, opened or fixed.", "x-data-class": "operational" }, "set_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who set the default in force (the org admin, for the org's); null when opened or fixed.", "x-data-class": "operational" }, "set_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the default in force was set; null when opened or fixed.", "x-data-class": "operational" }, "my_default_view_id": { "type": [ "string", "null" ], "description": "The caller's own default, while they may open it; null when none (reset to the org default).", "x-data-class": "operational" }, "org_default_view_id": { "type": [ "string", "null" ], "description": "The org default, while the caller may open it; null when none (reset to the fixed keys).", "x-data-class": "operational" } }, "required": [ "mode", "in_force", "view_id", "title", "capability", "args", "grouped_by", "default_id", "user_id", "set_by", "set_at", "my_default_view_id", "org_default_view_id" ], "additionalProperties": false }, "annotations": { "title": "Set the org default view", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_portfolio_members", "title": "Set a portfolio's orgs", "description": "Replaces a portfolio's orgs with the set given, and returns the set. A portfolio in an account holds only that account's orgs. Sending the same set again, in any order, changes nothing.", "inputSchema": { "type": "object", "properties": { "portfolio_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-portfolio-id", "description": "The portfolio." }, "org_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id" }, "maxItems": 500, "uniqueItems": true, "description": "Every org the portfolio is to hold, and no others. An empty list empties it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "portfolio_id", "org_ids" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "portfolio_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-portfolio-id", "description": "The portfolio.", "x-data-class": "operational" }, "org_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id" }, "description": "Its orgs, sorted.", "x-data-class": "operational" } }, "required": [ "portfolio_id", "org_ids" ], "additionalProperties": false }, "annotations": { "title": "Set a portfolio's orgs", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_session_mode", "title": "Switch between live and test", "description": "Switches the caller's own session between live and test. In test, everything the session reads and writes is the org's test twin: the same members, roles, units and settings, and its own business data. Switching to test brings the twin in line with the live org first. Only admins and people with API key access may switch to test; anyone in test may switch back to live. Refused in test for an org with no twin. Setting the mode the session is already in changes nothing.", "inputSchema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live or test." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "mode" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "live", "test" ], "description": "The session's mode now.", "x-data-class": "operational" }, "org_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the session now acts in: the live org, or its twin in test. Null for a session that has selected no org.", "x-data-class": "operational" }, "live_org_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The live org, whose people these are.", "x-data-class": "operational" } }, "required": [ "mode", "org_id", "live_org_id" ], "additionalProperties": false }, "annotations": { "title": "Switch between live and test", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_session_policy", "title": "Set an org's session settings", "description": "Sets how long a session lasts in the org: signed out after idle_minutes without a request (15 to 1440) and after absolute_hours from sign-in whatever happens (1 to 168, 7 days being the most Trade HQ allows), whether a change to what someone may do signs them out (reauth_on_role_change), and whether a new sign-in signs the person's older sessions out (single_session). A session already past a new limit is signed out on its next request. Saving the settings already in effect changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose session settings to set." }, "idle_minutes": { "type": "integer", "minimum": 15, "maximum": 1440, "description": "Minutes without a request after which a session is signed out: 15 to 1440." }, "absolute_hours": { "type": "integer", "minimum": 1, "maximum": 168, "description": "Hours after sign-in after which a session is signed out whatever happens: 1 to 168." }, "reauth_on_role_change": { "type": "boolean", "description": "Whether a change to someone's role, units or template signs them out." }, "single_session": { "type": "boolean", "description": "Whether a new sign-in signs the person's older sessions out." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "idle_minutes", "absolute_hours", "reauth_on_role_change", "single_session" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "current": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "sso", "mfa", "session", "network", "drift" ] }, "policy": { "oneOf": [ { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "required": { "type": "boolean" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "domain", "required", "bypass_until" ], "additionalProperties": false } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "connection_id": { "type": "string" }, "jit": { "type": "boolean" }, "default_role_template": { "type": [ "string", "null" ] }, "idp_mfa_trusted": { "type": "boolean" }, "allow_manual_additions": { "type": "boolean" } }, "required": [ "connection_id", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions" ], "additionalProperties": false } } }, "required": [ "domains", "connections" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "required", "required_for_templates" ] }, "templates": { "type": "array", "items": { "type": "string" } }, "grace_days": { "type": "integer", "minimum": 0, "maximum": 30 }, "accept_idp_mfa": { "type": "boolean" } }, "required": [ "mode", "templates", "grace_days", "accept_idp_mfa" ], "additionalProperties": false }, { "type": "object", "properties": { "idle_minutes": { "type": "integer", "minimum": 15, "maximum": 1440 }, "absolute_hours": { "type": "integer", "minimum": 1, "maximum": 168 }, "reauth_on_role_change": { "type": "boolean" }, "single_session": { "type": "boolean" } }, "required": [ "idle_minutes", "absolute_hours", "reauth_on_role_change", "single_session" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "monitor", "enforce" ] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "cidr": { "type": "string" }, "label": { "type": "string" } }, "required": [ "cidr", "label" ], "additionalProperties": false } }, "applies_to": { "type": "string", "enum": [ "members", "api_keys", "both" ] } }, "required": [ "mode", "entries", "applies_to" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "quarantine", "alert_only" ] } }, "required": [ "action" ], "additionalProperties": false } ] }, "is_default": { "type": "boolean" }, "version": { "type": [ "integer", "null" ], "minimum": 1 }, "changed_by": { "type": [ "string", "null" ] }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "section", "policy", "is_default", "version", "changed_by", "changed_at" ], "additionalProperties": false, "description": "The session section as it now stands, with its version.", "x-data-class": "operational" } }, "required": [ "org_id", "current" ], "additionalProperties": false }, "annotations": { "title": "Set an org's session settings", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "set_sso_policy", "title": "Set an org's single sign-on settings", "description": "Sets the org's single sign-on settings for one connection and its domain: whether members at the domain must sign in through the connection (required), just-in-time membership on a first sign-in (jit) and the role template it gives (default_role_template, never the Owner), whether the IdP's MFA counts toward the org's MFA settings (idp_mfa_trusted), and allow_manual_additions. bypass \"start\" is the IdP-outage lever: for 24 hours members at the domain may use magic link and passkey again; only the account owner or an Owner may pull it, and \"end\" lifts it early. Inputs left out are left as they are.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org." }, "connection_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The connection, as list_sso_connections names it." }, "required": { "type": "boolean", "description": "Whether members at the connection's domain must sign in through it. Needs an active connection." }, "jit": { "type": "boolean", "description": "Whether a first sign-in through the connection makes the person a member." }, "default_role_template": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The role template a just-in-time member gets: a shipped template other than owner, or one of this org's own." }, "idp_mfa_trusted": { "type": "boolean", "description": "Whether the IdP's MFA counts toward this org's MFA settings." }, "allow_manual_additions": { "type": "boolean", "description": "Whether invites stay allowed for the domain while a directory manages it." }, "bypass": { "type": "string", "enum": [ "start", "end" ], "description": "start: allow magic link and passkey at the domain for 24 hours (the IdP-outage lever; account owner or Owner only). end: stop that early." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "connection_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "connection_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "Trade HQ's id for the connection.", "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 belongs to.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What the org's admins call it.", "x-data-class": "operational" }, "protocol": { "type": "string", "enum": [ "saml", "oidc" ], "description": "saml or oidc.", "x-data-class": "operational" }, "domain": { "type": "string", "description": "The verified email domain it serves.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "creating", "awaiting_metadata", "ready_to_test", "active", "deleting", "deleted" ], "description": "creating (Clerk has not answered yet), awaiting_metadata, ready_to_test, active, deleting or deleted.", "x-data-class": "operational" }, "active": { "type": "boolean", "description": "Whether people sign in through it.", "x-data-class": "operational" }, "acs_url": { "type": [ "string", "null" ], "description": "The service provider's ACS URL, for the IdP admin; null until Clerk has answered.", "x-data-class": "operational" }, "sp_entity_id": { "type": [ "string", "null" ], "description": "The service provider's entity id, for the IdP admin; null until Clerk has answered.", "x-data-class": "operational" }, "sp_metadata_url": { "type": [ "string", "null" ], "description": "The service provider's metadata URL; null until Clerk has answered.", "x-data-class": "operational" }, "idp_metadata_url": { "type": [ "string", "null" ], "description": "The IdP metadata URL saved, if a URL was.", "x-data-class": "operational" }, "has_idp_metadata": { "type": "boolean", "description": "Whether IdP metadata is saved, as a URL or as uploaded XML.", "x-data-class": "operational" }, "required": { "type": "boolean", "description": "Whether members at its domain must sign in through it.", "x-data-class": "operational" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time", "description": "While the outage lever holds, when it ends; null otherwise.", "x-data-class": "operational" }, "jit": { "type": "boolean", "description": "Whether a first sign-in through it makes the person a member.", "x-data-class": "operational" }, "default_role_template": { "type": [ "string", "null" ], "description": "The role template a just-in-time member gets.", "x-data-class": "operational" }, "idp_mfa_trusted": { "type": "boolean", "description": "Whether the IdP's MFA counts toward the org's MFA settings.", "x-data-class": "operational" }, "allow_manual_additions": { "type": "boolean", "description": "Whether invites stay allowed for its domain while a directory manages it (TRA-486).", "x-data-class": "operational" }, "last_sign_in_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The last sign-in through it.", "x-data-class": "operational" }, "idp_certificate_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the IdP's signing certificate expires, once known.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was added.", "x-data-class": "operational" }, "caller_may_bypass": { "type": "boolean", "description": "Whether the caller may pull the outage lever: the account owner, or the Owner role template in the org.", "x-data-class": "operational" } }, "required": [ "connection_id", "org_id", "name", "protocol", "domain", "status", "active", "acs_url", "sp_entity_id", "sp_metadata_url", "idp_metadata_url", "has_idp_metadata", "required", "bypass_until", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions", "last_sign_in_at", "idp_certificate_expires_at", "created_at", "caller_may_bypass" ], "additionalProperties": false }, "annotations": { "title": "Set an org's single sign-on settings", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "share_view", "title": "Share a saved view", "description": "Shares a saved view of the caller's: with named teammates (user_ids, each a member of the org), with the org (with_org), or both. The call is the whole audience and replaces what stood; nobody named and with_org false makes it private again. Whoever opens a shared view runs its call under their own permissions, never the owner's, so it shows them nothing they could not read themselves. Only the owner shares a view (view_not_yours).", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the view is in." }, "view_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The view to share: one of the caller's own." }, "with_org": { "type": "boolean", "description": "Whether every member of the org reads it." }, "user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id" }, "maxItems": 100, "uniqueItems": true, "description": "The teammates who read it by name, as user ids; empty for nobody by name." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "view_id", "with_org", "user_ids" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "view_id": { "type": "string", "description": "The view: a UUID, or system: for a system view.", "x-data-class": "operational" }, "capability": { "type": "string", "enum": [ "list_inventory", "summarize_catalog", "list_catalog" ], "description": "The list capability it calls.", "x-data-class": "operational" }, "mode": { "type": [ "string", "null" ], "enum": [ "inventory", "sales", "sales_lines", null ], "description": "inventory: a grid of units. sales: a Sales catalog view, the grouped read with its split_by, source slice and layout. sales_lines: the sales grid's line table, a list_catalog call. Null only for a capability in no mode, which every_savable_capability_is_in_exactly_one_mode holds never happens.", "x-data-class": "operational" }, "contract": { "type": "string", "description": "The capability's contract and the stored call's version, @.", "x-data-class": "operational" }, "args": { "type": "object", "properties": { "filters": { "type": "object", "description": "The list's filters input, as the capability declares it." }, "q": { "type": "string", "description": "The list's q input." }, "sort": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "key": { "type": "string", "description": "One of the called capability's sort keys." }, "dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Leave out for the key's own direction." } }, "required": [ "key" ], "additionalProperties": false }, "description": "The list's sort input: one key and its direction." }, "fields": { "type": "array", "items": { "type": "string" }, "description": "The list's fields input." }, "limit": { "type": "integer", "description": "The list's limit input." }, "split_by": { "type": "array", "items": { "type": "string" }, "description": "A Sales catalog view's split_by, in the order the attributes were switched on (summarize_catalog's input)." }, "slice": { "type": "string", "enum": [ "owned", "partner", "supplier", "all" ], "description": "A Sales catalog view's source slice: owned, partner, supplier or all." }, "layout": { "type": "string", "enum": [ "cards", "rows" ], "description": "A Sales catalog view's layout: cards or rows." } }, "additionalProperties": false, "description": "The call's arguments: filters, q, sort, fields and limit, as given.", "x-data-class": "operational" }, "title": { "type": "string", "description": "What it is called.", "x-data-class": "operational" }, "pinned": { "type": "boolean", "description": "Whether it is pinned to the top.", "x-data-class": "operational" }, "visibility": { "type": "string", "enum": [ "private", "org-read", "org-write" ], "description": "private: its owner alone. org-read: every member reads it. org-write: every member reads, changes and deletes it. A system view is org-read.", "x-data-class": "operational" }, "system": { "type": "boolean", "description": "A system view: declared for every org, never changed.", "x-data-class": "operational" }, "owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who saved it; null for a system view and for a moved view whose owner is gone.", "x-data-class": "operational" }, "writable": { "type": "boolean", "description": "Whether the caller may change or delete it.", "x-data-class": "operational" }, "unmapped": { "type": "array", "items": { "type": "string" }, "description": "What of an older saved search the call could not carry, each as field: why. Empty for a view saved as a call.", "x-data-class": "operational" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it last changed; null for a system view.", "x-data-class": "operational" }, "shared_with": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "format": "tradehq-user-id", "description": "The teammate it is shared with." }, "shared_by": { "type": "string", "format": "tradehq-user-id", "description": "Who shared it: its owner." }, "created_at": { "type": "string", "format": "date-time", "description": "When." } }, "required": [ "user_id", "shared_by", "created_at" ], "additionalProperties": false }, "description": "The teammates its owner shared it with by name, each {user_id, shared_by, created_at}, by user id. Empty for a system view.", "x-data-class": "operational" }, "pins": { "type": "array", "items": { "type": "object", "properties": { "tab": { "type": "string", "enum": [ "depots", "sell", "source", "intel" ], "description": "The tab whose Home shows it." }, "for": { "type": "string", "enum": [ "me", "everyone" ], "description": "me: the caller's own pin. everyone: an org admin's, on every member's Home." }, "user_id": { "type": [ "string", "null" ], "format": "tradehq-user-id", "description": "The caller, on their own pin; null on the org's." }, "pinned_by": { "type": "string", "format": "tradehq-user-id", "description": "Who pinned it: the caller, or the org admin who pinned it for everyone." }, "created_at": { "type": "string", "format": "date-time", "description": "When." } }, "required": [ "tab", "for", "user_id", "pinned_by", "created_at" ], "additionalProperties": false }, "description": "Where it is pinned for the caller, by tab: their own pins (for me) and the org's (for everyone, an org admin's). Empty for a system view.", "x-data-class": "operational" } }, "required": [ "view_id", "capability", "mode", "contract", "args", "title", "pinned", "visibility", "system", "owner_user_id", "writable", "unmapped", "updated_at", "shared_with", "pins" ], "additionalProperties": false }, "annotations": { "title": "Share a saved view", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "step_back_flag", "title": "Roll a flag back one wave", "description": "Moves one registered feature flag one wave down in PostHog: from everyone to 50% of customer orgs, then 25%, 10%, the beta lists, staff, and off. Name the wave you saw; if the flag has moved since, nothing changes. Refused for a flag already off or not in PostHog (nothing is below it) and for one with a rule made in PostHog. Each move is recorded with who made it. Send an Idempotency-Key header. Staff only.", "inputSchema": { "type": "object", "properties": { "flag_key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The flag's key, as the registry has it." }, "from": { "type": "string", "enum": [ "absent", "off", "staff", "beta", "orgs_10", "orgs_25", "orgs_50", "everyone", "custom" ], "description": "The wave you saw the flag on (list_flags' wave). If PostHog has it anywhere else, nothing changes." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "flag_key", "from" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "action_id": { "type": "string", "description": "This move's audit row.", "x-data-class": "operational" }, "flag_key": { "type": "string", "description": "The flag moved.", "x-data-class": "operational" }, "action": { "type": "string", "enum": [ "advance", "roll_back", "set_lists" ], "description": "advance, roll_back, or set_lists (TRA-1461: the beta lists chosen).", "x-data-class": "operational" }, "from_wave": { "type": "string", "description": "The wave PostHog had it on.", "x-data-class": "operational" }, "to_wave": { "type": "string", "description": "The wave it is on now.", "x-data-class": "operational" }, "acted_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who moved it: the staff member or agent, never PostHog's key.", "x-data-class": "operational" }, "acted_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" }, "posthog_url": { "type": [ "string", "null" ], "description": "The flag in PostHog; null on a replay.", "x-data-class": "operational" } }, "required": [ "action_id", "flag_key", "action", "from_wave", "to_wave", "acted_by", "acted_at", "posthog_url" ], "additionalProperties": false }, "annotations": { "title": "Roll a flag back one wave", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "submit_serial_batch", "title": "Submit unit numbers against a confirmed purchase order", "description": "For the supplier of an org's purchase order that it has confirmed: sends the ISO 6346 unit numbers of the containers it is supplying. Every number's check digit is validated before any is accepted. The numbers go onto the confirmation's staged rows in the buyer's PO ingest, filling its lines in order, so the buyer's apply creates each container with its number. Refused once the buyer has applied the confirmation, for a unit already submitted, and for more units than the confirmation has left to number.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org that owns the purchase order: the buyer." }, "document_kind": { "type": "string", "enum": [ "asset_intake", "order" ], "description": "asset_intake: a purchase order. An order is refused." }, "document_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The purchase order's id." }, "unit_numbers": { "type": "array", "minItems": 1, "maxItems": 500, "uniqueItems": true, "items": { "type": "string", "pattern": "^[ \\t\\n\\f\\r]*[A-Za-z]{3}[UJZujz][0-9]{7}[ \\t\\n\\f\\r]*$", "format": "iso6346", "description": "Trimmed and upper-cased, then held to ISO 6346 with its check digit; two items that are one unit in different case are refused as a repeat." }, "description": "The unit numbers, in the order to fill the confirmation's lines: each ISO 6346, owner code, category, serial and check digit. Either case is accepted and stored upper case; one unit twice, in any case, is refused." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "document_kind", "document_id", "unit_numbers" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "post_id": { "type": "string", "description": "The batch.", "x-data-class": "operational" }, "unit_number": { "type": "string", "description": "One unit number, accepted.", "x-data-class": "operational" }, "ingest_row_id": { "type": "string", "description": "The staged ingest_purchase_orders row that now carries it.", "x-data-class": "operational" }, "ingest_document_id": { "type": "string", "description": "The confirmation's ingest document.", "x-data-class": "operational" } }, "required": [ "post_id", "unit_number", "ingest_row_id", "ingest_document_id" ], "additionalProperties": false } }, "next_after": { "type": [ "string", "null" ], "description": "Pass as `after` for the next page; null on the last one." } }, "required": [ "items", "next_after" ], "additionalProperties": false }, "annotations": { "title": "Submit unit numbers against a confirmed purchase order", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "subscribe_audit", "title": "Subscribe to an org's audit log", "description": "Subscribes an email digest or a Slack incoming webhook to an org's audit log, or changes or disables that subscription. alerts_only narrows it to the admin activity alerts: a new admin, an SSO change, an API key created. A digest is sent hourly or daily with counts only; Slack gets one message per event with ids and names only. One destination is one subscription, so subscribing it again changes it; enabled false turns it off. The Slack webhook URL is never returned.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose audit log is subscribed to." }, "channel": { "type": "string", "enum": [ "digest", "slack" ], "description": "digest: an email summary through Resend. slack: a Slack incoming webhook." }, "destination": { "type": "string", "minLength": 3, "maxLength": 512, "description": "For digest, the one email address. For slack, the incoming webhook URL, https://hooks.slack.com/services/..." }, "alerts_only": { "type": "boolean", "description": "Only the admin activity alerts (default false: every audit event of the org)." }, "cadence": { "type": "string", "enum": [ "hourly", "daily" ], "description": "Digest only: hourly (the default) or daily." }, "enabled": { "type": "boolean", "description": "false turns the subscription off (default true)." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "channel", "destination" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "The subscription'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.", "x-data-class": "operational" }, "channel": { "type": "string", "enum": [ "digest", "slack" ], "description": "digest or slack.", "x-data-class": "operational" }, "destination": { "anyOf": [ { "type": "string" }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The email address for a digest; for Slack, only the host, because the webhook URL is a credential.", "x-data-class": "personal" }, "alerts_only": { "type": "boolean", "description": "Whether only admin activity alerts are sent.", "x-data-class": "operational" }, "cadence": { "type": [ "string", "null" ], "enum": [ "hourly", "daily", null ], "description": "A digest's cadence; null for Slack, which posts each event as it is recorded.", "x-data-class": "operational" }, "enabled": { "type": "boolean", "description": "Whether it sends.", "x-data-class": "operational" } }, "required": [ "subscription_id", "org_id", "channel", "destination", "alerts_only", "cadence", "enabled" ], "additionalProperties": false }, "annotations": { "title": "Subscribe to an org's audit log", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "summarize_catalog", "title": "Summarize catalog", "description": "Counts an org's sales catalog lines matching the same filters list_catalog takes, and sums their unit counts: total, available, reserved, secured, pending, available and secured, available and pending. Then groups every one of those lines, never one page, by market, size, type and condition, split by split_by in its order: each group and split with its lines, catalog ids, counts and counts per value of every attribute not split, and its Wholesale and Retail min, max and avg.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose catalog it is." }, "filters": { "type": "object", "properties": { "market": { "type": "string", "minLength": 1, "maxLength": 128, "format": "tradehq-market", "x-filter-kind": "id_reference", "description": "A place equipment sits at, is priced from, or moves between. Availability and price are location-qualified everywhere in the trade (\"what's available where at what cost\"), which makes Location a first-class dimension of every sub-domain rather than an attribute of any one of them. A Depot is a facility at a Location; cities, regions, and ports are Locations without being facilities." }, "depot": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^Y[0-9A-Za-z]{1,18}$", "format": "tradehq-depot-id", "x-filter-kind": "id_reference", "description": "A facility that stores, handles, inspects, and repairs containers: the physical node of the operations clearinghouse. Carries fee schedules and rates, generates gate-in and gate-out events, and holds inventory whose states the depot sub-domain defines. Trade HQ's schema calls this a yard; the industry says depot; both names are attested and kept. Industry-wide, a depot is identified by a BIC Facility Code, a nine-character child code of the UN/LOCODE." }, "size": { "type": "array", "items": { "type": "string", "enum": [ "10", "20", "40", "45", "53" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Nominal container lengths in feet as traded: 10, 20, 40, 45, 53. A convention: the set differs by market (53ft is North American domestic), and TEU arithmetic is derived from it, not stored on it." }, "type": { "type": "array", "items": { "type": "string", "enum": [ "std", "hc", "stddd", "hcdd", "stdos", "hcos", "hcos2dr", "hcos4dr", "stdot", "hcot", "stdrf", "hcrf", "fr", "duocon" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The construction-type vocabulary for containers: standard, high cube, open top, open side, double door, flat rack, reefer, and combinations. These are Trade HQ's internal codes with practitioner definitions; they are not ISO 6346 size-type codes, and the mapping to ISO is an open question (OQ-003)." }, "condition": { "type": "array", "items": { "type": "string", "enum": [ "new", "cw", "wwt", "asis", "iicl", "reefer-pti", "reefer-nopti", "reefer-broken", "twotrip" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The condition ladder used to grade a container's state for sale or lease. A convention, not an axiom: the ladder and its labels vary by sub-market and era, so the ontology records the attested set without hard-coding order." }, "availability": { "type": "array", "items": { "type": "string", "enum": [ "available" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The commercial-availability half of inventory state: whether the holder will offer a unit right now. Seat-relative by nature, a lessor's available and a trader's available are different judgments over the same box, which is why availability is the holder's tenant-private call expressed in this canonical vocabulary rather than a physical fact." }, "color": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 50, "uniqueItems": true, "x-filter-kind": "text_set", "description": "The container's colour, as recorded: any of the values given." }, "forklift_pockets": { "type": "array", "items": { "type": "boolean" }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "x-filter-kind": "boolean_set", "description": "Whether the containers have forklift pockets: true, false, or both for any line that records it." }, "lockbox": { "type": "array", "items": { "type": "boolean" }, "minItems": 1, "maxItems": 2, "uniqueItems": true, "x-filter-kind": "boolean_set", "description": "Whether the containers have a lockbox: true, false, or both for any line that records it." }, "vents": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 50, "uniqueItems": true, "x-filter-kind": "text_set", "description": "The containers' vents, as recorded: any of the values given." }, "handles": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 50, "uniqueItems": true, "x-filter-kind": "text_set", "description": "The containers' door handles, as recorded: any of the values given." }, "repair_state": { "type": "array", "items": { "type": "string", "enum": [ "undamaged", "awaiting-estimate", "pending-approval", "pending-repair", "repaired", "unrepairable", "damaged-not-repaired" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Where a unit stands in maintenance and repair: undamaged, damaged and waiting on an estimate, an estimate waiting on approval, approved and waiting on the repair, repaired, or damaged and not to be repaired. A dimension apart from ConditionGrade: a grade names the criteria a unit meets, a repair state names the work outstanding against it. The filter term repair_state in the list capabilities." }, "wholesale_price": { "type": "object", "properties": { "min": { "type": "string", "pattern": "^\\s*[0-9]{1,11}(\\.[0-9]{1,4})?\\s*$", "description": "The least value included, a decimal of at most four places." }, "max": { "type": "string", "pattern": "^\\s*[0-9]{1,11}(\\.[0-9]{1,4})?\\s*$", "description": "The greatest value included, a decimal of at most four places." } }, "minProperties": 1, "additionalProperties": false, "x-filter-kind": "decimal_range", "description": "The line's Wholesale (suggested) price, between min and max inclusive; a line with no Wholesale is not selected." } }, "additionalProperties": false, "minProperties": 1, "x-combine": "and", "description": "Lines matching every term given." }, "split_by": { "type": "array", "items": { "type": "string", "enum": [ "color", "forklift_pockets", "lockbox", "vents", "handles", "depot", "source", "damage" ] }, "uniqueItems": true, "maxItems": 8, "description": "The attributes the groups split by, nested in this order (the order they were switched on): any of color, forklift_pockets, lockbox, vents, handles, depot, source and damage, each once. None when left out." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "The lines matching the filters.", "x-data-class": "operational" }, "total_count": { "type": "integer", "minimum": 0, "description": "Their units, summed.", "x-data-class": "operational" }, "available_count": { "type": "integer", "minimum": 0, "description": "Their units available to sell, summed.", "x-data-class": "operational" }, "reserved_count": { "type": "integer", "minimum": 0, "description": "Their units reserved, summed.", "x-data-class": "operational" }, "secured_count": { "type": "integer", "minimum": 0, "description": "Their units secured, summed.", "x-data-class": "operational" }, "pending_count": { "type": "integer", "minimum": 0, "description": "Their units pending, summed.", "x-data-class": "operational" }, "available_secured_count": { "type": "integer", "minimum": 0, "description": "Their units available and secured, summed.", "x-data-class": "operational" }, "available_pending_count": { "type": "integer", "minimum": 0, "description": "Their units available and pending, summed.", "x-data-class": "operational" }, "split_by": { "type": "array", "items": { "type": "string" }, "description": "The attributes the groups split by, in the order they nest: the split_by given, or none.", "x-data-class": "operational" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "lines": { "type": "integer", "minimum": 0 }, "catalog_ids": { "type": "array", "items": { "type": "string" } }, "total_count": { "type": "integer", "minimum": 0 }, "available_count": { "type": "integer", "minimum": 0 }, "reserved_count": { "type": "integer", "minimum": 0 }, "secured_count": { "type": "integer", "minimum": 0 }, "pending_count": { "type": "integer", "minimum": 0 }, "available_secured_count": { "type": "integer", "minimum": 0 }, "available_pending_count": { "type": "integer", "minimum": 0 }, "photo": { "type": [ "object", "null" ], "properties": { "photo_id": { "type": "string" }, "container": { "type": "string" }, "taken_at": { "type": "string" } }, "required": [ "photo_id", "container", "taken_at" ], "additionalProperties": false }, "values": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": [ "string", "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "lines": { "type": "integer", "minimum": 0 }, "available_count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "name", "lines", "available_count" ], "additionalProperties": false } } }, "market": { "type": [ "string", "null" ] }, "size": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "condition": { "type": [ "string", "null" ] }, "splits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "lines": { "type": "integer", "minimum": 0 }, "catalog_ids": { "type": "array", "items": { "type": "string" } }, "total_count": { "type": "integer", "minimum": 0 }, "available_count": { "type": "integer", "minimum": 0 }, "reserved_count": { "type": "integer", "minimum": 0 }, "secured_count": { "type": "integer", "minimum": 0 }, "pending_count": { "type": "integer", "minimum": 0 }, "available_secured_count": { "type": "integer", "minimum": 0 }, "available_pending_count": { "type": "integer", "minimum": 0 }, "photo": { "type": [ "object", "null" ], "properties": { "photo_id": { "type": "string" }, "container": { "type": "string" }, "taken_at": { "type": "string" } }, "required": [ "photo_id", "container", "taken_at" ], "additionalProperties": false }, "values": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": [ "string", "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "lines": { "type": "integer", "minimum": 0 }, "available_count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "name", "lines", "available_count" ], "additionalProperties": false } } }, "attribute": { "type": "string", "enum": [ "color", "forklift_pockets", "lockbox", "vents", "handles", "depot", "source", "damage" ] }, "value": { "type": [ "string", "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "splits": { "type": "array", "items": { "type": "object" } } }, "required": [ "id", "lines", "catalog_ids", "total_count", "available_count", "reserved_count", "secured_count", "pending_count", "available_secured_count", "available_pending_count", "photo", "values", "attribute", "value", "name", "splits" ] } } }, "required": [ "id", "lines", "catalog_ids", "total_count", "available_count", "reserved_count", "secured_count", "pending_count", "available_secured_count", "available_pending_count", "photo", "values", "market", "size", "type", "condition", "splits" ] }, "description": "Every line the filters select, grouped by market, size, type and condition, ordered by those four (nulls last). Each group: id, market, size, type, condition, lines, catalog_ids (distinct, sorted), the seven counts summed under their list names (landed is available_secured_count, incoming available_pending_count), values (for every attribute not in split_by, its values with lines and available_count each, most available first; a depot's carries its name) and splits (the first split_by attribute's values, ordered by value, false before true, nulls last; each split: id, attribute, value, name, the same counts, values and its own splits by the next attribute, empty on the last). Every group and split carries photo: one real yard photo of a unit on its lines ({photo_id, container, taken_at}; a sound unit before a damaged one, then the newest, never one an org admin hid), or null when none of its units has one.", "x-data-class": "operational" }, "prices": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "wholesale": { "type": "object", "properties": { "min": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+\\.[0-9]{4}$" }, "max": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+\\.[0-9]{4}$" }, "avg": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+\\.[0-9]{4}$" }, "lines": { "type": "integer", "minimum": 0 } }, "required": [ "min", "max", "avg", "lines" ], "additionalProperties": false }, "retail": { "type": "object", "properties": { "min": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+\\.[0-9]{4}$" }, "max": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+\\.[0-9]{4}$" }, "avg": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+\\.[0-9]{4}$" }, "lines": { "type": "integer", "minimum": 0 } }, "required": [ "min", "max", "avg", "lines" ], "additionalProperties": false } }, "required": [ "id", "wholesale", "retail" ], "additionalProperties": false } }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "One entry per group and split, by its id: wholesale (suggested_price) and retail (retail_price), each min, max and avg (the unweighted mean over the lines that carry that price, rounded half away from zero) as 4-place decimal strings, and the lines priced. A price no line carries is null; the from price is min.", "x-data-class": "commercial" } }, "required": [ "total", "total_count", "available_count", "reserved_count", "secured_count", "pending_count", "available_secured_count", "available_pending_count", "split_by", "groups", "prices" ], "additionalProperties": false }, "annotations": { "title": "Summarize catalog", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "summarize_inventory", "title": "Summarize inventory", "description": "Counts an org's units matching the same filters and q list_inventory takes (with no acquisition filter, units pending or acquired), and answers the lowest, highest and average total cost among them, and their lanes: units by origin market and destination market with the median transit days.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose inventory it is." }, "filters": { "type": "object", "properties": { "acquisition": { "type": "array", "items": { "type": "string", "enum": [ "pending", "acquired", "cancelled" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The acquisition half of inventory state: whether the holder is still buying a unit, has it, or will not get it. The third dimension of InventoryState beside availability and custody, by Sage's decision of 2026-10-05, so that units being bought sit in the same lists as units held. Cancelled is terminal and leaves no holder state: a cancelled unit has no availability and no custody." }, "availability": { "type": "array", "items": { "type": "string", "enum": [ "available", "committed", "withdrawn" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The commercial-availability half of inventory state: whether the holder will offer a unit right now. Seat-relative by nature, a lessor's available and a trader's available are different judgments over the same box, which is why availability is the holder's tenant-private call expressed in this canonical vocabulary rather than a physical fact." }, "custody": { "type": "array", "items": { "type": "string", "enum": [ "in-depot", "on-hire", "disposed", "in-transit" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The physical-and-contractual half of inventory state: where a unit sits and under whose control. Closer to fact than judgment: in-depot is derivable from gate-event pairs, on-hire from lease commitments, disposed from exits. Every seat reads these the same way, which is what separates custody from availability." }, "depot": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^Y[0-9A-Za-z]{1,18}$", "format": "tradehq-depot-id", "x-filter-kind": "id_reference", "description": "A facility that stores, handles, inspects, and repairs containers: the physical node of the operations clearinghouse. Carries fee schedules and rates, generates gate-in and gate-out events, and holds inventory whose states the depot sub-domain defines. Trade HQ's schema calls this a yard; the industry says depot; both names are attested and kept. Industry-wide, a depot is identified by a BIC Facility Code, a nine-character child code of the UN/LOCODE." }, "size": { "type": "array", "items": { "type": "string", "enum": [ "10", "20", "40", "45", "53" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Nominal container lengths in feet as traded: 10, 20, 40, 45, 53. A convention: the set differs by market (53ft is North American domestic), and TEU arithmetic is derived from it, not stored on it." }, "type": { "type": "array", "items": { "type": "string", "enum": [ "std", "hc", "stddd", "hcdd", "stdos", "hcos", "hcos2dr", "hcos4dr", "stdot", "hcot", "stdrf", "hcrf", "fr", "duocon" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The construction-type vocabulary for containers: standard, high cube, open top, open side, double door, flat rack, reefer, and combinations. These are Trade HQ's internal codes with practitioner definitions; they are not ISO 6346 size-type codes, and the mapping to ISO is an open question (OQ-003)." }, "condition": { "type": "array", "items": { "type": "string", "enum": [ "new", "cw", "wwt", "asis", "iicl", "reefer-pti", "reefer-nopti", "reefer-broken", "twotrip" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The condition ladder used to grade a container's state for sale or lease. A convention, not an axiom: the ladder and its labels vary by sub-market and era, so the ontology records the attested set without hard-coding order." }, "in_depot_since": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "The day the unit's most recent residency began: a range of days, or true for a unit that has been gated in and false for one that never has." }, "gated_out": { "type": "boolean", "x-filter-kind": "presence", "description": "True: the unit's most recent residency has ended. False: it has not, so the unit is still in the depot or has never been gated in." }, "acquisition_channel": { "type": "array", "items": { "type": "string", "enum": [ "direct", "gate-buy", "yard-buy", "consignment", "factory-direct", "inland-transfer", "open-inventory" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "How a holder sources a unit: bought direct, bought in transit to a customer (gate buy), bought where it sits in a supplier's yard (yard buy), taken on consignment, bought from the factory, transferred in from a supplier's depot account, or listed as open inventory before any unit lands. One half of today's purchase_order_type, split by Sage's decision of 2026-10-05; the other half is HoldingBasis." }, "holding_basis": { "type": "array", "items": { "type": "string", "enum": [ "owned", "leased-in", "subleased" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The basis on which a holder holds an acquired unit: it owns it, it leases it in from a supplier, or it leases it in and lets it on to a customer. The other half of today's purchase_order_type, split by Sage's decision of 2026-10-05, read together with steward_type. Instrument's two forms as they apply to the holder's own stock: ownership follows a sale, leased-in and subleased follow a lease." }, "vendor_bill_paid": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "When the holder paid the vendor's bill for the unit: a range of days, or true for paid and false for not paid." }, "vendor_eta": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "The day the vendor expects to deliver the unit: a range of days, or true for a unit with an ETA and false for one without." }, "origin_market": { "type": "string", "minLength": 1, "maxLength": 128, "format": "tradehq-market", "x-filter-kind": "id_reference", "description": "The market the unit's most recent purchase order picks it up in, its origin, as the purchase order names it (for example Charlotte, NC): matched exactly." }, "origin_depot": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^Y[0-9A-Za-z]{1,18}$", "format": "tradehq-depot-id", "x-filter-kind": "id_reference", "description": "The depot the unit's most recent purchase order picks it up at, its origin depot." }, "pickup_date": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "The day the unit's most recent purchase order picks it up at its origin, the P/U Date: a range of days, or true for a unit with one and false for one without." }, "transit_days": { "type": "object", "properties": { "from": { "type": "integer", "minimum": -3650, "maximum": 3650, "description": "The lowest value included." }, "to": { "type": "integer", "minimum": -3650, "maximum": 3650, "description": "The highest value included." } }, "minProperties": 1, "additionalProperties": false, "x-filter-kind": "int_range", "description": "Days from the unit's P/U Date to its vendor ETA: a range of whole days, inclusive. A unit missing either date has no transit days and matches no range; a negative number is an ETA before the P/U Date." }, "repair_state": { "type": "array", "items": { "type": "string", "enum": [ "undamaged", "awaiting-estimate", "pending-approval", "pending-repair", "repaired", "unrepairable", "damaged-not-repaired" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Where a unit stands in maintenance and repair: undamaged, damaged and waiting on an estimate, an estimate waiting on approval, approved and waiting on the repair, repaired, or damaged and not to be repaired. A dimension apart from ConditionGrade: a grade names the criteria a unit meets, a repair state names the work outstanding against it. The filter term repair_state in the list capabilities." }, "customer": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^CT[0-9A-Za-z]{1,18}$", "format": "tradehq-contact-id", "x-filter-kind": "id_reference", "description": "The customer contact on the unit's most recent order." }, "vendor": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^CT[0-9A-Za-z]{1,18}$", "format": "tradehq-contact-id", "x-filter-kind": "id_reference", "description": "The vendor contact the holder acquired the unit from." }, "tag": { "type": "string", "minLength": 1, "maxLength": 64, "format": "tradehq-org-tag", "x-filter-kind": "id_reference", "description": "One of the org's tags: units carrying it." } }, "additionalProperties": false, "minProperties": 1, "x-combine": "and", "description": "Units matching every term given. With no acquisition term, units pending or acquired." }, "q": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The start of a BIC number, booking number, release booking number, intake id, vendor bill id or invoice number." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "The units matching the filters.", "x-data-class": "operational" }, "total_cost_min": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The lowest total cost among them in USD, as a decimal string; null when none carries one.", "x-data-class": "commercial" }, "total_cost_max": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The highest, as a decimal string.", "x-data-class": "commercial" }, "total_cost_avg": { "anyOf": [ { "type": [ "string", "null" ] }, { "const": "•••", "description": "Masked by the caller's data policy." }, { "type": "null", "description": "Denied by the caller's data policy." } ], "description": "The average, to four places, as a decimal string.", "x-data-class": "commercial" }, "lanes": { "type": "array", "items": { "type": "object", "properties": { "origin_market": { "type": "string", "description": "Where the lane's units are picked up." }, "destination_market": { "type": "string", "description": "The market they are bought into." }, "units": { "type": "integer", "minimum": 1, "description": "The units on the lane." }, "purchase_orders": { "type": "integer", "minimum": 0, "description": "The purchase orders on the lane with a P/U Date and an ETA: the sample the median reads." }, "median_transit_days": { "type": [ "integer", "null" ], "description": "The median of those purchase orders' transit days, in whole days; null below three purchase orders." } }, "required": [ "origin_market", "destination_market", "units", "purchase_orders", "median_transit_days" ], "additionalProperties": false }, "description": "The units by lane, an origin market and a destination market, most units first and at most 100: each lane's unit count, and the median transit days (P/U Date to vendor ETA) over its purchase orders, null below three purchase orders. A unit with no origin or no destination market is on no lane.", "x-data-class": "operational" } }, "required": [ "total", "total_cost_min", "total_cost_max", "total_cost_avg", "lanes" ], "additionalProperties": false }, "annotations": { "title": "Summarize inventory", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "summarize_purchase_orders", "title": "Summarize purchase orders", "description": "Counts an org's purchase orders matching the same filters and q list_purchase_orders takes, sums their containers and landed containers, and answers the median transit days from P/U Date to ETA over those that have both.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose purchase orders they are." }, "filters": { "type": "object", "properties": { "vendor": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^CT[0-9A-Za-z]{1,18}$", "format": "tradehq-contact-id", "x-filter-kind": "id_reference", "description": "The supplier contact the purchase order buys from." }, "origin_market": { "type": "string", "minLength": 1, "maxLength": 128, "format": "tradehq-market", "x-filter-kind": "id_reference", "description": "The market the purchase order's containers come from: the supplier's nearest port or metro, as recorded." }, "destination_market": { "type": "string", "minLength": 1, "maxLength": 128, "format": "tradehq-market", "x-filter-kind": "id_reference", "description": "The market the purchase order's containers are delivered to, as recorded." }, "pickup_date": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "The day the containers are picked up at the origin (P/U Date): a range of days, or true for a purchase order with one and false for one without." }, "vendor_eta": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false }, { "type": "boolean", "description": "True: the date is set. False: it is empty." } ], "x-filter-kind": "date_range", "description": "The day the supplier expects the containers to arrive for gate-in at the destination: a range of days, or true for a purchase order with an ETA and false for one without." }, "acquisition_channel": { "type": "array", "items": { "type": "string", "enum": [ "direct", "gate-buy", "yard-buy", "consignment", "factory-direct", "inland-transfer", "open-inventory" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "How a holder sources a unit: bought direct, bought in transit to a customer (gate buy), bought where it sits in a supplier's yard (yard buy), taken on consignment, bought from the factory, transferred in from a supplier's depot account, or listed as open inventory before any unit lands. One half of today's purchase_order_type, split by Sage's decision of 2026-10-05; the other half is HoldingBasis." }, "inventory_type": { "type": "array", "items": { "type": "string", "enum": [ "direct", "factory-direct-purchase", "yard-buy", "inland-yard-transfer", "gate-buy", "consignment", "lease", "sublease", "open-inventory", "open-inventory-landed" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "The purchase order's type as recorded, the Procure list's Inventory Type: direct, factory direct purchase, yard buy, inland yard transfer, gate buy, consignment, lease, sublease, open inventory, or open inventory landed." }, "purchase_order_status": { "type": "array", "items": { "type": "string", "enum": [ "pending", "in-progress", "completed", "cancelled" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Where the purchase order stands: pending, in progress (partly filled), completed or cancelled (voided)." } }, "additionalProperties": false, "minProperties": 1, "x-combine": "and", "description": "Purchase orders matching every term given." }, "q": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The start of a purchase order number, a unit number on it or a supplier bill on it, case ignored." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "The purchase orders matching the filters.", "x-data-class": "operational" }, "container_count": { "type": "integer", "minimum": 0, "description": "Their containers, summed, not counting cancelled ones.", "x-data-class": "operational" }, "landed_count": { "type": "integer", "minimum": 0, "description": "Of those, the ones no longer pending, summed.", "x-data-class": "operational" }, "median_transit_days": { "type": [ "integer", "null" ], "description": "The median days from P/U Date to ETA over those that have both; null when none does.", "x-data-class": "operational" } }, "required": [ "total", "container_count", "landed_count", "median_transit_days" ], "additionalProperties": false }, "annotations": { "title": "Summarize purchase orders", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "summarize_reports", "title": "Summarize customer reports", "description": "Counts the customer reports list_reports lists for the same org_id, account_id, filters and q, reported within period (days, Pacific time; every day when left out): how many, how many stand in each status, and the median calendar days from reported to fixed and to Trade HQ's first response. A private report counts in the org's numbers, without its title, unless the count is narrowed by reporter, following, unread, private or q.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "One org's reports. A member names their own org; staff and an account owner may leave it out for every org they reach." }, "account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "format": "tradehq-account-id", "description": "One account's orgs. An account owner may name only an account they own." }, "filters": { "type": "object", "properties": { "status": { "type": "array", "items": { "type": "string", "enum": [ "received", "waiting_on_you", "planned", "fixed", "answered", "wont_fix", "duplicate" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "Where the report stands in plain words: received, waiting on you, planned, fixed, answered, won't fix or duplicate, derived from its ticket in the support tracker and never set by hand." }, "kind": { "type": "array", "items": { "type": "string", "enum": [ "feedback", "problem", "question" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "What the report is about: feedback on the product, a problem that stops or slows the reporter, or a question about how to do something." }, "filed_via": { "type": "array", "items": { "type": "string", "enum": [ "app", "email", "staff" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "How the report reached the support team: in the app, by email to the support address, or filed by staff for the customer." }, "impact": { "type": "array", "items": { "type": "string", "enum": [ "blocking", "slowing", "suggestion" ] }, "minItems": 1, "uniqueItems": true, "x-filter-kind": "enum_set", "description": "How much the reported problem hurts, in the reporter's own estimate: blocking, slowing or a suggestion. Absent when the reporter gave none." }, "reported": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The first day included." }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "format": "date", "description": "The last day included." } }, "minProperties": 1, "additionalProperties": false, "x-filter-kind": "date_range", "description": "When the report was filed: the moment its ticket was created, read by day (Pacific time) when a list filters on a date range." }, "reporter": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]+$", "x-filter-kind": "id_reference", "description": "The member who filed the report in the app: a user id, or me for the caller. An email-filed report has a sender's address instead, and a report staff filed for the customer has neither." }, "following": { "type": "boolean", "x-filter-kind": "presence", "description": "Whether the person asking follows the report: true for the reports they follow (their own from the day each was filed, and any they chose to follow), false for the rest." }, "unread": { "type": "boolean", "x-filter-kind": "presence", "description": "Whether the report changed since the person asking last saw it: true for a report with a change newer than the last one they saw, or that they have never opened." }, "private": { "type": "boolean", "x-filter-kind": "presence", "description": "Whether the reporter marked the report private: then only the reporter and Trade HQ staff see it. true lists the private reports the person asking may see." } }, "additionalProperties": false, "minProperties": 1, "x-combine": "and", "description": "Reports matching every term given." }, "q": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Words in a report's title or text, case ignored: \"already reported?\"." }, "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "additionalProperties": false, "minProperties": 1, "description": "The days counted, {from?, to?}, YYYY-MM-DD and inclusive, Pacific time; every day when left out." } }, "required": [], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "reported": { "type": "integer", "minimum": 0, "description": "How many reports were reported in the period and match the filters.", "x-data-class": "operational" }, "by_status": { "type": "object", "description": "Of those, how many stand in each status: every status, zero included.", "x-data-class": "operational" }, "median_days_to_fix": { "type": [ "number", "null" ], "description": "The median calendar days, Pacific time, from reported to fixed, over those fixed; null when none is.", "x-data-class": "operational" }, "median_days_to_first_response": { "type": [ "number", "null" ], "description": "The median calendar days from reported to Trade HQ's first response, over those answered; null when none is.", "x-data-class": "operational" }, "period": { "type": "object", "description": "The period counted, {from, to}, each null when left open.", "x-data-class": "operational" } }, "required": [ "reported", "by_status", "median_days_to_fix", "median_days_to_first_response", "period" ], "additionalProperties": false }, "annotations": { "title": "Summarize customer reports", "readOnlyHint": true, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:read" } }, { "name": "suspend_org", "title": "Suspend an org", "description": "Suspends an org: its users, and its test twin's, are refused on every call until it is live again. Nothing of the org's is deleted. On an org whose deletion is scheduled, the suspension is what cancelling the deletion returns it to. Calling it again changes nothing. It records who suspended the org and, when given, why; staff see both, the org's own account sees who and never why. A test twin, an org the repository declares and a purged org are refused.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org to suspend." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why it is suspended, trimmed. Trade HQ staff see it with who suspended the org and when; the org's own account does not." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "active", "suspended", "deletion_scheduled", "purged" ], "description": "suspended, or deletion_scheduled when its deletion is counting down.", "x-data-class": "operational" }, "purge_after": { "type": [ "string", "null" ], "format": "date-time", "description": "When a scheduled deletion may be purged; null when none is scheduled.", "x-data-class": "operational" } }, "required": [ "org_id", "state", "purge_after" ], "additionalProperties": false }, "annotations": { "title": "Suspend an org", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "switch_org", "title": "Switch organization", "description": "Moves the signed-in user's own session to another org: every later request acts in that org. Only an org list_switchable_orgs returns for the caller is accepted; any other is refused. Switching to the org the session is already in changes nothing. A device pinned to a unit cannot switch.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org to switch to: an org_id list_switchable_orgs returned." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "from_org": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the session was in; null for a session that had selected none.", "x-data-class": "operational" }, "to_org": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the session is in now.", "x-data-class": "operational" } }, "required": [ "from_org", "to_org" ], "additionalProperties": false }, "annotations": { "title": "Switch organization", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "turn_off_flag", "title": "Turn a flag off", "description": "Switches one registered feature flag off in PostHog for everyone, from any wave. A release flag off hides its feature from everyone, staff included; a kill switch off gives everyone the new screen. A flag PostHog does not have is created switched off. Refused for a flag already off. Recorded with who did it. Send an Idempotency-Key header. Staff only.", "inputSchema": { "type": "object", "properties": { "flag_key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The flag's key, as the registry has it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "flag_key" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "action_id": { "type": "string", "description": "This move's audit row.", "x-data-class": "operational" }, "flag_key": { "type": "string", "description": "The flag moved.", "x-data-class": "operational" }, "action": { "type": "string", "enum": [ "advance", "roll_back", "set_lists" ], "description": "advance, roll_back, or set_lists (TRA-1461: the beta lists chosen).", "x-data-class": "operational" }, "from_wave": { "type": "string", "description": "The wave PostHog had it on.", "x-data-class": "operational" }, "to_wave": { "type": "string", "description": "The wave it is on now.", "x-data-class": "operational" }, "acted_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who moved it: the staff member or agent, never PostHog's key.", "x-data-class": "operational" }, "acted_at": { "type": "string", "format": "date-time", "description": "When.", "x-data-class": "operational" }, "posthog_url": { "type": [ "string", "null" ], "description": "The flag in PostHog; null on a replay.", "x-data-class": "operational" } }, "required": [ "action_id", "flag_key", "action", "from_wave", "to_wave", "acted_by", "acted_at", "posthog_url" ], "additionalProperties": false }, "annotations": { "title": "Turn a flag off", "readOnlyHint": false, "idempotentHint": false, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "unfollow_report", "title": "Unfollow a customer report", "description": "Stops following a customer report: it no longer shows unread to the caller, and its updates no longer reach them. Open to anyone who may get the report, its reporter included, who may unfollow their own. Unfollowing writes an unfollowed event on the report's timeline; unfollowing a report you do not follow changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the report is in." }, "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report: its CUS ticket's Linear id, as list_reports and get_report answer it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "report_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "report_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The report.", "x-data-class": "operational" }, "following": { "type": "boolean", "description": "Whether the caller follows the report now.", "x-data-class": "operational" } }, "required": [ "report_id", "following" ], "additionalProperties": false }, "annotations": { "title": "Unfollow a customer report", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "update_org_settings", "title": "Update an org's settings", "description": "Sets or clears an org's own settings and returns its effective settings, each with the level it came from. Settings inherit platform > account > org > unit > user; a key the platform or the org's account has locked, or one the platform does not let an org change, is refused and nothing is applied. Locking a key fixes it for the org's units and users. Sending the same change again changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org whose settings change. Not a test twin: change its live org." }, "settings": { "type": "object", "properties": { "base_currency": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "The ISO 4217 currency the books are kept in. An org decides it; its units and people do not." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "The ISO 4217 currency the books are kept in. An org decides it; its units and people do not. Null clears the org's own value." }, "date_format": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "enum": [ "YYYY-MM-DD", "DD/MM/YYYY", "MM/DD/YYYY" ], "description": "How dates are shown." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "How dates are shown. Null clears the org's own value." }, "fiscal_year_start": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "pattern": "^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "The first day of the fiscal year, MM-DD. An org decides it; its units and people do not." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "The first day of the fiscal year, MM-DD. An org decides it; its units and people do not. Null clears the org's own value." }, "locale": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "enum": [ "en-US", "en-GB", "de-DE", "fr-FR", "es-ES", "nl-NL" ], "description": "The language and regional format of the interface." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "The language and regional format of the interface. Null clears the org's own value." }, "numbering_series_booking": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How bookings are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "How bookings are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. Null clears the org's own value." }, "numbering_series_invoice": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How invoices are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "How invoices are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. Null clears the org's own value." }, "numbering_series_order": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How sales orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "How sales orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. Null clears the org's own value." }, "numbering_series_purchase_order": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How purchase orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "How purchase orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. Null clears the org's own value." }, "numbering_series_release": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How releases are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. A yard may number its own." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "How releases are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. A yard may number its own. Null clears the org's own value." }, "numbering_series_vendor_bill": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How vendor bills are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "How vendor bills are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. Null clears the org's own value." }, "shell_last_tab": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "enum": [ "depots", "sell", "source", "intel" ], "description": "The tab of the app's header a person last chose, which they land on when they sign in." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "The tab of the app's header a person last chose, which they land on when they sign in. Null clears the org's own value." }, "timezone": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(UTC|[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+)+)$", "description": "The IANA time zone times are shown in." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "The IANA time zone times are shown in. Null clears the org's own value." }, "units_of_measure": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "enum": [ "metric", "imperial" ], "description": "Metric or imperial weights and dimensions. An org decides it for everyone in it." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "Metric or imperial weights and dimensions. An org decides it for everyone in it. Null clears the org's own value." }, "week_starts_on": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "enum": [ "monday", "sunday" ], "description": "The first day of a week in calendars and weekly reports." }, "locked": { "type": "boolean", "default": false, "description": "True: no unit or user may override it." } }, "required": [ "value" ], "additionalProperties": false, "description": "The first day of a week in calendars and weekly reports. Null clears the org's own value." } }, "minProperties": 1, "additionalProperties": false, "description": "The keys to change: each to {value, locked} or to null to clear the org's own value." }, "expected_version": { "type": "string", "minLength": 1, "maxLength": 128, "description": "The version a previous answer carried. If the org's settings have changed since, nothing is applied and the call is refused version_conflict. Leave out to write unconditionally." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "settings" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org.", "x-data-class": "operational" }, "settings": { "type": "object", "properties": { "base_currency": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "The ISO 4217 currency the books are kept in. An org decides it; its units and people do not." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "date_format": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "YYYY-MM-DD", "DD/MM/YYYY", "MM/DD/YYYY" ], "description": "How dates are shown." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "fiscal_year_start": { "type": "object", "properties": { "value": { "type": "string", "pattern": "^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$", "description": "The first day of the fiscal year, MM-DD. An org decides it; its units and people do not." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "locale": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "en-US", "en-GB", "de-DE", "fr-FR", "es-ES", "nl-NL" ], "description": "The language and regional format of the interface." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_booking": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How bookings are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_invoice": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How invoices are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_order": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How sales orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_purchase_order": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How purchase orders are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_release": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How releases are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}. A yard may number its own." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "numbering_series_vendor_bill": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^([A-Z0-9/._-]|\\{(yyyy|yy|mm|seq:([1-9]|1[0-2]))\\})+$", "description": "How vendor bills are numbered: literals, {yyyy}, {yy}, {mm} and one {seq:N}." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "shell_last_tab": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "depots", "sell", "source", "intel" ], "description": "The tab of the app's header a person last chose, which they land on when they sign in." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "timezone": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^(UTC|[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+)+)$", "description": "The IANA time zone times are shown in." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "units_of_measure": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "metric", "imperial" ], "description": "Metric or imperial weights and dimensions. An org decides it for everyone in it." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false }, "week_starts_on": { "type": "object", "properties": { "value": { "type": "string", "enum": [ "monday", "sunday" ], "description": "The first day of a week in calendars and weekly reports." }, "source": { "type": "string", "enum": [ "platform", "account", "org", "unit", "user" ] }, "locked_at": { "type": [ "string", "null" ], "enum": [ "platform", "account", "org", "unit", "user", null ] } }, "required": [ "value", "source", "locked_at" ], "additionalProperties": false } }, "required": [ "base_currency", "date_format", "fiscal_year_start", "locale", "numbering_series_booking", "numbering_series_invoice", "numbering_series_order", "numbering_series_purchase_order", "numbering_series_release", "numbering_series_vendor_bill", "shell_last_tab", "timezone", "units_of_measure", "week_starts_on" ], "additionalProperties": false, "description": "Every key's effective value at the org, where it came from, and where it is locked.", "x-data-class": "operational" }, "version": { "type": "string", "description": "The version of the org's own settings this call left: send it as expected_version, or as If-Match.", "x-data-class": "operational" } }, "required": [ "org_id", "settings", "version" ], "additionalProperties": false }, "annotations": { "title": "Update an org's settings", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "update_role_template", "title": "Edit a role template", "description": "Renames one of the org's own role templates, changes its description, and adds the permissions in `grant` and removes those in `revoke`. Everyone holding it holds the change at once. Shipped templates cannot be edited; clone one instead. You can edit only a template that carries nothing your own role in the org does not, and it can end up carrying only permissions your role carries. The same edit again changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the template belongs to." }, "role_id": { "type": "string", "minLength": 1, "maxLength": 20, "description": "The org's own template to edit: a clone id (RT and twelve characters)." }, "title": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Its new name, unique within the org." }, "description": { "type": "string", "minLength": 1, "maxLength": 400, "description": "What it is for." }, "grant": { "type": "array", "items": { "type": "string", "enum": [ "org.admin", "org.member", "org.guest", "role.read", "role.manage", "api_key.read" ] }, "uniqueItems": true, "description": "Permissions to add." }, "revoke": { "type": "array", "items": { "type": "string", "enum": [ "org.admin", "org.member", "org.guest", "role.read", "role.manage", "api_key.read" ] }, "uniqueItems": true, "description": "Permissions to remove." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "role_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "role_id": { "type": "string", "description": "The template'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 belongs to.", "x-data-class": "operational" }, "title": { "type": "string", "description": "Its name.", "x-data-class": "operational" }, "description": { "type": [ "string", "null" ], "description": "What it is for.", "x-data-class": "operational" }, "cloned_from": { "type": "string", "description": "The template it was cloned from.", "x-data-class": "operational" }, "modules": { "type": "array", "items": { "type": "string" }, "description": "Its module tags.", "x-data-class": "operational" }, "permissions": { "type": "array", "items": { "type": "string" }, "description": "The permissions it now carries.", "x-data-class": "operational" }, "clerk_role": { "type": "string", "description": "The Clerk built-in role its members hold: org:admin when it carries org.admin, else org:member (TRA-963).", "x-data-class": "operational" } }, "required": [ "role_id", "org_id", "title", "description", "cloned_from", "modules", "permissions", "clerk_role" ], "additionalProperties": false }, "annotations": { "title": "Edit a role template", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "update_service_account", "title": "Update a service account", "description": "Changes a service account: its name, its primary and backup owner (both named, two different active members of the org), its role template (never Owner or Admin), or its expiry, renewed with expires_in_days to at most 365 days from now. A suspended account given two active owners is active again, and an expired one renewed works again. Its mode never changes, and a disabled account is final. The same change again changes nothing.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the account belongs to." }, "service_account_id": { "type": "string", "minLength": 1, "maxLength": 14, "description": "The account to change." }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "A new name." }, "owner_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The primary owner. Naming either owner names the pair the account ends with, which must be two different active members." }, "backup_owner_user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The backup owner, who takes over when the primary is deactivated." }, "role_template_id": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A new role template: shipped or the org's own, never owner or admin." }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Renew: the account expires this many days from now, at most 365." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "service_account_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "service_account_id": { "type": "string", "description": "The account'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 live org it belongs to.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What it is for.", "x-data-class": "operational" }, "owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Its primary owner; null only while it is suspended for want of one.", "x-data-class": "operational" }, "backup_owner_user_id": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Its backup owner, who takes over when the primary is deactivated; null once that has happened.", "x-data-class": "operational" }, "role_template_id": { "type": "string", "description": "The role template it acts under: never Owner or Admin.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live or test; its keys are sk_live_ or sk_test_ to match.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "active", "suspended", "disabled", "expired" ], "description": "active; suspended when its last owner was deactivated, until an admin reassigns it; disabled, which is final; or expired.", "x-data-class": "operational" }, "expires_at": { "type": "string", "format": "date-time", "description": "When it and every key of it stop working, unless renewed.", "x-data-class": "operational" }, "keys": { "type": "integer", "description": "How many working keys it holds.", "x-data-class": "operational" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The start of the last minute any key of it was served a request; null if never.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was made.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who made it.", "x-data-class": "operational" } }, "required": [ "service_account_id", "org_id", "name", "owner_user_id", "backup_owner_user_id", "role_template_id", "mode", "status", "expires_at", "keys", "last_used_at", "created_at", "created_by" ], "additionalProperties": false }, "annotations": { "title": "Update a service account", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "update_sso_connection", "title": "Update a single sign-on connection", "description": "Changes a single sign-on connection: its name, its IdP metadata (idp_metadata_url, an https URL, or idp_metadata, the IdP's metadata XML), and whether people sign in through it (active). Activating needs the metadata saved. Clerk is updated to match shortly after. Inputs left out are left as they are.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org." }, "connection_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "The connection, as list_sso_connections names it." }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "A new name." }, "idp_metadata_url": { "type": "string", "minLength": 9, "maxLength": 2048, "description": "The IdP's metadata URL, https. Replaces any uploaded XML." }, "idp_metadata": { "type": "string", "minLength": 1, "maxLength": 200000, "description": "The IdP's metadata XML, uploaded. Replaces any metadata URL." }, "active": { "type": "boolean", "description": "Whether people sign in through it." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "connection_id" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "connection_id": { "type": "string", "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$", "format": "uuid", "description": "Trade HQ's id for the connection.", "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 belongs to.", "x-data-class": "operational" }, "name": { "type": "string", "description": "What the org's admins call it.", "x-data-class": "operational" }, "protocol": { "type": "string", "enum": [ "saml", "oidc" ], "description": "saml or oidc.", "x-data-class": "operational" }, "domain": { "type": "string", "description": "The verified email domain it serves.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "creating", "awaiting_metadata", "ready_to_test", "active", "deleting", "deleted" ], "description": "creating (Clerk has not answered yet), awaiting_metadata, ready_to_test, active, deleting or deleted.", "x-data-class": "operational" }, "active": { "type": "boolean", "description": "Whether people sign in through it.", "x-data-class": "operational" }, "acs_url": { "type": [ "string", "null" ], "description": "The service provider's ACS URL, for the IdP admin; null until Clerk has answered.", "x-data-class": "operational" }, "sp_entity_id": { "type": [ "string", "null" ], "description": "The service provider's entity id, for the IdP admin; null until Clerk has answered.", "x-data-class": "operational" }, "sp_metadata_url": { "type": [ "string", "null" ], "description": "The service provider's metadata URL; null until Clerk has answered.", "x-data-class": "operational" }, "idp_metadata_url": { "type": [ "string", "null" ], "description": "The IdP metadata URL saved, if a URL was.", "x-data-class": "operational" }, "has_idp_metadata": { "type": "boolean", "description": "Whether IdP metadata is saved, as a URL or as uploaded XML.", "x-data-class": "operational" }, "required": { "type": "boolean", "description": "Whether members at its domain must sign in through it.", "x-data-class": "operational" }, "bypass_until": { "type": [ "string", "null" ], "format": "date-time", "description": "While the outage lever holds, when it ends; null otherwise.", "x-data-class": "operational" }, "jit": { "type": "boolean", "description": "Whether a first sign-in through it makes the person a member.", "x-data-class": "operational" }, "default_role_template": { "type": [ "string", "null" ], "description": "The role template a just-in-time member gets.", "x-data-class": "operational" }, "idp_mfa_trusted": { "type": "boolean", "description": "Whether the IdP's MFA counts toward the org's MFA settings.", "x-data-class": "operational" }, "allow_manual_additions": { "type": "boolean", "description": "Whether invites stay allowed for its domain while a directory manages it (TRA-486).", "x-data-class": "operational" }, "last_sign_in_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The last sign-in through it.", "x-data-class": "operational" }, "idp_certificate_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the IdP's signing certificate expires, once known.", "x-data-class": "operational" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was added.", "x-data-class": "operational" }, "caller_may_bypass": { "type": "boolean", "description": "Whether the caller may pull the outage lever: the account owner, or the Owner role template in the org.", "x-data-class": "operational" } }, "required": [ "connection_id", "org_id", "name", "protocol", "domain", "status", "active", "acs_url", "sp_entity_id", "sp_metadata_url", "idp_metadata_url", "has_idp_metadata", "required", "bypass_until", "jit", "default_role_template", "idp_mfa_trusted", "allow_manual_additions", "last_sign_in_at", "idp_certificate_expires_at", "created_at", "caller_may_bypass" ], "additionalProperties": false }, "annotations": { "title": "Update a single sign-on connection", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } }, { "name": "verify_domain", "title": "Verify an email domain", "description": "Claims an email domain for the org and verifies it. The first call answers status pending with a DNS TXT record to publish (record_name, record_value); call again once it is published and the domain is verified. Other orgs may claim the same domain while it is pending; the first to publish its record verifies it, and a verified domain is that org's alone. Its join_policy starts as invite_only: set_domain_join_policy decides whether a person signing up at it may ask to join.", "inputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The live org claiming the domain." }, "domain": { "type": "string", "minLength": 3, "maxLength": 253, "description": "The email domain, such as example.com." }, "confirmation": { "type": "string", "minLength": 1, "description": "Leave out on the first call: it changes nothing and answers with an approval request, an exception bound to exactly these arguments and what they act on. The person you act for decides it in Container Trade HQ; you cannot. Once they approve, send the same arguments again with this set to its exception_id. The approval is spent once and expires." } }, "required": [ "org_id", "domain" ], "additionalProperties": false }, "outputSchema": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org claiming it.", "x-data-class": "operational" }, "domain": { "type": "string", "description": "The domain, lower case.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "verified" ], "description": "pending until the TXT record is found, then verified.", "x-data-class": "operational" }, "record_name": { "type": "string", "description": "Where to publish the TXT record.", "x-data-class": "operational" }, "record_value": { "type": "string", "description": "What the TXT record carries.", "x-data-class": "operational" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was verified.", "x-data-class": "operational" }, "verified_by": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who verified it.", "x-data-class": "operational" }, "join_policy": { "type": "string", "enum": [ "invite_only", "request" ], "description": "invite_only, or request: a person signing up at the domain is put to the org's admins as a join request.", "x-data-class": "operational" }, "created_by": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "Who claimed it.", "x-data-class": "operational" } }, "required": [ "org_id", "domain", "status", "record_name", "record_value", "verified_at", "verified_by", "join_policy", "created_by" ], "additionalProperties": false }, "annotations": { "title": "Verify an email domain", "readOnlyHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "containertradehq.com/scope": "tradehq:act", "containertradehq.com/approval": "bound" } } ] }