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

Get existing metadata attributes to see what's already available
Create/update options for select-type attributes as needed
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.

PreviousIntro NextAssets

Last updated 2 months ago