> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/developers/using-the-api/metadata-guide.md).

# 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`
* **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/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
* `value_type`: The attribute type, one of `str`, `single_select`, `multi_select`, `float`, `int`, `bool`, `datetime`, `rating`, `relation`, or `lookup`
* `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/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": "EXISTING_OPTION_ID",
        "name": "Option 1",
        "color": "light_blue",
        "user": true
      },
      {
        "id": "",
        "name": "Option 2",
        "color": "light_green",
        "user": true
      }
    ]
  }'
```

### Important Notes for Options:

* **Include ALL options**: You must include existing options plus new ones, or existing options will be archived and no longer available to choose
* **Option IDs**: Every option needs an `id` field, but you don't need to generate IDs yourself. For existing options, use the `id` returned by the GET call. For new options, send an empty string (`""`) and Shade creates the ID. An option with an empty `id` whose name matches an existing option reuses that option
* **Available colors**: `pink`, `red`, `yellow`, `light_green`, `dark_green`, `light_blue`, `dark_blue`, `purple`
* **Set user to true**: This indicates user-created options

### Adding a Single Option

To add one option without resending the full list, use the option endpoint. It returns the new option, including its generated `id`.

```
POST /workspaces/drives/{DRIVE_ID}/metadata/{METADATA_ID}/option
```

```bash
curl -X POST "https://api.shade.inc/workspaces/drives/YOUR_DRIVE_ID/metadata/METADATA_ID/option" \
  -H "Authorization: YOUR_SHADE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "option_name": "Option 3",
    "option_color": "purple"
  }'
```

This only works for single-select and multi-select attributes, and fails if an option with the same name already exists.

## 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/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/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/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 archiving them
* Use meaningful names for your options
* Reuse the option IDs returned by the API, and leave `id` empty for new options so Shade generates them
* 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/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/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": "",
        "name": "In Progress",
        "color": "yellow",
        "user": true
      },
      {
        "id": "",
        "name": "Completed",
        "color": "light_green",
        "user": true
      }
    ]
  }'

# 3. Set metadata value on an asset (use an option id returned by step 2)
curl -X PUT "https://api.shade.inc/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": "OPTION_ID"
  }'
```

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
