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
  }
}

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); 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
  }
}