Changelog

This page tracks every notable change to the Raster REST API. The format follows Keep a Changelog.

REST is versioned per request through the Api-Version header, whose value is a date string such as Api-Version: 2026-07-08. The header is required on every request. Every response carries Vary: Api-Version so caches key bodies per version. During the Alpha, every Api-Version value receives the current behavior, so a breaking change reaches every integration.

2026-10-07 — Approval for every library member

Changed

• Viewers can set approval. PATCH …/assets/:assetId/approval accepts an OAuth access token whose account has any role on the library, Viewer included, matching who can set approval in the app.

2026-10-06 — Asset approval

Added

• Set an asset's approval. PATCH …/assets/:assetId/approval marks an asset in_review, approved, or needs_changes, with an optional note. It takes an OAuth access token; an API key is rejected with 403 APPROVAL_REQUIRES_USER, and an organization without a paid plan with 403 PAID_PLAN_REQUIRED.
• Filter search by approval. approval on GET …/search/assets returns only assets in one approval state, or none for assets with no approval.
• Asset.approval carries the asset's current approval. See Approval.

2026-09-23 — Variant delete

Changed

• A variant can no longer be moved to trash on its own. A variant id in ids on DELETE …/assets now fails the whole call with 400 BAD_USER_INPUT before anything moves, matching the Raster app and POST …/assets/transfer. Delete the original instead; its variants go to trash with it.

2026-09-15 — Library counts

Deprecated

• photosCount on a library is deprecated. It is still returned as an alias of assetsCount, so existing integrations keep working; new integrations should read assetsCount.

2026-09-14 — Tag filter

Changed

• tags on GET …/assets takes up to 50 tags. An asset matches when it carries any of them; more than 50 is rejected with 400 BAD_USER_INPUT. See GET …/assets.

2026-08-24 — Video variants

Changed

• A variant may now be a video. parentId on POST /organizations/:orgId/libraries/:libraryId/assets accepts a video asset, and the uploaded file must be the same kind of media as the parent: a photo takes image variants, a video takes video variants. Posting a video to a photo (or a photo to a video) is rejected with 400 BAD_USER_INPUT. See POST …/assets.
• Promote works on videos. POST …/assets/:assetId/promote accepts a video asset; the promoted variant's file replaces what the asset serves at the same URL, and its duration, metadata and poster travel with it. The promote is rejected when the asset is neither an image nor a video, when the variant is a different kind of media than the asset, or while the asset is itself still being processed (a video whose poster is not ready yet). See POST …/assets/:assetId/promote.

2026-08-12 — Video capture details

Added

• Asset.video.capture carries a video's capture details: recordedAt, make, model, software, and latitude / longitude / altitude, read from the container's own metadata tags. It is null on containers that carry none, which is common for screen recordings and anything re-encoded. Coordinates are always returned as a pair. Available over MCP. See AssetCapture.

2026-08-07 — Video metadata on assets

Added

• Asset carries duration and metadata. duration is the clip length in seconds; metadata holds what was read from the asset's own bytes: capture (how it was shot) and, on videos, video with the source's codec, frameRate, bitrate, hasAudio, audioCodec, audioLayout, and audioSampleRate. Both are null on assets uploaded before this data was captured, and on a search hit. Available over MCP. See Asset, AssetMetadata and VideoStream.

2026-07-21 — Set a variant as the default

Added

• POST /organizations/:orgId/libraries/:libraryId/assets/:assetId/promote makes a variant the asset's default. The variant's image replaces what the asset serves at the same URL, so anything already embedding that URL shows the new image without being updated. The previous default is preserved as a new variant and keeps the name it had; the asset keeps its id and URL and takes the promoted variant's name; its description and the tags generated from its image follow the image, while tags you added yourself stay on the asset. Returns { assetId, promotedVariantId, demotedVariantId }. Available over MCP. See POST …/assets/:assetId/promote.

2026-07-16 — Asset variants

Added

• The unfiltered GET /assets list now returns each original asset's live variants inline, in the variants field. Previously only GET /assets/:assetId populated them. Available over MCP. See GET /assets.

Changed

• views is renamed to variants on the Asset wire (list, get, search, and upload responses), and the AssetView object is renamed to AssetVariant. Read variants instead of views. Allowed under the Alpha policy at the top of this page.

Removed

• type removed from the Asset wire. It was always main on an asset and variant on a nested entry. Read parentId to tell an original from a variant: it is null on an original and the parent's id on a variant. Allowed under the Alpha policy at the top of this page.

2026-07-08 — Thumbnails consolidated onto sizes

Removed

• thumbUrl and thumbHighUrl removed from the Asset wire. The responsive sizes map replaces them, with blurhash for an inline placeholder. sizes is a JSON-encoded map of the image's longest edge (px) to CDN URL; parse it client-side to pick a thumbnail for your display size. Clients reading thumbUrl / thumbHighUrl no longer receive them and must switch to sizes. Applies to the list, get, search, and upload responses. Allowed under the Alpha policy at the top of this page.

