openapi: 3.1.0
info:
  title: Box Skill Invocations API
  description: Needs a description.
paths:
  /skill_invocations/{skill_id}:
    put:
      operationId: put_skill_invocations_id
      summary: Update all Box Skill cards on file
      tags:
        - Skill Invocations
      x-box-tag: skills
      description: >-
        An alternative method that can be used to overwrite and update all Box
        Skill

        metadata cards on a file.
      parameters:
        - name: skill_id
          description: The ID of the skill to apply this metadata for.
          example: '33243242'
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - status
                - metadata
                - file
              properties:
                status:
                  type: string
                  description: >-
                    Defines the status of this invocation. Set this to `success`
                    when setting Skill cards.
                  example: success
                  enum:
                    - invoked
                    - processing
                    - success
                    - transient_failure
                    - permanent_failure
                metadata:
                  type: object
                  description: >-
                    The metadata to set for this skill. This is a list of

                    Box Skills cards. These cards will overwrite any existing
                    Box

                    skill cards on the file.
                  properties:
                    cards:
                      type: array
                      description: A list of Box Skill cards to apply to this file.
                      items:
                        oneOf:
                          - $ref: '#/components/schemas/KeywordSkillCard'
                          - $ref: '#/components/schemas/TimelineSkillCard'
                          - $ref: '#/components/schemas/TranscriptSkillCard'
                          - $ref: '#/components/schemas/StatusSkillCard'
                file:
                  type: object
                  description: The file to assign the cards to.
                  properties:
                    type:
                      type: string
                      description: '`file`'
                      example: file
                      enum:
                        - file
                    id:
                      type: string
                      description: The ID of the file
                      example: '3243244'
                file_version:
                  type: object
                  description: The optional file version to assign the cards to.
                  properties:
                    type:
                      type: string
                      description: '`file_version`'
                      example: file_version
                      enum:
                        - file_version
                    id:
                      type: string
                      description: The ID of the file version
                      example: '731381601045'
                usage:
                  type: object
                  description: >-
                    A descriptor that defines what items are affected by this
                    call.


                    Set this to the default values when setting a card to a
                    `success`

                    state, and leave it out in most other situations.
                  properties:
                    unit:
                      type: string
                      example: file
                      description: '`file`'
                    value:
                      type: number
                      example: 1
                      description: '`1`'
      responses:
        '200':
          description: >-
            Returns an empty response when the card has been successfully
            updated.
        '400':
          description: >-
            Returns an error when the request body is not valid.


            * `schema_validation_failed` - The request body contains a value for
            a for

            a field that either does not exist, or for which the value or type
            does

            not match the expected field type. An example might be an unknown
            option

            for an `enum` or `multiSelect` field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: >-
            Returns an error when the file could not be found or the user does
            not

            have access.


            * `not_found` - The file could not be found, or the user does not
            have

            access to the file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    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
tags:
  - name: Skill Invocations