{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Container Trade HQ API", "version": "2026-10-01", "description": "Every capability of Container Trade HQ, one POST each under /v1/cap. Generated from the capability registry; never edited by hand.", "x-tradehq-input-revision": "fa5200f22a1157a430469d906dfd492defc024c655730ab5cad32f524e5658d7", "x-tradehq-stable-url": "https://containertradehq.com/openapi.json" }, "servers": [ { "url": "https://api.containertradehq.com" } ], "security": [ { "apiKey": [] } ], "paths": { "/v1/cap/acknowledge_push": { "post": { "operationId": "acknowledge_push", "summary": "Open a push", "description": "Records that the caller opened a push sent to them, and answers what it was about: the capability event or the exception, by id. A push sent to anyone else is refused. Opening it again changes nothing.\n\nWho may call it: any one of: self.act (the signed-in caller, about themself only; it names no other user); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgePushInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgePushResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgePushResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `push_not_found`: no push sent to the caller has that id; another user's gets the same answer.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "push_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.push.acknowledge", "contract": 2, "ticket": "TRA-297", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/acknowledge_push" }, "x-tradehq-errors": "declared" } }, "/v1/cap/add_file": { "post": { "operationId": "add_file", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddFileInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddFileResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddFileResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `retry_key_mismatch`: the Idempotency-Key was already used with other inputs; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was created.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `file_too_large_for_add_file`: the file is larger than one call carries; a person uploads it with create_upload; `content_not_decodable`: content is not standard base64; `files_unavailable`: this deployment has no intake or files store configured yet; `org_is_a_test_twin`: the org is a test twin; files belong to its live org.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "file_too_large_for_add_file", "content_not_decodable", "files_unavailable", "org_is_a_test_twin" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.file.add", "contract": 2, "ticket": "TRA-884", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/add_file" }, "x-tradehq-errors": "declared" } }, "/v1/cap/advance_flag_wave": { "post": { "operationId": "advance_flag_wave", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvanceFlagWaveInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvanceFlagWaveResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvanceFlagWaveResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-243", "authority": "act", "shape": "entity", "tenancy": "canonical-registry", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/advance_flag_wave" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/announce_deprecated_versions": { "post": { "operationId": "announce_deprecated_versions", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnounceDeprecatedVersionsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnounceDeprecatedVersionsResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnnounceDeprecatedVersionsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `release_not_current`: the release named is not this deployment's current version: the release has not reached it yet, or the date is wrong.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "release_not_current" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.api_version.announce_deprecated", "contract": 2, "ticket": "TRA-620", "authority": "act", "shape": "entity", "tenancy": "abstract", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/announce_deprecated_versions" }, "x-tradehq-errors": "declared" } }, "/v1/cap/anonymize_user": { "post": { "operationId": "anonymize_user", "summary": "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.\n\nWho may call it: any one of: account.owner (account role owner or higher in the account of EVERY org the user `user_id` belongs to; an org with no account blocks); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymizeUserInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymizeUserResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymizeUserResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-319", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/anonymize_user" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/approve_grant": { "post": { "operationId": "approve_grant", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveGrantInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveGrantResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveGrantResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `grant_not_pending`: the request was already decided, withdrawn or revoked.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "grant_not_pending" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `no_such_grant`: the org has no such grant; `granted_staff_cannot_decide`: a grant is decided by the org's own admin, never by staff in the org through a grant or by its grantee; `hours_only_on_approve`: hours is an approval's duration; a rejection takes none; `org_untyped`: the org has no tradehq_org row, so the decision plane can record nothing against it.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_such_grant", "granted_staff_cannot_decide", "hours_only_on_approve", "org_untyped" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.staff_grant.approve", "contract": 2, "ticket": "TRA-320", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/approve_grant" }, "x-tradehq-errors": "declared" } }, "/v1/cap/break_glass_access": { "post": { "operationId": "break_glass_access", "summary": "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.\n\nWho may call it: any one of: staff.break_glass (staff.ops held in the Internal org, tradehq_role.staff_role, by a person the TRA-318 adoption logged as break-glass in tradehq_role.staff_role_log: Sage and Sonja only); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreakGlassAccessInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreakGlassAccessResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreakGlassAccessResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `retry_key_mismatch`: the Idempotency-Key was already used with a different request; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was applied; `grant_already_pending`: a request from the caller to the org is still waiting on its admins; `grant_already_active`: the caller already holds an active grant to the org.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "idempotency_key_reused", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost", "grant_already_pending", "grant_already_active" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `grant_not_a_customer_org`: a grant is to a customer or demo org that is not a test twin; `grantee_already_a_member`: the caller is a member of the org and needs no grant.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "grant_not_a_customer_org", "grantee_already_a_member" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.staff_grant.break_glass", "contract": 2, "ticket": "TRA-320", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/break_glass_access" }, "x-tradehq-errors": "declared" } }, "/v1/cap/cancel_org_deletion": { "post": { "operationId": "cancel_org_deletion", "summary": "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.\n\nWho may call it: any one of: account.owner (account role owner or higher in the account of the org `org_id`); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrgDeletionInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrgDeletionResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrgDeletionResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-316", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/cancel_org_deletion" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/check_ip_allowlist": { "post": { "operationId": "check_ip_allowlist", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckIpAllowlistInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckIpAllowlistResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `security_policy_unenforced`: the org's stored network section does not parse.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "security_policy_unenforced" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.ip_allowlist.check", "contract": 2, "ticket": "TRA-489", "authority": "read", "shape": "scalar", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/check_ip_allowlist" }, "x-tradehq-errors": "declared" } }, "/v1/cap/claim_depot": { "post": { "operationId": "claim_depot", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimDepotInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimDepotResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimDepotResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-310", "authority": "act", "shape": "entity", "tenancy": "canonical-registry", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/claim_depot" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/claim_party": { "post": { "operationId": "claim_party", "summary": "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.\n\nWho may call it: any one of: staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPartyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPartyResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPartyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-310", "authority": "act", "shape": "entity", "tenancy": "canonical-registry", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/claim_party" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/clone_role_template": { "post": { "operationId": "clone_role_template", "summary": "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.\n\nWho may call it: any one of: role.manage (carried by the caller's role template in the org `org_id`); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneRoleTemplateInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneRoleTemplateResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloneRoleTemplateResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-317", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/clone_role_template" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/close_access_review": { "post": { "operationId": "close_access_review", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseAccessReviewInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseAccessReviewResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseAccessReviewResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `access_review_not_found`: the org has no such access review; `items_undecided`: an item of the review is not decided yet; the message says how many.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "access_review_not_found", "items_undecided" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.access_review.close", "contract": 2, "ticket": "TRA-491", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/close_access_review" }, "x-tradehq-errors": "declared" } }, "/v1/cap/complete_upload": { "post": { "operationId": "complete_upload", "summary": "Finish a file upload", "description": "Finishes an upload create_upload started, once the bytes have been PUT to its link: checks the object is the declared size and type and hands it to be filed. Calling it again answers the upload as it stands.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteUploadInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteUploadResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteUploadResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `upload_not_arrived`: nothing has been uploaded to the link yet.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "upload_not_arrived" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `upload_size_mismatch`: the uploaded object is not the size create_upload declared; `upload_type_mismatch`: the uploaded object is not the content type create_upload declared; `files_unavailable`: this deployment has no intake or files store configured yet; `org_is_a_test_twin`: the org is a test twin; files belong to its live org.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "upload_size_mismatch", "upload_type_mismatch", "files_unavailable", "org_is_a_test_twin" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.upload.complete", "contract": 2, "ticket": "TRA-884", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/complete_upload" }, "x-tradehq-errors": "declared" } }, "/v1/cap/confirm_purchase_order": { "post": { "operationId": "confirm_purchase_order", "summary": "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.\n\nWho may call it: any one of: org.guest (carried by the caller's role template in the org `org_id`, which owns the document `document_kind`/`document_id`); counterparty (org.member carried by the caller's role template in an org that holds a seat on the document; it reads its own seat); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPurchaseOrderInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPurchaseOrderResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPurchaseOrderResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-323", "authority": "act", "shape": "entity", "tenancy": "controlled-share", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/confirm_purchase_order" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/confirm_report": { "post": { "operationId": "confirm_report", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmReportInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmReportResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmReportResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `report_not_found`: the org has no such report, or it is private to its reporter; `report_not_confirmable`: only a Fixed or Answered report is confirmed; `confirmation_not_recorded`: the confirmation could not reach Trade HQ support just now; send it again; `reports_unavailable`: this deployment has no broker credential for reports yet; nothing was sent.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "report_not_found", "report_not_confirmable", "confirmation_not_recorded", "reports_unavailable" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.customer_report.confirm", "contract": 2, "ticket": "TRA-1472", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/confirm_report" }, "x-tradehq-errors": "declared" } }, "/v1/cap/convert_sandbox": { "post": { "operationId": "convert_sandbox", "summary": "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.\n\nWho may call it: any one of: staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertSandboxInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertSandboxResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertSandboxResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `not_a_sandbox`: the org is not a public sandbox, so there is nothing to convert; `sandbox_expired`: the sandbox is past its expiry, or purged, and is being deleted; `sandbox_already_converted`: the sandbox was already converted, under another key; nothing was changed; `idempotency_key_reused`: this Idempotency-Key already converted a sandbox with other inputs; `admin_already_provisioned`: the existing account already has a provisioning for that admin email; `retry_key_mismatch`: the Idempotency-Key was already used with a different request; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was applied.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "not_a_sandbox", "sandbox_expired", "sandbox_already_converted", "idempotency_key_reused", "admin_already_provisioned", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `account_choice`: the call names both an existing account and a new one, or neither, or an account that does not exist; `admin_email_invalid`: the first admin's address is not an email address a person signs in with.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "account_choice", "admin_email_invalid" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.sandbox.convert", "contract": 2, "ticket": "TRA-474", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/convert_sandbox" }, "x-tradehq-errors": "declared" } }, "/v1/cap/create_access_review": { "post": { "operationId": "create_access_review", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessReviewInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessReviewResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccessReviewResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `idempotency_key_reused`: this Idempotency-Key already started an access review with different inputs; `retry_key_mismatch`: the Idempotency-Key was already used with different inputs; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; no review was started.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "idempotency_key_reused", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `nothing_to_review`: none of members, guests, service_accounts, api_keys and staff_grants is true; `due_date_passed`: the due date is before today (UTC).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "nothing_to_review", "due_date_passed" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.access_review.create", "contract": 2, "ticket": "TRA-491", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/create_access_review" }, "x-tradehq-errors": "declared" } }, "/v1/cap/create_account": { "post": { "operationId": "create_account", "summary": "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.\n\nWho may call it: any one of: staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-314", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/create_account" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/create_api_key": { "post": { "operationId": "create_api_key", "summary": "Create an API key", "description": "Issues an API key on an org: sk_live_ reaches the org, sk_test_ its test twin. Every key belongs to an active service account of the org (service_account_id), acts as that account and takes its mode. The answer to the call that issues it carries the whole key in `secret`. The secret is never stored, by Trade HQ or by this call's idempotency record (the key's row is the record, and it holds only the key's hash), so it can never be shown again: a retry with the same Idempotency-Key and inputs answers the same key with `secret` null and `replayed` true, and creates nothing. The key is pinned to the API version current today unless `api_version` names another version this service serves. A key may do only what `grants` names (TRA-619), each a permission the issuer holds in the org and the account's role template carries, and only while that template still carries it: a key granted nothing calls nothing.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); api_key.read (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-321", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/create_api_key" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/create_data_share": { "post": { "operationId": "create_data_share", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataShareInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataShareResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataShareResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-313", "authority": "act", "shape": "entity", "tenancy": "controlled-share", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/create_data_share" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/create_invite_link": { "post": { "operationId": "create_invite_link", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInviteLinkInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInviteLinkResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInviteLinkResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-319", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/create_invite_link" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/create_org": { "post": { "operationId": "create_org", "summary": "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.\n\nWho may call it: any one of: staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in at least one account; the call is scoped to those accounts); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-293", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/create_org" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/create_portfolio": { "post": { "operationId": "create_portfolio", "summary": "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.\n\nWho may call it: any one of: staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in at least one account; the call is scoped to those accounts); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePortfolioInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePortfolioResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePortfolioResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-314", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/create_portfolio" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/create_service_account": { "post": { "operationId": "create_service_account", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceAccountInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceAccountResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceAccountResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `idempotency_key_reused`: this Idempotency-Key already made a service account with different inputs; `retry_key_mismatch`: the Idempotency-Key was already used with different inputs; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; no account was made.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "idempotency_key_reused", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `org_is_a_test_twin`: the org is a test twin; make the account on its live org with mode test; `owners_must_differ`: the primary and the backup owner are the same person; `owner_not_active_member`: an owner is deactivated or not a member of the org; `role_template_not_assignable`: the role template is Owner, Admin, a guest's, or carries org.admin or role.manage; `unknown_role_template`: the role template is neither shipped nor the org's own; `permission_not_held`: the role template carries a permission the calling admin's own role does not.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "org_is_a_test_twin", "owners_must_differ", "owner_not_active_member", "role_template_not_assignable", "unknown_role_template", "permission_not_held" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.service_account.create", "contract": 2, "ticket": "TRA-493", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/create_service_account" }, "x-tradehq-errors": "declared" } }, "/v1/cap/create_sso_connection": { "post": { "operationId": "create_sso_connection", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSsoConnectionInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSsoConnectionResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSsoConnectionResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `domain_has_connection`: a single sign-on connection already serves the domain; `retry_key_mismatch`: the Idempotency-Key was already used with other inputs; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was created.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "domain_has_connection", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `domain_not_verified`: the domain is not one this org has verified; `org_is_a_test_twin`: the org is a test twin; connections belong to its live org.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "domain_not_verified", "org_is_a_test_twin" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.sso_connection.create", "contract": 2, "ticket": "TRA-485", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/create_sso_connection" }, "x-tradehq-errors": "declared" } }, "/v1/cap/create_unit": { "post": { "operationId": "create_unit", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`, or by a role held on the unit `parent_id` or any unit above it by a member of that org; without `parent_id`, by the template); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUnitInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUnitResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUnitResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-311", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/create_unit" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/create_upload": { "post": { "operationId": "create_upload", "summary": "Start a file upload", "description": "Starts uploading one file into the org: answers a link that accepts one PUT of exactly the declared size and content type, for ten minutes. PUT the bytes there with those two headers, then call complete_upload with the upload_id to file it. Files up to 5 GiB.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `retry_key_mismatch`: the Idempotency-Key was already used with other inputs; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was created.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `file_too_large`: the declared size is above the 5 GiB single-upload ceiling; `files_unavailable`: this deployment has no intake or files store configured yet; `org_is_a_test_twin`: the org is a test twin; files belong to its live org.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "file_too_large", "files_unavailable", "org_is_a_test_twin" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.upload.create", "contract": 2, "ticket": "TRA-884", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/create_upload" }, "x-tradehq-errors": "declared" } }, "/v1/cap/deactivate_user": { "post": { "operationId": "deactivate_user", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in EVERY org the user `user_id` belongs to); account.owner (account role owner or higher in the account of EVERY org the user `user_id` belongs to; an org with no account blocks); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateUserInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateUserResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateUserResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-293", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/deactivate_user" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/decide_access_review_item": { "post": { "operationId": "decide_access_review_item", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideAccessReviewItemInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideAccessReviewItemResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideAccessReviewItemResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `item_already_decided`: the item was decided otherwise; a decision is final.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "item_already_decided" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `access_review_not_found`: the org has no such access review; `access_review_item_not_found`: the review has no such item; `review_closed`: the review is closed; its decisions are final; `own_review_item`: the item is the caller's own row; another admin decides it; `decision_not_available`: change_role is a member's alone; `role_template_required`: change_role needs role_template_id; `review_act_refused`: the act the decision runs refused; its own code is in the message and nothing was recorded; `review_act_unavailable`: the act the decision runs is not available to this org yet; nothing was recorded.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "access_review_not_found", "access_review_item_not_found", "review_closed", "own_review_item", "decision_not_available", "role_template_required", "review_act_refused", "review_act_unavailable" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.access_review_item.decide", "contract": 2, "ticket": "TRA-491", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/decide_access_review_item" }, "x-tradehq-errors": "declared" } }, "/v1/cap/decline_data_share": { "post": { "operationId": "decline_data_share", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineDataShareInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineDataShareResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeclineDataShareResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `data_share_not_received`: no share by that id is made to the party this org has claimed; `data_share_revoked`: the org that made the share revoked it, so it is sent nothing.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "data_share_not_received", "data_share_revoked" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.data_share.decline", "contract": 2, "ticket": "TRA-468", "authority": "act", "shape": "entity", "tenancy": "controlled-share", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/decline_data_share" }, "x-tradehq-errors": "declared" } }, "/v1/cap/delete_file": { "post": { "operationId": "delete_file", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFileInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFileResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteFileResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `files_unavailable`: this deployment has no intake or files store configured yet.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "files_unavailable" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.file.delete", "contract": 2, "ticket": "TRA-884", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/delete_file" }, "x-tradehq-errors": "declared" } }, "/v1/cap/delete_role_template": { "post": { "operationId": "delete_role_template", "summary": "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.\n\nWho may call it: any one of: role.manage (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRoleTemplateInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRoleTemplateResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRoleTemplateResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-448", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/delete_role_template" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/delete_sso_connection": { "post": { "operationId": "delete_sso_connection", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSsoConnectionInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSsoConnectionResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSsoConnectionResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `connection_not_found`: the org has no such connection; `security_policy_unenforced`: the stored sso section does not parse.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "connection_not_found", "security_policy_unenforced" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.sso_connection.delete", "contract": 2, "ticket": "TRA-485", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/delete_sso_connection" }, "x-tradehq-errors": "declared" } }, "/v1/cap/delete_view": { "post": { "operationId": "delete_view", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteViewInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteViewResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteViewResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_view`: the org has no view by that id that the caller may read; `view_read_only`: a system view, or a view the caller may read and not change: another member's, shared org-read.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_view", "view_read_only" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.saved_view.delete", "contract": 2, "ticket": "TRA-590", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/delete_view" }, "x-tradehq-errors": "declared" } }, "/v1/cap/disable_service_account": { "post": { "operationId": "disable_service_account", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableServiceAccountInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableServiceAccountResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableServiceAccountResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `service_account_not_found`: the org has no such service account.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "service_account_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.service_account.disable", "contract": 2, "ticket": "TRA-493", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/disable_service_account" }, "x-tradehq-errors": "declared" } }, "/v1/cap/export_audit_events": { "post": { "operationId": "export_audit_events", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in the account of the org `org_id`); org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportAuditEventsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportAuditEventsResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportAuditEventsResponse" } } } }, "202": { "description": "accepted: an async contract's call has started", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportAuditEventsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `audit_export_running`: an export of this org's audit log is still running; wait for it to land; `idempotency_key_reused`: this Idempotency-Key already made an export of another org, or by someone else; `retry_key_mismatch`: the Idempotency-Key was already used with different inputs; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; no export was made.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "audit_export_running", "idempotency_key_reused", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `audit_export_unavailable`: this deployment has no object store or no link secret for audit exports yet.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "audit_export_unavailable" ] }, "429": { "description": "A rate limit is reached. Platform codes: `rate_limited`: the API key's rate limit is reached. This capability's codes: `audit_export_busy`: as many exports as front-door builds at once are building or waiting; try again in a minute.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "rate_limited", "audit_export_busy" ] }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.audit_event.export", "contract": 2, "ticket": "TRA-500", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "async", "reference": "https://containertradehq.com/docs/capabilities/export_audit_events" }, "x-tradehq-errors": "declared" } }, "/v1/cap/follow_report": { "post": { "operationId": "follow_report", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowReportInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowReportResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowReportResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `report_not_found`: no report by that id in that org is one the caller may get: it does not exist, it is another org's, or it is private to its reporter.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "report_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.customer_report.follow", "contract": 2, "ticket": "TRA-1473", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/follow_report" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_acting_scope": { "post": { "operationId": "get_acting_scope", "summary": "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.\n\nWho may call it: any one of: self.read (the signed-in caller, about themself only; it names no other user); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActingScopeInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActingScopeResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-327", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_acting_scope" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/get_api_usage": { "post": { "operationId": "get_api_usage", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); api_key.read (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiUsageInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiUsageResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-321", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_api_usage" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/get_data_policy": { "post": { "operationId": "get_data_policy", "summary": "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.\n\nWho may call it: any one of: role.read (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDataPolicyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDataPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_role_template`: the role template is neither shipped nor one of this org's own.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_role_template" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.data_policy.get", "contract": 2, "ticket": "TRA-492", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_data_policy" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_file": { "post": { "operationId": "get_file", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFileInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFileResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `file_tenancy_mismatch`: the stored object does not carry this file's org and id; nothing was answered and the tenancy alarm was raised; `files_unavailable`: this deployment has no intake or files store configured yet.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "file_tenancy_mismatch", "files_unavailable" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.file.get", "contract": 2, "ticket": "TRA-884", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_file" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_identity_sync": { "post": { "operationId": "get_identity_sync", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetIdentitySyncInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetIdentitySyncResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.identity_sync.get", "contract": 2, "ticket": "TRA-490", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_identity_sync" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_impersonation": { "post": { "operationId": "get_impersonation", "summary": "Read an impersonation you started", "description": "Answers an impersonation the caller started with impersonate_user, as it stands: pending until Clerk issues the one-time sign-in link, then ready with the link until it expires; failed, expired or ended otherwise. Call it until status is ready. Only the staff member who started the impersonation is answered; any other id is not found.\n\nWho may call it: any one of: staff.break_glass (staff.ops held in the Internal org, tradehq_role.staff_role, by a person the TRA-318 adoption logged as break-glass in tradehq_role.staff_role_log: Sage and Sonja only); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetImpersonationInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetImpersonationResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `impersonation_not_found`: no impersonation in the org by that id was started by the caller.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "impersonation_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.impersonation.get", "contract": 2, "ticket": "TRA-634", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_impersonation" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_my_settings": { "post": { "operationId": "get_my_settings", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMySettingsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMySettingsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.my_settings.get", "contract": 2, "ticket": "TRA-1369", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_my_settings" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_notification_policy": { "post": { "operationId": "get_notification_policy", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetNotificationPolicyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetNotificationPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.notification_policy.get", "contract": 2, "ticket": "TRA-475", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_notification_policy" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 6, "walk_max": 6, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/get_onboarding_status": { "post": { "operationId": "get_onboarding_status", "summary": "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.\n\nWho may call it: any one of: account.owner (account role owner or higher in the account of the org `org_id`); org.admin (carried by the caller's role template in the org `org_id`); staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOnboardingStatusInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOnboardingStatusResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-328", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_onboarding_status" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/get_purchase_order_suggestions": { "post": { "operationId": "get_purchase_order_suggestions", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPurchaseOrderSuggestionsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPurchaseOrderSuggestionsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.purchase_order_suggestions.get", "contract": 2, "ticket": "TRA-1267", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_purchase_order_suggestions" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_purge_readiness": { "post": { "operationId": "get_purge_readiness", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPurgeReadinessInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPurgeReadinessResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `capability_not_enabled`: the capability's release flag is off for the caller; `org_not_scheduled`: the org has no deletion scheduled, so there is no purge to be ready for; `org_has_no_lifecycle`: the org has no lifecycle row: a ported org nothing has typed yet; `org_has_no_type`: the org has a lifecycle row and no type row; a person repairs it; `org_is_twin`: a test twin follows its live org; `org_declared`: the org is declared in db/tradehq/orgs.json and leaves by a reviewed change; `org_purged`: the org is purged; only its tombstone is left.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "capability_not_enabled", "org_not_scheduled", "org_has_no_lifecycle", "org_has_no_type", "org_is_twin", "org_declared", "org_purged" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.org.purge_readiness", "contract": 2, "ticket": "TRA-467", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_purge_readiness" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_report": { "post": { "operationId": "get_report", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in the account of the org `org_id`); org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReportInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetReportResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `report_not_found`: no report by that id in that org is one the caller may see: it does not exist, it is another org's, or it is private to its reporter.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "report_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.customer_report.get", "contract": 2, "ticket": "TRA-1471", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_report" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_security_policy": { "post": { "operationId": "get_security_policy", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSecurityPolicyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSecurityPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `security_policy_unenforced`: a stored section of the org's security settings does not parse; the step that applies them refuses the org's requests with the same code until a person restores it.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "security_policy_unenforced" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.security_policy.get", "contract": 2, "ticket": "TRA-565", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_security_policy" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_supplier_purchase_order": { "post": { "operationId": "get_supplier_purchase_order", "summary": "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.\n\nWho may call it: any one of: org.guest (carried by the caller's role template in the org `org_id`, which owns the document `document_kind`/`document_id`); counterparty (org.member carried by the caller's role template in an org that holds a seat on the document; it reads its own seat); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSupplierPurchaseOrderInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSupplierPurchaseOrderResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `several_seller_parties`: the caller belongs to more than one org seated as this purchase order's seller; read it from a session in one of them.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "several_seller_parties" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.supplier_purchase_order.get", "contract": 2, "ticket": "TRA-803", "authority": "read", "shape": "entity", "tenancy": "controlled-share", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_supplier_purchase_order" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_tenant_health": { "post": { "operationId": "get_tenant_health", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTenantHealthInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTenantHealthResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-335", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_tenant_health" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/get_test_twin": { "post": { "operationId": "get_test_twin", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTestTwinInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTestTwinResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-309", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_test_twin" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/get_view": { "post": { "operationId": "get_view", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetViewInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetViewResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_view`: the org has no view by that id that the caller may read; `view_call_refused`: the view's stored call, run as the caller, was refused: the message names the capability and its code.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_view", "view_call_refused" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.saved_view.get", "contract": 2, "ticket": "TRA-1377", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_view" }, "x-tradehq-errors": "declared" } }, "/v1/cap/get_view_default": { "post": { "operationId": "get_view_default", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetViewDefaultInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetViewDefaultResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_view`: the org has no view by that id that the caller may read.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_view" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.view_default.get", "contract": 2, "ticket": "TRA-1382", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/get_view_default" }, "x-tradehq-errors": "declared" } }, "/v1/cap/grant_capability": { "post": { "operationId": "grant_capability", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCapabilityInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCapabilityResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCapabilityResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `idempotency_key_reused`: the Idempotency-Key already made a grant with different inputs; `retry_key_mismatch`: the Idempotency-Key was already used with a different request; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was applied.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "idempotency_key_reused", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `capability_not_released`: the release-grant-capability flag is off for the caller; it may be turned on later; `org_is_a_test_twin`: a test twin has its live org's grants; grant on the live org; `capability_retired`: the capability is retired and no longer granted; `not_an_add_on`: the capability is not sold as an add-on; `expiry_not_in_the_future`: the expiry is not after today in UTC; `capability_not_found`: no capability has that name; `org_has_no_type`: the org has no type row, so it has no entitlements to add to.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "capability_not_released", "org_is_a_test_twin", "capability_retired", "not_an_add_on", "expiry_not_in_the_future", "capability_not_found", "org_has_no_type" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.capability_grant.create", "contract": 2, "ticket": "TRA-239", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/grant_capability" }, "x-tradehq-errors": "declared" } }, "/v1/cap/grant_staff_role": { "post": { "operationId": "grant_staff_role", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantStaffRoleInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantStaffRoleResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantStaffRoleResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `not_internal_member`: the user is not a member of Trade HQ's Internal org; invite them into it first; `user_anonymized`: the user is anonymized, and an anonymized user holds no role; `user_deactivated`: the user is deactivated; reinstate them before making them staff.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "not_internal_member", "user_anonymized", "user_deactivated" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.staff_role.grant", "contract": 2, "ticket": "TRA-447", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/grant_staff_role" }, "x-tradehq-errors": "declared" } }, "/v1/cap/grant_unit_role": { "post": { "operationId": "grant_unit_role", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); org.member (carried by the caller's role template in the org `org_id`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantUnitRoleInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantUnitRoleResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantUnitRoleResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `own_access`: You can't change your own access. Another admin can.; `unit_outside_caller`: You administer {your unit} and the units beneath it. {unit} is outside it.; `not_a_member`: {Name} isn't a member of this organization. Invite them in Members first.; `unknown_role_template`: the role template is neither shipped nor one of this org's own; `counterparty_role`: Counterparty roles are given in Guests, not on a unit.; `permission_not_unit_scoped`: {Role} carries {permission}, which applies to the whole organization and can't be given on a unit.; `permission_above_caller`: {Role} carries {permission}, which you don't hold on {unit}.; `holder_above_caller`: {Name}'s role on {unit} carries {permission}, which you don't hold there.; `tree_too_large`: the org's unit tree holds more units than one call reads.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "own_access", "unit_outside_caller", "not_a_member", "unknown_role_template", "counterparty_role", "permission_not_unit_scoped", "permission_above_caller", "holder_above_caller", "tree_too_large" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.unit_role.grant", "contract": 2, "ticket": "TRA-473", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/grant_unit_role" }, "x-tradehq-errors": "declared" } }, "/v1/cap/hide_catalog_photo": { "post": { "operationId": "hide_catalog_photo", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HideCatalogPhotoInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HideCatalogPhotoResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HideCatalogPhotoResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `photo_not_found`: the org has no unit photo with that id.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "photo_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.catalog_photo.hide", "contract": 2, "ticket": "TRA-1384", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/hide_catalog_photo" }, "x-tradehq-errors": "declared" } }, "/v1/cap/impersonate_user": { "post": { "operationId": "impersonate_user", "summary": "Sign in as a customer's user", "description": "Staff operations, holding an active act grant to the org, signs in as one of its members to see what they see, for a number of minutes (thirty unless said, at most four hours). The answer carries a one-time sign-in link once Clerk has issued it: read it with get_impersonation until status is ready. The impersonated session shows a banner on every screen, every act in it is recorded as staff acting as the user, and it ends when the minutes pass or the grant ends. A member who holds a staff role cannot be impersonated.\n\nWho may call it: any one of: staff.break_glass (staff.ops held in the Internal org, tradehq_role.staff_role, by a person the TRA-318 adoption logged as break-glass in tradehq_role.staff_role_log: Sage and Sonja only); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpersonateUserInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpersonateUserResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpersonateUserResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `retry_key_mismatch`: the Idempotency-Key was already used with a different request; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was applied.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "idempotency_key_reused", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `impersonation_needs_an_act_grant`: signing in as a member needs an active act grant to the org; `user_not_impersonable`: only a live member of the org who holds no staff role, and not the caller, can be signed in as.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "impersonation_needs_an_act_grant", "user_not_impersonable" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.user.impersonate", "contract": 2, "ticket": "TRA-320", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/impersonate_user" }, "x-tradehq-errors": "declared" } }, "/v1/cap/import_units": { "post": { "operationId": "import_units", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`, or by a role held on the unit `parent_id` or any unit above it by a member of that org; without `parent_id`, by the template); staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportUnitsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportUnitsResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportUnitsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-311", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/import_units" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/import_users": { "post": { "operationId": "import_users", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportUsersInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportUsersResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportUsersResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-319", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/import_users" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/invite_guest": { "post": { "operationId": "invite_guest", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`, which owns the document `document_kind`/`document_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteGuestInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteGuestResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteGuestResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-322", "authority": "act", "shape": "entity", "tenancy": "controlled-share", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/invite_guest" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/invite_user": { "post": { "operationId": "invite_user", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUserInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUserResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUserResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-319", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/invite_user" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/list_access_reviews": { "post": { "operationId": "list_access_reviews", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccessReviewsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccessReviewsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.access_review.list", "contract": 2, "ticket": "TRA-491", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_access_reviews" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 1000, "walk_max": 1000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_account_members": { "post": { "operationId": "list_account_members", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.member (account role member or higher in at least one account; the call is scoped to those accounts); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccountMembersInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccountMembersResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.account_member.list", "contract": 2, "ticket": "TRA-471", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_account_members" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 200, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_accounts": { "post": { "operationId": "list_accounts", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id` names; with no `org_id`, unsatisfiable); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccountsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAccountsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-314", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_accounts" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_agent_reads": { "post": { "operationId": "list_agent_reads", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentReadsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentReadsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.agent_read.list", "contract": 2, "ticket": "TRA-879", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_agent_reads" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 200, "walk_max": 200, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_announcements": { "post": { "operationId": "list_announcements", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAnnouncementsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAnnouncementsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-335", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_announcements" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_api_keys": { "post": { "operationId": "list_api_keys", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); api_key.read (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiKeysInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiKeysResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-321", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_api_keys" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_audit_events": { "post": { "operationId": "list_audit_events", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in the account of the org `org_id`); org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditEventsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditEventsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.audit_event.list", "contract": 2, "ticket": "TRA-333", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_audit_events" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 200, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_audit_exports": { "post": { "operationId": "list_audit_exports", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in the account of the org `org_id`); org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditExportsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditExportsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.audit_export.list", "contract": 2, "ticket": "TRA-500", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_audit_exports" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 50, "walk_max": 1000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_beta_lists": { "post": { "operationId": "list_beta_lists", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBetaListsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBetaListsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-1461", "authority": "read", "shape": "collection", "tenancy": "canonical-registry", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_beta_lists" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_beta_members": { "post": { "operationId": "list_beta_members", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBetaMembersInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBetaMembersResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-243", "authority": "read", "shape": "collection", "tenancy": "canonical-registry", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_beta_members" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_capability_events": { "post": { "operationId": "list_capability_events", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCapabilityEventsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCapabilityEventsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.capability_event.list", "contract": 2, "ticket": "TRA-804", "authority": "read", "shape": "collection", "tenancy": "canonical-registry", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_capability_events" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 200, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_catalog": { "post": { "operationId": "list_catalog", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCatalogInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCatalogResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `walk_ceiling_reached`: the cursor walk has answered 10,000 rows, the most one walk answers.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "walk_ceiling_reached" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.catalog.list", "contract": 2, "ticket": "TRA-674", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_catalog" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": "after", "next": "next_after", "page_max": 500, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_data_fields": { "post": { "operationId": "list_data_fields", "summary": "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.\n\nWho may call it: any one of: role.read (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDataFieldsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDataFieldsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.data_field.list", "contract": 2, "ticket": "TRA-492", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_data_fields" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 4, "walk_max": 4, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_data_shares": { "post": { "operationId": "list_data_shares", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); counterparty (org.member carried by the caller's role template in an org that holds a seat on the document; it reads its own seat); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDataSharesInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDataSharesResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-313", "authority": "read", "shape": "collection", "tenancy": "controlled-share", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_data_shares" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_depot_references": { "post": { "operationId": "list_depot_references", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDepotReferencesInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDepotReferencesResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.depot_reference.list", "contract": 2, "ticket": "TRA-477", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_depot_references" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 200, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_depot_registry": { "post": { "operationId": "list_depot_registry", "summary": "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).\n\nWho may call it: any one of: any.authenticated (any signed-in caller with a user row; a read of a registry every tenant sees the same); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDepotRegistryInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDepotRegistryResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-310", "authority": "read", "shape": "collection", "tenancy": "canonical-registry", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_depot_registry" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_devices": { "post": { "operationId": "list_devices", "summary": "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.\n\nWho may call it: any one of: self.read (the signed-in caller, about themself only; it names no other user); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDevicesInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDevicesResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-297", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_devices" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_document_parties": { "post": { "operationId": "list_document_parties", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`, which owns the document `document_kind`/`document_id`); counterparty (org.member carried by the caller's role template in an org that holds a seat on the document; it reads its own seat); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDocumentPartiesInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDocumentPartiesResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-312", "authority": "read", "shape": "collection", "tenancy": "controlled-share", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_document_parties" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_domains": { "post": { "operationId": "list_domains", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDomainsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDomainsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.org_domain.list", "contract": 2, "ticket": "TRA-464", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_domains" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 1000, "walk_max": 1000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_files": { "post": { "operationId": "list_files", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFilesInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFilesResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.file.list", "contract": 2, "ticket": "TRA-884", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_files" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 200, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_flag_actions": { "post": { "operationId": "list_flag_actions", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFlagActionsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFlagActionsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-243", "authority": "read", "shape": "collection", "tenancy": "canonical-registry", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_flag_actions" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_flag_staff": { "post": { "operationId": "list_flag_staff", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFlagStaffInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFlagStaffResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-1488", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_flag_staff" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_flags": { "post": { "operationId": "list_flags", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFlagsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFlagsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-243", "authority": "read", "shape": "collection", "tenancy": "canonical-registry", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_flags" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_fx_rates": { "post": { "operationId": "list_fx_rates", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFxRatesInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFxRatesResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-315", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_fx_rates" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_granted_capabilities": { "post": { "operationId": "list_granted_capabilities", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGrantedCapabilitiesInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGrantedCapabilitiesResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `capability_not_released`: the release-grant-capability flag is off for the caller; it may be turned on later.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "capability_not_released" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.capability_grant.list", "contract": 2, "ticket": "TRA-239", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_granted_capabilities" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 200, "walk_max": 200, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_guest_documents": { "post": { "operationId": "list_guest_documents", "summary": "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.\n\nWho may call it: any one of: org.guest (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGuestDocumentsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGuestDocumentsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-322", "authority": "read", "shape": "collection", "tenancy": "controlled-share", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_guest_documents" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_guests": { "post": { "operationId": "list_guests", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGuestsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGuestsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-322", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_guests" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_identity_findings": { "post": { "operationId": "list_identity_findings", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListIdentityFindingsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListIdentityFindingsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.identity_finding.list", "contract": 2, "ticket": "TRA-490", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_identity_findings" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 500, "walk_max": 500, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_inventory": { "post": { "operationId": "list_inventory", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInventoryInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInventoryResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `walk_ceiling_reached`: the cursor walk has answered 10,000 rows, the most one walk answers.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "walk_ceiling_reached" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.inventory.list", "contract": 2, "ticket": "TRA-589", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_inventory" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": "after", "next": "next_after", "page_max": 500, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_my_notifications": { "post": { "operationId": "list_my_notifications", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMyNotificationsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMyNotificationsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.notification_preference.list", "contract": 2, "ticket": "TRA-475", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_my_notifications" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 7, "walk_max": 7, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_org_grants": { "post": { "operationId": "list_org_grants", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgGrantsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgGrantsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.org_grant.list", "contract": 2, "ticket": "TRA-320", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_org_grants" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 1000, "walk_max": 1000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_orgs": { "post": { "operationId": "list_orgs", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.member (account role member or higher in at least one account; the call is scoped to those accounts); org.admin (carried by the caller's role template in the org `org_id` names; with no `org_id`, unsatisfiable); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListOrgsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-293", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_orgs" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_permissions": { "post": { "operationId": "list_permissions", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPermissionsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPermissionsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-317", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_permissions" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_portfolios": { "post": { "operationId": "list_portfolios", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in at least one account; the call is scoped to those accounts); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPortfoliosInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPortfoliosResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-470", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_portfolios" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_purchase_orders": { "post": { "operationId": "list_purchase_orders", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPurchaseOrdersInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPurchaseOrdersResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `walk_ceiling_reached`: the cursor walk has answered 10,000 rows, the most one walk answers.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "walk_ceiling_reached" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.purchase_orders.list", "contract": 2, "ticket": "TRA-1359", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_purchase_orders" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": "after", "next": "next_after", "page_max": 500, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_received_data_shares": { "post": { "operationId": "list_received_data_shares", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReceivedDataSharesInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReceivedDataSharesResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `org_party_unclaimed`: the org has claimed no party, so no share can reach it.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "org_party_unclaimed" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.data_share.list_received", "contract": 2, "ticket": "TRA-468", "authority": "read", "shape": "collection", "tenancy": "controlled-share", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_received_data_shares" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 1000, "walk_max": 1000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_report_opens": { "post": { "operationId": "list_report_opens", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReportOpensInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReportOpensResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.report_open.list", "contract": 2, "ticket": "TRA-1374", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_report_opens" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 13, "walk_max": 13, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_reports": { "post": { "operationId": "list_reports", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in at least one account; the call is scoped to those accounts); org.member (carried by the caller's role template in the org `org_id` names; with no `org_id`, unsatisfiable); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReportsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReportsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `walk_ceiling_reached`: the cursor walk has answered 10,000 rows, the most one walk answers.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "walk_ceiling_reached" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.customer_report.list", "contract": 2, "ticket": "TRA-1471", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_reports" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": "after", "next": "next_after", "page_max": 200, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_role_templates": { "post": { "operationId": "list_role_templates", "summary": "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.\n\nWho may call it: any one of: role.read (carried by the caller's role template in the org `org_id`); staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRoleTemplatesInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRoleTemplatesResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-317", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_role_templates" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_saved_views": { "post": { "operationId": "list_saved_views", "summary": "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).\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSavedViewsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSavedViewsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `too_many_views`: the caller may read more than 200 views of this capability in the org, the most one listing answers.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "too_many_views" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.saved_view.list", "contract": 2, "ticket": "TRA-590", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_saved_views" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 200, "walk_max": 200, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_service_accounts": { "post": { "operationId": "list_service_accounts", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); api_key.read (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListServiceAccountsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListServiceAccountsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.service_account.list", "contract": 2, "ticket": "TRA-493", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_service_accounts" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 1000, "walk_max": 1000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_sessions": { "post": { "operationId": "list_sessions", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSessionsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSessionsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `security_policy_unenforced`: the org's stored security settings do not parse; the step that applies them refuses the org's requests with the same code until a person restores them.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "security_policy_unenforced" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.session.list", "contract": 2, "ticket": "TRA-488", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_sessions" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 1000, "walk_max": 1000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_shared_catalog": { "post": { "operationId": "list_shared_catalog", "summary": "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).\n\nWho may call it: any one of: share.recipient (the caller is the user the recipient row named by share_inbound_id is addressed to, on a share the org made that is active, unexpired and not cancelled for them; no membership is asked); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSharedCatalogInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSharedCatalogResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `walk_ceiling_reached`: the cursor walk has answered 10,000 rows, the most one walk answers; `field_not_granted`: the fields asked for include a price the share does not show.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "walk_ceiling_reached", "field_not_granted" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.shared_catalog.list", "contract": 2, "ticket": "TRA-675", "authority": "read", "shape": "collection", "tenancy": "controlled-share", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_shared_catalog" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": "after", "next": "next_after", "page_max": 500, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_sso_connections": { "post": { "operationId": "list_sso_connections", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSsoConnectionsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSsoConnectionsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.sso_connection.list", "contract": 2, "ticket": "TRA-485", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_sso_connections" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 100, "walk_max": 100, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_staff": { "post": { "operationId": "list_staff", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListStaffInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListStaffResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-447", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_staff" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_staff_grants": { "post": { "operationId": "list_staff_grants", "summary": "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).\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); staff.any (any staff role held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListStaffGrantsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListStaffGrantsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-320", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_staff_grants" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_supplier_posts": { "post": { "operationId": "list_supplier_posts", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSupplierPostsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSupplierPostsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.supplier_post.list", "contract": 2, "ticket": "TRA-803", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_supplier_posts" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 100, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_switchable_orgs": { "post": { "operationId": "list_switchable_orgs", "summary": "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.\n\nWho may call it: any one of: self.read (the signed-in caller, about themself only; it names no other user); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSwitchableOrgsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSwitchableOrgsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-325", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_switchable_orgs" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_unit_access": { "post": { "operationId": "list_unit_access", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); org.member (carried by the caller's role template in the org `org_id`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUnitAccessInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUnitAccessResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unit_outside_caller`: You administer {your unit} and the units beneath it. {unit} is outside it.; `tree_too_large`: the org's unit tree holds more units than one listing reads.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unit_outside_caller", "tree_too_large" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.unit_role.list", "contract": 2, "ticket": "TRA-473", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_unit_access" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 200, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_units": { "post": { "operationId": "list_units", "summary": "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).\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`, or by a role held on the unit `root_id` or any unit above it by a member of that org; without `root_id`, by the template); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUnitsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUnitsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `tree_too_large`: the org's unit tree holds more units than one listing reads.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "tree_too_large" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.unit.list", "contract": 2, "ticket": "TRA-311", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_units" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 1000, "walk_max": 10000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_user_factors": { "post": { "operationId": "list_user_factors", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUserFactorsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUserFactorsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `security_policy_unenforced`: the stored mfa section does not parse.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "security_policy_unenforced" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.user_factor.list", "contract": 2, "ticket": "TRA-487", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_user_factors" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 5000, "walk_max": 5000, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/list_users": { "post": { "operationId": "list_users", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUsersInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUsersResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-319", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/list_users" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/mark_report_seen": { "post": { "operationId": "mark_report_seen", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkReportSeenInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkReportSeenResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkReportSeenResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `report_not_found`: no report by that id in that org is one the caller may get: it does not exist, it is another org's, or it is private to its reporter.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "report_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.customer_report.mark_seen", "contract": 2, "ticket": "TRA-1473", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/mark_report_seen" }, "x-tradehq-errors": "declared" } }, "/v1/cap/move_unit": { "post": { "operationId": "move_unit", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveUnitInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveUnitResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveUnitResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-311", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/move_unit" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/pin_view": { "post": { "operationId": "pin_view", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinViewInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinViewResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinViewResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_view`: the org has no view by that id that the caller may read; `view_read_only`: a system view, or a view the caller may read and not change: another member's, shared org-read; `org_pin_admin_only`: a pin for everyone in the org is made or removed only by an org admin; `view_not_shared_with_org`: a view is pinned for everyone only once its owner has shared it with the org, so no member is shown a card they cannot open.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_view", "view_read_only", "org_pin_admin_only", "view_not_shared_with_org" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.saved_view.pin", "contract": 2, "ticket": "TRA-1377", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/pin_view" }, "x-tradehq-errors": "declared" } }, "/v1/cap/post_production_status": { "post": { "operationId": "post_production_status", "summary": "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.\n\nWho may call it: any one of: org.guest (carried by the caller's role template in the org `org_id`, which owns the document `document_kind`/`document_id`); counterparty (org.member carried by the caller's role template in an org that holds a seat on the document; it reads its own seat); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostProductionStatusInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostProductionStatusResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostProductionStatusResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-323", "authority": "act", "shape": "entity", "tenancy": "controlled-share", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/post_production_status" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/preview_data_share": { "post": { "operationId": "preview_data_share", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); share (org.member carried by the caller's role template in an org that has claimed the share's party, for a stored share named by data_share_id that is not revoked or declined); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewDataShareInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewDataShareResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-313", "authority": "read", "shape": "entity", "tenancy": "controlled-share", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/preview_data_share" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/provision_account": { "post": { "operationId": "provision_account", "summary": "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.\n\nWho may call it: any one of: staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionAccountInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionAccountResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionAccountResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-328", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/provision_account" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/provision_sandbox": { "post": { "operationId": "provision_sandbox", "summary": "Provision a sandbox", "description": "Creates a public sandbox for anybody, signed in or not: a test-mode-only org with sample yards and containers and no live data, and one sk_test_ API key that reaches it. Both expire 14 days later, when the sandbox is purged. The answer carries the whole key in `secret` once: a retry with the same Idempotency-Key answers the same sandbox with `secret` null. Limited to a few sandboxes per client a day, and a ceiling for everybody an hour; past a limit the call is refused with 429 and creates nothing. Every answer names the sandbox, which is how a Trade HQ contact finds it to keep it as a company's account.\n\nWho may call it: any one of: anyone (anybody, signed in or not, on the dispatcher's anonymous path; limited by what the call creates); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionSandboxInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionSandboxResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionSandboxResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-332", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/provision_sandbox" }, "x-tradehq-errors": "not_declared", "security": [] } }, "/v1/cap/publish_announcement": { "post": { "operationId": "publish_announcement", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishAnnouncementInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishAnnouncementResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishAnnouncementResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-335", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/publish_announcement" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/purge_org": { "post": { "operationId": "purge_org", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeOrgInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeOrgResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeOrgResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `purge_dry_run_superseded`: a newer dry run replaced the one named; its approvals no longer count, so approve the current one; `purge_counts_changed`: the purge stopped on the dry run named because the counts changed, and deleted nothing; run a new dry run and approve again.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "purge_dry_run_superseded", "purge_counts_changed" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `countdown_running`: the 30 day deletion countdown has not ended; `org_not_scheduled`: the org has no deletion scheduled; `purge_dry_run_required`: no finished dry run by that id for the org's current deletion; run one and approve it once it has counted; `org_has_no_lifecycle`: the org has no lifecycle row: a ported org nothing has typed yet; `org_has_no_type`: the org has a lifecycle row and no type row; a person repairs it; `org_is_twin`: a test twin follows its live org; `org_declared`: the org is declared in db/tradehq/orgs.json and leaves by a reviewed change; `org_purged`: the org is purged; only its tombstone is left.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "countdown_running", "org_not_scheduled", "purge_dry_run_required", "org_has_no_lifecycle", "org_has_no_type", "org_is_twin", "org_declared", "org_purged" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.org.purge", "contract": 2, "ticket": "TRA-316", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/purge_org" }, "x-tradehq-errors": "declared" } }, "/v1/cap/record_gate_event": { "post": { "operationId": "record_gate_event", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordGateEventInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordGateEventResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordGateEventResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `retry_key_mismatch`: the Idempotency-Key was already used with a different report; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was recorded.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `capability_not_enabled`: record_gate_event is not switched on for this org yet (its release flag); `observed_before_occurred`: observed_at is before occurred_at; a movement is not learned of before it happens; `observed_in_future`: observed_at is later than now, past five minutes of clock skew; `unknown_depot`: the depot is not a yard of this org or a shared one.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "capability_not_enabled", "observed_before_occurred", "observed_in_future", "unknown_depot" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.gate_event.record", "contract": 2, "ticket": "TRA-456", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/record_gate_event" }, "x-tradehq-errors": "declared" } }, "/v1/cap/record_report_open": { "post": { "operationId": "record_report_open", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordReportOpenInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordReportOpenResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordReportOpenResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `idempotency_key_reused`: this Idempotency-Key already recorded a different open, past the retry store's retention; `retry_key_mismatch`: the Idempotency-Key was already used with a different request; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was applied.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "idempotency_key_reused", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.report_open.record", "contract": 2, "ticket": "TRA-1374", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/record_report_open" }, "x-tradehq-errors": "declared" } }, "/v1/cap/reference_depot": { "post": { "operationId": "reference_depot", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceDepotInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceDepotResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferenceDepotResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-310", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/reference_depot" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/register_device": { "post": { "operationId": "register_device", "summary": "Register this device", "description": "Registers an app installation by proving it holds its key, and binds it to the signed-in user in the session's org. Takes the installation's P-256 public key, a challenge from POST /v1/device/challenge and the key's signature over the installation, the challenge and the user, and optionally an Expo push token, which replaces the device's previous one. An installation bound to another user is refused until they revoke it. An org admin may enroll a managed (shared) device, which reads only.\n\nWho may call it: any one of: self.act (the signed-in caller, about themself only; it names no other user); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterDeviceInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterDeviceResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterDeviceResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `public_key_invalid`: public_point is not the standard base64 of an uncompressed P-256 point on the curve; `challenge_invalid`: the challenge was not issued to the caller for this installation, is spent, or has expired; ask for a fresh one; `signature_invalid`: the signature is not the installation key's over the installation, the challenge and the caller; `installation_bound_elsewhere`: the installation is bound to another user; it can be bound again only once they revoke it; `managed_requires_org_admin`: a managed (shared) device is enrolled only by an admin of the session's org; `managed_differs`: the installation is already bound to the caller with the other managed setting; revoke it and enroll it again; `unit_not_in_org`: unit_id is not a unit of the session's org; `push_token_invalid`: expo_push_token is not an Expo push token (ExponentPushToken[...]); `org_required`: the session has selected no org to bind the device in.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "public_key_invalid", "challenge_invalid", "signature_invalid", "installation_bound_elsewhere", "managed_requires_org_admin", "managed_differs", "unit_not_in_org", "push_token_invalid", "org_required" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.device.register", "contract": 2, "ticket": "TRA-297", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/register_device" }, "x-tradehq-errors": "declared" } }, "/v1/cap/reinstate_user": { "post": { "operationId": "reinstate_user", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in EVERY org the user `user_id` belongs to); account.owner (account role owner or higher in the account of EVERY org the user `user_id` belongs to; an org with no account blocks); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReinstateUserInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReinstateUserResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReinstateUserResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-319", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/reinstate_user" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/remove_account_member": { "post": { "operationId": "remove_account_member", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in at least one account; the call is scoped to those accounts); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveAccountMemberInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveAccountMemberResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveAccountMemberResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `last_account_owner`: the person is the account's only owner.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "last_account_owner" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.account_member.remove", "contract": 2, "ticket": "TRA-471", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/remove_account_member" }, "x-tradehq-errors": "declared" } }, "/v1/cap/remove_depot_reference": { "post": { "operationId": "remove_depot_reference", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveDepotReferenceInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveDepotReferenceResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveDepotReferenceResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.depot_reference.remove", "contract": 2, "ticket": "TRA-477", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/remove_depot_reference" }, "x-tradehq-errors": "declared" } }, "/v1/cap/remove_domain": { "post": { "operationId": "remove_domain", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveDomainInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveDomainResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveDomainResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `domain_in_use`: an SSO connection or Directory Sync directory still uses the domain.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "domain_in_use" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_domain`: the org neither has the domain nor ever removed it.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_domain" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.org_domain.remove", "contract": 2, "ticket": "TRA-464", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/remove_domain" }, "x-tradehq-errors": "declared" } }, "/v1/cap/reopen_report": { "post": { "operationId": "reopen_report", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReopenReportInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReopenReportResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReopenReportResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `retry_key_mismatch`: the Idempotency-Key was already used with a different reopen; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `report_not_found`: the org has no such report, or it is private to its reporter; `report_not_reopenable`: only a Fixed or Answered report is reported again; `reopen_not_filed`: the new report could not be filed just now; send it again with the same Idempotency-Key; `reports_unavailable`: this deployment has no broker credential for reports yet; nothing was sent.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "report_not_found", "report_not_reopenable", "reopen_not_filed", "reports_unavailable" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.customer_report.reopen", "contract": 2, "ticket": "TRA-1472", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/reopen_report" }, "x-tradehq-errors": "declared" } }, "/v1/cap/replay_event_delivery": { "post": { "operationId": "replay_event_delivery", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayEventDeliveryInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayEventDeliveryResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayEventDeliveryResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `event_not_found`: no capability event has that id.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "event_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.event_delivery.replay", "contract": 2, "ticket": "TRA-398", "authority": "act", "shape": "entity", "tenancy": "canonical-registry", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/replay_event_delivery" }, "x-tradehq-errors": "declared" } }, "/v1/cap/reply_to_report": { "post": { "operationId": "reply_to_report", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyToReportInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyToReportResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyToReportResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `retry_key_mismatch`: the Idempotency-Key was already used with a different reply; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `report_not_found`: the org has no such report, or it is private to its reporter; `reply_not_delivered`: the reply could not be delivered just now; send it again with the same Idempotency-Key; `reports_unavailable`: this deployment has no broker credential for reports yet; nothing was sent.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "report_not_found", "reply_not_delivered", "reports_unavailable" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.customer_report.reply", "contract": 2, "ticket": "TRA-1472", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/reply_to_report" }, "x-tradehq-errors": "declared" } }, "/v1/cap/request_staff_grant": { "post": { "operationId": "request_staff_grant", "summary": "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.\n\nWho may call it: any one of: staff.any (any staff role held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestStaffGrantInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestStaffGrantResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestStaffGrantResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `retry_key_mismatch`: the Idempotency-Key was already used with a different request; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was applied; `grant_already_pending`: a request from the caller to the org is still waiting on its admins; `grant_already_active`: the caller already holds an active grant to the org.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "idempotency_key_reused", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost", "grant_already_pending", "grant_already_active" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `grant_not_a_customer_org`: a grant is to a customer or demo org that is not a test twin; `grantee_already_a_member`: the caller is a member of the org and needs no grant; `org_untyped`: the org has no tradehq_org row, so the decision plane can record nothing against it.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "grant_not_a_customer_org", "grantee_already_a_member", "org_untyped" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.staff_grant.request", "contract": 2, "ticket": "TRA-320", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/request_staff_grant" }, "x-tradehq-errors": "declared" } }, "/v1/cap/reset_user_mfa": { "post": { "operationId": "reset_user_mfa", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in EVERY org the user `user_id` belongs to); account.owner (account role owner or higher in the account of EVERY org the user `user_id` belongs to; an org with no account blocks); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetUserMfaInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetUserMfaResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetUserMfaResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.user_mfa.reset", "contract": 2, "ticket": "TRA-487", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/reset_user_mfa" }, "x-tradehq-errors": "declared" } }, "/v1/cap/resolve_identity_finding": { "post": { "operationId": "resolve_identity_finding", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIdentityFindingInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIdentityFindingResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIdentityFindingResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `finding_not_found`: the org holds no such finding; `finding_resolved`: the finding was already resolved with another decision; `decision_not_offered`: the decision is not one the finding's kind offers; `role_template_required`: admit names the role template to admit with; `owner_not_admittable`: nobody is admitted as Owner from a finding; `permission_not_held`: the template, or the member's current one, carries a permission the caller's own role in the org does not; `unknown_role_template`: the template is neither shipped nor one of the org's; `directory_managed`: a directory manages the membership, so its role is the directory's; `no_trade_hq_user`: the Clerk user is no Trade HQ user, so there is nobody to admit; invite the person instead; `staff_may_only_remove`: staff may only remove.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "finding_not_found", "finding_resolved", "decision_not_offered", "role_template_required", "owner_not_admittable", "permission_not_held", "unknown_role_template", "directory_managed", "no_trade_hq_user", "staff_may_only_remove" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.identity_finding.resolve", "contract": 2, "ticket": "TRA-490", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/resolve_identity_finding" }, "x-tradehq-errors": "declared" } }, "/v1/cap/restore_security_policy": { "post": { "operationId": "restore_security_policy", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreSecurityPolicyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreSecurityPolicyResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreSecurityPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `policy_version_not_found`: the section's history holds no such version; `policy_not_enforceable`: the version is not the section's default and this build does not enforce the section yet, so restoring it would refuse every request of the org; `security_policy_unenforced`: a stored version of the section does not parse.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "policy_version_not_found", "policy_not_enforceable", "security_policy_unenforced" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.security_policy.restore", "contract": 2, "ticket": "TRA-565", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/restore_security_policy" }, "x-tradehq-errors": "declared" } }, "/v1/cap/resume_org": { "post": { "operationId": "resume_org", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeOrgInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeOrgResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeOrgResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `org_deletion_scheduled`: the org's deletion is counting down; cancel the deletion first (it returns the org to suspended), then resume it.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "org_deletion_scheduled" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `capability_not_enabled`: the capability's release flag is off for the caller; `org_has_no_lifecycle`: the org has no lifecycle row: a ported org nothing has typed yet; `org_has_no_type`: the org has a lifecycle row and no type row; a person repairs it; `org_is_twin`: a test twin follows its live org; `org_declared`: the org is declared in db/tradehq/orgs.json and leaves by a reviewed change; `org_purged`: the org is purged; only its tombstone is left.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "capability_not_enabled", "org_has_no_lifecycle", "org_has_no_type", "org_is_twin", "org_declared", "org_purged" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.org.resume", "contract": 2, "ticket": "TRA-479", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/resume_org" }, "x-tradehq-errors": "declared" } }, "/v1/cap/revoke_api_key": { "post": { "operationId": "revoke_api_key", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeApiKeyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeApiKeyResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeApiKeyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-321", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/revoke_api_key" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/revoke_capability_grant": { "post": { "operationId": "revoke_capability_grant", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeCapabilityGrantInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeCapabilityGrantResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeCapabilityGrantResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `capability_not_released`: the release-grant-capability flag is off for the caller; it may be turned on later; `grant_not_found`: the org has no grant with that id.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "capability_not_released", "grant_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.capability_grant.revoke", "contract": 2, "ticket": "TRA-239", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/revoke_capability_grant" }, "x-tradehq-errors": "declared" } }, "/v1/cap/revoke_data_share": { "post": { "operationId": "revoke_data_share", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeDataShareInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeDataShareResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeDataShareResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-313", "authority": "act", "shape": "entity", "tenancy": "controlled-share", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/revoke_data_share" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/revoke_device": { "post": { "operationId": "revoke_device", "summary": "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.\n\nWho may call it: any one of: self.act (the signed-in caller, about themself only; it names no other user); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeDeviceInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeDeviceResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeDeviceResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `binding_not_found`: no binding of the caller's has that id; another user's gets the same answer.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "binding_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.device.revoke", "contract": 2, "ticket": "TRA-297", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/revoke_device" }, "x-tradehq-errors": "declared" } }, "/v1/cap/revoke_grant": { "post": { "operationId": "revoke_grant", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); staff.any (any staff role held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeGrantInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeGrantResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeGrantResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `no_such_grant`: the org has no such grant; `org_untyped`: the org has no tradehq_org row, so the decision plane can record nothing against it.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_such_grant", "org_untyped" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.staff_grant.revoke", "contract": 2, "ticket": "TRA-320", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/revoke_grant" }, "x-tradehq-errors": "declared" } }, "/v1/cap/revoke_guest": { "post": { "operationId": "revoke_guest", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeGuestInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeGuestResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeGuestResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `not_a_guest`: the user is not and never was a guest of the org, or is a member of it under a member template.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "not_a_guest" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.guest.revoke", "contract": 2, "ticket": "TRA-465", "authority": "act", "shape": "entity", "tenancy": "controlled-share", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/revoke_guest" }, "x-tradehq-errors": "declared" } }, "/v1/cap/revoke_sessions": { "post": { "operationId": "revoke_sessions", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeSessionsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeSessionsResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeSessionsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `session_not_found`: the session named is not one front-door has seen in the org.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "session_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.session.revoke", "contract": 2, "ticket": "TRA-488", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/revoke_sessions" }, "x-tradehq-errors": "declared" } }, "/v1/cap/revoke_staff_role": { "post": { "operationId": "revoke_staff_role", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeStaffRoleInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeStaffRoleResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeStaffRoleResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `last_staff_ops`: the user is the last active holder of staff_ops; grant it to someone else first.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "last_staff_ops" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.staff_role.revoke", "contract": 2, "ticket": "TRA-447", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/revoke_staff_role" }, "x-tradehq-errors": "declared" } }, "/v1/cap/revoke_unit_role": { "post": { "operationId": "revoke_unit_role", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); org.member (carried by the caller's role template in the org `org_id`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeUnitRoleInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeUnitRoleResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeUnitRoleResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `own_access`: You can't change your own access. Another admin can.; `unit_outside_caller`: You administer {your unit} and the units beneath it. {unit} is outside it.; `holder_above_caller`: {Name}'s role on {unit} carries {permission}, which you don't hold there.; `tree_too_large`: the org's unit tree holds more units than one call reads.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "own_access", "unit_outside_caller", "holder_above_caller", "tree_too_large" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.unit_role.revoke", "contract": 2, "ticket": "TRA-473", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/revoke_unit_role" }, "x-tradehq-errors": "declared" } }, "/v1/cap/roll_back_flag": { "post": { "operationId": "roll_back_flag", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollBackFlagInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollBackFlagResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollBackFlagResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-243", "authority": "act", "shape": "entity", "tenancy": "canonical-registry", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/roll_back_flag" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/rotate_api_key": { "post": { "operationId": "rotate_api_key", "summary": "Rotate an API key", "description": "Issues a successor to one of the org's API keys, with the same name, mode, API version and limits, and keeps the old key working for an overlap window (24 hours unless overlap_hours says otherwise) so the integration can switch without a gap. The answer carries the successor's whole key in `secret` ONCE. A BK_ key's successor is an sk_live_ key. The successor carries its predecessor's grants (TRA-619). Send an Idempotency-Key header: a retry with the same key and inputs answers the same successor, without its secret.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateApiKeyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateApiKeyResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateApiKeyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-321", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/rotate_api_key" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/route_held_file": { "post": { "operationId": "route_held_file", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteHeldFileInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteHeldFileResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteHeldFileResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `held_object_missing`: the intake holds no object for this held file, neither held nor back at its holding key.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "held_object_missing" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `files_unavailable`: this deployment has no intake or files store configured yet; `org_is_a_test_twin`: the org is a test twin; files belong to its live org.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "files_unavailable", "org_is_a_test_twin" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.file.route_held", "contract": 2, "ticket": "TRA-884", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/route_held_file" }, "x-tradehq-errors": "declared" } }, "/v1/cap/run_identity_reconcile": { "post": { "operationId": "run_identity_reconcile", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunIdentityReconcileInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunIdentityReconcileResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunIdentityReconcileResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `retry_key_mismatch`: the Idempotency-Key was already used for another org; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was queued.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.identity_reconcile.run", "contract": 2, "ticket": "TRA-490", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/run_identity_reconcile" }, "x-tradehq-errors": "declared" } }, "/v1/cap/run_purge_dry_run": { "post": { "operationId": "run_purge_dry_run", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPurgeDryRunInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPurgeDryRunResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPurgeDryRunResponse" } } } }, "202": { "description": "accepted: an async contract's call has started", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPurgeDryRunResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `purge_dry_run_running`: a dry run of this org is still counting; wait for it to land; `idempotency_key_reused`: this Idempotency-Key already made a dry run of another org, or by someone else; `retry_key_mismatch`: the Idempotency-Key was already used with different inputs; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; no dry run was made.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "purge_dry_run_running", "idempotency_key_reused", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `capability_not_enabled`: the capability's release flag is off for the caller; `org_not_scheduled`: the org has no deletion scheduled, so there is no purge to count; `org_has_no_lifecycle`: the org has no lifecycle row: a ported org nothing has typed yet; `org_has_no_type`: the org has a lifecycle row and no type row; a person repairs it; `org_is_twin`: a test twin follows its live org; `org_declared`: the org is declared in db/tradehq/orgs.json and leaves by a reviewed change; `org_purged`: the org is purged; only its tombstone is left.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "capability_not_enabled", "org_not_scheduled", "org_has_no_lifecycle", "org_has_no_type", "org_is_twin", "org_declared", "org_purged" ] }, "429": { "description": "A rate limit is reached. Platform codes: `rate_limited`: the API key's rate limit is reached. This capability's codes: `purge_dry_run_busy`: as many dry runs as front-door counts at once are counting or waiting; try again in a minute.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "rate_limited", "purge_dry_run_busy" ] }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.org.purge_dry_run", "contract": 2, "ticket": "TRA-467", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "async", "reference": "https://containertradehq.com/docs/capabilities/run_purge_dry_run" }, "x-tradehq-errors": "declared" } }, "/v1/cap/save_view": { "post": { "operationId": "save_view", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveViewInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveViewResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveViewResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `idempotency_key_reused`: this Idempotency-Key already saved a different view, past the retry store's retention; `retry_key_mismatch`: the Idempotency-Key was already used with a different request; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was applied.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "idempotency_key_reused", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_view`: the org has no view by that id that the caller may read; `view_read_only`: a system view, or a view the caller may read and not change: another member's, shared org-read.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_view", "view_read_only" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.saved_view.save", "contract": 2, "ticket": "TRA-590", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/save_view" }, "x-tradehq-errors": "declared" } }, "/v1/cap/schedule_org_deletion": { "post": { "operationId": "schedule_org_deletion", "summary": "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.\n\nWho may call it: any one of: account.owner (account role owner or higher in the account of the org `org_id`); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleOrgDeletionInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleOrgDeletionResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleOrgDeletionResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-316", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/schedule_org_deletion" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/search_party_directory": { "post": { "operationId": "search_party_directory", "summary": "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).\n\nWho may call it: any one of: any.authenticated (any signed-in caller with a user row; a read of a registry every tenant sees the same); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPartyDirectoryInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPartyDirectoryResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-310", "authority": "read", "shape": "collection", "tenancy": "canonical-registry", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/search_party_directory" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/search_records": { "post": { "operationId": "search_records", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRecordsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRecordsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.record.search", "contract": 2, "ticket": "TRA-1373", "authority": "read", "shape": "collection", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/search_records" }, "x-tradehq-errors": "declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": 50, "walk_max": 50, "ceiling": "declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/send_feedback": { "post": { "operationId": "send_feedback", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendFeedbackInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendFeedbackResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendFeedbackResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `retry_key_mismatch`: the Idempotency-Key was already used with a different report; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `feedback_unavailable`: this deployment has no broker credential for feedback yet; nothing was sent; `bad_page`: page is not a path in the app (/...); `feedback_not_filed`: the report could not be filed just now; send it again with the same Idempotency-Key.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "feedback_unavailable", "bad_page", "feedback_not_filed" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.feedback.send", "contract": 2, "ticket": "TRA-957", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/send_feedback" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_account_role": { "post": { "operationId": "set_account_role", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in at least one account; the call is scoped to those accounts); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAccountRoleInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAccountRoleResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAccountRoleResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `last_account_owner`: the change would leave the account with no owner; `account_person_not_in_entity`: the person is a member of none of the account's entities; `user_deactivated`: the person is deactivated, so they are neither added nor made an owner.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "last_account_owner", "account_person_not_in_entity", "user_deactivated" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.account_member.set_role", "contract": 2, "ticket": "TRA-471", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_account_role" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_acting_scope": { "post": { "operationId": "set_acting_scope", "summary": "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.\n\nWho may call it: any one of: self.act (the signed-in caller, about themself only; it names no other user); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetActingScopeInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetActingScopeResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetActingScopeResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-327", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_acting_scope" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/set_api_key_limits": { "post": { "operationId": "set_api_key_limits", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetApiKeyLimitsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetApiKeyLimitsResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetApiKeyLimitsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-321", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_api_key_limits" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/set_api_key_version": { "post": { "operationId": "set_api_key_version", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetApiKeyVersionInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetApiKeyVersionResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetApiKeyVersionResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `api_key_not_found`: the org has no API key by that id; `api_key_is_legacy`: a BK_ key has no pin and follows the current version; rotate it into an sk_live_ key and pin that; `api_key_not_active`: the key is revoked, and a revoked key is never accepted whatever its pin; `unknown_api_version`: the version is not one this API serves; a key pinned to it would be refused on every request.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "api_key_not_found", "api_key_is_legacy", "api_key_not_active", "unknown_api_version" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.api_key.set_version", "contract": 2, "ticket": "TRA-620", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_api_key_version" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_beta_list_member": { "post": { "operationId": "set_beta_list_member", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBetaListMemberInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBetaListMemberResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBetaListMemberResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-243", "authority": "act", "shape": "entity", "tenancy": "canonical-registry", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_beta_list_member" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/set_catalog_price": { "post": { "operationId": "set_catalog_price", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCatalogPriceInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCatalogPriceResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCatalogPriceResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `retry_key_mismatch`: the Idempotency-Key was already used with a different request; `retry_key_in_flight`: a request with this Idempotency-Key is still running; `retry_key_lost`: another request took over this Idempotency-Key first; nothing was applied.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "retry_key_mismatch", "retry_key_in_flight", "retry_key_lost" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_catalog_line`: catalog_id names no line of this org's catalog; `empty_catalog_group`: group_key covers no line of this org's catalog; `price_ceiling_reached`: group_key covers more than 10,000 catalog lines, the most one call prices.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_catalog_line", "empty_catalog_group", "price_ceiling_reached" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.catalog.price", "contract": 2, "ticket": "TRA-1381", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_catalog_price" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_customer_stage": { "post": { "operationId": "set_customer_stage", "summary": "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.\n\nWho may call it: any one of: staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCustomerStageInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCustomerStageResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCustomerStageResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `org_not_customer`: the org is not a customer org: an internal, demo, synthetic or system org reads as Internal in Linear whatever its stage, so it has none; `org_is_twin`: a test twin follows its live org; set the live org's stage; `org_has_no_type`: the org has no type row: a ported org nothing has typed yet.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "org_not_customer", "org_is_twin", "org_has_no_type" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.org_customer_stage.set", "contract": 2, "ticket": "TRA-1273", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_customer_stage" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_data_policy": { "post": { "operationId": "set_data_policy", "summary": "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.\n\nWho may call it: any one of: role.manage (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDataPolicyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDataPolicyResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDataPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_role_template`: the role template is neither shipped nor one of this org's own; `shipped_template_read_only`: a shipped role template's data policy is read-only; clone the template and set the clone's; `record_scope_not_built`: unit_subtree and portfolio narrow nothing yet; use whole_org; `record_scope_locked`: a Counterparty template is locked to its party's seat; `party_seat_needs_a_counterparty_template`: only a Counterparty template's members hold a party whose seats a data policy can scope to; `org_admin_required`: until step-up assurance exists (TRA-487), changing a data policy takes a role template carrying org.admin as well as role.manage.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_role_template", "shipped_template_read_only", "record_scope_not_built", "record_scope_locked", "party_seat_needs_a_counterparty_template", "org_admin_required" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.data_policy.set", "contract": 2, "ticket": "TRA-492", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_data_policy" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_document_parties": { "post": { "operationId": "set_document_parties", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`, which owns the document `document_kind`/`document_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDocumentPartiesInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDocumentPartiesResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDocumentPartiesResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-312", "authority": "act", "shape": "entity", "tenancy": "controlled-share", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_document_parties" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/set_domain_join_policy": { "post": { "operationId": "set_domain_join_policy", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDomainJoinPolicyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDomainJoinPolicyResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDomainJoinPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-321", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_domain_join_policy" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/set_flag_lists": { "post": { "operationId": "set_flag_lists", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFlagListsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFlagListsResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFlagListsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-1461", "authority": "act", "shape": "entity", "tenancy": "canonical-registry", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_flag_lists" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/set_fx_rate_override": { "post": { "operationId": "set_fx_rate_override", "summary": "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.\n\nWho may call it: any one of: account.finance (admits nobody until an account finance role in tradehq_identity.account_member); staff.finance (the staff role staff_finance held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFxRateOverrideInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFxRateOverrideResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFxRateOverrideResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-315", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_fx_rate_override" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/set_ip_allowlist": { "post": { "operationId": "set_ip_allowlist", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetIpAllowlistInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetIpAllowlistResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetIpAllowlistResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `enforce_unavailable`: enforce mode is not available on this deployment until front-door's ingress self-check is true: the origin is reachable through Cloudflare only and Cloudflare's client address is authenticated; `caller_not_allowed`: enforce mode is refused while the caller's own address is outside the list: add it first; `network_policy_invalid`: the list is not one the section can hold: a mode other than off names at least one range; `security_policy_unenforced`: the stored network section does not parse.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "enforce_unavailable", "caller_not_allowed", "network_policy_invalid", "security_policy_unenforced" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.ip_allowlist.set", "contract": 2, "ticket": "TRA-489", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_ip_allowlist" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_maintenance_banner": { "post": { "operationId": "set_maintenance_banner", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMaintenanceBannerInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMaintenanceBannerResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMaintenanceBannerResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-335", "authority": "act", "shape": "entity", "tenancy": "canonical-registry", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_maintenance_banner" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/set_member_role": { "post": { "operationId": "set_member_role", "summary": "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.\n\nWho may call it: any one of: account.owner (account role owner or higher in the account of the org `org_id`); org.admin (carried by the caller's role template in the org `org_id`); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMemberRoleInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMemberRoleResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMemberRoleResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-319", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_member_role" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/set_mfa_policy": { "post": { "operationId": "set_mfa_policy", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMfaPolicyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMfaPolicyResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMfaPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `mfa_policy_invalid`: required_for_templates names no template, or templates are named for another mode; `role_template_unknown`: a template named is neither a shipped role template nor one of this org's own; `security_policy_unenforced`: the stored mfa section does not parse.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "mfa_policy_invalid", "role_template_unknown", "security_policy_unenforced" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.mfa_policy.set", "contract": 2, "ticket": "TRA-487", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_mfa_policy" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_my_notification": { "post": { "operationId": "set_my_notification", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMyNotificationInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMyNotificationResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMyNotificationResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `notice_required`: the notice reaches the caller whatever they choose: fixed in code for an org admin, or required by the org's notification settings; `notice_not_visible`: the caller's role cannot see what this notice is about, so it cannot be added; `cadence_is_digest_only`: a cadence was sent for a notice kind that is not sent on a schedule: only the audit log digest and Report updates are; `cadence_not_offered`: the cadence is not one this kind is sent on: hourly or daily for the audit log digest; immediately, daily or weekly for Report updates.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "notice_required", "notice_not_visible", "cadence_is_digest_only", "cadence_not_offered" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.notification_preference.set", "contract": 2, "ticket": "TRA-475", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_my_notification" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_my_settings": { "post": { "operationId": "set_my_settings", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMySettingsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMySettingsResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMySettingsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `setting_locked`: the platform, the org's account or the org locked this key.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "setting_locked" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.my_settings.set", "contract": 2, "ticket": "TRA-1369", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_my_settings" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_my_view_default": { "post": { "operationId": "set_my_view_default", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMyViewDefaultInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMyViewDefaultResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMyViewDefaultResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_view`: the org has no view by that id that the caller may read.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_view" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.view_default.set_mine", "contract": 2, "ticket": "TRA-1382", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_my_view_default" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_notification_policy": { "post": { "operationId": "set_notification_policy", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetNotificationPolicyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetNotificationPolicyResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetNotificationPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `cadence_is_digest_only`: a cadence was sent for a notice kind other than the audit log digest; `invalid_email`: an outside recipient is not an email address; `invalid_slack_webhook`: a Slack channel's URL is not an incoming webhook, or its id is not one the org already holds; `unknown_member`: a member recipient is not a current member of the org.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "cadence_is_digest_only", "invalid_email", "invalid_slack_webhook", "unknown_member" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.notification_policy.set", "contract": 2, "ticket": "TRA-475", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_notification_policy" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_org_view_default": { "post": { "operationId": "set_org_view_default", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetOrgViewDefaultInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetOrgViewDefaultResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetOrgViewDefaultResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_view`: the org has no view by that id that the caller may read; `view_not_shared`: an org default is a view every member can open: shared org-read or org-write.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_view", "view_not_shared" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.view_default.set_org", "contract": 2, "ticket": "TRA-1382", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_org_view_default" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_portfolio_members": { "post": { "operationId": "set_portfolio_members", "summary": "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.\n\nWho may call it: any one of: staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in the account that owns the portfolio `portfolio_id`; a portfolio with no account is staff's); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPortfolioMembersInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPortfolioMembersResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPortfolioMembersResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-314", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_portfolio_members" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/set_session_mode": { "post": { "operationId": "set_session_mode", "summary": "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.\n\nWho may call it: any one of: self.read (the signed-in caller, about themself only; it names no other user); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSessionModeInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSessionModeResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSessionModeResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-309", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_session_mode" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/set_session_policy": { "post": { "operationId": "set_session_policy", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSessionPolicyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSessionPolicyResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSessionPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `security_policy_unenforced`: the org's stored session section does not parse; restore it first.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "security_policy_unenforced" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.session_policy.set", "contract": 2, "ticket": "TRA-488", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_session_policy" }, "x-tradehq-errors": "declared" } }, "/v1/cap/set_sso_policy": { "post": { "operationId": "set_sso_policy", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSsoPolicyInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSsoPolicyResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSsoPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `connection_not_found`: the org has no such connection; `connection_not_active`: SSO cannot be required through a connection that is not active: nobody at the domain could sign in; `jit_needs_template`: just-in-time membership needs a default role template; `owner_not_assignable`: the Owner role template is never given by a sign-in; `unknown_role_template`: the role template is neither shipped nor one of this org's; `permission_not_held`: the role template carries a permission the caller's own role in this org does not; `bypass_owner_only`: only the account owner or a holder of the Owner role template may allow magic link and passkey during an IdP outage; `sso_not_required`: the domain does not require SSO, so there is nothing to bypass; `security_policy_unenforced`: the stored sso section does not parse.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "connection_not_found", "connection_not_active", "jit_needs_template", "owner_not_assignable", "unknown_role_template", "permission_not_held", "bypass_owner_only", "sso_not_required", "security_policy_unenforced" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.sso_policy.set", "contract": 2, "ticket": "TRA-485", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/set_sso_policy" }, "x-tradehq-errors": "declared" } }, "/v1/cap/share_view": { "post": { "operationId": "share_view", "summary": "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).\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareViewInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareViewResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareViewResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `unknown_view`: the org has no view by that id that the caller may read; `view_not_yours`: the caller reads the view and is not its owner, who alone shares it; or it is a system view, which nobody owns; `not_a_teammate`: a person named to share with is not a member of the view's org.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unknown_view", "view_not_yours", "not_a_teammate" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.saved_view.share", "contract": 2, "ticket": "TRA-1377", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/share_view" }, "x-tradehq-errors": "declared" } }, "/v1/cap/step_back_flag": { "post": { "operationId": "step_back_flag", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepBackFlagInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepBackFlagResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepBackFlagResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-1461", "authority": "act", "shape": "entity", "tenancy": "canonical-registry", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/step_back_flag" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/submit_serial_batch": { "post": { "operationId": "submit_serial_batch", "summary": "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.\n\nWho may call it: any one of: org.guest (carried by the caller's role template in the org `org_id`, which owns the document `document_kind`/`document_id`); counterparty (org.member carried by the caller's role template in an org that holds a seat on the document; it reads its own seat); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitSerialBatchInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitSerialBatchResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitSerialBatchResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-323", "authority": "act", "shape": "collection", "tenancy": "controlled-share", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/submit_serial_batch" }, "x-tradehq-errors": "not_declared", "x-tradehq-pagination": { "cursor_input": null, "next": "next_after", "page_max": null, "walk_max": null, "ceiling": "not_declared", "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } } }, "/v1/cap/subscribe_audit": { "post": { "operationId": "subscribe_audit", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeAuditInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeAuditResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeAuditResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `cadence_is_digest_only`: a cadence was sent for a Slack subscription; only a digest has one; `invalid_slack_webhook`: the destination is not a Slack incoming webhook URL; `invalid_email`: the destination is not an email address a digest can be sent to.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "cadence_is_digest_only", "invalid_slack_webhook", "invalid_email" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.audit_subscription.set", "contract": 2, "ticket": "TRA-333", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/subscribe_audit" }, "x-tradehq-errors": "declared" } }, "/v1/cap/summarize_catalog": { "post": { "operationId": "summarize_catalog", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeCatalogInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeCatalogResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `group_ceiling_reached`: the filters select more than 50,000 lines, the most one grouped read groups.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "group_ceiling_reached" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.catalog.summarize", "contract": 2, "ticket": "TRA-674", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/summarize_catalog" }, "x-tradehq-errors": "declared" } }, "/v1/cap/summarize_inventory": { "post": { "operationId": "summarize_inventory", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeInventoryInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeInventoryResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.inventory.summarize", "contract": 2, "ticket": "TRA-589", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/summarize_inventory" }, "x-tradehq-errors": "declared" } }, "/v1/cap/summarize_purchase_orders": { "post": { "operationId": "summarize_purchase_orders", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizePurchaseOrdersInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizePurchaseOrdersResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.purchase_orders.summarize", "contract": 2, "ticket": "TRA-1359", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/summarize_purchase_orders" }, "x-tradehq-errors": "declared" } }, "/v1/cap/summarize_reports": { "post": { "operationId": "summarize_reports", "summary": "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.\n\nWho may call it: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in at least one account; the call is scoped to those accounts); org.member (carried by the caller's role template in the org `org_id` names; with no `org_id`, unsatisfiable); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeReportsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeReportsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.customer_report.summarize", "contract": 2, "ticket": "TRA-1471", "authority": "read", "shape": "entity", "tenancy": "tenant-private", "idempotency": "safe", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/summarize_reports" }, "x-tradehq-errors": "declared" } }, "/v1/cap/suspend_org": { "post": { "operationId": "suspend_org", "summary": "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.\n\nWho may call it: any one of: account.owner (account role owner or higher in the account of the org `org_id`); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuspendOrgInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuspendOrgResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuspendOrgResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-316", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/suspend_org" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/switch_org": { "post": { "operationId": "switch_org", "summary": "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.\n\nWho may call it: any one of: self.act (the signed-in caller, about themself only; it names no other user); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchOrgInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchOrgResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchOrgResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `org_not_switchable`: the org is not one list_switchable_orgs returns for the caller; an org that does not exist gets the same answer; `session_required`: the call carries no signed-in session to move; `session_not_callers`: the session the call names is not one of the caller's.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "org_not_switchable", "session_required", "session_not_callers" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.org.switch", "contract": 2, "ticket": "TRA-472", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/switch_org" }, "x-tradehq-errors": "declared" } }, "/v1/cap/turn_off_flag": { "post": { "operationId": "turn_off_flag", "summary": "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.\n\nWho may call it: any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TurnOffFlagInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TurnOffFlagResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TurnOffFlagResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-1461", "authority": "act", "shape": "entity", "tenancy": "canonical-registry", "idempotency": "keyed", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/turn_off_flag" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/unfollow_report": { "post": { "operationId": "unfollow_report", "summary": "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.\n\nWho may call it: any one of: org.member (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnfollowReportInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnfollowReportResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnfollowReportResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `report_not_found`: no report by that id in that org is one the caller may get: it does not exist, it is another org's, or it is private to its reporter.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "report_not_found" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.customer_report.unfollow", "contract": 2, "ticket": "TRA-1473", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/unfollow_report" }, "x-tradehq-errors": "declared" } }, "/v1/cap/update_org_settings": { "post": { "operationId": "update_org_settings", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" }, { "name": "If-Match", "in": "header", "required": false, "description": "The version `expected_version` expects; the write is unconditional. A stale one is 409 version_conflict.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgSettingsInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgSettingsResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgSettingsResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `version_conflict`: the org's settings changed since the expected version; read them again.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "version_conflict" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `twin_mirrors_live`: the org is a test twin, whose settings are its live org's; `setting_not_overridable`: the platform does not let an org set this key; `setting_locked`: the platform or the org's account locked this key.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "twin_mirrors_live", "setting_not_overridable", "setting_locked" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.org_settings.update", "contract": 2, "ticket": "TRA-314", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/update_org_settings" }, "x-tradehq-errors": "declared" } }, "/v1/cap/update_role_template": { "post": { "operationId": "update_role_template", "summary": "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.\n\nWho may call it: any one of: role.manage (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleTemplateInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleTemplateResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleTemplateResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-448", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/update_role_template" }, "x-tradehq-errors": "not_declared" } }, "/v1/cap/update_service_account": { "post": { "operationId": "update_service_account", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateServiceAccountInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateServiceAccountResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateServiceAccountResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `service_account_not_found`: the org has no such service account; `service_account_disabled`: the account is disabled, which is final; `two_owners_required`: reassigning owners names both: the account would be left without a primary or a backup; `owners_must_differ`: the primary and the backup owner are the same person; `owner_not_active_member`: an owner is deactivated or not a member of the org; `role_template_not_assignable`: the role template is Owner, Admin, a guest's, or carries org.admin or role.manage; `unknown_role_template`: the role template is neither shipped nor the org's own; `permission_not_held`: the role template carries a permission the calling admin's own role does not.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "service_account_not_found", "service_account_disabled", "two_owners_required", "owners_must_differ", "owner_not_active_member", "role_template_not_assignable", "unknown_role_template", "permission_not_held" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.service_account.update", "contract": 2, "ticket": "TRA-493", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/update_service_account" }, "x-tradehq-errors": "declared" } }, "/v1/cap/update_sso_connection": { "post": { "operationId": "update_sso_connection", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSsoConnectionInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSsoConnectionResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSsoConnectionResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again. This capability's codes: `connection_not_created`: Clerk has not created the connection yet; try again shortly; `connection_required`: SSO is required through this connection, so it cannot be deactivated.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict", "connection_not_created", "connection_required" ] }, "422": { "description": "A rule of the capability refused the call. This capability's codes: `connection_not_found`: the org has no such connection; `metadata_required`: a connection is activated only once its IdP metadata is saved; `invalid_metadata`: IdP metadata is an https URL or XML, one of the two; `security_policy_unenforced`: the stored sso section does not parse.", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "connection_not_found", "metadata_required", "invalid_metadata", "security_policy_unenforced" ] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": "cap.sso_connection.update", "contract": 2, "ticket": "TRA-485", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/update_sso_connection" }, "x-tradehq-errors": "declared" } }, "/v1/cap/verify_domain": { "post": { "operationId": "verify_domain", "summary": "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.\n\nWho may call it: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first.", "parameters": [ { "$ref": "#/components/parameters/TradeHqVersion" } ], "requestBody": { "required": true, "description": "The capability's inputs, as one JSON object in the body (send {} for none).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyDomainInput" } } } }, "responses": { "200": { "description": "served, or the first call's result replayed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyDomainResponse" } } } }, "201": { "description": "created", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyDomainResponse" } } } }, "400": { "$ref": "#/components/responses/Platform400" }, "401": { "$ref": "#/components/responses/Platform401" }, "403": { "$ref": "#/components/responses/Platform403" }, "404": { "$ref": "#/components/responses/Platform404" }, "409": { "$ref": "#/components/responses/Platform409" }, "422": { "description": "A rule of the capability refused the call. This contract does not declare its codes yet (v1).", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [] }, "429": { "$ref": "#/components/responses/Platform429" }, "5XX": { "$ref": "#/components/responses/Platform5XX" } }, "x-tradehq-capability": { "id": null, "contract": 1, "ticket": "TRA-321", "authority": "act", "shape": "entity", "tenancy": "tenant-private", "idempotency": "natural", "execution": "sync", "reference": "https://containertradehq.com/docs/capabilities/verify_domain" }, "x-tradehq-errors": "not_declared" } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_... or sk_test_... (an organisation API key)", "description": "An organisation API key as a bearer token. sk_test_ acts in the org's test twin. NOT YET SERVED: authz.actor_kinds names api_key on no surface, so no key is admitted on /v1/cap until TRA-619 lands; this scheme is the contract that ticket serves.", "x-tradehq-served": false } }, "parameters": { "TradeHqVersion": { "name": "Trade-HQ-Version", "in": "header", "required": false, "description": "The API version, YYYY-MM-DD. the request's header, then the API key's pin, then the current version; every response says which served it in the same header.", "schema": { "type": "string", "enum": [ "2026-10-01" ] } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "headers": { "TradeHqVersion": { "description": "The version that served the response.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "TradeHqTraceId": { "description": "The request id: this call's trace id, also in traceparent.", "schema": { "type": "string" }, "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" }, "ETag": { "description": "on a contract with an expected version, the response's ETag is the version the call left; If-Match takes it back", "schema": { "type": "string" } } }, "responses": { "Platform400": { "description": "The request is malformed. Platform codes: `malformed_version`: Trade-HQ-Version must be a single date, YYYY-MM-DD, naming a version this API serves; the current version is 2026-10-01; `unknown_version`: Trade-HQ-Version YYYY-MM-DD is not a version this API serves; it serves 2026-10-01; `unknown_pinned_version`: this API key is pinned to YYYY-MM-DD, which this API no longer serves; send Trade-HQ-Version, or re-pin the key; `malformed_pinned_version`: this API key's pinned version is not a YYYY-MM-DD date; send Trade-HQ-Version, or re-pin the key to a supported version (the current version is 2026-10-01); `invalid_body`: the body is not JSON; `body_not_object`: the body must be a JSON object of this capability's inputs (send {} for none); it was an array; `invalid_input`: an input is missing, undeclared or not of its declared type; `idempotency_key_required`: this capability requires an Idempotency-Key header; `idempotency_key_invalid`: Idempotency-Key must be 1 to 255 characters of visible ASCII, space and tab, after surrounding whitespace is trimmed", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "malformed_version", "unknown_version", "unknown_pinned_version", "malformed_pinned_version", "invalid_body", "body_not_object", "invalid_input", "idempotency_key_required", "idempotency_key_invalid" ] }, "Platform401": { "description": "No usable credential. Platform codes: `unauthenticated`: authentication required; `invalid_credential`: invalid credential; `expired_token`: expired credential; `no_session`: no session; `service_account_expired`: the API key's service account has expired; `service_account_disabled`: the API key's service account is disabled; `service_account_suspended`: the API key's service account is suspended; `session_expired_policy`: this session has ended under the organisation's session policy; sign in again; `session_revoked`: this session has been signed out; sign in again", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unauthenticated", "invalid_credential", "expired_token", "no_session", "service_account_expired", "service_account_disabled", "service_account_suspended", "session_expired_policy", "session_revoked" ] }, "Platform403": { "description": "The caller may not make this call. Platform codes: `org_not_permitted`: organisation not permitted; `org_not_selected`: no organisation selected; `no_org_membership`: no organisation membership; `guest_not_permitted`: a guest of this organisation may read only their own documents; `read_only_credential`: this credential is read-only: it reaches /v1/graphql and /whoami and nothing else; `org_locked`: organisation suspended or scheduled for deletion; `system_org`: a system organisation is no person's organisation; `impersonation_not_permitted`: this impersonated session is no longer permitted; `sso_required`: this organisation requires single sign-on for your address; `ip_not_allowed`: your network is not allowed by your organization; `mfa_required`: this organisation requires a second factor: set one up, then sign in again; `key_not_granted`: this API key is not granted what this route needs; `membership_quarantined`: this membership is quarantined until an administrator reviews it; `capability_requires_user`: the capability plane is called by a signed-in user; `caller_deactivated`: the calling user is deactivated; `device_revoked`: this device has been revoked; `device_read_only`: a managed (shared) device reads; it acts on nothing; `capability_forbidden`: the caller may not call this capability on this target; `capability_not_entitled`: this org's plan does not include this capability; `reauthentication_required`: this act needs a second factor verified in the last 10 minutes: reverify, then send the same call again with the same Idempotency-Key", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "org_not_permitted", "org_not_selected", "no_org_membership", "guest_not_permitted", "read_only_credential", "org_locked", "system_org", "impersonation_not_permitted", "sso_required", "ip_not_allowed", "mfa_required", "key_not_granted", "membership_quarantined", "capability_requires_user", "caller_deactivated", "device_revoked", "device_read_only", "capability_forbidden", "capability_not_entitled", "reauthentication_required" ] }, "Platform404": { "description": "No such capability or target. Platform codes: `capability_not_found`: no capability is registered under that name; `target_not_found`: the target does not exist; `capability_not_released`: this capability is not released to this org", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "capability_not_found", "target_not_found", "capability_not_released" ] }, "Platform409": { "description": "The call conflicts with the target's state. Platform codes: `no_test_twin`: organisation has no test twin; `idempotency_key_reused`: the Idempotency-Key was sent before with other inputs; `version_conflict`: If-Match named a version the target is no longer at; read it again", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "no_test_twin", "idempotency_key_reused", "version_conflict" ] }, "Platform429": { "description": "A rate limit is reached. Platform codes: `rate_limited`: the API key's rate limit is reached", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "rate_limited" ], "x-tradehq-rate-limit-headers": { "x-tradehq-contract": "pending", "x-tradehq-contract-ticket": "TRA-620" } }, "Platform5XX": { "description": "The service could not answer. Platform codes: `unavailable`: dependency unavailable; `org_frozen`: organisation frozen for migration; `security_policy_unenforced`: the organisation's security policy cannot be applied; `org_frozen`: the target org is frozen for its cutover; `idempotency_input_missing`: the idempotency key's input is absent after validation; `unexpected_unique_violation`: the write violated the unique constraint , which is not the org id's; `unexpected_check_violation`: the write violated the check constraint ; `unavailable`: a dependency is unavailable; `internal`: an internal error", "headers": { "Trade-HQ-Version": { "$ref": "#/components/headers/TradeHqVersion" }, "trade-hq-trace-id": { "$ref": "#/components/headers/TradeHqTraceId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" } } }, "x-tradehq-codes": [ "unavailable", "org_frozen", "security_policy_unenforced", "org_frozen", "idempotency_input_missing", "unexpected_unique_violation", "unexpected_check_violation", "unavailable", "internal" ] } }, "schemas": { "Refusal": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string", "description": "the input a 400 invalid_input is about" }, "deny": { "type": "string", "description": "on a 403 about authority, the closed deny code (authz.deny_reasons' public codes)" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "AcknowledgePushInput": { "type": "object", "properties": { "push_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 push, as its deep link names it." } }, "required": [ "push_id" ], "additionalProperties": false }, "AcknowledgePushOutput": { "type": "object", "properties": { "push_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 push.", "x-data-class": "operational" }, "source_kind": { "type": "string", "enum": [ "capability_event", "exception" ], "description": "What it was about.", "x-data-class": "operational" }, "source_id": { "type": "string", "description": "The event's or the exception's id.", "x-data-class": "operational" }, "event_type": { "type": "string", "description": "The event's type, or exception.raised.", "x-data-class": "operational" } }, "required": [ "push_id", "source_kind", "source_id", "event_type" ], "additionalProperties": false }, "AcknowledgePushResponse": { "type": "object", "properties": { "capability": { "const": "acknowledge_push" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/AcknowledgePushOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "AddFileInput": { "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." } }, "required": [ "org_id", "name", "content_type", "content" ], "additionalProperties": false }, "AddFileOutput": { "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 }, "AddFileResponse": { "type": "object", "properties": { "capability": { "const": "add_file" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/AddFileOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "AdvanceFlagWaveInput": { "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." } }, "required": [ "flag_key", "from" ], "additionalProperties": false }, "AdvanceFlagWaveOutput": { "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 }, "AdvanceFlagWaveResponse": { "type": "object", "properties": { "capability": { "const": "advance_flag_wave" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/AdvanceFlagWaveOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "AnnounceDeprecatedVersionsInput": { "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." } }, "required": [ "release" ], "additionalProperties": false }, "AnnounceDeprecatedVersionsOutput": { "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 }, "AnnounceDeprecatedVersionsResponse": { "type": "object", "properties": { "capability": { "const": "announce_deprecated_versions" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/AnnounceDeprecatedVersionsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "AnonymizeUserInput": { "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." } }, "required": [ "user_id" ], "additionalProperties": false }, "AnonymizeUserOutput": { "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 }, "AnonymizeUserResponse": { "type": "object", "properties": { "capability": { "const": "anonymize_user" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/AnonymizeUserOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ApproveGrantInput": { "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)." } }, "required": [ "org_id", "grant_id", "decision" ], "additionalProperties": false }, "ApproveGrantOutput": { "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 }, "ApproveGrantResponse": { "type": "object", "properties": { "capability": { "const": "approve_grant" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ApproveGrantOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "BreakGlassAccessInput": { "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." } }, "required": [ "org_id", "reason" ], "additionalProperties": false }, "BreakGlassAccessOutput": { "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 }, "BreakGlassAccessResponse": { "type": "object", "properties": { "capability": { "const": "break_glass_access" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/BreakGlassAccessOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CancelOrgDeletionInput": { "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." } }, "required": [ "org_id" ], "additionalProperties": false }, "CancelOrgDeletionOutput": { "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 }, "CancelOrgDeletionResponse": { "type": "object", "properties": { "capability": { "const": "cancel_org_deletion" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CancelOrgDeletionOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CheckIpAllowlistInput": { "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 }, "CheckIpAllowlistOutput": { "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 }, "CheckIpAllowlistResponse": { "type": "object", "properties": { "capability": { "const": "check_ip_allowlist" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CheckIpAllowlistOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ClaimDepotInput": { "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." } }, "required": [ "org_id", "unit_id", "bfc" ], "additionalProperties": false }, "ClaimDepotOutput": { "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 }, "ClaimDepotResponse": { "type": "object", "properties": { "capability": { "const": "claim_depot" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ClaimDepotOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ClaimPartyInput": { "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." } }, "required": [ "org_id", "party_id", "name" ], "additionalProperties": false }, "ClaimPartyOutput": { "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 }, "ClaimPartyResponse": { "type": "object", "properties": { "capability": { "const": "claim_party" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ClaimPartyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CloneRoleTemplateInput": { "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." } }, "required": [ "org_id", "source", "title" ], "additionalProperties": false }, "CloneRoleTemplateOutput": { "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 }, "CloneRoleTemplateResponse": { "type": "object", "properties": { "capability": { "const": "clone_role_template" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CloneRoleTemplateOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CloseAccessReviewInput": { "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." } }, "required": [ "org_id", "review_id" ], "additionalProperties": false }, "CloseAccessReviewOutput": { "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 }, "CloseAccessReviewResponse": { "type": "object", "properties": { "capability": { "const": "close_access_review" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CloseAccessReviewOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CompleteUploadInput": { "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." }, "upload_id": { "type": "string", "minLength": 26, "maxLength": 26, "description": "The upload_id create_upload answered." } }, "required": [ "org_id", "upload_id" ], "additionalProperties": false }, "CompleteUploadOutput": { "type": "object", "properties": { "upload_id": { "type": "string", "description": "The upload.", "x-data-class": "operational" }, "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the file is for.", "x-data-class": "operational" }, "state": { "type": "string", "enum": [ "received", "filed", "held", "expired" ], "description": "received when it is waiting to be filed, then 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 declared.", "x-data-class": "operational" } }, "required": [ "upload_id", "org_id", "state", "size", "content_type" ], "additionalProperties": false }, "CompleteUploadResponse": { "type": "object", "properties": { "capability": { "const": "complete_upload" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CompleteUploadOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ConfirmPurchaseOrderInput": { "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." } }, "required": [ "org_id", "document_kind", "document_id", "lines" ], "additionalProperties": false }, "ConfirmPurchaseOrderOutput": { "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 }, "ConfirmPurchaseOrderResponse": { "type": "object", "properties": { "capability": { "const": "confirm_purchase_order" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ConfirmPurchaseOrderOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ConfirmReportInput": { "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." } }, "required": [ "org_id", "report_id" ], "additionalProperties": false }, "ConfirmReportOutput": { "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 }, "ConfirmReportResponse": { "type": "object", "properties": { "capability": { "const": "confirm_report" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ConfirmReportOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ConvertSandboxInput": { "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)." } }, "required": [ "org_id", "org_name", "admin_email" ], "additionalProperties": false }, "ConvertSandboxOutput": { "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 }, "ConvertSandboxResponse": { "type": "object", "properties": { "capability": { "const": "convert_sandbox" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ConvertSandboxOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CreateAccessReviewInput": { "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." } }, "required": [ "org_id", "name", "due_on" ], "additionalProperties": false }, "CreateAccessReviewOutput": { "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 }, "CreateAccessReviewResponse": { "type": "object", "properties": { "capability": { "const": "create_access_review" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CreateAccessReviewOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CreateAccountInput": { "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." } }, "required": [ "name" ], "additionalProperties": false }, "CreateAccountOutput": { "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 }, "CreateAccountResponse": { "type": "object", "properties": { "capability": { "const": "create_account" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CreateAccountOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CreateApiKeyInput": { "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 key acts for." }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "What the key is for, such as the integration that holds it." }, "service_account_id": { "type": "string", "minLength": 1, "maxLength": 14, "description": "The service account that owns the key: an active account of this org, made with create_service_account. The key acts as it." }, "mode": { "type": "string", "enum": [ "live", "test" ], "description": "The service account's mode, which is the default: live for an sk_live_ key, test for an sk_test_ key that reaches the org's test twin. A mode other than the account's is refused." }, "api_version": { "type": "string", "enum": [ "2026-10-01" ], "description": "The API version to pin the key to. Defaults to the version current today." }, "grants": { "type": "array", "items": { "type": "string", "enum": [ "org.admin", "org.member", "org.guest", "role.read", "role.manage", "api_key.read" ] }, "uniqueItems": true, "description": "What the key may do (TRA-619): org.member, role.read or api_key.read, each one you hold in the org and the service account's role template carries. Absent or empty, the key is granted nothing." }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "Days until the key stops working. Absent, it works until it is revoked or rotated." } }, "required": [ "org_id", "name", "service_account_id" ], "additionalProperties": false }, "CreateApiKeyOutput": { "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" }, "secret": { "type": [ "string", "null" ], "description": "The whole key, on the call that issued it and never again: it is stored nowhere, so a replay answers null.", "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", "secret" ], "additionalProperties": false }, "CreateApiKeyResponse": { "type": "object", "properties": { "capability": { "const": "create_api_key" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CreateApiKeyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CreateDataShareInput": { "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." } }, "required": [ "org_id", "party_id", "query", "recipients" ], "additionalProperties": false, "oneOf": [ { "properties": { "query": { "const": "vendor_bill_request" } }, "required": [ "query", "request_id" ], "not": { "anyOf": [ { "required": [ "contact_id" ] } ] } }, { "properties": { "query": { "const": "vendor_forecast" } }, "required": [ "query", "contact_id" ], "not": { "anyOf": [ { "required": [ "request_id" ] } ] } }, { "properties": { "query": { "const": "vendor_sell_through" } }, "required": [ "query", "contact_id" ], "not": { "anyOf": [ { "required": [ "request_id" ] } ] } } ] }, "CreateDataShareOutput": { "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 }, "CreateDataShareResponse": { "type": "object", "properties": { "capability": { "const": "create_data_share" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CreateDataShareOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CreateInviteLinkInput": { "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." } }, "required": [ "org_id" ], "additionalProperties": false }, "CreateInviteLinkOutput": { "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 }, "CreateInviteLinkResponse": { "type": "object", "properties": { "capability": { "const": "create_invite_link" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CreateInviteLinkOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CreateOrgInput": { "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." } }, "required": [ "name", "org_type" ], "additionalProperties": false }, "CreateOrgOutput": { "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 }, "CreateOrgResponse": { "type": "object", "properties": { "capability": { "const": "create_org" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CreateOrgOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CreatePortfolioInput": { "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." } }, "required": [ "name" ], "additionalProperties": false }, "CreatePortfolioOutput": { "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 }, "CreatePortfolioResponse": { "type": "object", "properties": { "capability": { "const": "create_portfolio" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CreatePortfolioOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CreateServiceAccountInput": { "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." } }, "required": [ "org_id", "name", "owner_user_id", "backup_owner_user_id", "role_template_id" ], "additionalProperties": false }, "CreateServiceAccountOutput": { "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 }, "CreateServiceAccountResponse": { "type": "object", "properties": { "capability": { "const": "create_service_account" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CreateServiceAccountOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CreateSsoConnectionInput": { "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." } }, "required": [ "org_id", "name", "protocol", "domain" ], "additionalProperties": false }, "CreateSsoConnectionOutput": { "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 }, "CreateSsoConnectionResponse": { "type": "object", "properties": { "capability": { "const": "create_sso_connection" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CreateSsoConnectionOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CreateUnitInput": { "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." } }, "required": [ "org_id", "kind", "name" ], "additionalProperties": false }, "CreateUnitOutput": { "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 }, "CreateUnitResponse": { "type": "object", "properties": { "capability": { "const": "create_unit" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CreateUnitOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "CreateUploadInput": { "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." }, "size": { "type": "integer", "minimum": 0, "maximum": 1125899906842624, "description": "The file's exact size in bytes; the link accepts no other. At most 5 GiB (5368709120)." }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The file's content type, such as application/pdf; the link accepts no other." }, "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." } }, "required": [ "org_id", "name", "size", "content_type" ], "additionalProperties": false }, "CreateUploadOutput": { "type": "object", "properties": { "upload_id": { "type": "string", "description": "The upload's id, for complete_upload.", "x-data-class": "operational" }, "org_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The org the file is for.", "x-data-class": "operational" }, "method": { "type": "string", "description": "Always PUT.", "x-data-class": "operational" }, "upload_url": { "type": "string", "description": "Where to PUT the bytes, with the content-length and content-type headers as declared.", "x-data-class": "operational" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the link stops accepting the PUT.", "x-data-class": "operational" }, "size": { "type": "integer", "description": "The size the link accepts.", "x-data-class": "operational" }, "content_type": { "type": "string", "description": "The content type the link accepts.", "x-data-class": "operational" } }, "required": [ "upload_id", "org_id", "method", "upload_url", "expires_at", "size", "content_type" ], "additionalProperties": false }, "CreateUploadResponse": { "type": "object", "properties": { "capability": { "const": "create_upload" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/CreateUploadOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "DeactivateUserInput": { "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." } }, "required": [ "user_id" ], "additionalProperties": false }, "DeactivateUserOutput": { "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 }, "DeactivateUserResponse": { "type": "object", "properties": { "capability": { "const": "deactivate_user" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/DeactivateUserOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "DecideAccessReviewItemInput": { "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." } }, "required": [ "org_id", "review_id", "item_id", "decision" ], "additionalProperties": false }, "DecideAccessReviewItemOutput": { "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 }, "DecideAccessReviewItemResponse": { "type": "object", "properties": { "capability": { "const": "decide_access_review_item" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/DecideAccessReviewItemOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "DeclineDataShareInput": { "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." } }, "required": [ "org_id", "data_share_id" ], "additionalProperties": false }, "DeclineDataShareOutput": { "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 }, "DeclineDataShareResponse": { "type": "object", "properties": { "capability": { "const": "decline_data_share" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/DeclineDataShareOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "DeleteFileInput": { "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 }, "DeleteFileOutput": { "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 }, "DeleteFileResponse": { "type": "object", "properties": { "capability": { "const": "delete_file" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/DeleteFileOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "DeleteRoleTemplateInput": { "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)." } }, "required": [ "org_id", "role_id" ], "additionalProperties": false }, "DeleteRoleTemplateOutput": { "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 }, "DeleteRoleTemplateResponse": { "type": "object", "properties": { "capability": { "const": "delete_role_template" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/DeleteRoleTemplateOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "DeleteSsoConnectionInput": { "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": [ "org_id", "connection_id" ], "additionalProperties": false }, "DeleteSsoConnectionOutput": { "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 }, "DeleteSsoConnectionResponse": { "type": "object", "properties": { "capability": { "const": "delete_sso_connection" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/DeleteSsoConnectionOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "DeleteViewInput": { "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." } }, "required": [ "org_id", "view_id" ], "additionalProperties": false }, "DeleteViewOutput": { "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 }, "DeleteViewResponse": { "type": "object", "properties": { "capability": { "const": "delete_view" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/DeleteViewOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "DisableServiceAccountInput": { "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." } }, "required": [ "org_id", "service_account_id" ], "additionalProperties": false }, "DisableServiceAccountOutput": { "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 }, "DisableServiceAccountResponse": { "type": "object", "properties": { "capability": { "const": "disable_service_account" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/DisableServiceAccountOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ExportAuditEventsInput": { "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)." } }, "required": [ "org_id" ], "additionalProperties": false }, "ExportAuditEventsOutput": { "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 }, "ExportAuditEventsResponse": { "type": "object", "properties": { "capability": { "const": "export_audit_events" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ExportAuditEventsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "FollowReportInput": { "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." } }, "required": [ "org_id", "report_id" ], "additionalProperties": false }, "FollowReportOutput": { "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 }, "FollowReportResponse": { "type": "object", "properties": { "capability": { "const": "follow_report" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/FollowReportOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetActingScopeInput": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "GetActingScopeOutput": { "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 }, "GetActingScopeResponse": { "type": "object", "properties": { "capability": { "const": "get_acting_scope" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetActingScopeOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetApiUsageInput": { "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 }, "GetApiUsageOutput": { "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 }, "GetApiUsageResponse": { "type": "object", "properties": { "capability": { "const": "get_api_usage" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetApiUsageOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetDataPolicyInput": { "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 }, "GetDataPolicyOutput": { "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 }, "GetDataPolicyResponse": { "type": "object", "properties": { "capability": { "const": "get_data_policy" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetDataPolicyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetFileInput": { "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 }, "GetFileOutput": { "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 }, "GetFileResponse": { "type": "object", "properties": { "capability": { "const": "get_file" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetFileOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetIdentitySyncInput": { "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 }, "GetIdentitySyncOutput": { "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 }, "GetIdentitySyncResponse": { "type": "object", "properties": { "capability": { "const": "get_identity_sync" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetIdentitySyncOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetImpersonationInput": { "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 impersonation is in." }, "impersonation_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 impersonation, as impersonate_user answered it." } }, "required": [ "org_id", "impersonation_id" ], "additionalProperties": false }, "GetImpersonationOutput": { "type": "object", "properties": { "impersonation_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 impersonation.", "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 in.", "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 is impersonated.", "x-data-class": "operational" }, "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 act grant that allows it.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "ready", "failed", "expired", "ended" ], "description": "pending until the link is issued, then ready; failed, expired or ended.", "x-data-class": "operational" }, "sign_in_url": { "type": [ "string", "null" ], "description": "The one-time sign-in link, while status is ready: answered by get_impersonation alone, never by impersonate_user. Open it in a private window.", "x-data-class": "operational" }, "token_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the link stops working.", "x-data-class": "operational" }, "session_expires_at": { "type": "string", "format": "date-time", "description": "When the impersonated session ends.", "x-data-class": "operational" }, "failed": { "type": [ "string", "null" ], "description": "Why the link could not be issued, when it could not.", "x-data-class": "operational" } }, "required": [ "impersonation_id", "org_id", "user_id", "grant_id", "status", "sign_in_url", "token_expires_at", "session_expires_at", "failed" ], "additionalProperties": false }, "GetImpersonationResponse": { "type": "object", "properties": { "capability": { "const": "get_impersonation" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetImpersonationOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetMySettingsInput": { "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 }, "GetMySettingsOutput": { "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 }, "GetMySettingsResponse": { "type": "object", "properties": { "capability": { "const": "get_my_settings" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetMySettingsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetNotificationPolicyInput": { "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 }, "GetNotificationPolicyOutput": { "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 }, "GetNotificationPolicyResponse": { "type": "object", "properties": { "capability": { "const": "get_notification_policy" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetNotificationPolicyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetOnboardingStatusInput": { "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 }, "GetOnboardingStatusOutput": { "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 }, "GetOnboardingStatusResponse": { "type": "object", "properties": { "capability": { "const": "get_onboarding_status" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetOnboardingStatusOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetPurchaseOrderSuggestionsInput": { "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 }, "GetPurchaseOrderSuggestionsOutput": { "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 }, "GetPurchaseOrderSuggestionsResponse": { "type": "object", "properties": { "capability": { "const": "get_purchase_order_suggestions" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetPurchaseOrderSuggestionsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetPurgeReadinessInput": { "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 }, "GetPurgeReadinessOutput": { "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 }, "GetPurgeReadinessResponse": { "type": "object", "properties": { "capability": { "const": "get_purge_readiness" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetPurgeReadinessOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetReportInput": { "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 }, "GetReportOutput": { "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 }, "GetReportResponse": { "type": "object", "properties": { "capability": { "const": "get_report" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetReportOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetSecurityPolicyInput": { "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 }, "GetSecurityPolicyOutput": { "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 }, "GetSecurityPolicyResponse": { "type": "object", "properties": { "capability": { "const": "get_security_policy" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetSecurityPolicyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetSupplierPurchaseOrderInput": { "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 }, "GetSupplierPurchaseOrderOutput": { "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 }, "GetSupplierPurchaseOrderResponse": { "type": "object", "properties": { "capability": { "const": "get_supplier_purchase_order" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetSupplierPurchaseOrderOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetTenantHealthInput": { "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 }, "GetTenantHealthOutput": { "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 }, "GetTenantHealthResponse": { "type": "object", "properties": { "capability": { "const": "get_tenant_health" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetTenantHealthOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetTestTwinInput": { "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 }, "GetTestTwinOutput": { "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 }, "GetTestTwinResponse": { "type": "object", "properties": { "capability": { "const": "get_test_twin" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetTestTwinOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetViewInput": { "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 }, "GetViewOutput": { "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 }, "GetViewResponse": { "type": "object", "properties": { "capability": { "const": "get_view" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetViewOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GetViewDefaultInput": { "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 }, "GetViewDefaultOutput": { "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 }, "GetViewDefaultResponse": { "type": "object", "properties": { "capability": { "const": "get_view_default" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GetViewDefaultOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GrantCapabilityInput": { "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." } }, "required": [ "org_id", "capability_id", "kind", "reason" ], "additionalProperties": false }, "GrantCapabilityOutput": { "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 }, "GrantCapabilityResponse": { "type": "object", "properties": { "capability": { "const": "grant_capability" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GrantCapabilityOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GrantStaffRoleInput": { "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." } }, "required": [ "user_id", "role_id" ], "additionalProperties": false }, "GrantStaffRoleOutput": { "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 }, "GrantStaffRoleResponse": { "type": "object", "properties": { "capability": { "const": "grant_staff_role" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GrantStaffRoleOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "GrantUnitRoleInput": { "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...)." } }, "required": [ "org_id", "unit_id", "user_id", "role_template_id" ], "additionalProperties": false }, "GrantUnitRoleOutput": { "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 }, "GrantUnitRoleResponse": { "type": "object", "properties": { "capability": { "const": "grant_unit_role" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/GrantUnitRoleOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "HideCatalogPhotoInput": { "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." } }, "required": [ "org_id", "photo_id", "hidden" ], "additionalProperties": false }, "HideCatalogPhotoOutput": { "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 }, "HideCatalogPhotoResponse": { "type": "object", "properties": { "capability": { "const": "hide_catalog_photo" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/HideCatalogPhotoOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ImpersonateUserInput": { "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 holds an act grant to, and the user is a member of." }, "user_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-user-id", "description": "The member to sign in as." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why, recorded with every act the session makes." }, "minutes": { "type": "integer", "minimum": 5, "maximum": 240, "default": 30, "description": "How long the impersonated session may last: thirty minutes unless said." } }, "required": [ "org_id", "user_id", "reason" ], "additionalProperties": false }, "ImpersonateUserOutput": { "type": "object", "properties": { "impersonation_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 impersonation.", "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 in.", "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 is impersonated.", "x-data-class": "operational" }, "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 act grant that allows it.", "x-data-class": "operational" }, "status": { "type": "string", "enum": [ "pending", "ready", "failed", "expired", "ended" ], "description": "pending until the link is issued, then ready; failed, expired or ended.", "x-data-class": "operational" }, "sign_in_url": { "type": [ "string", "null" ], "description": "The one-time sign-in link, while status is ready: answered by get_impersonation alone, never by impersonate_user. Open it in a private window.", "x-data-class": "operational" }, "token_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the link stops working.", "x-data-class": "operational" }, "session_expires_at": { "type": "string", "format": "date-time", "description": "When the impersonated session ends.", "x-data-class": "operational" }, "failed": { "type": [ "string", "null" ], "description": "Why the link could not be issued, when it could not.", "x-data-class": "operational" } }, "required": [ "impersonation_id", "org_id", "user_id", "grant_id", "status", "sign_in_url", "token_expires_at", "session_expires_at", "failed" ], "additionalProperties": false }, "ImpersonateUserResponse": { "type": "object", "properties": { "capability": { "const": "impersonate_user" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ImpersonateUserOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ImportUnitsInput": { "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." } }, "required": [ "org_id", "csv" ], "additionalProperties": false }, "ImportUnitsOutput": { "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 }, "ImportUnitsResponse": { "type": "object", "properties": { "capability": { "const": "import_units" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ImportUnitsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ImportUsersInput": { "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." } }, "required": [ "org_id", "invitees" ], "additionalProperties": false }, "ImportUsersOutput": { "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 }, "ImportUsersResponse": { "type": "object", "properties": { "capability": { "const": "import_users" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ImportUsersOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "InviteGuestInput": { "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." } }, "required": [ "org_id", "document_kind", "document_id", "party_id", "seat", "email" ], "additionalProperties": false }, "InviteGuestOutput": { "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 }, "InviteGuestResponse": { "type": "object", "properties": { "capability": { "const": "invite_guest" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/InviteGuestOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "InviteUserInput": { "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." } }, "required": [ "org_id", "email" ], "additionalProperties": false }, "InviteUserOutput": { "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 }, "InviteUserResponse": { "type": "object", "properties": { "capability": { "const": "invite_user" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/InviteUserOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListAccessReviewsInput": { "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 }, "ListAccessReviewsOutput": { "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 }, "ListAccessReviewsResponse": { "type": "object", "properties": { "capability": { "const": "list_access_reviews" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListAccessReviewsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListAccountMembersInput": { "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 }, "ListAccountMembersOutput": { "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 }, "ListAccountMembersResponse": { "type": "object", "properties": { "capability": { "const": "list_account_members" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListAccountMembersOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListAccountsInput": { "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 }, "ListAccountsOutput": { "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 }, "ListAccountsResponse": { "type": "object", "properties": { "capability": { "const": "list_accounts" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListAccountsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListAgentReadsInput": { "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 }, "ListAgentReadsOutput": { "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 }, "ListAgentReadsResponse": { "type": "object", "properties": { "capability": { "const": "list_agent_reads" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListAgentReadsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListAnnouncementsInput": { "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 }, "ListAnnouncementsOutput": { "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 }, "ListAnnouncementsResponse": { "type": "object", "properties": { "capability": { "const": "list_announcements" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListAnnouncementsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListApiKeysInput": { "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 }, "ListApiKeysOutput": { "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 }, "ListApiKeysResponse": { "type": "object", "properties": { "capability": { "const": "list_api_keys" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListApiKeysOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListAuditEventsInput": { "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 }, "ListAuditEventsOutput": { "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 }, "ListAuditEventsResponse": { "type": "object", "properties": { "capability": { "const": "list_audit_events" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListAuditEventsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListAuditExportsInput": { "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 }, "ListAuditExportsOutput": { "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 }, "ListAuditExportsResponse": { "type": "object", "properties": { "capability": { "const": "list_audit_exports" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListAuditExportsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListBetaListsInput": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "ListBetaListsOutput": { "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 }, "ListBetaListsResponse": { "type": "object", "properties": { "capability": { "const": "list_beta_lists" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListBetaListsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListBetaMembersInput": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "ListBetaMembersOutput": { "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 }, "ListBetaMembersResponse": { "type": "object", "properties": { "capability": { "const": "list_beta_members" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListBetaMembersOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListCapabilityEventsInput": { "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 }, "ListCapabilityEventsOutput": { "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 }, "ListCapabilityEventsResponse": { "type": "object", "properties": { "capability": { "const": "list_capability_events" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListCapabilityEventsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListCatalogInput": { "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 }, "ListCatalogOutput": { "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 }, "ListCatalogResponse": { "type": "object", "properties": { "capability": { "const": "list_catalog" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListCatalogOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListDataFieldsInput": { "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 }, "ListDataFieldsOutput": { "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 }, "ListDataFieldsResponse": { "type": "object", "properties": { "capability": { "const": "list_data_fields" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListDataFieldsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListDataSharesInput": { "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 }, "ListDataSharesOutput": { "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 }, "ListDataSharesResponse": { "type": "object", "properties": { "capability": { "const": "list_data_shares" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListDataSharesOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListDepotReferencesInput": { "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 }, "ListDepotReferencesOutput": { "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 }, "ListDepotReferencesResponse": { "type": "object", "properties": { "capability": { "const": "list_depot_references" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListDepotReferencesOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListDepotRegistryInput": { "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 }, "ListDepotRegistryOutput": { "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 }, "ListDepotRegistryResponse": { "type": "object", "properties": { "capability": { "const": "list_depot_registry" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListDepotRegistryOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListDevicesInput": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "ListDevicesOutput": { "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 }, "ListDevicesResponse": { "type": "object", "properties": { "capability": { "const": "list_devices" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListDevicesOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListDocumentPartiesInput": { "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 }, "ListDocumentPartiesOutput": { "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 }, "ListDocumentPartiesResponse": { "type": "object", "properties": { "capability": { "const": "list_document_parties" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListDocumentPartiesOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListDomainsInput": { "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 }, "ListDomainsOutput": { "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 }, "ListDomainsResponse": { "type": "object", "properties": { "capability": { "const": "list_domains" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListDomainsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListFilesInput": { "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 }, "ListFilesOutput": { "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 }, "ListFilesResponse": { "type": "object", "properties": { "capability": { "const": "list_files" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListFilesOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListFlagActionsInput": { "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 }, "ListFlagActionsOutput": { "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 }, "ListFlagActionsResponse": { "type": "object", "properties": { "capability": { "const": "list_flag_actions" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListFlagActionsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListFlagStaffInput": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "ListFlagStaffOutput": { "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 }, "ListFlagStaffResponse": { "type": "object", "properties": { "capability": { "const": "list_flag_staff" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListFlagStaffOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListFlagsInput": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "ListFlagsOutput": { "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 }, "ListFlagsResponse": { "type": "object", "properties": { "capability": { "const": "list_flags" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListFlagsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListFxRatesInput": { "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 }, "ListFxRatesOutput": { "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 }, "ListFxRatesResponse": { "type": "object", "properties": { "capability": { "const": "list_fx_rates" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListFxRatesOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListGrantedCapabilitiesInput": { "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 }, "ListGrantedCapabilitiesOutput": { "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 }, "ListGrantedCapabilitiesResponse": { "type": "object", "properties": { "capability": { "const": "list_granted_capabilities" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListGrantedCapabilitiesOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListGuestDocumentsInput": { "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 }, "ListGuestDocumentsOutput": { "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 }, "ListGuestDocumentsResponse": { "type": "object", "properties": { "capability": { "const": "list_guest_documents" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListGuestDocumentsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListGuestsInput": { "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 }, "ListGuestsOutput": { "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 }, "ListGuestsResponse": { "type": "object", "properties": { "capability": { "const": "list_guests" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListGuestsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListIdentityFindingsInput": { "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 }, "ListIdentityFindingsOutput": { "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 }, "ListIdentityFindingsResponse": { "type": "object", "properties": { "capability": { "const": "list_identity_findings" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListIdentityFindingsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListInventoryInput": { "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 }, "ListInventoryOutput": { "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 }, "ListInventoryResponse": { "type": "object", "properties": { "capability": { "const": "list_inventory" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListInventoryOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListMyNotificationsInput": { "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 }, "ListMyNotificationsOutput": { "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 }, "ListMyNotificationsResponse": { "type": "object", "properties": { "capability": { "const": "list_my_notifications" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListMyNotificationsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListOrgGrantsInput": { "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 }, "ListOrgGrantsOutput": { "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 }, "ListOrgGrantsResponse": { "type": "object", "properties": { "capability": { "const": "list_org_grants" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListOrgGrantsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListOrgsInput": { "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 }, "ListOrgsOutput": { "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 }, "ListOrgsResponse": { "type": "object", "properties": { "capability": { "const": "list_orgs" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListOrgsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListPermissionsInput": { "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 }, "ListPermissionsOutput": { "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 }, "ListPermissionsResponse": { "type": "object", "properties": { "capability": { "const": "list_permissions" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListPermissionsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListPortfoliosInput": { "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 }, "ListPortfoliosOutput": { "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 }, "ListPortfoliosResponse": { "type": "object", "properties": { "capability": { "const": "list_portfolios" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListPortfoliosOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListPurchaseOrdersInput": { "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 }, "ListPurchaseOrdersOutput": { "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 }, "ListPurchaseOrdersResponse": { "type": "object", "properties": { "capability": { "const": "list_purchase_orders" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListPurchaseOrdersOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListReceivedDataSharesInput": { "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 }, "ListReceivedDataSharesOutput": { "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 }, "ListReceivedDataSharesResponse": { "type": "object", "properties": { "capability": { "const": "list_received_data_shares" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListReceivedDataSharesOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListReportOpensInput": { "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 }, "ListReportOpensOutput": { "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 }, "ListReportOpensResponse": { "type": "object", "properties": { "capability": { "const": "list_report_opens" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListReportOpensOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListReportsInput": { "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 }, "ListReportsOutput": { "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 }, "ListReportsResponse": { "type": "object", "properties": { "capability": { "const": "list_reports" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListReportsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListRoleTemplatesInput": { "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 }, "ListRoleTemplatesOutput": { "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 }, "ListRoleTemplatesResponse": { "type": "object", "properties": { "capability": { "const": "list_role_templates" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListRoleTemplatesOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListSavedViewsInput": { "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 }, "ListSavedViewsOutput": { "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 }, "ListSavedViewsResponse": { "type": "object", "properties": { "capability": { "const": "list_saved_views" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListSavedViewsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListServiceAccountsInput": { "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 }, "ListServiceAccountsOutput": { "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 }, "ListServiceAccountsResponse": { "type": "object", "properties": { "capability": { "const": "list_service_accounts" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListServiceAccountsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListSessionsInput": { "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 }, "ListSessionsOutput": { "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 }, "ListSessionsResponse": { "type": "object", "properties": { "capability": { "const": "list_sessions" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListSessionsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListSharedCatalogInput": { "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 }, "ListSharedCatalogOutput": { "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 }, "ListSharedCatalogResponse": { "type": "object", "properties": { "capability": { "const": "list_shared_catalog" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListSharedCatalogOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListSsoConnectionsInput": { "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 }, "ListSsoConnectionsOutput": { "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 }, "ListSsoConnectionsResponse": { "type": "object", "properties": { "capability": { "const": "list_sso_connections" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListSsoConnectionsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListStaffInput": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "ListStaffOutput": { "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 }, "ListStaffResponse": { "type": "object", "properties": { "capability": { "const": "list_staff" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListStaffOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListStaffGrantsInput": { "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 }, "ListStaffGrantsOutput": { "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 }, "ListStaffGrantsResponse": { "type": "object", "properties": { "capability": { "const": "list_staff_grants" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListStaffGrantsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListSupplierPostsInput": { "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 }, "ListSupplierPostsOutput": { "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 }, "ListSupplierPostsResponse": { "type": "object", "properties": { "capability": { "const": "list_supplier_posts" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListSupplierPostsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListSwitchableOrgsInput": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "ListSwitchableOrgsOutput": { "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 }, "ListSwitchableOrgsResponse": { "type": "object", "properties": { "capability": { "const": "list_switchable_orgs" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListSwitchableOrgsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListUnitAccessInput": { "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 }, "ListUnitAccessOutput": { "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 }, "ListUnitAccessResponse": { "type": "object", "properties": { "capability": { "const": "list_unit_access" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListUnitAccessOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListUnitsInput": { "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 }, "ListUnitsOutput": { "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 }, "ListUnitsResponse": { "type": "object", "properties": { "capability": { "const": "list_units" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListUnitsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListUserFactorsInput": { "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 }, "ListUserFactorsOutput": { "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 }, "ListUserFactorsResponse": { "type": "object", "properties": { "capability": { "const": "list_user_factors" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListUserFactorsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ListUsersInput": { "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 }, "ListUsersOutput": { "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 }, "ListUsersResponse": { "type": "object", "properties": { "capability": { "const": "list_users" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ListUsersOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "MarkReportSeenInput": { "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." } }, "required": [ "org_id", "report_id" ], "additionalProperties": false }, "MarkReportSeenOutput": { "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 }, "MarkReportSeenResponse": { "type": "object", "properties": { "capability": { "const": "mark_report_seen" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/MarkReportSeenOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "MoveUnitInput": { "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." } }, "required": [ "org_id", "unit_id" ], "additionalProperties": false }, "MoveUnitOutput": { "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 }, "MoveUnitResponse": { "type": "object", "properties": { "capability": { "const": "move_unit" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/MoveUnitOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "PinViewInput": { "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." } }, "required": [ "org_id", "view_id", "tab" ], "additionalProperties": false }, "PinViewOutput": { "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 }, "PinViewResponse": { "type": "object", "properties": { "capability": { "const": "pin_view" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/PinViewOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "PostProductionStatusInput": { "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." } }, "required": [ "org_id", "document_kind", "document_id", "status" ], "additionalProperties": false }, "PostProductionStatusOutput": { "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 }, "PostProductionStatusResponse": { "type": "object", "properties": { "capability": { "const": "post_production_status" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/PostProductionStatusOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "PreviewDataShareInput": { "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, "oneOf": [ { "required": [ "data_share_id" ], "not": { "anyOf": [ { "required": [ "party_id" ] }, { "required": [ "query" ] }, { "required": [ "contact_id" ] }, { "required": [ "request_id" ] } ] } }, { "properties": { "query": { "const": "vendor_bill_request" } }, "required": [ "party_id", "query", "request_id" ], "not": { "anyOf": [ { "required": [ "data_share_id" ] }, { "required": [ "contact_id" ] } ] } }, { "properties": { "query": { "const": "vendor_forecast" } }, "required": [ "party_id", "query", "contact_id" ], "not": { "anyOf": [ { "required": [ "data_share_id" ] }, { "required": [ "request_id" ] } ] } }, { "properties": { "query": { "const": "vendor_sell_through" } }, "required": [ "party_id", "query", "contact_id" ], "not": { "anyOf": [ { "required": [ "data_share_id" ] }, { "required": [ "request_id" ] } ] } } ] }, "PreviewDataShareOutput": { "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 }, "PreviewDataShareResponse": { "type": "object", "properties": { "capability": { "const": "preview_data_share" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/PreviewDataShareOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ProvisionAccountInput": { "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)." } }, "required": [ "account_name", "admin_email" ], "additionalProperties": false }, "ProvisionAccountOutput": { "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 }, "ProvisionAccountResponse": { "type": "object", "properties": { "capability": { "const": "provision_account" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ProvisionAccountOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ProvisionSandboxInput": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "ProvisionSandboxOutput": { "type": "object", "properties": { "sandbox_id": { "type": "string", "minLength": 1, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]{1,20}$", "format": "tradehq-org-id", "description": "The sandbox: the test-mode org the key reaches.", "x-data-class": "operational" }, "key_id": { "type": "string", "description": "The key's id, its public part.", "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" }, "secret": { "type": [ "string", "null" ], "description": "The whole sk_test_ key, on the call that made the sandbox and never again: it is stored nowhere, so a replay answers null.", "x-data-class": "operational" }, "mode": { "type": "string", "enum": [ "test" ], "description": "Always test: the key never reaches live data.", "x-data-class": "operational" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the sandbox and its key stop and the sandbox is purged.", "x-data-class": "operational" }, "lifetime_days": { "type": "integer", "description": "How long a sandbox lives: 14.", "x-data-class": "operational" }, "name": { "type": "string", "description": "The sandbox's name, \"Trade HQ sandbox\" and six characters. Not a secret: give it to a Trade HQ contact to keep the sandbox as a company's account (TRA-474).", "x-data-class": "operational" } }, "required": [ "sandbox_id", "key_id", "display", "secret", "mode", "expires_at", "lifetime_days", "name" ], "additionalProperties": false }, "ProvisionSandboxResponse": { "type": "object", "properties": { "capability": { "const": "provision_sandbox" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ProvisionSandboxOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "PublishAnnouncementInput": { "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." } }, "required": [ "account_id", "title", "body", "severity" ], "additionalProperties": false }, "PublishAnnouncementOutput": { "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 }, "PublishAnnouncementResponse": { "type": "object", "properties": { "capability": { "const": "publish_announcement" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/PublishAnnouncementOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "PurgeOrgInput": { "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." } }, "required": [ "org_id", "dry_run_id" ], "additionalProperties": false }, "PurgeOrgOutput": { "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 }, "PurgeOrgResponse": { "type": "object", "properties": { "capability": { "const": "purge_org" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/PurgeOrgOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RecordGateEventInput": { "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." } }, "required": [ "org_id", "kind", "container", "depot", "occurred_at", "source" ], "additionalProperties": false }, "RecordGateEventOutput": { "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 }, "RecordGateEventResponse": { "type": "object", "properties": { "capability": { "const": "record_gate_event" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RecordGateEventOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RecordReportOpenInput": { "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." } }, "required": [ "org_id", "report" ], "additionalProperties": false }, "RecordReportOpenOutput": { "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 }, "RecordReportOpenResponse": { "type": "object", "properties": { "capability": { "const": "record_report_open" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RecordReportOpenOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ReferenceDepotInput": { "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." } }, "required": [ "org_id", "bfc", "alias" ], "additionalProperties": false }, "ReferenceDepotOutput": { "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 }, "ReferenceDepotResponse": { "type": "object", "properties": { "capability": { "const": "reference_depot" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ReferenceDepotOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RegisterDeviceInput": { "type": "object", "properties": { "public_point": { "type": "string", "minLength": 80, "maxLength": 100, "description": "The installation's P-256 public key, as its 65-byte uncompressed SEC1 point, standard base64." }, "platform": { "type": "string", "enum": [ "ios", "android" ], "description": "The app's platform." }, "app_version": { "type": "string", "minLength": 1, "maxLength": 64, "description": "The app's version." }, "challenge": { "type": "string", "minLength": 1, "maxLength": 64, "description": "A challenge POST /v1/device/challenge issued to the caller for this installation." }, "signature": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The installation key's ECDSA P-256/SHA-256 signature, DER, standard base64, over the registration message (installation, challenge, caller)." }, "expo_push_token": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The Expo push token the app was given. A new one replaces the previous." }, "managed": { "type": "boolean", "description": "A shared or kiosk device, enrolled by an org admin: it reads only. Absent is false." }, "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": "A unit of the session's org the device belongs to (TRA-324's yard identity)." } }, "required": [ "public_point", "platform", "app_version", "challenge", "signature" ], "additionalProperties": false }, "RegisterDeviceOutput": { "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: the device's principal id.", "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, derived from its key.", "x-data-class": "operational" }, "managed": { "type": "boolean", "description": "Whether it is a managed (shared) device.", "x-data-class": "operational" }, "push": { "type": "boolean", "description": "Whether it has a live push destination.", "x-data-class": "operational" } }, "required": [ "binding_id", "installation_id", "managed", "push" ], "additionalProperties": false }, "RegisterDeviceResponse": { "type": "object", "properties": { "capability": { "const": "register_device" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RegisterDeviceOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ReinstateUserInput": { "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." } }, "required": [ "user_id" ], "additionalProperties": false }, "ReinstateUserOutput": { "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 }, "ReinstateUserResponse": { "type": "object", "properties": { "capability": { "const": "reinstate_user" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ReinstateUserOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RemoveAccountMemberInput": { "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." } }, "required": [ "account_id", "user_id" ], "additionalProperties": false }, "RemoveAccountMemberOutput": { "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 }, "RemoveAccountMemberResponse": { "type": "object", "properties": { "capability": { "const": "remove_account_member" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RemoveAccountMemberOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RemoveDepotReferenceInput": { "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." } }, "required": [ "org_id", "depot_reference_id" ], "additionalProperties": false }, "RemoveDepotReferenceOutput": { "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 }, "RemoveDepotReferenceResponse": { "type": "object", "properties": { "capability": { "const": "remove_depot_reference" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RemoveDepotReferenceOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RemoveDomainInput": { "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." } }, "required": [ "org_id", "domain" ], "additionalProperties": false }, "RemoveDomainOutput": { "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 }, "RemoveDomainResponse": { "type": "object", "properties": { "capability": { "const": "remove_domain" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RemoveDomainOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ReopenReportInput": { "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." } }, "required": [ "org_id", "report_id", "body" ], "additionalProperties": false }, "ReopenReportOutput": { "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 }, "ReopenReportResponse": { "type": "object", "properties": { "capability": { "const": "reopen_report" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ReopenReportOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ReplayEventDeliveryInput": { "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." } }, "required": [ "event_id", "reason" ], "additionalProperties": false }, "ReplayEventDeliveryOutput": { "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 }, "ReplayEventDeliveryResponse": { "type": "object", "properties": { "capability": { "const": "replay_event_delivery" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ReplayEventDeliveryOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ReplyToReportInput": { "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." } }, "required": [ "org_id", "report_id", "body" ], "additionalProperties": false }, "ReplyToReportOutput": { "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 }, "ReplyToReportResponse": { "type": "object", "properties": { "capability": { "const": "reply_to_report" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ReplyToReportOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RequestStaffGrantInput": { "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." } }, "required": [ "org_id", "reason" ], "additionalProperties": false }, "RequestStaffGrantOutput": { "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 }, "RequestStaffGrantResponse": { "type": "object", "properties": { "capability": { "const": "request_staff_grant" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RequestStaffGrantOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ResetUserMfaInput": { "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." } }, "required": [ "user_id" ], "additionalProperties": false }, "ResetUserMfaOutput": { "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 }, "ResetUserMfaResponse": { "type": "object", "properties": { "capability": { "const": "reset_user_mfa" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ResetUserMfaOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ResolveIdentityFindingInput": { "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." } }, "required": [ "org_id", "finding_id", "decision" ], "additionalProperties": false }, "ResolveIdentityFindingOutput": { "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 }, "ResolveIdentityFindingResponse": { "type": "object", "properties": { "capability": { "const": "resolve_identity_finding" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ResolveIdentityFindingOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RestoreSecurityPolicyInput": { "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." } }, "required": [ "org_id", "section", "version" ], "additionalProperties": false }, "RestoreSecurityPolicyOutput": { "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 }, "RestoreSecurityPolicyResponse": { "type": "object", "properties": { "capability": { "const": "restore_security_policy" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RestoreSecurityPolicyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ResumeOrgInput": { "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." } }, "required": [ "org_id" ], "additionalProperties": false }, "ResumeOrgOutput": { "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 }, "ResumeOrgResponse": { "type": "object", "properties": { "capability": { "const": "resume_org" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ResumeOrgOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RevokeApiKeyInput": { "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)." } }, "required": [ "org_id", "key_id" ], "additionalProperties": false }, "RevokeApiKeyOutput": { "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 }, "RevokeApiKeyResponse": { "type": "object", "properties": { "capability": { "const": "revoke_api_key" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RevokeApiKeyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RevokeCapabilityGrantInput": { "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." } }, "required": [ "org_id", "org_grant_id", "reason" ], "additionalProperties": false }, "RevokeCapabilityGrantOutput": { "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 }, "RevokeCapabilityGrantResponse": { "type": "object", "properties": { "capability": { "const": "revoke_capability_grant" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RevokeCapabilityGrantOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RevokeDataShareInput": { "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." } }, "required": [ "org_id", "data_share_id" ], "additionalProperties": false }, "RevokeDataShareOutput": { "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 }, "RevokeDataShareResponse": { "type": "object", "properties": { "capability": { "const": "revoke_data_share" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RevokeDataShareOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RevokeDeviceInput": { "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." } }, "required": [ "binding_id" ], "additionalProperties": false }, "RevokeDeviceOutput": { "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 }, "RevokeDeviceResponse": { "type": "object", "properties": { "capability": { "const": "revoke_device" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RevokeDeviceOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RevokeGrantInput": { "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." } }, "required": [ "org_id", "grant_id" ], "additionalProperties": false }, "RevokeGrantOutput": { "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 }, "RevokeGrantResponse": { "type": "object", "properties": { "capability": { "const": "revoke_grant" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RevokeGrantOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RevokeGuestInput": { "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." } }, "required": [ "org_id", "user_id" ], "additionalProperties": false }, "RevokeGuestOutput": { "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 }, "RevokeGuestResponse": { "type": "object", "properties": { "capability": { "const": "revoke_guest" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RevokeGuestOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RevokeSessionsInput": { "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." } }, "required": [ "org_id" ], "additionalProperties": false }, "RevokeSessionsOutput": { "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 }, "RevokeSessionsResponse": { "type": "object", "properties": { "capability": { "const": "revoke_sessions" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RevokeSessionsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RevokeStaffRoleInput": { "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." } }, "required": [ "user_id", "role_id" ], "additionalProperties": false }, "RevokeStaffRoleOutput": { "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 }, "RevokeStaffRoleResponse": { "type": "object", "properties": { "capability": { "const": "revoke_staff_role" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RevokeStaffRoleOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RevokeUnitRoleInput": { "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." } }, "required": [ "org_id", "unit_id", "user_id" ], "additionalProperties": false }, "RevokeUnitRoleOutput": { "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 }, "RevokeUnitRoleResponse": { "type": "object", "properties": { "capability": { "const": "revoke_unit_role" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RevokeUnitRoleOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RollBackFlagInput": { "type": "object", "properties": { "flag_key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The flag's key, as the registry has it." } }, "required": [ "flag_key" ], "additionalProperties": false }, "RollBackFlagOutput": { "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 }, "RollBackFlagResponse": { "type": "object", "properties": { "capability": { "const": "roll_back_flag" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RollBackFlagOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RotateApiKeyInput": { "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 succeed." }, "overlap_hours": { "type": "integer", "minimum": 0, "maximum": 168, "default": 24, "description": "How long the old key keeps working, in hours: 24 by default, at most a week, 0 to end it now." } }, "required": [ "org_id", "key_id" ], "additionalProperties": false }, "RotateApiKeyOutput": { "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" }, "secret": { "type": [ "string", "null" ], "description": "The whole key, on the call that issued it and never again: it is stored nowhere, so a replay answers null.", "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", "secret" ], "additionalProperties": false }, "RotateApiKeyResponse": { "type": "object", "properties": { "capability": { "const": "rotate_api_key" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RotateApiKeyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RouteHeldFileInput": { "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." } }, "required": [ "org_id", "upload_id" ], "additionalProperties": false }, "RouteHeldFileOutput": { "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 }, "RouteHeldFileResponse": { "type": "object", "properties": { "capability": { "const": "route_held_file" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RouteHeldFileOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RunIdentityReconcileInput": { "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." } }, "required": [ "org_id" ], "additionalProperties": false }, "RunIdentityReconcileOutput": { "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 }, "RunIdentityReconcileResponse": { "type": "object", "properties": { "capability": { "const": "run_identity_reconcile" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RunIdentityReconcileOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "RunPurgeDryRunInput": { "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 }, "RunPurgeDryRunOutput": { "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 }, "RunPurgeDryRunResponse": { "type": "object", "properties": { "capability": { "const": "run_purge_dry_run" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/RunPurgeDryRunOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SaveViewInput": { "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." } }, "required": [ "org_id", "capability", "args", "title" ], "additionalProperties": false }, "SaveViewOutput": { "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 }, "SaveViewResponse": { "type": "object", "properties": { "capability": { "const": "save_view" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SaveViewOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ScheduleOrgDeletionInput": { "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." } }, "required": [ "org_id" ], "additionalProperties": false }, "ScheduleOrgDeletionOutput": { "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 }, "ScheduleOrgDeletionResponse": { "type": "object", "properties": { "capability": { "const": "schedule_org_deletion" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ScheduleOrgDeletionOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SearchPartyDirectoryInput": { "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 }, "SearchPartyDirectoryOutput": { "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 }, "SearchPartyDirectoryResponse": { "type": "object", "properties": { "capability": { "const": "search_party_directory" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SearchPartyDirectoryOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SearchRecordsInput": { "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 }, "SearchRecordsOutput": { "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 }, "SearchRecordsResponse": { "type": "object", "properties": { "capability": { "const": "search_records" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SearchRecordsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SendFeedbackInput": { "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." } }, "required": [ "org_id", "kind", "message", "impact", "page" ], "additionalProperties": false }, "SendFeedbackOutput": { "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 }, "SendFeedbackResponse": { "type": "object", "properties": { "capability": { "const": "send_feedback" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SendFeedbackOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetAccountRoleInput": { "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." } }, "required": [ "account_id", "user_id", "role" ], "additionalProperties": false }, "SetAccountRoleOutput": { "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 }, "SetAccountRoleResponse": { "type": "object", "properties": { "capability": { "const": "set_account_role" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetAccountRoleOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetActingScopeInput": { "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." } }, "required": [ "scope" ], "additionalProperties": false }, "SetActingScopeOutput": { "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 }, "SetActingScopeResponse": { "type": "object", "properties": { "capability": { "const": "set_acting_scope" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetActingScopeOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetApiKeyLimitsInput": { "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." } }, "required": [ "org_id", "key_id", "requests_per_minute", "requests_per_day" ], "additionalProperties": false }, "SetApiKeyLimitsOutput": { "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 }, "SetApiKeyLimitsResponse": { "type": "object", "properties": { "capability": { "const": "set_api_key_limits" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetApiKeyLimitsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetApiKeyVersionInput": { "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." } }, "required": [ "org_id", "key_id", "api_version" ], "additionalProperties": false }, "SetApiKeyVersionOutput": { "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 }, "SetApiKeyVersionResponse": { "type": "object", "properties": { "capability": { "const": "set_api_key_version" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetApiKeyVersionOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetBetaListMemberInput": { "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." } }, "required": [ "list", "member_kind", "member_id", "state" ], "additionalProperties": false }, "SetBetaListMemberOutput": { "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 }, "SetBetaListMemberResponse": { "type": "object", "properties": { "capability": { "const": "set_beta_list_member" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetBetaListMemberOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetCatalogPriceInput": { "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." } }, "required": [ "org_id" ], "additionalProperties": false }, "SetCatalogPriceOutput": { "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 }, "SetCatalogPriceResponse": { "type": "object", "properties": { "capability": { "const": "set_catalog_price" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetCatalogPriceOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetCustomerStageInput": { "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." } }, "required": [ "org_id", "stage" ], "additionalProperties": false }, "SetCustomerStageOutput": { "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 }, "SetCustomerStageResponse": { "type": "object", "properties": { "capability": { "const": "set_customer_stage" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetCustomerStageOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetDataPolicyInput": { "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." } }, "required": [ "org_id", "role_id", "record_scope", "commercial_read", "commercial_export", "financial_read", "financial_export", "personal_read", "personal_export" ], "additionalProperties": false }, "SetDataPolicyOutput": { "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 }, "SetDataPolicyResponse": { "type": "object", "properties": { "capability": { "const": "set_data_policy" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetDataPolicyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetDocumentPartiesInput": { "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." } }, "required": [ "org_id", "document_kind", "document_id", "parties" ], "additionalProperties": false }, "SetDocumentPartiesOutput": { "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 }, "SetDocumentPartiesResponse": { "type": "object", "properties": { "capability": { "const": "set_document_parties" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetDocumentPartiesOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetDomainJoinPolicyInput": { "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." } }, "required": [ "org_id", "domain", "join_policy" ], "additionalProperties": false }, "SetDomainJoinPolicyOutput": { "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 }, "SetDomainJoinPolicyResponse": { "type": "object", "properties": { "capability": { "const": "set_domain_join_policy" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetDomainJoinPolicyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetFlagListsInput": { "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." } }, "required": [ "flag_key", "from", "lists" ], "additionalProperties": false }, "SetFlagListsOutput": { "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 }, "SetFlagListsResponse": { "type": "object", "properties": { "capability": { "const": "set_flag_lists" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetFlagListsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetFxRateOverrideInput": { "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)." } }, "required": [ "currency", "rate_date", "rate", "reason" ], "additionalProperties": false }, "SetFxRateOverrideOutput": { "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 }, "SetFxRateOverrideResponse": { "type": "object", "properties": { "capability": { "const": "set_fx_rate_override" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetFxRateOverrideOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetIpAllowlistInput": { "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)." } }, "required": [ "org_id", "mode", "applies_to", "entries" ], "additionalProperties": false }, "SetIpAllowlistOutput": { "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 }, "SetIpAllowlistResponse": { "type": "object", "properties": { "capability": { "const": "set_ip_allowlist" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetIpAllowlistOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetMaintenanceBannerInput": { "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." } }, "required": [ "state" ], "additionalProperties": false }, "SetMaintenanceBannerOutput": { "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 }, "SetMaintenanceBannerResponse": { "type": "object", "properties": { "capability": { "const": "set_maintenance_banner" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetMaintenanceBannerOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetMemberRoleInput": { "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." } }, "required": [ "org_id", "user_id", "role_template_id" ], "additionalProperties": false }, "SetMemberRoleOutput": { "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 }, "SetMemberRoleResponse": { "type": "object", "properties": { "capability": { "const": "set_member_role" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetMemberRoleOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetMfaPolicyInput": { "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." } }, "required": [ "org_id", "mode", "templates", "grace_days", "accept_idp_mfa" ], "additionalProperties": false }, "SetMfaPolicyOutput": { "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 }, "SetMfaPolicyResponse": { "type": "object", "properties": { "capability": { "const": "set_mfa_policy" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetMfaPolicyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetMyNotificationInput": { "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." } }, "required": [ "org_id", "kind", "on" ], "additionalProperties": false }, "SetMyNotificationOutput": { "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 }, "SetMyNotificationResponse": { "type": "object", "properties": { "capability": { "const": "set_my_notification" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetMyNotificationOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetMySettingsInput": { "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." } }, "required": [ "org_id", "settings" ], "additionalProperties": false }, "SetMySettingsOutput": { "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 }, "SetMySettingsResponse": { "type": "object", "properties": { "capability": { "const": "set_my_settings" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetMySettingsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetMyViewDefaultInput": { "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." } }, "required": [ "org_id", "mode" ], "additionalProperties": false }, "SetMyViewDefaultOutput": { "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 }, "SetMyViewDefaultResponse": { "type": "object", "properties": { "capability": { "const": "set_my_view_default" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetMyViewDefaultOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetNotificationPolicyInput": { "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)." } }, "required": [ "org_id", "kind", "recipients" ], "additionalProperties": false }, "SetNotificationPolicyOutput": { "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 }, "SetNotificationPolicyResponse": { "type": "object", "properties": { "capability": { "const": "set_notification_policy" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetNotificationPolicyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetOrgViewDefaultInput": { "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." } }, "required": [ "org_id", "mode" ], "additionalProperties": false }, "SetOrgViewDefaultOutput": { "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 }, "SetOrgViewDefaultResponse": { "type": "object", "properties": { "capability": { "const": "set_org_view_default" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetOrgViewDefaultOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetPortfolioMembersInput": { "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." } }, "required": [ "portfolio_id", "org_ids" ], "additionalProperties": false }, "SetPortfolioMembersOutput": { "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 }, "SetPortfolioMembersResponse": { "type": "object", "properties": { "capability": { "const": "set_portfolio_members" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetPortfolioMembersOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetSessionModeInput": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "live", "test" ], "description": "live or test." } }, "required": [ "mode" ], "additionalProperties": false }, "SetSessionModeOutput": { "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 }, "SetSessionModeResponse": { "type": "object", "properties": { "capability": { "const": "set_session_mode" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetSessionModeOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetSessionPolicyInput": { "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." } }, "required": [ "org_id", "idle_minutes", "absolute_hours", "reauth_on_role_change", "single_session" ], "additionalProperties": false }, "SetSessionPolicyOutput": { "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 }, "SetSessionPolicyResponse": { "type": "object", "properties": { "capability": { "const": "set_session_policy" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetSessionPolicyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SetSsoPolicyInput": { "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." } }, "required": [ "org_id", "connection_id" ], "additionalProperties": false }, "SetSsoPolicyOutput": { "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 }, "SetSsoPolicyResponse": { "type": "object", "properties": { "capability": { "const": "set_sso_policy" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SetSsoPolicyOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "ShareViewInput": { "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." } }, "required": [ "org_id", "view_id", "with_org", "user_ids" ], "additionalProperties": false }, "ShareViewOutput": { "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 }, "ShareViewResponse": { "type": "object", "properties": { "capability": { "const": "share_view" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/ShareViewOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "StepBackFlagInput": { "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." } }, "required": [ "flag_key", "from" ], "additionalProperties": false }, "StepBackFlagOutput": { "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 }, "StepBackFlagResponse": { "type": "object", "properties": { "capability": { "const": "step_back_flag" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/StepBackFlagOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SubmitSerialBatchInput": { "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." } }, "required": [ "org_id", "document_kind", "document_id", "unit_numbers" ], "additionalProperties": false }, "SubmitSerialBatchOutput": { "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 }, "SubmitSerialBatchResponse": { "type": "object", "properties": { "capability": { "const": "submit_serial_batch" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SubmitSerialBatchOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SubscribeAuditInput": { "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)." } }, "required": [ "org_id", "channel", "destination" ], "additionalProperties": false }, "SubscribeAuditOutput": { "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 }, "SubscribeAuditResponse": { "type": "object", "properties": { "capability": { "const": "subscribe_audit" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SubscribeAuditOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SummarizeCatalogInput": { "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 }, "SummarizeCatalogOutput": { "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 }, "SummarizeCatalogResponse": { "type": "object", "properties": { "capability": { "const": "summarize_catalog" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SummarizeCatalogOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SummarizeInventoryInput": { "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 }, "SummarizeInventoryOutput": { "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 }, "SummarizeInventoryResponse": { "type": "object", "properties": { "capability": { "const": "summarize_inventory" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SummarizeInventoryOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SummarizePurchaseOrdersInput": { "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 }, "SummarizePurchaseOrdersOutput": { "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 }, "SummarizePurchaseOrdersResponse": { "type": "object", "properties": { "capability": { "const": "summarize_purchase_orders" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SummarizePurchaseOrdersOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SummarizeReportsInput": { "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 }, "SummarizeReportsOutput": { "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 }, "SummarizeReportsResponse": { "type": "object", "properties": { "capability": { "const": "summarize_reports" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SummarizeReportsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SuspendOrgInput": { "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." } }, "required": [ "org_id" ], "additionalProperties": false }, "SuspendOrgOutput": { "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 }, "SuspendOrgResponse": { "type": "object", "properties": { "capability": { "const": "suspend_org" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SuspendOrgOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "SwitchOrgInput": { "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." } }, "required": [ "org_id" ], "additionalProperties": false }, "SwitchOrgOutput": { "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 }, "SwitchOrgResponse": { "type": "object", "properties": { "capability": { "const": "switch_org" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/SwitchOrgOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "TurnOffFlagInput": { "type": "object", "properties": { "flag_key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The flag's key, as the registry has it." } }, "required": [ "flag_key" ], "additionalProperties": false }, "TurnOffFlagOutput": { "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 }, "TurnOffFlagResponse": { "type": "object", "properties": { "capability": { "const": "turn_off_flag" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/TurnOffFlagOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "UnfollowReportInput": { "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." } }, "required": [ "org_id", "report_id" ], "additionalProperties": false }, "UnfollowReportOutput": { "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 }, "UnfollowReportResponse": { "type": "object", "properties": { "capability": { "const": "unfollow_report" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/UnfollowReportOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "UpdateOrgSettingsInput": { "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." } }, "required": [ "org_id", "settings" ], "additionalProperties": false }, "UpdateOrgSettingsOutput": { "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 }, "UpdateOrgSettingsResponse": { "type": "object", "properties": { "capability": { "const": "update_org_settings" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/UpdateOrgSettingsOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "UpdateRoleTemplateInput": { "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." } }, "required": [ "org_id", "role_id" ], "additionalProperties": false }, "UpdateRoleTemplateOutput": { "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 }, "UpdateRoleTemplateResponse": { "type": "object", "properties": { "capability": { "const": "update_role_template" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/UpdateRoleTemplateOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "UpdateServiceAccountInput": { "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." } }, "required": [ "org_id", "service_account_id" ], "additionalProperties": false }, "UpdateServiceAccountOutput": { "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 }, "UpdateServiceAccountResponse": { "type": "object", "properties": { "capability": { "const": "update_service_account" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/UpdateServiceAccountOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "UpdateSsoConnectionInput": { "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." } }, "required": [ "org_id", "connection_id" ], "additionalProperties": false }, "UpdateSsoConnectionOutput": { "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 }, "UpdateSsoConnectionResponse": { "type": "object", "properties": { "capability": { "const": "update_sso_connection" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/UpdateSsoConnectionOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false }, "VerifyDomainInput": { "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." } }, "required": [ "org_id", "domain" ], "additionalProperties": false }, "VerifyDomainOutput": { "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 }, "VerifyDomainResponse": { "type": "object", "properties": { "capability": { "const": "verify_domain" }, "replayed": { "type": "boolean", "description": "true when this call found the first call's result and changed nothing" }, "result": { "$ref": "#/components/schemas/VerifyDomainOutput" }, "events": { "type": "array", "items": { "type": "string" }, "description": "the events this call recorded; none on a replay" } }, "required": [ "capability", "replayed", "result", "events" ], "additionalProperties": false } } } }