# Set file visibility

> Make one stored file public or private.

`PATCH https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/objects/{object_id}/visibility` (key permission: `buckets:write`)

Sets a stored zip or asset to `public`, `private`, or `inherit` (follow the bucket, the default). A public file is served, decrypted, at its `public_url` (images on `https://img.cdn.clatterlabs.xyz/<id>`, other files on `https://files.cdn-buckets.clatterlabs.xyz`) to anyone with the link; switching it back to private blocks the link on the next request. Recorded as an `object.visibility_changed` event. Counts as 1 token like any request. Making an image private retires its image id for good; it gets a new one if it's made public again.

## Authorizations

- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): The Account ID that owns the key, like `CL-7K2M9QXA`. Find it in Console › Settings. A missing value answers `401 missing_account_id`; someone else's answers `401 account_mismatch`.

## Path parameters

- `bucket_id` (string, required): The bucket id (`cbk_…`).
- `object_id` (string, required): The object id (`cbo_…`) of a stored zip or asset.

## Body

- `visibility` (string, required): `public`, `private` or `inherit`.

## Response

- `object` (string): `upload` while it's being uploaded, then `object`.
- `id` (string): The upload id, which is also the stored object's id (`cbo_…`).
- `bucket_id` (string): The bucket it belongs to.
- `kind` (string): `archive` (a zip of code) or `asset` (any other file).
- `name` (string): The file name.
- `target_path` (string): Archives only: the folder the zip is unpacked into (`""` = the whole tree).
- `size` (integer): Size in bytes.
- `chunk_size` (integer): Bytes per chunk: 16,777,216 (16 MiB).
- `chunk_count` (integer): How many chunks the file has.
- `status` (string): `uploading`, `processing` (building the preview), `ready` or `failed`.
- `received_chunks` (integer[]): While `uploading`: the chunk indexes already stored. Upload only the missing ones to resume.
- `preview` (object): Archives only: `{ status, files, skipped, skipped_examples, stripped_folder, ms }`. `status` is `pending`, `extracting`, `ready`, `partial`, `failed` or `off`; `ms` is how long building the preview took, in milliseconds.
- `visibility` (string): The file's own setting: `inherit` (default: follow the bucket), `private` or `public`.
- `effective_visibility` (string): What applies now: `private` or `public` (the file's setting, or the bucket's when it's `inherit`).
- `public_url` (string | null): The file's public link while it's public and stored, `null` otherwise. Images (`image/*`) get `https://img.cdn.clatterlabs.xyz/<id>`; everything else `https://files.cdn-buckets.clatterlabs.xyz/<object_id>/<name>`. See [Public files](/code-buckets/public-files).
- `served_as` (string): `image` (public link on img.cdn.clatterlabs.xyz, cached for a year) or `file` (files.cdn-buckets.clatterlabs.xyz).
- `encrypted` (boolean): Always `true`.
- `created_at / completed_at` (string): ISO 8601 timestamps.

## Example request

```bash
curl -X PATCH "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/objects/OBJECT_ID/visibility" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "public"
  }'
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| `400` | `bad_request` | `visibility` isn't `public`, `private` or `inherit`. |
| `401` | `invalid_api_key / missing_account_id / account_mismatch` | The key or Account ID is wrong. |
| `402` | `quota_exceeded` | This month's free tokens are used up. |
| `403` | `insufficient_scope` | The key lacks the permission. |
| `404` | `not_found` | No bucket or object with that id on your account. |
| `409` | `not_ready` | The upload isn't complete yet. |

## Example response

```json
{
  "object": "object",
  "id": "cbo_x4p8t2w6r1k9m3q7n5d0",
  "bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
  "kind": "asset",
  "name": "hero.png",
  "content_type": "image/png",
  "size": 482133,
  "chunk_size": 16777216,
  "chunk_count": 1,
  "status": "ready",
  "visibility": "public",
  "effective_visibility": "public",
  "public_url": "https://img.cdn.clatterlabs.xyz/V1StGXR8Z5jdHi6BmyT2kq",
  "served_as": "image",
  "encrypted": true,
  "created_at": "2026-10-28T14:05:11.482Z",
  "completed_at": "2026-10-28T14:06:40.019Z"
}
```