{"openapi":"3.1.0","info":{"title":"Box Governance (BYOK) API","version":"0.1.0","description":"Box Governance (BYOK) lets an AI assistant read your own Box Governance data through the Box Governance API with a key you supply (developer token or OAuth access token (developer tokens expire quickly)). Read-only: 8 tools (list_retention_policies, get_retention_policy, list_retention_policy_assignments, list_file_version_retentions, list_legal_hold_policies, get_legal_hold_policy,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-box-governance.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-box-governance/docs"},"termsOfService":"https://connectorbay.com/byok-box-governance/terms"},"servers":[{"url":"https://byok-box-governance.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-box-governance/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_retention_policies":{"post":{"operationId":"list_retention_policies","summary":"List the enterprise's retention policies with type, length in days, disposition action, status and assignment counts. Ne","description":"List the enterprise's retention policies with type, length in days, disposition action, status and assignment counts. Needs Box Governance and the manage retention policies scope. Use for \"Which retention policies does our Box account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"policy_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only policies whose name starts with this text.","title":"Policy Name"},"policy_type":{"anyOf":[{"enum":["finite","indefinite"],"type":"string"},{"type":"null"}],"default":null,"description":"Only policies of this type.","title":"Policy Type"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many entries to return (1 to 1000).","title":"Limit"},"marker":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging marker: the next_marker value of the previous answer (omit for the first page).","title":"Marker"}},"title":"list_retention_policiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_retention_policy":{"post":{"operationId":"get_retention_policy","summary":"Get one retention policy by id with its length, disposition action, owner-extension settings and assignment counts. Use ","description":"Get one retention policy by id with its length, disposition action, owner-extension settings and assignment counts. Use for \"What are the settings of Box retention policy 11111\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"retention_policy_id":{"description":"Retention policy id from list_retention_policies.","maxLength":200,"title":"Retention Policy Id","type":"string"}},"required":["retention_policy_id"],"title":"get_retention_policyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_retention_policy_assignments":{"post":{"operationId":"list_retention_policy_assignments","summary":"List where a retention policy applies (folders, the whole enterprise or a metadata template), with assignment time. Use ","description":"List where a retention policy applies (folders, the whole enterprise or a metadata template), with assignment time. Use for \"Which folders does Box retention policy 11111 apply to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"retention_policy_id":{"description":"Retention policy id from list_retention_policies.","maxLength":200,"title":"Retention Policy Id","type":"string"},"type":{"anyOf":[{"enum":["folder","enterprise","metadata_template"],"type":"string"},{"type":"null"}],"default":null,"description":"Only assignments to this kind of target.","title":"Type"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many entries to return (1 to 1000).","title":"Limit"},"marker":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging marker: the next_marker value of the previous answer (omit for the first page).","title":"Marker"}},"required":["retention_policy_id"],"title":"list_retention_policy_assignmentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_file_version_retentions":{"post":{"operationId":"list_file_version_retentions","summary":"List retention records of file versions (when the retention was applied and when the file version is due for disposition","description":"List retention records of file versions (when the retention was applied and when the file version is due for disposition), filtered by file, policy or date. Use for \"Which Box file versions are due for disposition under policy 11111\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"file_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records for this file id.","title":"File Id"},"policy_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records under this retention policy id.","title":"Policy Id"},"disposition_action":{"anyOf":[{"enum":["permanently_delete","remove_retention"],"type":"string"},{"type":"null"}],"default":null,"description":"Only records with this disposition action.","title":"Disposition Action"},"disposition_before":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records due for disposition before this ISO 8601 time.","title":"Disposition Before"},"disposition_after":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only records due for disposition after this ISO 8601 time.","title":"Disposition After"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many entries to return (1 to 1000).","title":"Limit"},"marker":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging marker: the next_marker value of the previous answer (omit for the first page).","title":"Marker"}},"title":"list_file_version_retentionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_legal_hold_policies":{"post":{"operationId":"list_legal_hold_policies","summary":"List the enterprise's legal hold policies with status, description, custodian assignment counts and date filters. Needs ","description":"List the enterprise's legal hold policies with status, description, custodian assignment counts and date filters. Needs Box Governance. Use for \"Which legal hold policies are active in our Box account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"policy_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only policies whose name starts with this text.","title":"Policy Name"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many entries to return (1 to 1000).","title":"Limit"},"marker":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging marker: the next_marker value of the previous answer (omit for the first page).","title":"Marker"}},"title":"list_legal_hold_policiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_legal_hold_policy":{"post":{"operationId":"get_legal_hold_policy","summary":"Get one legal hold policy by id with status, description, date filters and assignment counts. Use for \"What is Box legal","description":"Get one legal hold policy by id with status, description, date filters and assignment counts. Use for \"What is Box legal hold policy 22222\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"legal_hold_policy_id":{"description":"Legal hold policy id from list_legal_hold_policies.","maxLength":200,"title":"Legal Hold Policy Id","type":"string"}},"required":["legal_hold_policy_id"],"title":"get_legal_hold_policyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_legal_hold_assignments":{"post":{"operationId":"list_legal_hold_assignments","summary":"List what a legal hold policy is assigned to (users, folders, files, file versions), with assignment time. Use for \"Who ","description":"List what a legal hold policy is assigned to (users, folders, files, file versions), with assignment time. Use for \"Who and what is under Box legal hold policy 22222\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"policy_id":{"description":"Legal hold policy id from list_legal_hold_policies.","maxLength":40,"title":"Policy Id","type":"string"},"assign_to_type":{"anyOf":[{"enum":["file","file_version","folder","user","ownership","interactions"],"type":"string"},{"type":"null"}],"default":null,"description":"Only assignments to this kind of target.","title":"Assign To Type"},"assign_to_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only assignments to the target with this id (use with assign_to_type).","title":"Assign To Id"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many entries to return (1 to 1000).","title":"Limit"},"marker":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging marker: the next_marker value of the previous answer (omit for the first page).","title":"Marker"}},"required":["policy_id"],"title":"list_legal_hold_assignmentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_file_version_legal_holds":{"post":{"operationId":"list_file_version_legal_holds","summary":"List file versions held by a legal hold policy, with the file name and the assignments that hold them. Use for \"Which Bo","description":"List file versions held by a legal hold policy, with the file name and the assignments that hold them. Use for \"Which Box file versions are held under legal hold policy 22222\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"policy_id":{"description":"Legal hold policy id from list_legal_hold_policies.","maxLength":40,"title":"Policy Id","type":"string"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many entries to return (1 to 1000).","title":"Limit"},"marker":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging marker: the next_marker value of the previous answer (omit for the first page).","title":"Marker"}},"required":["policy_id"],"title":"list_file_version_legal_holdsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}