Create an attribute

POST

/v1/media-attributes

const url = 'https://api.focal.inc/v1/media-attributes';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"space_id":"6916bc3d-e1ab-425b-ac25-eefada01a9a2","name":"Campaign","type":"text","multiple":true,"hide_from_guests":false,"options":[{"name":"Spring Launch","description":"Assets for the Spring 2027 launch campaign."}],"allow_create":false,"show_in_library":true,"autofill":{"prompt":"Pick the campaign this asset belongs to, based on its content and filename.","allowed_media_types":["videos"],"name_only":false}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

• Production

Add a custom field to a space’s media library. The type is fixed at creation (stored values are encoded per type); tags fields can be seeded with options, and every option’s id is returned so you can write values against it immediately.

Creatable types: text, number, tags, checkbox, date, link, user.

Required scope: spaces:write — the scope for a space’s own settings, deliberately separate from media:write (which writes attribute values), because reconfiguring a field reaches every media in the space.

The scope alone is not the gate. When the credential acts for a specific user (an MCP connector grant), that user must also be an organization admin or an owner of the space, or the call is rejected with 403. API tokens are exempt from that check, since only an organization admin can create one. The matching MCP tool is additionally advertised as destructive and non-idempotent, so connector hosts ask the user before each call. Rate-limit cost: 10. Requires an Idempotency-Key.

Authorizations

• bearerAuth

Parameters

Header Parameters

Idempotency-Key

required

string

<= 255 characters

Example

looker-sync-2027-03-04-0001

Client-generated key (≤255 chars) for safe retries. A retry with the same key replays the original response instead of re-applying the write; reusing a key with a different body → 400, an in-flight key → 409.

Request Body^required

Media typeapplication/json

object

space_id

required

The space whose media library gets the new field.

string format: uuid

Example

6916bc3d-e1ab-425b-ac25-eefada01a9a2

name

required

Display name of the field. 1–255 characters.

string

>= 1 characters <= 255 characters

Example

Campaign

type

required

The kind of field to create. Cannot be changed afterwards — stored values are encoded per type — so create a new field instead of retyping one.

string

Allowed values: text number tags checkbox date link user

multiple

Whether the field holds multiple values per media. Only tags and user fields can (400 on any other type). Switching a populated field from multiple to single is destructive — every cell keeps only its first value, across the whole space.

boolean

Example

true

hide_from_guests

Hide this field from Guest users in the media player.

boolean

Example

false

options

Initial options, in display order. tags fields only (400 on any other type); each option’s id is generated and returned. At most 499 options per field.

Array<object>

object

name

required

The option’s label. Must be unique within the field (case-insensitive).

string

>= 1 characters <= 255 characters

Example

Spring Launch

description

Help text shown next to the option in Focal when picking tags. At most 500 characters; send an empty string to clear it.

string

<= 500 characters

Example

Assets for the Spring 2027 launch campaign.

allow_create

Whether new options may be added to this field ad hoc — both while tagging in the app and via POST /v1/media-attributes/{id}/options on the media:write scope alone. When this is false, that call needs spaces:write (plus admin/owner for a connector) instead of being rejected outright. Defaults to false on create, matching the app. tags fields only.

boolean

Example

false

show_in_library

Surface this field’s options as clickable suggestions in media library search. tags fields only.

boolean

Example

true

autofill

AI autofill for this field — an object to configure it, null to turn it off. text and tags fields only (400 on any other type). Enabling it requires a prompt, either in this call or already stored. Turning it on makes the AI write values across the space’s media, so treat it as a change with reach.

object

prompt

The instruction the AI follows when filling this field — e.g. “the primary call to action in this ad”. Required: autofill enabled with no instruction never runs, so this API won’t create that state (the app allows it mid-edit). Rich prompts written in the app may @mention other fields; those read back flattened to @Label text, and writing a plain string replaces the rich content. At most 4000 chars.

string

>= 1 characters <= 4000 characters

Example

Pick the campaign this asset belongs to, based on its content and filename.

allowed_media_types

Restrict autofill to these media kinds. null (the default) runs it on everything. Use this rather than wording the prompt to opt out — a column restricted here is never queued for the wrong kind of media in the first place.

Array<string>

nullable

Allowed values: statics videos

Example

[
  "videos"
]

name_only

