Mutations

Mutations change data in Raster. Every mutation is a POST request to https://api.raster.app/ and needs an API key or OAuth access token with Write access to the target library.

uploadAssets

Uploads up to 20 files to a library in a single request.

Parameters

Returns

Example

mutation {
  uploadAssets(
    organizationId: "acme-co"
    libraryId: "barcelona"
    files: [$file1, $file2]
  ) {
    responseText
    assets {
      id
      name
      filename
      contentType
      created
      tags
      status
      progress
    }
  }
}

deleteAssets

Moves one or more assets to trash (soft delete), as the Raster app does. They leave assets and searchAssets immediately, stay recoverable from trash, and are permanently removed after 30 days.

Trashing an asset also trashes its variants. A variant goes to trash only with its original, so a variant id in assets fails the whole call with 400 BAD_USER_INPUT before anything moves. Pass the original's id instead.

Parameters

Returns

Example

mutation {
  deleteAssets(
    organizationId: "acme-co"
    libraryId: "barcelona"
    assets: ["asset-123", "asset-456"]
  ) {
    success
    message
    ids
  }
}

tagAssets

Applies one or more tags to a batch of assets in a single library. The call is idempotent: (asset, tag) pairs the asset already carries are skipped and don't count toward taggedCount.

Parameters

Returns

Example

mutation {
  tagAssets(
    organizationId: "acme-co"
    libraryId: "barcelona"
    assetIds: ["asset-123", "asset-456"]
    tags: ["sunset", "landscape"]
  ) {
    taggedCount
  }
}

untagAssets

Removes one or more tags from a batch of assets in a single library. Like tagAssets, it is idempotent: pairs the asset doesn't carry are skipped.

Parameters

Returns

Example

mutation {
  untagAssets(
    organizationId: "acme-co"
    libraryId: "barcelona"
    assetIds: ["asset-123"]
    tags: ["landscape"]
  ) {
    untaggedCount
  }
}

updateAssetDescription

Replaces the description on a single asset. The value is stored verbatim. Pass an empty string to clear the field.

Parameters

Returns

Example

mutation {
  updateAssetDescription(
    organizationId: "acme-co"
    libraryId: "barcelona"
    assetId: "asset-123"
    description: "Golden hour over the Mediterranean."
  ) {
    assetId
    description
  }
}

transferAssets

Moves a batch of assets from one library to another within the same organization. A target library outside the organization fails with 404 API_KEY_NOT_AUTHORIZED_FOR_LIBRARY, the same response as a library the credential cannot reach. When the source and target are the same library, the call changes nothing and returns transferredCount: 0.

Parameters

Returns

Example

mutation {
  transferAssets(
    organizationId: "acme-co"
    sourceLibraryId: "barcelona"
    targetLibraryId: "lisbon"
    assetIds: ["asset-123", "asset-456"]
  ) {
    transferredCount
    sourceLibraryId
    targetLibraryId
  }
}

promoteVariant

Makes one of an asset's variants its default. The variant's file replaces what the asset serves, at the same URL. Anything already embedding that URL shows the new file without being updated, so you can correct or replace a published asset without changing any link to it. It works the same for a photo and for a video.

The previous default is kept as a new variant with the name it had, so it can be promoted back. The asset keeps its id and URL and takes the promoted variant's name. The asset's description and the tags generated from its image follow the image: the promoted variant hands over any it carries, and the preserved variant keeps the ones that described it. Tags you added yourself stay on the asset. The promoted variant's own entry is removed, because its image is now the asset's.

Rejected with BAD_USER_INPUT when the id names an original rather than a variant, when the variant is archived or still processing, when the asset is not live, when the asset is itself still being processed (a video whose poster is not ready yet), when the asset is neither an image nor a video, or when the variant is a different kind of media than the asset. If another promote is already running on the same asset, the mutation fails with CONFLICT. Wait for it to finish, then retry.

Parameters

Returns

The response confirms the promote is accepted and returns the three ids. The image swap and the removal of the promoted variant's entry complete a moment later. Re-fetch the asset after a short delay to see the change. Its variants list is final once the swap finishes.

Example

mutation {
  promoteVariant(
    organizationId: "acme-co"
    libraryId: "barcelona"
    variantId: "var789"
  ) {
    assetId
    promotedVariantId
    demotedVariantId
  }
}

createLibrary

Creates a new library inside an organization. The caller must be an API key with write access to at least one library or, over OAuth, an Owner of the organization. A read-only key cannot create libraries. A library created with an API key is added to that key's allowlist, so the same key can use it immediately. Your whole team sees the new library in the Raster app.

Parameters

Returns

The new Library, with zeroed counters and no tags. The call fails with:

• LIBRARY_URL_TAKEN (409) when the slug is taken.
• LIBRARY_LIMIT_EXCEEDED (400) when the organization is at its free-plan library cap.
• PRO_PLAN_CANCELED (403) when the organization's Pro plan ended while it still has more than one member.
• API_KEY_READ_ONLY (403) when the key is read-only.
• FORBIDDEN (403) when an OAuth access token's account is not an Owner of the organization.

Example

mutation {
  createLibrary(organizationId: "acme-co", name: "Marketing", slug: "marketing") {
    id
    name
    assetsCount
  }
}

renameLibrary

Renames a library your API key has access to. The new name appears everywhere the library is shown, for every member. The URL slug is unchanged.

Parameters

Returns

The updated Library. A key not authorized for the library, or a missing library, fails with 404.

Example

mutation {
  renameLibrary(organizationId: "acme-co", libraryId: "marketing", name: "Marketing 2026") {
    id
    name
  }
}