# Object Storage (GCS)

Blob store backed by Google Cloud Storage. Upload via the edge proxy (authenticated), read directly from GCS (public URL, no key).

## Prerequisites

Provision this resource before use. Edge requests without provisioning will error.

### Provision

    curl -s -X POST https://cohesivity.ai/api/resources/object-storage \
      -H "Authorization: Bearer <coh_management_key>"

### Delete

    curl -s -X DELETE https://cohesivity.ai/api/resources/object-storage \
      -H "Authorization: Bearer <coh_management_key>"

**Important:** Provision this resource now, before building or running the application. Provisioning is the agent's job, not the application's.

## Common Mistakes

- **Using the original filename for download/delete.** Upload adds a random hash to the filename for security (e.g., `cat.jpg` → `cat-a3f8b2c1d4e5f6g7.jpg`). Always use the `path` returned by the upload response, not the original filename.
- **Putting `?key=` URLs in browser-visible HTML.** Never use `<img src="...?key=coh_app_...">`. Use the `url` from the upload response instead — it's a permanent public link with no key.
- **Trying to GET via the edge proxy.** Reads go directly to GCS via the `url` returned by upload. The edge proxy only handles PUT (upload) and DELETE.

## How It Works

Object storage is a blob store: write by path, read by path.

1. **Upload** via the edge proxy (authenticated): `PUT /edge/object-storage/<path>?key=<key>`
2. Response returns `{ok, path, url}` — `path` has a random hash suffix, `url` is a permanent public GCS link
3. **Store `path`** in your database alongside your data — this is your file index
4. **Read** using the `url` directly (e.g., `<img src={post.image_url} />`) — goes straight to Google's CDN, no key, no proxy
5. **Delete** via the edge proxy (authenticated): `DELETE /edge/object-storage/<path>?key=<key>`

## Upload

    PUT https://cohesivity.ai/edge/object-storage/<path>?key=<coh_application_key>
    Content-Type: image/jpeg
    Body: <file bytes>

Response:

    { "ok": true, "path": "photos/cat-a3f8b2c1d4e5f6g7.jpg", "url": "https://storage.googleapis.com/.../<tenant>/photos/cat-a3f8b2c1d4e5f6g7.jpg" }

- `path` — the stored filename (with random hash). Use this for DELETE and store it in your database.
- `url` — permanent public URL. Use this in `<img src>`, `<a href>`, etc. Goes directly to GCS.
- Content-Type is preserved: whatever you set on upload is served on read.

## Delete

    DELETE https://cohesivity.ai/edge/object-storage/<path>?key=<coh_application_key>

Use the `path` from the upload response (the hashed filename).

## Behavior

- **Filenames get a random hash suffix.** `photos/cat.jpg` becomes `photos/cat-a3f8b2c1d4e5f6g7.jpg`. This makes URLs unguessable — knowing the original filename is not enough to access the file.
- **Reads go direct to GCS.** The `url` from upload points to Google's CDN. No Cohesivity proxy, no key in the URL.
- **Blob store model.** Upload returns the file path — store it in your database alongside your data. This is your file index, just like any CDN or blob store.
- **Path rules:** no `..` (directory traversal blocked), no leading/trailing slashes, no backslashes. Paths are case-sensitive.
- **Max file size:** Limited by request timeout and memory. Files up to ~50 MB work reliably.
- **For images:** compress and resize on the client before uploading. Recommended: max 1200px longest side, JPEG quality 0.8.