When true the AI sees only the media’s filename — no visual analysis, transcript, or metadata. Much cheaper and faster, and the right choice when the answer is encoded in a naming convention.

boolean

Example

false

Responses

201

Created

Media typeapplication/json

object

data

required

object

id

required

The attribute definition id — referenced by media payloads as attributes[].attribute_id.

string format: uuid

name

required

Display name of the field, as media payloads carry in attributes[].attribute_name.

string

type

required

The field’s kind — same enum as attributes[].attribute_type on media payloads. tags fields carry selectable options; fetch them via GET /v1/media-attributes/{id}. user fields hold user ids — resolve them via GET /v1/users.

string

Allowed values: text number tags checkbox date link user

multiple

required

Whether the field holds multiple values per media (e.g. multi-select). Mirrors attributes[].multiple.

boolean

space_id

required

string format: uuid

organization_id

required

string format: uuid

created_at

required

string format: date-time

updated_at

required

string format: date-time

options

required

For tags fields, the selectable options in display order. null for field types that have no options concept.

Array<object>

nullable

object

id

required

Stable option id — the value media payloads carry in attributes[].value for this option. Option renames keep this id; match on it rather than on name when tracking options over time.

string

name

required

Human-readable option label. This is the string media payloads carry in attributes[].display_value for this option.

string

description

required

The option’s help text, shown next to it in Focal when picking tags — what this option means, or when to use it. Empty string when unset; never null, so it’s safe to render directly. Not carried on media payloads, which reference the option by id/display_value only.

string

autofill

required

The field’s AI autofill configuration, or null when autofill is off — which is also what field types that can’t autofill (everything but text and tags) always report. For a tags field the model is additionally given each option’s name and description, so option descriptions act as per-option guidance on top of this instruction.

object

prompt

required

The instruction the AI follows, as plain text. A prompt written in the app with @mentions of other fields is flattened to @Label here.

string

allowed_media_types

required

The media kinds this runs on, or null for all of them.

Array<string>

nullable

Allowed values: statics videos

name_only

required

Whether the AI sees only the filename rather than analyzing the media itself.

boolean

Example

{
  "data": {
    "id": "846196ad-9fa2-40a8-8938-655a962220e1",
    "name": "Campaign",
    "type": "text",
    "multiple": true,
    "space_id": "6916bc3d-e1ab-425b-ac25-eefada01a9a2",
    "organization_id": "b46d9033-24b2-4441-87ad-2151088fde01",
    "created_at": "2027-03-04T10:15:00Z",
    "updated_at": "2027-03-06T14:42:00Z",
    "options": [
      {
        "id": "80f1e4d3-cbab-42a0-a397-318f348f5f93",
        "name": "Spring Launch",
        "description": "Assets for the Spring 2027 launch campaign."
      }
    ],
    "autofill": {
      "prompt": "Pick the campaign this asset belongs to, based on its content and filename.",
      "allowed_media_types": [
        "videos"
      ],
      "name_only": false
    }
  }
}

400

The request was malformed (invalid cursor, unknown type, validation failure, etc.). error.code is bad_request.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "bad_request",
    "message": "Invalid request body",
    "details": [
      {
        "field": "space_id",
        "issue": "Invalid UUID"
      }
    ]
  }
}

401

Missing, invalid, or disabled token. error.code is unauthenticated.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "unauthenticated",
    "message": "Bearer token is missing or invalid"
  }
}

403

The token doesn’t have the scope this endpoint requires. error.code is forbidden.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "forbidden",
    "message": "Token doesn't have the required scope"
  }
}

404

Resource doesn’t exist or is outside the token’s space allow-list. The two cases share a response shape so a restricted token can’t probe for the existence of out-of-scope spaces. error.code is not_found.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "not_found",
    "message": "Not found"
  }
}

409

The request conflicts with the current state. Most commonly a concurrent request carrying the same Idempotency-Key is still in flight. error.code is conflict.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "conflict",
    "message": "A request with this Idempotency-Key is already being processed"
  }
}

429

Rate limit exceeded. error.code is rate_limited. Wait the number of seconds in the Retry-After header before retrying. Quotas are per-token; see the “Rate limiting” section at the top of this document.

Media typeapplication/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 1000 units per 60s exceeded (this request cost 5)"
  }
}

Headers

Retry-After

integer

Example

12

Seconds to wait before retrying.