Get an attribute

GET

/v1/media-attributes/{id}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1");

struct curl_slist *headers = NULL;
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.Get,
    RequestUri = new Uri("https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1"),
    Headers =
    {
        { "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"

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

  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"))
    .header("Authorization", "Bearer <token>")
    .method("GET", 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")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build();

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

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.focal.inc/v1/media-attributes/846196ad-9fa2-40a8-8938-655a962220e1',
  headers: {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';
const options = {method: 'GET', headers: {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")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build()

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

use reqwest;

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

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Authorization", "Bearer <token>".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.get(url)
        .headers(headers)
        .send()
        .await;

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

    dbg!(results);
}

Fetch a single attribute definition by id, including its selectable options when the field is a tags field (null for other types). Use this to resolve a tags field’s option set cheaply instead of scanning media values.

Only field types that surface values on media payloads resolve (text, number, tags, checkbox, date, link, user).

Returns 404 when the definition doesn’t exist, is archived, belongs to another organization, or sits outside the token’s space allow-list — the cases share a response so a restricted token can’t probe for out-of-scope definitions.

Pass fields to trim the response to the properties you actually need — e.g. ?fields=name,html_url returns just those (plus id, always). Unknown names are rejected rather than ignored.

Required scope: media:read. Rate-limit cost: 1.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string format: uuid

Example

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

Query Parameters

fields

string

Return only these properties of each media attribute, instead of the full object. id is always included. Omit for the complete object. Selectable: id, name, type, multiple, space_id, organization_id, created_at, updated_at, options, autofill.

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"
  }
}

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.