2026-06-03 — Single-asset read, key context, library management

Added

• GET /:orgId/libraries/:libraryId/assets/:assetId: fetch one asset by id, returning the same Asset shape the list endpoint returns. Reads one asset's url, tags, description, and dimensions without paging GET /assets. Returns 404 when the asset is missing, in another library, or in trash. Available over MCP as the get_asset tool. See GET /assets/:assetId.
• GET /me: resolve the organization and libraries your API key can act on, so a client holding only a key can discover the organizationId every org-scoped endpoint needs. Available over MCP as the whoami tool. Full parameters and response shape: GET /me.
• POST /libraries: create an organization, a starter library, and an API key with no account and no existing key, for clients (typically AI agents) creating a library on someone's behalf. Anonymous; available over both REST and MCP (the create_organization tool). Full parameters, response, and limits: POST /libraries.
• POST /:orgId/libraries: create a new library inside an organization you already have an API key for. The new library is granted to your key, so the same key can upload to it immediately, and it appears for your team in the web app. This needs a key with write access. Optional slug sets the URL. Available over MCP as create_library. See POST /:orgId/libraries.
• PATCH /:orgId/libraries/:libraryId: rename a library. The new name shows everywhere, including each team member's view. Available over MCP as rename_library. See PATCH /libraries/:libraryId.

Changed

• DELETE /:orgId/libraries/:libraryId/assets now moves assets to trash (soft delete) instead of deleting them immediately, matching the Raster app. Deleted assets leave GET /assets and search right away, stay recoverable from trash, and are permanently removed after 30 days. The request/response shape is unchanged; the success message now reads "Moved N assets to trash", and ids returns the assets actually moved (so ids.length equals N). The call is idempotent: re-deleting ids already in trash returns "Moved 0 assets to trash", ids: [], success: true. Emptying the trash permanently is done in the Raster app. Applies to MCP delete_assets too.
• The anonymous, no-account MCP tool was renamed create_library → create_organization, since it creates a whole new organization. The new authenticated MCP create_library tool creates a library in an organization you already have a key for.

2026-05-28 — Asset metadata mutations

Added

• Batch-tag, untag, transfer, and re-describe assets over REST with four new Write endpoints:
  • POST /:orgId/libraries/:libraryId/assets/tag: apply up to 20 tags to up to 100 assets, returns { taggedCount }. See POST /assets/tag.
  • POST /:orgId/libraries/:libraryId/assets/untag: remove tags the same way, returns { untaggedCount }. See POST /assets/untag.
  • PATCH /:orgId/libraries/:libraryId/assets/:assetId/description: replace a single asset's description verbatim (no trim, no AI rewrite), returns { assetId, description }. See PATCH /:assetId/description.
  • POST /:orgId/libraries/:libraryId/assets/transfer: move up to 100 assets to another library in the same organization, returns { transferredCount, sourceLibraryId, targetLibraryId }. See POST /assets/transfer.

2026-05-27 — Search API + Uploader cleanup

Added

• GET /:orgId/search/assets: search assets across the libraries an API key authorizes. Organization-scoped; supports q, libraries, page, and pageSize. Returns SearchResult with hits, found, and page; each hit is an Asset plus optional highlights and score. See GET /search/assets.
• Objects reference page with the wire shapes (Asset, Library, Tag, SearchHit, SearchResult, SearchHitHighlights, Uploader, AssetVariant). Endpoint pages now link here instead of inlining each type.

Removed

• Uploader.integration removed from the wire. The field naming the upload's source is no longer returned on uploadedBy. Clients reading uploadedBy.integration will receive undefined. The full Uploader shape is now { name }. Allowed under the Alpha policy at the top of this page.

2026-05-20 — Initial Alpha release

Added

• REST transport at https://api.raster.app/organizations/..., authenticated with organization API keys.
• Api-Version request header (required) and Vary: Api-Version response header on every reply.
• { data } / { error: { code, message } } response envelope on every endpoint, including auth rejections and unknown-path 404s.
• GET /:orgId/libraries: list libraries in an organization.
• GET /:orgId/libraries/:libraryId/assets: list assets, with page, pageSize, and tags filters (repeatable or comma-separated).
• GET /:orgId/libraries/:libraryId/tags: list tags with limit.
• POST /:orgId/libraries/:libraryId/assets: multipart upload (files field), returns each new asset including a permanent CDN url.
• DELETE /:orgId/libraries/:libraryId/assets: batch delete by id.
• Timestamps on the wire are unix milliseconds (number).

Security

• Bearer-token authentication on every endpoint.
• Per-library access levels (Read / Write) enforced on every request before any data is read or written.