# Get a public URL

> A stored file's stable public link, and whether it works right now.

`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/objects/{object_id}/public-url` (key permission: `buckets:read`)

Returns the file's public link: `https://img.cdn.clatterlabs.xyz/<id>` for images (`image/*`), `https://files.cdn-buckets.clatterlabs.xyz/<object_id>/<name>` for everything else. `public` says whether it works right now. An image's id is replaced when it stops being public, so ask again after making it public.

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

## Response

- `object` (string): Always `public_url`.
- `object_id / bucket_id` (string): The file and its bucket.
- `url` (string): The public link (images: img.cdn.clatterlabs.xyz/<id>; other files: files.cdn-buckets.clatterlabs.xyz/<object_id>/<name>).
- `served_as` (string): `image` (public link on img.cdn.clatterlabs.xyz, cached for a year) or `file` (files.cdn-buckets.clatterlabs.xyz).
- `content_type` (string): The `Content-Type` the link is served with.
- `public` (boolean): `true` when the link works now.
- `visibility` (string): The file's own setting: `inherit`, `private` or `public`.
- `effective_visibility` (string): `public` or `private`: what applies now.
- `bucket_visibility` (string): The bucket's default.

## Example request

```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/objects/OBJECT_ID/public-url" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| `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": "public_url",
  "object_id": "cbo_x4p8t2w6r1k9m3q7n5d0",
  "bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
  "url": "https://img.cdn.clatterlabs.xyz/V1StGXR8Z5jdHi6BmyT2kq",
  "served_as": "image",
  "content_type": "image/png",
  "public": true,
  "visibility": "inherit",
  "effective_visibility": "public",
  "bucket_visibility": "public"
}
```