CrowdRiff API v2 → v3 Migration Guide

What changed in v3?

v3 is a read-only, content-retrieval API. Key changes at a glance:

New base URL: https://api.crowdriff.com/v3/public
No write operations — POST/PUT endpoints are not available in v3
No analytics endpoints — Gallery, Asset, and CTA analytics are removed
No full-text search — POST /search is removed; folder-scoped search via q parameter is available as a partial replacement
Media Hub albums — v3 support is coming in late May 2026; continue using v2 until then

See the full API reference at https://app.crowdriff.com/api-docs.

Do I need to update my authentication?

No. Your existing API token works with v3. Continue passing a Bearer token in the Authorization header, same as v2.

How did pagination change?

Update the following pagination parameters and response fields:

What	v2	v3
Next page token (response)	`paging.next_key`	`next_page_key` (top-level)
Next page token (request param)	`after`	`page_key`
Page size param	Varied	`page_size` (default 50, max 500)
Token expiry	15 minutes	No documented expiry

❗Heads up: Bulk retrieval via comma-separated IDs (e.g. GET /albums/101,102,103) is no longer supported. Retrieve resources individually.

How did error responses change?

v2: {"error": {"message": "some error"}}
v3: {"error": "some error"}

Update your error parsing to read error directly instead of error.message. v3 also adds 404 responses with specific messages per resource type. Rate limiting remains unchanged at 2,500 requests per 15 minutes.

How did the endpoints change?

Galleries

Galleries were previously a type of "App" in v2. They are now a top-level resource.

v2	v3	Notes
`GET /apps` (filtered to galleries)	`GET /galleries`	New param: `include_asset_count`
`GET /apps/{id}`	`GET /galleries/{gallery_id}`
`GET /apps/{id}/assets`	`GET /galleries/{gallery_id}/assets`	Rights-status filtering removed

Removed v2 response fields: hash, layout_id, theme_id, type

v3 returns: id, label, asset_count (when requested), created_at, updated_at

Folders (My Visuals)

Folders in v3 correspond to My Visuals folders. v3 replaces v2 albums with folders.

v2	v3	Notes
`GET /folders`	`GET /folders`	New params: `parent_id`, `include_asset_count`, `order_by`, `order_direction`
`GET /folders/{id}`	`GET /folders/{folder_id}`	New params: `include_asset_count`, `include_share_link`
No equivalent	`GET /folders/{folder_id}/assets`	New. Supports `q` (search), `order_by`, `order_direction`

Removed v2 fields: category, collection_id, albums[]

New v3 fields: parent_id, sub_folder_count. Asset counts are opt-in via include_asset_count=true.

Maps (new in v3)

Maps are a new resource type with no v2 equivalent.

Endpoint	Description
`GET /maps`	List maps
`GET /maps/{map_id}`	Get a map
`GET /maps/{map_id}/places`	List places on a map
`GET /maps/{map_id}/places/{place_id}`	Get a place
`GET /maps/{map_id}/places/{place_id}/assets`	List assets at a place

Removed endpoints (no v3 equivalent)

The following v2 endpoints have no replacement in v3:

v2 endpoint	What it did
`POST /search`	Full-text search across the collection
`PUT /albums/{id}/assets`	Add assets to album
`GET /albums`, `GET /albums/{id}`	Album listing and retrieval
`GET /ctas`, `GET /ctas/{id}`	CTA listing and retrieval
Gallery, Asset, and CTA Analytics endpoints	All analytics

Partial search replacement: GET /folders/{folder_id}/assets supports a q parameter for full-text search, scoped to a single folder.

How did asset fields change?

Media field renames

For video assets (media_type: video):

v2	v3
`image_original`	`video_poster_original`
`image_gallery`	`video_poster_standard`
`image_fullscreen`	`video_poster_large`
`video_gallery_clip`	`video_preview_clip`

For non-video assets:

v2	v3
`image_gallery`	`image_standard`
`image_fullscreen`	`image_large`

Rights field renames

All rights-related fields are consolidated under a single rights object.

v2	v3
`license.type`	`rights.type`
`license.restriction_notes`	`rights.restriction_notes`
`license.expiry_at`	`rights.expiry_at`
`external_license.license_author`	`rights.approved_by`
`external_license.license_note`	`rights.approval_note`

New fields in v3

Field	Type	Description
`alt_text`	object	`{ "text": "..." }` (language field from v2 is dropped)
`aspect_ratio`	number	e.g. `0.5625`

Restructured fields

Location: Was cr_location.* fields. Now a nested location object. Note: lon is renamed to lng.
User: Was { full_name, screen_name, avatar_url, followers, uuid }. Now { full_name, screen_name } only.
MediaFile: All image/video variants now use { url, width, height, size }.

Removed fields

The following fields are no longer returned in v3 asset responses:

Collection/app context: albums, apps, collection, folders, groups, ctas, recommend, partner, sidekick
Curation/moderation: curated, curated_at, hidden, deleted_at, is_spam, public, editorial
Rights/compliance: downloadable, drm_at, drm_screenshots
Social metadata: fb_source_page_id, instagram_graph, native_comments, native_likes, native_media_id, native_post_id, native_user_id, native_media_order
Location internals: cr_location_id, cr_location_label, location, location_geo, location_id, location_label
Files/thumbnails: file_original, file_name, video_low, thumbnails, thumbnail_embed, thumbnail_fullscreen, thumbnail_gallery, thumbnail_height, thumbnail_mobile, thumbnail_width, preview_image
Scoring/analytics: likes, pixel_count, score_v1, search_score, quality_score, relevance
System: doc_version, media_filter, media_product_type, objects, version
User fields: avatar_url, followers, uuid

Quick migration checklist

Use this checklist to track your integration updates before the August 31, 2026 deadline.

Update base URL from /v2/ to /v3/public
Update pagination: after → page_key, paging.next_key → next_page_key
Update error parsing: error.message → error
Replace app/gallery endpoints with new gallery endpoints
Update folder endpoints for new params and response shape
Rename asset media fields (apply correct mapping for video vs. non-video assets)
Update rights fields: license.* and external_license.* → consolidated rights object
Update location parsing: cr_location.* → nested location object (note: lon → lng)
Update user parsing: remove references to avatar_url, followers, uuid
Remove references to all dropped fields
If using search: evaluate whether folder-scoped q parameter meets your needs
If using analytics: plan an alternative approach (not available in v3)
If using write operations: plan an alternative approach (v3 is read-only)
If using Media Hub albums via API: wait for v3 support, coming late May 2026
Test your integration against v3 endpoints before August 31, 2026

Need more help?

If you have any other questions, feel free to send us a message!