List columns

GET

/v1/boards/{id}/columns

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.focal.inc/v1/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/columns");

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/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/columns"),
    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/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/columns"

  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/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/columns"))
    .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/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/columns")
  .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/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/columns',
  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/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/columns';
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/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/columns")
  .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/boards/24ce3d43-516c-4375-9d51-e9a2c8333683/columns";

    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);
}

List the columns defined on a board, ordered by creation time descending. The board id is taken from the path — there’s no space_id query param because the board itself pins the space.

This listing order is the board’s column order: it’s the order each row’s fields array arrives in from GET /v1/boards/{id}/rows when you don’t pass columns. A board carries no left-to-right order of its own — Column.order is a legacy field nothing maintains, so don’t sort by it; the order a board is presented in belongs to a view, as its visible_column_ids.

tags columns carry their selectable options ({ id, name } in display order); mediacolumn columns carry media_attribute_id and media_attribute_type (the media attribute definition they mirror and its data type), plus the attribute’s options when it’s a tags field; other column types report null for all three. config carries additional type-specific settings (e.g. a number column’s unit/decimal_places, a text column’s character_limit) — see Column.config for the full per-type field list; null for types with none.

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

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: boards:read. Rate-limit cost: 5.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string format: uuid

Example

24ce3d43-516c-4375-9d51-e9a2c8333683

Query Parameters

limit

integer

>= 1 <= 100

Max rows per page (1–100). Default 25.

cursor

string

Pagination cursor returned as next_cursor from the previous page.

fields

string

Return only these properties of each column, instead of the full object. id is always included. Omit for the complete object. Selectable: id, board_id, name, type, sub_type, multiple, order, options, media_attribute_id, media_attribute_type, config, organization_id, space_id, created_at, updated_at.

Responses

200

application/json

object

data

required

Array<object>

object

required

string format: uuid

board_id

required

ID of the board this column belongs to.

string format: uuid

name

required

Human-readable column label.

string

type

required

Data type of this column. Dispatch on this when reading the column’s value on a row (Row.fields[].value) to know the JSON shape to expect (for a multi-value column — Row.fields[].multiple is true — it’s the type of each array element):

number / rating → JSON number
checkbox → JSON true / false
date / updatedat → ISO 8601 string
tags / user / media / relation / list → JSON string
richtext → Markdown string
mediacolumn → the referenced media attribute’s type (e.g. a user attribute stores user id strings)
checklist / insights / metricsdata / externaldata / mediaattribute → JSON object
everything else → JSON string

string

Allowed values: text media number tags checkbox user date color link rating richtext updatedat createdat relation mediacolumn externaldata creativeid checklist list insights mediaattribute metricsdata

sub_type

required

Optional refinement of type — present on system columns (e.g. name for the title column, created-by, due-date) that have a special role in the board. null for plain user-defined columns. The title column is identified by sub_type === "name" and its value is also hoisted to Row.title.

string

nullable

Allowed values: name created-by updated-by start-date due-date

multiple

required

When true, the column stores an array of values per row (e.g. multi-select). When false, a single value. For mediacolumn columns this reflects the mirrored media attribute’s cardinality.

boolean

order

required

Legacy sort position — don’t sort by this. No part of the product maintains it: it’s null on the large majority of columns and stale where it is set (it only survives being copied when a board is duplicated or transferred), so a board’s columns can’t be ordered by it. Column order and visibility are a property of a view instead: read a view’s visible_column_ids for the order a board is actually presented in. For a stable order, rely on the listing order of GET /v1/boards/{id}/columns (newest first), which is also the order each row’s fields array uses.

number

nullable

options

required

For tags columns — and mediacolumn columns whose mirrored media attribute is a tags field (media_attribute_type: "tags") — the selectable options in display order (each { id, name }). Such a cell stores option id(s) in Row.fields[].value; map them against this list, or read the resolved label(s) directly from Row.fields[].display_value. null for column types that have no options.

Array<object>

nullable

object

required

Stable option id — the value a tags cell stores in Row.fields[].value.

string

name

required

Human-readable option label shown in the UI.

string

media_attribute_id

required

For mediacolumn columns, the id of the media attribute definition this column mirrors. Attributes of the public field types (text, number, tags, checkbox, date, link, user) can be fetched via GET /v1/media-attributes/{id}, and the inline media_attribute_type, multiple, and options carry everything needed to interpret or write the cell. null for every other column type.

string format: uuid

nullable

media_attribute_type

required

For mediacolumn columns, the data type of the mirrored media attribute — the type that governs the cell’s value shape, writability, and multiple flag (the column’s own type stays "mediacolumn"). null for every other column type, or when the mirrored attribute no longer exists (the column is then read-only).

string

nullable

Allowed values: text number tags checkbox date link user

config

required

Any of:

object

character_limit

required

number

nullable

uppercase

required

boolean

wrap_text

required

boolean

text_format

required

string

nullable

Allowed values: capitalize uppercase lowercase titlecase

object

unit

required

string

nullable

unit_position

required

Whether unit renders before or after the number.

string

Allowed values: prefix suffix

decimal_places

required

number

nullable

number_format

required

string

nullable

Allowed values: bytes duration aspectRatio compact percentage

object

date_format

required

object

style

required

How the date/timestamp value is displayed.

string

Allowed values: friendly iso local month week relative

show_year

required

boolean

hide_current_year

required

With show_year on, still omit the year for dates in the current year.

boolean

show_time

boolean

object

media_column_ids

required

IDs of this board’s media columns whose attached media receive this attribute’s value when the cell is written.

Array<string>

object

naming_convention_id

required

string

nullable

media_column_ids

required

IDs of this board’s media columns this naming convention generates a filename for.

Array<string>

trigger_type

required

string

nullable

Allowed values: new-row new-media automation

automation_id

required

string

nullable

organization_id

required

string format: uuid

space_id

required

string format: uuid

created_at

required

string format: date-time

updated_at

required

string format: date-time

next_cursor

required

Pass back as cursor to fetch the next page. null on the last page.

string

nullable

has_more

required

true when another page is available. Equivalent to next_cursor !== null.

boolean

Example

{
  "data": [
    {
      "id": "87674a42-14d6-4ea3-abce-0507004eb2a0",
      "board_id": "24ce3d43-516c-4375-9d51-e9a2c8333683",
      "name": "Deliverable",
      "type": "text",
      "sub_type": "name",
      "multiple": false,
      "order": null,
      "options": null,
      "media_attribute_id": null,
      "media_attribute_type": "text",
      "config": {
        "character_limit": 280,
        "uppercase": false,
        "wrap_text": true,
        "text_format": "capitalize"
      },
      "organization_id": "b46d9033-24b2-4441-87ad-2151088fde01",
      "space_id": "6916bc3d-e1ab-425b-ac25-eefada01a9a2",
      "created_at": "2027-03-04T10:15:00Z",
      "updated_at": "2027-03-06T14:42:00Z"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNy0wMy0wNFQxMDoxNTowMC4wMDBaIiwiaSI6Ijc4NmJlZWRhLTU1YWMtNDAyNS1iZjZlLTQzYjI5MThlODRhOSJ9",
  "has_more": true
}

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.