Skip to main content
PUT
/
skill_invocations
/
{skill_id}
Update all Box Skill cards on file
curl -i -X PUT "https://api.box.com/2.0/skill_invocations/33243242" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "status": "success",
       "metadata": {
         "cards": [{
            "type": "skill_card",
            "skill_card_type": "keyword",
            "skill_card_title": {
              "code": "license-plates",
              "message": "Licence Plates"
            },
            "skill": {
              "type": "service",
              "id": "license-plates-service"
            },
            "invocation": {
              "type": "skill_invocation",
              "id": "license-plates-service-123"
            },
            "entries": [
              { "text": "DD-26-YT" },
              { "text": "DN86 BOX" }
            ]
          },{
            "type": "skill_card",
            "skill_card_type": "transcript",
            "skill_card_title": {
              "code": "video-transcription",
              "message": "Video Transcription"
            },
            "skill": {
              "type": "service",
              "id": "video-transcription-service"
            },
            "invocation": {
              "type": "skill_invocation",
              "id": "video-transcription-service-123"
            },
            "duration": 1000,
            "entries": [
              {
                "text": "Hi John, have I told you about Box recently?",
                "appears": [{ "start": 0 }]
              },
              {
                "text": "No Aaron, you have not. Tell me more!",
                "appears": [{ "start": 5 }]
              }
            ]
          },{
            "type": "skill_card",
            "skill_card_type": "timeline",
            "skill_card_title": {
              "code": "face-detection",
              "message": "Faces"
            },
            "skill": {
              "type": "service",
              "id": "face-detection-service"
            },
            "invocation": {
              "type": "skill_invocation",
              "id": "face-detection-service-123"
            },
            "duration": 1000,
            "entries": [
              {
                "text": "John",
                "appears": [{ "start": 0, "end": 5 }, { "start": 10, "end": 15 }],
                "image_url": "https://example.com/john.png"
              },
              {
                "text": "Aaron",
                "appears": [{ "start": 5, "end": 10 }],
                "image_url": "https://example.com/aaron.png"
              }
            ]
          },{
            "type": "skill_card",
            "skill_card_type": "status",
            "skill_card_title": {
              "code": "hold",
              "message": "Please hold..."
            },
            "skill": {
              "type": "service",
              "id": "face-detection-service"
            },
            "invocation": {
              "type": "skill_invocation",
              "id": "face-detection-service-123"
            },
            "status": {
              "code": "processing",
              "message": "We are processing this file right now."
            }
          }]
       },
       "file": {
         "id": "12345"
       },
       "usage": {
         "unit": "file",
         "value": 1
       }
     }'
{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

Documentation Index

Fetch the complete documentation index at: https://developer.box.com/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
skill_id
string
required

The ID of the skill to apply this metadata for.

Body

application/json
​
status
enum<string>
required

Defines the status of this invocation. Set this to success when setting Skill cards.

Available options:
invoked,
processing,
success,
transient_failure,
permanent_failure
Example:

"success"

​
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.

​
file
object
required

The file to assign the cards to.

​
file_version
object

The optional file version to assign the cards to.

​
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.

Response

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