Metadata Guide

A beginner's guide to creating and managing metadata attributes and options using the Shade API.

Prerequisites

• Shade API key (stored in environment variable SHADE_KEY)

• Drive ID for your Shade workspace

• Basic understanding of REST APIs and curl commands

Base Information

• API Base URL: https://api.shade.inc/v1

• Authentication: Include your API key in the Authorization header

• Content Type: Always use application/json for POST/PUT requests

1. Getting Metadata Attributes

First, you'll want to see what metadata attributes already exist in your drive.

API Endpoint

GET /workspaces/drives/{DRIVE_ID}/metadata

Curl Command

curl -X GET "https://api.shade.inc/v1/workspaces/drives/YOUR_DRIVE_ID/metadata" \
  -H "Authorization: YOUR_SHADE_API_KEY"

Response

This returns an array of metadata attributes, each containing:

• id: The metadata ID (needed for updates)

• name: The attribute name

• type: The attribute type (text, singleselect, multiselect, etc.)

• options: Array of options for select-type fields

2. Creating/Updating Options for Select Attributes

To add new options to single-select or multi-select metadata attributes, you update the entire attribute.

API Endpoint

PUT /workspaces/drives/{DRIVE_ID}/metadata/{METADATA_ID}

Curl Command

curl -X PUT "https://api.shade.inc/v1/workspaces/drives/YOUR_DRIVE_ID/metadata/METADATA_ID" \
  -H "Authorization: YOUR_SHADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Attribute Name",
    "automated": false,
    "prompt": "",
    "default": "",
    "add_new_options": true,
    "options": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Option 1",
        "color": "blue",
        "user": true
      },
      {
        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "name": "Option 2",
        "color": "green",
        "user": true
      }
    ]
  }'

Important Notes for Options:

• Include ALL options: You must include existing options plus new ones, or existing options will be removed

• Generate UUIDs: Each option needs a unique UUID (use uuidgen or online generators)

• Available colors: pink, red, yellow, light_green, dark_green, light_blue, purple

• Set user to true: This indicates user-created options

3. Setting Metadata Values on Assets

Once you have your metadata attributes and options set up, you can assign values to specific assets.

API Endpoint

PUT /assets/{ASSET_ID}/metadata/{METADATA_ID}/value

Curl Commands by Metadata Type

For Text Metadata:

curl -X PUT "https://api.shade.inc/v1/assets/ASSET_ID/metadata/METADATA_ID/value" \
  -H "Authorization: YOUR_SHADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "drive_id": "YOUR_DRIVE_ID",
    "metadata_attribute_value": "Some text value"
  }'

For Single Select Metadata:

curl -X PUT "https://api.shade.inc/v1/assets/ASSET_ID/metadata/METADATA_ID/value" \
  -H "Authorization: YOUR_SHADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "drive_id": "YOUR_DRIVE_ID",
    "metadata_attribute_value": "option-uuid-here"
  }'

For Multi-Select Metadata:

curl -X PUT "https://api.shade.inc/v1/assets/ASSET_ID/metadata/METADATA_ID/value" \
  -H "Authorization: YOUR_SHADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "drive_id": "YOUR_DRIVE_ID",
    "metadata_attribute_value": ["option-uuid-1", "option-uuid-2", "option-uuid-3"]
  }'

4. Common Workflow

1. Get existing metadata attributes to see what's already available

2. Create/update options for select-type attributes as needed

3. Set metadata values on your assets using the appropriate value format

5. Value Format Reference

Metadata Type	Value Format	Example
Text	String	"My text value"
Single Select	Option UUID	"550e8400-e29b-41d4-a716-446655440000"
Multi-Select	Array of Option UUIDs	["uuid1", "uuid2", "uuid3"]

6. Tips and Best Practices

• Always get the current metadata attributes first to understand the existing structure

• When updating options, include all existing options to avoid accidentally removing them

• Use meaningful names for your options

• Generate proper UUIDs for new options (don't make them up)

• Test with a single asset before bulk operations

• Handle API errors gracefully in your scripts

7. Error Handling

Common errors you might encounter:

• 401 Unauthorized: Check your API key

• 404 Not Found: Verify your drive ID, asset ID, or metadata ID

• 400 Bad Request: Check your JSON format and required fields

• 422 Unprocessible Entity: Verify the metadata value format matches the attribute type

Example: Complete Workflow

# 1. Get metadata attributes
curl -X GET "https://api.shade.inc/v1/workspaces/drives/YOUR_DRIVE_ID/metadata" \
  -H "Authorization: YOUR_API_KEY"

# 2. Add options to a select attribute (replace METADATA_ID with actual ID)
curl -X PUT "https://api.shade.inc/v1/workspaces/drives/YOUR_DRIVE_ID/metadata/METADATA_ID" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Status",
    "automated": false,
    "prompt": "",
    "default": "",
    "add_new_options": true,
    "options": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "In Progress",
        "color": "yellow",
        "user": true
      },
      {
        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "name": "Completed",
        "color": "green",
        "user": true
      }
    ]
  }'

# 3. Set metadata value on an asset
curl -X PUT "https://api.shade.inc/v1/assets/YOUR_ASSET_ID/metadata/METADATA_ID/value" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "drive_id": "YOUR_DRIVE_ID",
    "metadata_attribute_value": "550e8400-e29b-41d4-a716-446655440000"
  }'

Replace YOUR_DRIVE_ID, YOUR_API_KEY, METADATA_ID, and YOUR_ASSET_ID with your actual values.