Create a collection

POST

/v1/collections

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.focal.inc/v1/collections");

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>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{ \"space_id\": \"6916bc3d-e1ab-425b-ac25-eefada01a9a2\", \"name\": \"Spring lookbook – approved\", \"description\": \"Approved lookbook imagery for the spring launch.\", \"media_ids\": [ \"786beeda-55ac-4025-bf6e-43b2918e84a9\", \"7f114aec-ab11-4877-9b14-82e8c1cced16\" ], \"sharing\": { \"password\": \"pine-trail-2027\", \"expires_at\": \"2027-04-30\", \"allow_download\": true, \"allow_comments\": true, \"allow_status_change\": false } }");

CURLcode ret = curl_easy_perform(hnd);

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://api.focal.inc/v1/collections"),
    Headers =
    {
        { "Idempotency-Key", "looker-sync-2027-03-04-0001" },
        { "Authorization", "Bearer <token>" },
    },
    Content = new StringContent("{ \"space_id\": \"6916bc3d-e1ab-425b-ac25-eefada01a9a2\", \"name\": \"Spring lookbook – approved\", \"description\": \"Approved lookbook imagery for the spring launch.\", \"media_ids\": [ \"786beeda-55ac-4025-bf6e-43b2918e84a9\", \"7f114aec-ab11-4877-9b14-82e8c1cced16\" ], \"sharing\": { \"password\": \"pine-trail-2027\", \"expires_at\": \"2027-04-30\", \"allow_download\": true, \"allow_comments\": true, \"allow_status_change\": false } }")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

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

func main() {

  url := "https://api.focal.inc/v1/collections"

  payload := strings.NewReader("{ \"space_id\": \"6916bc3d-e1ab-425b-ac25-eefada01a9a2\", \"name\": \"Spring lookbook – approved\", \"description\": \"Approved lookbook imagery for the spring launch.\", \"media_ids\": [ \"786beeda-55ac-4025-bf6e-43b2918e84a9\", \"7f114aec-ab11-4877-9b14-82e8c1cced16\" ], \"sharing\": { \"password\": \"pine-trail-2027\", \"expires_at\": \"2027-04-30\", \"allow_download\": true, \"allow_comments\": true, \"allow_status_change\": false } }")

  req, _ := http.NewRequest("POST", url, payload)

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

  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/collections"))
    .header("Idempotency-Key", "looker-sync-2027-03-04-0001")
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{ \"space_id\": \"6916bc3d-e1ab-425b-ac25-eefada01a9a2\", \"name\": \"Spring lookbook – approved\", \"description\": \"Approved lookbook imagery for the spring launch.\", \"media_ids\": [ \"786beeda-55ac-4025-bf6e-43b2918e84a9\", \"7f114aec-ab11-4877-9b14-82e8c1cced16\" ], \"sharing\": { \"password\": \"pine-trail-2027\", \"expires_at\": \"2027-04-30\", \"allow_download\": true, \"allow_comments\": true, \"allow_status_change\": false } }"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{ \"space_id\": \"6916bc3d-e1ab-425b-ac25-eefada01a9a2\", \"name\": \"Spring lookbook – approved\", \"description\": \"Approved lookbook imagery for the spring launch.\", \"media_ids\": [ \"786beeda-55ac-4025-bf6e-43b2918e84a9\", \"7f114aec-ab11-4877-9b14-82e8c1cced16\" ], \"sharing\": { \"password\": \"pine-trail-2027\", \"expires_at\": \"2027-04-30\", \"allow_download\": true, \"allow_comments\": true, \"allow_status_change\": false } }");
Request request = new Request.Builder()
  .url("https://api.focal.inc/v1/collections")
  .post(body)
  .addHeader("Idempotency-Key", "looker-sync-2027-03-04-0001")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build();

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

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.focal.inc/v1/collections',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  data: {
    space_id: '6916bc3d-e1ab-425b-ac25-eefada01a9a2',
    name: 'Spring lookbook – approved',
    description: 'Approved lookbook imagery for the spring launch.',
    media_ids: ['786beeda-55ac-4025-bf6e-43b2918e84a9', '7f114aec-ab11-4877-9b14-82e8c1cced16'],
    sharing: {
      password: 'pine-trail-2027',
      expires_at: '2027-04-30',
      allow_download: true,
      allow_comments: true,
      allow_status_change: false
    }
  }
};

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

