Attachments

Attachments are the files behind a brand in Cake Slice. On this page, we'll dive into the different attachment endpoints you can use to manage attachments programmatically. We'll look at how to query, create, update, and delete attachments.

The attachment model

Properties

Name
id
Type
uuid
Description
Unique identifier for the attachment.
Name
filename
Type
string
Description
The filename of the attachment.
Name
height
Type
integer
Description
The height in pixels for the attachment (if applicable).
Name
width
Type
integer
Description
The width in pixels for the attachment (if applicable).
Name
size
Type
integer
Description
The size in bytes of the attachment.
Name
mimetype
Type
string
Description
The mimetype of the attachment.
Name
tags
Type
array
Description
Tags that have been applied to the attachment.
Name
caption
Type
string
Description
The caption of the attachment.
Name
description
Type
string
Description
The description of the attachment.
Name
state
Type
enum
Description
The current state of the attachment. This will change automatically as the attachment progresses through the system.
Can be one of created, uploaded, processed, or previewable.
Name
colors
Type
object
Description
Colors extracted from the attachment (if applicable).
Name
exif
Type
object
Description
Embedded EXIT metadata on the attachment (if applicable).
Name
iptc
Type
object
Description
Embedded IPTC metadata on the attachment (if applicable).
Name
library_id
Type
uuid
Description
The unique identifier of the library the attachment belongs to.
Name
created_at
Type
timestamp
Description
Timestamp of when the attachment was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the attachment was last updated.

GET/v1/libraries/:library_id/attachments

List all attachments

This endpoint allows you to retrieve a list of all the attachments for a given library.

Optional params

Name
include
Type
string
Description
A comma separated list of related resources to return in the response. Valid resources to include for attachments are organization and library.
See the API Overview guide for more details on usage.
Name
fields
Type
array
Description
A comma separate list of extra attributes that you would like returned for the attachment. Valid fields for attachments are colors, exif, and iptc.
See the API Overview guide for more details on usage.

Request

GET

/v1/libraries/:library_id/attachments

const response = await fetch(
  "https://api.cakeslice.com/v1/libraries/:library_id/attachments",
  {
    headers: {
      "Authorization": `Bearer ${token}`
    }
  }
)

await response.json()

Response

{
  "data": [
    {
      "id": "abc-def-123",
      "type": "attachment",
      "attributes": {
        "filename": "cake.png",
        "height": 1024,
        "width": 512,
        "size": 561744,
        "mimetype": "image/png",
        "tags": [
          "ai",
          "dessert"
        ],
        "caption": "a slice of cake with a cherry on top",
        "description": "The image features a slice of cake with a cherry on top, placed on a white plate. The cake is white and appears to be a delicious dessert. The plate is positioned on a dining table, which occupies the majority of the scene. The close-up view of the cake slice and cherry creates a mouth-watering visual, inviting the viewer to indulge in a sweet treat.",
        "state": "previewable",
        "library_id": "abc-def-123",
        "created_at": "2025-02-09T21:20:58.501Z",
        "updated_at": "2025-02-14T20:11:46.591Z"
      },
      "relationships": {}
    },
    ...
  ]
}

POST/v1/libraries/:library_id/attachments

Create an attachment

This endpoint allows you to create a new attachment for a given library.

Required attributes

Name
filename
Type
string
Description
The filename of the attachment.

Optional attributes

Name
caption
Type
string
Description
A short caption desribing the attachment.
Name
description
Type
string
Description
A long form description of the attachment.
Name
tags
Type
array
Description
A comma separated list of tags you'd like to have applied to the attachment.

Optional params

Name
include
Type
string
Description
A comma separated list of related resources to return in the response. Valid resources to include for attachments are organization and library.
See the API Overview guide for more details on usage.
Name
fields
Type
array
Description
A comma separate list of extra attributes that you would like returned for the attachment. Valid fields for attachments are colors, exif, and iptc.
See the API Overview guide for more details on usage.

Request

POST

/v1/libraries/:library_id/attachments

