---
title: "Update all Box Skill cards on file"
method: PUT
path: "/skill_invocations/{skill_id}"
tags: ["Skills"]
---

# Update all Box Skill cards on file

`PUT /skill_invocations/{skill_id}`

An alternative method that can be used to overwrite and update all Box Skill
metadata cards on a file.

## Path parameters

- `skill_id` string, required

## Request body

- object
  - `status` 'invoked' | 'processing' | 'success' | 'transient_failure' | 'permanent_failure', required — Defines the status of this invocation. Set this to `success` when setting Skill cards.
  - `metadata` object, required — 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.
    - `cards` SkillCard[] — A list of Box Skill cards to apply to this file.
      - union — Box Skill card.
        - object — A skill card that contains a set of keywords.
          - `created_at` string, date-time — The optional date and time this card was created at.
          - `type` 'skill_card', required — The value will always be `skill_card`.
          - `skill_card_type` 'keyword', required — The value will always be `keyword`.
          - `skill_card_title` object — The title of the card.
            - `code` string — An optional identifier for the title.
            - `message` string, required — The actual title to show in the UI.
          - `skill` object, required — The service that applied this metadata.
            - `type` 'service', required — The value will always be `service`.
            - `id` string, required — A custom identifier that represent the service that applied this metadata.
          - `invocation` object, required — The invocation of this service, used to track which instance of a service applied the metadata.
            - `type` 'skill_invocation', required — The value will always be `skill_invocation`.
            - `id` string, required — A custom identifier that represent the instance of the service that applied this metadata. For example, if your `image-recognition-service` runs on multiple nodes, this field can be used to identify the ID of the node that was used to apply the metadata.
          - `entries` object[], required — An list of entries in the metadata card.
            - `text` string — The text of the keyword.
        - object — A Box Skill metadata card that places a list of images on a timeline.
          - `created_at` string, date-time — The optional date and time this card was created at.
          - `type` 'skill_card', required — The value will always be `skill_card`.
          - `skill_card_type` 'timeline', required — The value will always be `timeline`.
          - `skill_card_title` object — The title of the card.
            - `code` string — An optional identifier for the title.
            - `message` string, required — The actual title to show in the UI.
          - `skill` object, required — The service that applied this metadata.
            - `type` 'service', required — The value will always be `service`.
            - `id` string, required — A custom identifier that represent the service that applied this metadata.
          - `invocation` object, required — The invocation of this service, used to track which instance of a service applied the metadata.
            - `type` 'skill_invocation', required — The value will always be `skill_invocation`.
            - `id` string, required — A custom identifier that represent the instance of the service that applied this metadata. For example, if your `image-recognition-service` runs on multiple nodes, this field can be used to identify the ID of the node that was used to apply the metadata.
          - `duration` integer — An total duration in seconds of the timeline.
          - `entries` object[], required — A list of entries on the timeline.
            - `text` string — The text of the entry. This would be the display name for an item being placed on the timeline, for example the name of the person who was detected in a video.
            - `appears` object[] — Defines a list of timestamps for when this item should appear on the timeline.
              - …
            - `image_url` string — The image to show on a for an entry that appears on a timeline. This image URL is required for every entry. The image will be shown in a list of items (for example faces), and clicking the image will show the user where that entry appears during the duration of this entry.
        - object — A Box Skill metadata card that adds a transcript to a file.
          - `created_at` string, date-time — The optional date and time this card was created at.
          - `type` 'skill_card', required — The value will always be `skill_card`.
          - `skill_card_type` 'transcript', required — The value will always be `transcript`.
          - `skill_card_title` object — The title of the card.
            - `code` string — An optional identifier for the title.
            - `message` string, required — The actual title to show in the UI.
          - `skill` object, required — The service that applied this metadata.
            - `type` 'service', required — The value will always be `service`.
            - `id` string, required — A custom identifier that represent the service that applied this metadata.
          - `invocation` object, required — The invocation of this service, used to track which instance of a service applied the metadata.
            - `type` 'skill_invocation', required — The value will always be `skill_invocation`.
            - `id` string, required — A custom identifier that represent the instance of the service that applied this metadata. For example, if your `image-recognition-service` runs on multiple nodes, this field can be used to identify the ID of the node that was used to apply the metadata.
          - `duration` integer — An optional total duration in seconds. Used with a `skill_card_type` of `transcript` or `timeline`.
          - `entries` object[], required — An list of entries for the card. This represents the individual entries of the transcription.
            - `text` string — The text of the entry. This would be the transcribed text assigned to the entry on the timeline.
            - `appears` object[] — Defines when a transcribed bit of text appears. This only includes a start time and no end time.
              - …
        - object — A Box Skill metadata card that puts a status message in the metadata sidebar.
          - `created_at` string, date-time — The optional date and time this card was created at.
          - `type` 'skill_card', required — The value will always be `skill_card`.
          - `skill_card_type` 'status', required — The value will always be `status`.
          - `skill_card_title` object — The title of the card.
            - `code` string — An optional identifier for the title.
            - `message` string, required — The actual title to show in the UI.
          - `status` object, required — Sets the status of the skill. This can be used to show a message to the user while the Skill is processing the data, or if it was not able to process the file.
            - `code` 'invoked' | 'processing' | 'success' | 'transient_failure' | 'permanent_failure', required — A code for the status of this Skill invocation. By default each of these will have their own accompanied messages. These can be adjusted by setting the `message` value on this object.
            - `message` string — A custom message that can be provided with this status. This will be shown in the web app to the end user.
          - `skill` object, required — The service that applied this metadata.
            - `type` 'service', required — The value will always be `service`.
            - `id` string, required — A custom identifier that represent the service that applied this metadata.
          - `invocation` object, required — The invocation of this service, used to track which instance of a service applied the metadata.
            - `type` 'skill_invocation', required — The value will always be `skill_invocation`.
            - `id` string, required — A custom identifier that represent the instance of the service that applied this metadata. For example, if your `image-recognition-service` runs on multiple nodes, this field can be used to identify the ID of the node that was used to apply the metadata.
  - `file` object, required — The file to assign the cards to.
    - `type` 'file' — The value will always be `file`.
    - `id` string — The ID of the file.
  - `file_version` object — The optional file version to assign the cards to.
    - `type` 'file_version' — The value will always be `file_version`.
    - `id` string — The ID of the file version.
  - `usage` object — 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.
    - `unit` string — The value will always be `file`.
    - `value` number — Number of resources affected.

## Response `200`

Returns an empty response when the card has been successfully updated.

## Other responses

- `400` — Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value 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.
- `404` — 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.
- `default` — An unexpected client error.

---

[API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)