Mutations

Mutations change data in Raster. Every mutation requires an API key with Write access to the target library, and is sent as a POST request to https://api.raster.app/.

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]
    email: "user@example.com"
  ) {
    responseText
    assets {
      id
      name
      filename
      contentType
      created
      tags
      status
      progress
    }
  }
}

deleteAssets

Moves one or more assets to trash (soft delete), matching the Raster app: they leave assets / searchAssets immediately but stay recoverable from trash and are permanently removed after 30 days.

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. Idempotent on (asset, tag) pairs the asset already carries — those pairs are silent skips and don't contribute to 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. Symmetric with tagAssets — idempotent on pairs the asset doesn't carry.

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. Cross-organization transfer is rejected with BAD_USER_INPUT. Same source and target resolves to a no-op (transferredCount: 0) with no writes.

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 a published asset can be corrected or replaced without changing any link to it. Works the same for a photo and for a video.

The previous default is preserved as a new variant, so it can be promoted back. The asset keeps its id, URL, and name. Its 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 has not landed 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 and 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 reflected — 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 your API key is already scoped to. The new library is added to your key's allowlist (so the same key can use it immediately) and is shown to your whole team in the Raster app. Because the new library is granted to your key, the key must have write access — a read-only key cannot create libraries.

Parameters

Returns

The new Library (zeroed counters, no tags). A taken slug fails with LIBRARY_URL_TAKEN (409); a free-plan library cap with LIBRARY_LIMIT_EXCEEDED (400); an organization whose Pro plan ended while it still has more than one member with PRO_PLAN_CANCELED (403); a read-only key with API_KEY_READ_ONLY (403).

Example

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

renameLibrary

Renames a library your API key has access to. Updates the library name everywhere it is shown (including each member's view); 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
  }
}