const response = await fetch(
  "https://api.cakeslice.com/v1/libraries/:library_id/attachments",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`
    },
    body: JSON.stringify({
      data: {
        attributes: {
          filename: "cake.png"
        }
      }
    })
  }
)

await response.json()

Response

{
  "data": {
    "id": "abc-def-123",
    "type": "attachment",
    "attributes": {
      "filename": "cake.png",
      "height": 1024,
      "width": 512,
      "size": 561744,
      "mimetype": "image/png",
      "tags": [
        "ai",
        "dessert"
      ],
      "caption": "a slice of cake with a cherry on top",
      "description": "The image features a slice of cake with a cherry on top, placed on a white plate. The cake is white and appears to be a delicious dessert. The plate is positioned on a dining table, which occupies the majority of the scene. The close-up view of the cake slice and cherry creates a mouth-watering visual, inviting the viewer to indulge in a sweet treat.",
      "state": "previewable",
      "library_id": "abc-def-123",
      "created_at": "2025-02-09T21:20:58.501Z",
      "updated_at": "2025-02-14T20:11:46.591Z"
    },
    "relationships": {}
  }
}

GET/v1/attachments/:id

Retrieve an attachment

This endpoint allows you to retrieve a attachment by providing the attachment id.

Optional params

Name
include
Type
string
Description
A comma separated list of related resources to return in the response. Valid resources to include for attachments are organization and library.
See the API Overview guide for more details on usage.
Name
fields
Type
array
Description
A comma separate list of extra attributes that you would like returned for the attachment. Valid fields for attachments are colors, exif, and iptc.
See the API Overview guide for more details on usage.

Request

GET

/v1/attachments/:id

const response = await fetch(
  "https://api.cakeslice.com/v1/attachments/:id",
  {
    headers: {
      "Authorization": `Bearer ${token}`
    }
  }
)

await response.json()

Response

{
  "id": "abc-def-123",
  "type": "attachment",
  "attributes": {
    "filename": "cake.png",
    "height": 1024,
    "width": 512,
    "size": 561744,
    "mimetype": "image/png",
    "tags": [
      "ai",
      "dessert"
    ],
    "caption": "a slice of cake with a cherry on top",
    "description": "The image features a slice of cake with a cherry on top, placed on a white plate. The cake is white and appears to be a delicious dessert. The plate is positioned on a dining table, which occupies the majority of the scene. The close-up view of the cake slice and cherry creates a mouth-watering visual, inviting the viewer to indulge in a sweet treat.",
    "state": "previewable",
    "library_id": "abc-def-123",
    "created_at": "2025-02-09T21:20:58.501Z",
    "updated_at": "2025-02-14T20:11:46.591Z"
  },
  "relationships": {}
}

PUT/v1/attachments/:id

Update a attachment

This endpoint allows you to perform an update on a attachment. Examples of updates are changing the caption, description, and tags of the attachment.

Optional attributes

Name
caption
Type
string
Description
A short caption desribing the attachment.
Name
description
Type
string
Description
A long form description of the attachment.
Name
tags
Type
array
Description
A comma separated list of tags you'd like to have applied to the attachment.

Optional params

Name
include
Type
string
Description
A comma separated list of related resources to return in the response. Valid resources to include for attachments are organization and library.
See the API Overview guide for more details on usage.
Name
fields
Type
array
Description
A comma separate list of extra attributes that you would like returned for the attachment. Valid fields for attachments are colors, exif, and iptc.
See the API Overview guide for more details on usage.

Request

PUT

/v1/attachments/:id

const response = await fetch(
  "https://api.cakeslice.com/v1/libraries/:library_id/attachments",
  {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${token}`
    },
    body: JSON.stringify({
      data: {
        attributes: {
          caption: "a slice of cake with a cherry on top"
        }
      }
    })
  }
)

await response.json()

Response

{
  "id": "abc-def-123",
  "type": "attachment",
  "attributes": {
    "filename": "cake.png",
    "height": 1024,
    "width": 512,
    "size": 561744,
    "mimetype": "image/png",
    "tags": [
      "ai",
      "dessert"
    ],
    "caption": "a slice of cake with a cherry on top",
    "description": "The image features a slice of cake with a cherry on top, placed on a white plate. The cake is white and appears to be a delicious dessert. The plate is positioned on a dining table, which occupies the majority of the scene. The close-up view of the cake slice and cherry creates a mouth-watering visual, inviting the viewer to indulge in a sweet treat.",
    "state": "previewable",
    "library_id": "abc-def-123",
    "created_at": "2025-02-09T21:20:58.501Z",
    "updated_at": "2025-02-14T20:11:46.591Z"
  },
  "relationships": {}
}

DELETE/v1/attachments/:id

Delete an attachment

This endpoint allows you to delete attachments. Note: This is permanent.

Request

DELETE

/v1/attachments/:id

const response = await fetch(
  "https://api.cakeslice.com/v1/attachments/:id",
  {
    method: "DELETE",
    headers: {
      "Authorization": `Bearer ${token}`
    }
  }
)

await response.json()

Response

No Content