Update a collection

PATCH

/v1/collections/{id}

const url = 'https://api.focal.inc/v1/collections/e46511f7-712d-4342-884d-1d4f2a460332';
const options = {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"name":"Spring lookbook – approved","description":"Approved lookbook imagery for the spring launch.","media_ids":["786beeda-55ac-4025-bf6e-43b2918e84a9","7f114aec-ab11-4877-9b14-82e8c1cced16"],"add_media_ids":["786beeda-55ac-4025-bf6e-43b2918e84a9","7f114aec-ab11-4877-9b14-82e8c1cced16"],"remove_media_ids":["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);
}

• Production

Rename a collection, change its description, change which media it holds, or configure its share link. Only the fields you include change.

sharing governs the public link in sharing.url: set or clear its password, set or clear an expiry day, and toggle whether guests may download, comment, or change media statuses. Only the sharing keys you include change. The link cannot be minted or revoked — archiving the collection is what stops it resolving.

Membership has three mutually exclusive forms: media_ids replaces the whole list (anything not named is removed), add_media_ids appends, and remove_media_ids takes ids out. Sending media_ids alongside either of the others is a 400. Removing media from a collection never touches the media themselves.

Returns the updated collection.

Required scope: collections:write. Rate-limit cost: 10. Honors an optional Idempotency-Key.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Example

e46511f7-712d-4342-884d-1d4f2a460332

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

Media typeapplication/json

object

name

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

nullable <= 2000 characters

Example

Approved lookbook imagery for the spring launch.

media_ids

REPLACES the collection’s membership with exactly this list, in this order — media not named here are removed. To add or remove a few without restating the rest, use add_media_ids / remove_media_ids instead. Cannot be combined with either.

Array<string>

Example

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

add_media_ids

Append these media to the end of the collection, keeping what is already there. Ids already in the collection are ignored rather than duplicated. Cannot be combined with media_ids.

Array<string>

Example

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

remove_media_ids

Remove these media from the collection, leaving the rest in order. Ids that aren’t in the collection are ignored. The media themselves are untouched — only the membership changes. Cannot be combined with media_ids.

Array<string>

Example

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

200

OK

Media typeapplication/json

object

data

required

object

id

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.

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.