const url = 'https://api.focal.inc/v1/collections';
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":"Spring lookbook – approved","description":"Approved lookbook imagery for the spring launch.","media_ids":["786beeda-55ac-4025-bf6e-43b2918e84a9","7f114aec-ab11-4877-9b14-82e8c1cced16"],"sharing":{"password":"pine-trail-2027","expires_at":"2027-04-30","allow_download":true,"allow_comments":true,"allow_status_change":false}}'
};

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

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{ \"space_id\": \"6916bc3d-e1ab-425b-ac25-eefada01a9a2\", \"name\": \"Spring lookbook – approved\", \"description\": \"Approved lookbook imagery for the spring launch.\", \"media_ids\": [ \"786beeda-55ac-4025-bf6e-43b2918e84a9\", \"7f114aec-ab11-4877-9b14-82e8c1cced16\" ], \"sharing\": { \"password\": \"pine-trail-2027\", \"expires_at\": \"2027-04-30\", \"allow_download\": true, \"allow_comments\": true, \"allow_status_change\": false } }")
val request = Request.Builder()
  .url("https://api.focal.inc/v1/collections")
  .post(body)
  .addHeader("Idempotency-Key", "looker-sync-2027-03-04-0001")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

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

use serde_json::json;
use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "https://api.focal.inc/v1/collections";

    let payload = json!({
        "space_id": "6916bc3d-e1ab-425b-ac25-eefada01a9a2",
        "name": "Spring lookbook – approved",
        "description": "Approved lookbook imagery for the spring launch.",
        "media_ids": ("786beeda-55ac-4025-bf6e-43b2918e84a9", "7f114aec-ab11-4877-9b14-82e8c1cced16"),
        "sharing": json!({
            "password": "pine-trail-2027",
            "expires_at": "2027-04-30",
            "allow_download": true,
            "allow_comments": true,
            "allow_status_change": false
        })
    });

    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());
    headers.insert("Content-Type", "application/json".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.post(url)
        .headers(headers)
        .json(&payload)
        .send()
        .await;

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

    dbg!(results);
}

curl --request POST \
  --url https://api.focal.inc/v1/collections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: looker-sync-2027-03-04-0001' \
  --data '{ "space_id": "6916bc3d-e1ab-425b-ac25-eefada01a9a2", "name": "Spring lookbook – approved", "description": "Approved lookbook imagery for the spring launch.", "media_ids": [ "786beeda-55ac-4025-bf6e-43b2918e84a9", "7f114aec-ab11-4877-9b14-82e8c1cced16" ], "sharing": { "password": "pine-trail-2027", "expires_at": "2027-04-30", "allow_download": true, "allow_comments": true, "allow_status_change": false } }'

wget --quiet \
  --method POST \
  --header 'Idempotency-Key: looker-sync-2027-03-04-0001' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --body-data '{ "space_id": "6916bc3d-e1ab-425b-ac25-eefada01a9a2", "name": "Spring lookbook – approved", "description": "Approved lookbook imagery for the spring launch.", "media_ids": [ "786beeda-55ac-4025-bf6e-43b2918e84a9", "7f114aec-ab11-4877-9b14-82e8c1cced16" ], "sharing": { "password": "pine-trail-2027", "expires_at": "2027-04-30", "allow_download": true, "allow_comments": true, "allow_status_change": false } }' \
  --output-document \
  - https://api.focal.inc/v1/collections

Create a collection in a space, optionally seeded with media. Every id in media_ids must be live media in that same space; one that isn’t fails the request rather than being dropped. Returns the created collection.

Every collection carries a share link (sharing.url) that opens a guest view in a browser with no Focal account. Pass sharing to set a password, an expiry day, and what guests may do before you hand the link out.

Required scope: collections:write. Rate-limit cost: 10. An Idempotency-Key header is required.

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. Required on POST; optional on PATCH/DELETE. A UUID v4 is recommended — generate one per logical write and reuse it only for retries of that write.

Request Body^required

application/json

object

space_id

required

The space to create the collection in.

string format: uuid

Example

6916bc3d-e1ab-425b-ac25-eefada01a9a2

