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.