openapi: 3.1.0 info: title: Box Authorize Authorization Integration Mappings API description: Needs a description. tags: - name: Integration Mappings description: 'Integration Mappings allow the users to manage where content from partner apps is stored in Box.' x-box-tag: integration_mappings paths: /integration_mappings/slack: get: operationId: get_integration_mappings_slack summary: Box List Slack integration mappings tags: - Integration Mappings x-box-tag: integration_mappings description: 'Lists [Slack integration mappings](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) in a users'' enterprise. You need Admin or Co-Admin role to use this endpoint.' parameters: - name: marker description: 'Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`.' in: query required: false example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii schema: type: string - name: limit description: The maximum number of items to return per page. in: query required: false example: 1000 schema: type: integer format: int64 maximum: 1000 - in: query name: partner_item_type schema: type: string enum: - channel nullable: false description: Mapped item type, for which the mapping should be returned example: channel - in: query name: partner_item_id schema: type: string nullable: false description: ID of the mapped item, for which the mapping should be returned example: '12345' - in: query name: box_item_id schema: type: string nullable: false description: Box item ID, for which the mappings should be returned example: '12345' - in: query name: box_item_type schema: nullable: false type: string enum: - folder description: Box item type, for which the mappings should be returned example: folder - in: query name: is_manually_created schema: type: boolean nullable: false description: Whether the mapping has been manually created example: true responses: '200': description: Returns a collection of integration mappings content: application/json: schema: $ref: '#/components/schemas/IntegrationMappings' '400': description: 'The server cannot or will not process the request due to an apparent client error.' content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: Returns a `not_found` error if the integration mapping could not be found. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' post: operationId: post_integration_mappings_slack summary: Box Create Slack integration mapping tags: - Integration Mappings x-box-tag: integration_mappings description: 'Creates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) by mapping a Slack channel to a Box item. You need Admin or Co-Admin role to use this endpoint.' requestBody: content: application/json: schema: $ref: '#/components/schemas/IntegrationMappingSlackCreateRequest' responses: '201': description: Returns the created integration mapping. content: application/json: schema: $ref: '#/components/schemas/IntegrationMapping' '400': description: "Returns a `bad_request` if an incorrect `options`\nwas supplied or the Box folder cannot be\nmapped to this `partner_item_id`.\nError codes:\n* `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account\ndoesn't have co-owner collaboration or is\nnot an owner of the `box_item_id`,\n* `CHANNEL_ALREADY_MAPPED` - channel is already\n mapped to another `box_item_id`,\n* `CHANNEL_NOT_FOUND` - channel was not found,\n* `CHANNEL_NOT_SUITABLE_FOR_CFS` - connect channel, not\nsuitable for Box as Content layer for Slack,\n* `BOX_ENTERPRISE_MISMATCH` - Box folder must be\nowned by the enterprise, which is configured\nto use Box as Content layer for Slack,\n* `CFS_DISABLED` - Box as Content layer\nfor Slack must be enabled for a provided\nSlack workspace or organization\n* `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must\nbe internally owned to the admin's enterprise,\n* `JWT_APP_NOT_AUTHORIZED` - JWT authorization error." content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: Returns a `not_found` error if the integration mapping could not be found. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' /integration_mappings/slack/{integration_mapping_id}: put: operationId: put_integration_mappings_slack_id summary: Box Update Slack integration mapping tags: - Integration Mappings x-box-tag: integration_mappings description: 'Updates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). Supports updating the Box folder ID and options. You need Admin or Co-Admin role to use this endpoint.' parameters: - name: integration_mapping_id description: An ID of an integration mapping example: '11235432' in: path required: true schema: type: string requestBody: content: application/json: schema: type: object properties: box_item: nullable: false allOf: - $ref: '#/components/schemas/IntegrationMappingBoxItemSlack' options: nullable: false allOf: - $ref: '#/components/schemas/IntegrationMappingSlackOptions' description: At least one of `box_item` and `options` must be provided. responses: '200': description: Returns the updated integration mapping object. content: application/json: schema: $ref: '#/components/schemas/IntegrationMapping' '400': description: "Returns a `bad_request` if an incorrect `options` was\nsupplied or the Box folder cannot be mapped to this `partner_item`.\nError codes:\n* `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account\n doesn't have co-owner collaboration or is\n not an owner of the `box_item_id`,\n* `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be\n internally owned to the admin's enterprise,\n* `JWT_APP_NOT_AUTHORIZED` - JWT authorization error." content: application/json: schema: $ref: '#/components/schemas/ClientError' '404': description: Returns `not_found` if integration mapping object was not found. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' delete: operationId: delete_integration_mappings_slack_id summary: Box Delete Slack integration mapping tags: - Integration Mappings x-box-tag: integration_mappings description: 'Deletes a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). You need Admin or Co-Admin role to use this endpoint.' parameters: - name: integration_mapping_id description: An ID of an integration mapping example: '11235432' in: path required: true schema: type: string responses: '204': description: Empty body in response '404': description: Returns a `not_found` error if the integration mapping could not be found. content: application/json: schema: $ref: '#/components/schemas/ClientError' default: description: An unexpected client error. content: application/json: schema: $ref: '#/components/schemas/ClientError' components: schemas: IntegrationMappingPartnerItemSlack: title: Integration mapping mapped item schema for type Slack type: object description: 'The schema for an integration mapping mapped item object for type Slack. Depending if Box for Slack is installed at the org or workspace level, provide **either** `slack_org_id` **or** `slack_workspace_id`. Do not use both parameters at the same time.' properties: type: type: string enum: - channel example: channel description: Type of the mapped item referenced in `id` nullable: false id: type: string example: C12378991223 description: ID of the mapped item (of type referenced in `type`) nullable: false slack_workspace_id: type: string example: T12352314 description: ID of the Slack workspace with which the item is associated. Use this parameter if Box for Slack is installed at a workspace level. Do not use `slack_org_id` at the same time. nullable: true slack_org_id: type: string example: E1234567 description: ID of the Slack org with which the item is associated. Use this parameter if Box for Slack is installed at the org level. Do not use `slack_workspace_id` at the same time. nullable: true required: - id - type IntegrationMappings: title: Integration mappings type: object x-box-resource-id: integration_mappings x-box-tag: integration_mappings description: 'A list of integration mapping objects.' allOf: - type: object description: 'The part of an API response that describes marker based pagination' properties: limit: description: 'The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.' example: 1000 type: integer format: int64 next_marker: description: The marker for the start of the next page of results. example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii type: string nullable: true - properties: entries: type: array description: A list of integration mappings items: $ref: '#/components/schemas/IntegrationMapping' Folder--Base: title: Folder (Base) type: object x-box-resource-id: folder--base x-box-sanitized: true x-box-tag: folders x-box-variants: - base - mini - standard - full x-box-variant: base description: 'The bare basic representation of a folder, the minimal amount of fields returned when using the `fields` query parameter.' required: - id - type properties: id: type: string nullable: false description: 'The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`.' example: '12345' etag: type: string nullable: true example: '1' description: 'The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened.' type: type: string description: '`folder`' example: folder enum: - folder nullable: false User--Base: title: User (Base) type: object x-box-resource-id: user--base x-box-tag: users x-box-variants: - base - mini - standard - full x-box-variant: base description: 'A mini representation of a user, used when nested within another resource.' required: - type - id properties: id: type: string description: The unique identifier for this user example: '11446498' type: type: string description: '`user`' example: user nullable: false enum: - user Folder--Mini: title: Folder (Mini) type: object x-box-resource-id: folder--mini x-box-variant: mini description: 'A mini representation of a file version, used when nested under another resource.' allOf: - $ref: '#/components/schemas/Folder--Base' - properties: sequence_id: allOf: - type: string example: '3' nullable: true description: 'A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource.' - nullable: false name: type: string description: The name of the folder. example: Contracts nullable: false IntegrationMappingBoxItemSlack: title: Integration mapping Box item schema for type Slack type: object description: The schema for an integration mapping Box item object for type Slack properties: type: type: string enum: - folder example: folder description: Type of the mapped item referenced in `id` nullable: false id: type: string example: '1234567891' description: ID of the mapped item (of type referenced in `type`) nullable: false required: - id - type IntegrationMapping--Base: title: Integration mapping (Base) type: object x-box-resource-id: integration_mapping--base x-box-tag: integration_mappings x-box-variant: base x-box-variants: - base - standard - mini description: 'A base representation of an integration mapping object.' properties: id: type: string nullable: false example: '12345' description: 'A unique identifier of a folder mapping (part of a composite key together with `integration_type`)' integration_type: type: string nullable: false description: 'Identifies the Box partner app, with which the mapping is associated. Currently only supports Slack. (part of the composite key together with `id`)' example: slack enum: - slack UserIntegrationMappings: title: User (Integration Mappings) type: object x-box-resource-id: user_integration_mappings_reference x-box-tag: users description: 'A user representation for integration mappings API purposes. Fields name and login are not required.' allOf: - $ref: '#/components/schemas/User--Base' - properties: name: type: string description: The display name of this user example: Aaron Levie maxLength: 50 nullable: false login: type: string format: email description: The primary email address of this user example: ceo@example.com nullable: false IntegrationMappingSlackOptions: title: Integration mapping options for type Slack type: object description: The schema for an integration mapping options object for Slack type. properties: is_access_management_disabled: type: boolean example: true description: 'Indicates whether or not channel member access to the underlying box item should be automatically managed. Depending on type of channel, access is managed through creating collaborations or shared links.' nullable: false IntegrationMappingSlackCreateRequest: title: Create integration mapping request type: object x-box-resource-id: integration_mapping_slack_create_request description: 'A request to create a Slack Integration Mapping object' properties: partner_item: allOf: - $ref: '#/components/schemas/IntegrationMappingPartnerItemSlack' nullable: false box_item: allOf: - $ref: '#/components/schemas/IntegrationMappingBoxItemSlack' nullable: false options: allOf: - $ref: '#/components/schemas/IntegrationMappingSlackOptions' nullable: false required: - partner_item - box_item IntegrationMapping: title: Integration mapping type: object x-box-resource-id: integration_mapping x-box-tag: integration_mappings x-box-variant: standard description: 'A standard representation of an integration mapping object.' allOf: - $ref: '#/components/schemas/IntegrationMapping--Base' - properties: type: type: string example: integration_mapping enum: - integration_mapping description: Mapping type nullable: false partner_item: oneOf: - $ref: '#/components/schemas/IntegrationMappingPartnerItemSlack' nullable: false description: Mapped item object for Slack box_item: allOf: - $ref: '#/components/schemas/Folder--Mini' description: 'The Box folder, to which the object from the partner app domain (referenced in `partner_item_id`) is mapped' nullable: false is_manually_created: type: boolean example: true description: 'Identifies whether the mapping has been manually set (as opposed to being automatically created)' nullable: false options: type: object nullable: false example: {} description: Integration mapping options for Slack anyOf: - $ref: '#/components/schemas/IntegrationMappingSlackOptions' created_by: allOf: - $ref: '#/components/schemas/UserIntegrationMappings' description: 'An object representing the user who created the integration mapping' nullable: false modified_by: allOf: - $ref: '#/components/schemas/UserIntegrationMappings' description: 'The user who last modified the integration mapping' nullable: false created_at: type: string format: date-time description: When the integration mapping object was created example: '2012-12-12T10:53:43-08:00' nullable: false modified_at: type: string format: date-time description: When the integration mapping object was last modified example: '2012-12-12T10:53:43-08:00' nullable: false required: - type - partner_item - box_item ClientError: title: Client error type: object x-box-resource-id: client_error description: A generic error properties: type: description: error example: error type: string enum: - error nullable: false status: description: The HTTP status of the response. example: 400 type: integer format: int32 nullable: false code: description: A Box-specific error code example: item_name_invalid type: string enum: - created - accepted - no_content - redirect - not_modified - bad_request - unauthorized - forbidden - not_found - method_not_allowed - conflict - precondition_failed - too_many_requests - internal_server_error - unavailable - item_name_invalid - insufficient_scope message: description: A short message describing the error. example: Method Not Allowed type: string nullable: false context_info: description: 'A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.' type: object nullable: true properties: message: type: string description: More details on the error. example: Something went wrong. help_url: description: A URL that links to more information about why this error occurred. example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/ type: string nullable: false request_id: description: 'A unique identifier for this response, which can be used when contacting Box support.' type: string example: abcdef123456 nullable: false