# Metadata Guide

## 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

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://academy.shade.inc/developers/using-the-api/metadata-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.