API Reference

API: Attachments

What It Does

The Attachments API lets you create metadata records for product attachments, list attachments for a product, and soft-delete attachments. Attachment metadata is managed through RPCs; actual file upload and download use the storage layer separately.

Authentication & Permissions

All RPCs require an authenticated session. Mutations require a role with sufficient permissions for the target brand.

RPCs

create_product_attachment_record

Creates a metadata record for a new product attachment.

Request

1{
2  "_brand_id": "uuid",
3  "_product_id": "uuid",
4  "_filename": "test-report.pdf",
5  "_mime_type": "application/pdf",
6  "_size_bytes": 204800
7}

Response

1{
2  "id": "uuid",
3  "product_id": "uuid",
4  "filename": "test-report.pdf",
5  "mime_type": "application/pdf",
6  "size_bytes": 204800,
7  "storage_path": "brand-uuid/product-uuid/attachment-uuid",
8  "created_at": "2026-01-15T12:00:00Z"
9}

Errors

  • Not authenticated — request has no valid JWT.
  • Forbidden — caller does not have sufficient access.
  • Invalid input — request is malformed or cannot be processed.

Notes

  • This RPC creates the metadata record only. File upload is handled separately via the storage layer.

list_product_attachments

Returns all active (non-deleted) attachments for a product.

Request

1{
2  "_brand_id": "uuid",
3  "_product_id": "uuid"
4}

Response

1[
2  {
3    "id": "uuid",
4    "filename": "test-report.pdf",
5    "mime_type": "application/pdf",
6    "size_bytes": 204800,
7    "storage_path": "brand-uuid/product-uuid/attachment-uuid",
8    "created_at": "2026-01-15T12:00:00Z"
9  }
10]

Errors

  • Not authenticated — request has no valid JWT.
  • Forbidden — caller does not have sufficient access.
  • Invalid input — request is malformed or cannot be processed.

soft_delete_product_attachment

Marks an attachment as deleted without permanently removing it.

Request

1{
2  "_brand_id": "uuid",
3  "_attachment_id": "uuid"
4}

Response

1{
2  "id": "uuid",
3  "is_deleted": true,
4  "deleted_at": "2026-01-15T13:00:00Z"
5}

Errors

  • Not authenticated — request has no valid JWT.
  • Forbidden — caller does not have sufficient access.
  • Invalid input — request is malformed or cannot be processed.

Notes

  • Soft-deleted attachments are excluded from list_product_attachments results.