name

required

Display name of the collection. 1–255 characters.

string

>= 1 characters <= 255 characters

Example

Spring lookbook – approved

description

Free-text description of the collection (≤2000 characters).

string

<= 2000 characters

Example

Approved lookbook imagery for the spring launch.

media_ids

Media to put in the collection, in display order. Every id must be live media in the same space; an id that isn’t rejects the whole entry rather than silently dropping it.

Array<string>

Example

[
  "786beeda-55ac-4025-bf6e-43b2918e84a9",
  "7f114aec-ab11-4877-9b14-82e8c1cced16"
]

sharing

Share-link settings. Only the keys you include change; the rest keep their current values. The link itself always exists and cannot be minted or revoked — archive the collection to stop it resolving.

object

password

Password a guest must type to open the share link. Send null to remove the password and let anyone with the link in. Never returned by any read — sharing.password_protected tells you whether one is set.

string

nullable >= 4 characters <= 255 characters

Example

pine-trail-2027

expires_at

Calendar day (YYYY-MM-DD) after which the share link stops resolving. Send null to let it live forever.

string format: date

nullable

Example

2027-04-30

allow_download

Let guests download the collection’s media.

boolean

Example

true

allow_comments

Let guests comment on the collection’s media.

boolean

Example

true

allow_status_change

Let guests change the status of the collection’s media.

boolean

Example

false

Responses

201

Created

application/json

object

data

required

object

required

string format: uuid

name

required

string

description

required

string

nullable

space_id

required

string format: uuid

organization_id

required

string format: uuid

media_count

required

How many media the collection holds.

integer

media_ids

required

The collection’s media, in display order. Select it only when you need the membership itself — a large collection returns thousands of ids; media_count alone is usually what you want.

Array<string>

created_by_id

required

The user who created the collection; null for collections created before the column existed.

string format: uuid

nullable

created_at

required

string format: date-time

updated_at

required

string format: date-time

html_url

required

Browser URL that opens this collection in the Focal web app. Hand this to users as a clickable link. This is the internal view and needs a Focal account — for a link to send outside the organization use sharing.url.

string

sharing

required

The collection’s share link and the settings that govern it.

object

url

required

The collection’s share link — the browser URL that opens its guest view, with no Focal account needed. Hand this to people outside the organization. Every collection has one; what the other sharing fields control is who gets past it and what they may do once inside.

string

password_protected

required

Whether the share link asks for a password before showing the collection. The password itself is never returned.

boolean

expires_at

required

Calendar day (YYYY-MM-DD) after which the share link stops resolving, or null when it never expires.

string format: date

nullable

allow_download

required

Whether guests may download the collection’s media.

boolean

allow_comments

required

Whether guests may comment on the collection’s media.

boolean

allow_status_change

required

Whether guests may change the status of the collection’s media.

boolean

Example

{
  "data": {
    "id": "e46511f7-712d-4342-884d-1d4f2a460332",
    "name": "Spring lookbook – approved",
    "description": "Approved lookbook imagery for the spring launch.",
    "space_id": "6916bc3d-e1ab-425b-ac25-eefada01a9a2",
    "organization_id": "b46d9033-24b2-4441-87ad-2151088fde01",
    "media_count": 2,
    "media_ids": [
      "786beeda-55ac-4025-bf6e-43b2918e84a9",
      "7f114aec-ab11-4877-9b14-82e8c1cced16"
    ],
    "created_by_id": "cfebb6ef-f092-4591-a6e3-e6667ab5a252",
    "created_at": "2027-03-04T10:15:00Z",
    "updated_at": "2027-03-06T14:42:00Z",
    "html_url": "https://app.focal.inc/spaces/6916bc3d-e1ab-425b-ac25-eefada01a9a2/collections/e46511f7-712d-4342-884d-1d4f2a460332",
    "sharing": {
      "url": "https://app.focal.inc/collections/e46511f7-712d-4342-884d-1d4f2a460332",
      "password_protected": true,
      "expires_at": "2027-04-30",
      "allow_download": true,
      "allow_comments": true,
      "allow_status_change": 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.

Create a collection

Authorizations

Parameters

Header Parameters

Example

Request Bodyrequired

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

409

Example

429

Example

Headers

Example

Request Body^required