Delete a tag option

DELETE

/v1/media-attributes/{id}/options/{option_id}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1/options/80f1e4d3-cbab-42a0-a397-318f348f5f93");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Idempotency-Key: looker-sync-2027-03-04-0001");
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Delete,
    RequestUri = new Uri("https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1/options/80f1e4d3-cbab-42a0-a397-318f348f5f93"),
    Headers =
    {
        { "Idempotency-Key", "looker-sync-2027-03-04-0001" },
        { "Authorization", "Bearer <token>" },
    },
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {

  url := "https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1/options/80f1e4d3-cbab-42a0-a397-318f348f5f93"

  req, _ := http.NewRequest("DELETE", url, nil)

  req.Header.Add("Idempotency-Key", "looker-sync-2027-03-04-0001")
  req.Header.Add("Authorization", "Bearer <token>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1/options/80f1e4d3-cbab-42a0-a397-318f348f5f93"))
    .header("Idempotency-Key", "looker-sync-2027-03-04-0001")
    .header("Authorization", "Bearer <token>")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1/options/80f1e4d3-cbab-42a0-a397-318f348f5f93")
  .delete(null)
  .addHeader("Idempotency-Key", "looker-sync-2027-03-04-0001")
  .addHeader("Authorization", "Bearer <token>")
  .build();

Response response = client.newCall(request).execute();

import axios from 'axios';

const options = {
  method: 'DELETE',
  url: 'https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1/options/80f1e4d3-cbab-42a0-a397-318f348f5f93',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>'
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

const url = 'https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1/options/80f1e4d3-cbab-42a0-a397-318f348f5f93';
const options = {
  method: 'DELETE',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>'
  }
};

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

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1/options/80f1e4d3-cbab-42a0-a397-318f348f5f93")
  .delete(null)
  .addHeader("Idempotency-Key", "looker-sync-2027-03-04-0001")
  .addHeader("Authorization", "Bearer <token>")
  .build()

val response = client.newCall(request).execute()

use std::str::FromStr;
use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1/options/80f1e4d3-cbab-42a0-a397-318f348f5f93";

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Idempotency-Key", "looker-sync-2027-03-04-0001".parse().unwrap());
    headers.insert("Authorization", "Bearer <token>".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.request(reqwest::Method::from_str("DELETE").unwrap(), url)
        .headers(headers)
        .send()
        .await;

    let results = response.unwrap()
        .json::<serde_json::Value>()
        .await
        .unwrap();

    dbg!(results);
}

curl --request DELETE \
  --url https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1/options/80f1e4d3-cbab-42a0-a397-318f348f5f93 \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: looker-sync-2027-03-04-0001'

wget --quiet \
  --method DELETE \
  --header 'Idempotency-Key: looker-sync-2027-03-04-0001' \
  --header 'Authorization: Bearer <token>' \
  --output-document \
  - https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1/options/80f1e4d3-cbab-42a0-a397-318f348f5f93

Permanently remove one option from a tags field and return the updated definition.

Destructive and irreversible. The option is deleted from the field and cleared from every media in the space currently tagged with it; those values are not recoverable. Only the named option is affected. To rename an option — keeping the media tagged with it — use PATCH /v1/media-attributes/{id} instead.

This is the only way to remove an option: PATCH rejects an options array that omits one rather than deleting by omission, so a removal is always something you asked for by id.

An option_id the field doesn’t have returns 400 rather than succeeding silently, so a wrong id never reads as a completed delete — note this makes a retry after a successful delete return 400 unless it carries the original Idempotency-Key.

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. Honors an optional Idempotency-Key.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string format: uuid

Example

846196ad-9fa2-40a8-8938-655a962220e1

option_id

required

string format: uuid

Example

80f1e4d3-cbab-42a0-a397-318f348f5f93

Id of the option to delete, as returned in the definition’s options[].id.

Header Parameters

Idempotency-Key

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.

Responses

200

application/json

object

data

required

object

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

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.

application/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.

application/json

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.

application/json

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.

application/json

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.

application/json

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.

application/json

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

Seconds to wait before retrying.