Get information about the currently authenticated user and organization

Get details about an organization by ID

Find an organization by slug. Useful when you have a custom-domain URL or know the slug but not the id.

Get the current user's role-derived abilities (manage Asset, view_details Tag, etc.) in an organization. Pair with INSUFFICIENT_SCOPE errors so you can distinguish role denial from missing token scope.

List every organization the current user belongs to (across orgs). Useful for multi-tenant agents picking which org to operate in.

List pending org invitations addressed to the current user.

Accept a pending org invitation by id.

Get the otpauth:// URI for setting up TOTP 2FA on the current user account (encode in a QR code).

Enable TOTP 2FA on the current user account by confirming a 6-digit code.

Disable TOTP 2FA on the current user account.

List organization memberships

Get membership details by ID

Update a membership

Re-run the OAuth authorization flow. Use this to switch to a different Mediagraph organization or re-authenticate.

Search for assets using filters and advanced query operators.

ADVANCED SEARCH QUERY SYNTAX (for the 'q' parameter):

• Basic: Just type a term to search all fields (e.g., "dog")

• Exclude: Use NOT or minus to exclude (e.g., "NOT dog" or "-dog")

• Combine: Use AND, OR, NOT (e.g., "dog AND cat", "dog OR cat", "dog NOT cat")

• Field search: Use field:value syntax (e.g., "tag_text:nature", "filename.keyword:IMG_1234.jpg")

• Wildcards: Use * (zero or more chars) or ? (single char) (e.g., "tag_text:part*", "tag_text:?artial")

• Existence: Use field:** to find assets with any value, NOT field:** for empty (e.g., "NOT tag_text:**" finds untagged assets)

• Complex: Use parentheses for grouping (e.g., "(dog OR cat) AND ext:jpg")

NOTE on multi-word queries: the API uses Elasticsearch cross_fields, so a multi-word query like "red barn" can match if "red" appears in one field and "barn" appears in another. Quote phrases ("red barn") to require both terms in the same field.

Sort: pass either 'order' or its alias 'direction' (asc/desc). Results have an implicit id:asc tiebreaker (except when using a custom sort).

COMMON SEARCH FIELDS:

• tag_text: Keywords/tags

• filename.keyword: Exact filename

• description: Asset description

• title: Asset title

• ext: File extension

• creator_text: Creator/photographer name

• copyright: Copyright text

• city, state, country: Location fields

Get detailed information about a specific asset

Update asset metadata

Delete (trash) an asset

Add tags to an asset

Get a download URL for an asset

Get a download URL for multiple assets (returns a ZIP file)

Get AI-generated auto tags for an asset

Get face taggings for an asset

Manually tag a face track in a video; indexes the cropped frame into Rekognition.

Trigger face detection for an existing video asset (for videos uploaded before video face tagging shipped).

Manually tag a detected face crop on an image asset and index it into Rekognition for org-wide face matching.

Workflow for "upload a headshot for a person tag":

1. Upload the headshot via upload_file (optionally with the person tag attached).

2. Call get_asset_face_taggings to get the face_id of the detected face crop.

3. Call tag_asset_face with the person tag's id (or a new name) + that face_id.

After indexing, future uploads automatically run face matching against this person.

Run face search on an asset using the org-wide face index; matches detected faces to indexed person tags. Reindexes the asset on success.

Block a detected face crop on an asset (creates a "Blocked Face" tag and excludes from future matching).

Toggle the per-asset "ignore" state on a detected face id. Useful for hiding low-confidence detections without blocking the face globally.

Hide all unidentified (unmatched) face crops on an asset.

Write to a custom meta field on an asset. The field's shape determines which value param to pass:

• free (free-text): pass value (or text)

• select (single-pick): pass custom_meta_value_id

• multi (multi-pick): pass custom_meta_value_ids (array)

Pass none of value/text/*_id to clear the field. The asset is reindexed on success.

Super-admin diagnostic: show which Elasticsearch fields/terms matched a query for a given asset.

Delete a single PublishedImage row. Auto-cleans the parent PublishedAsset when the last image is removed.

Get version history for an asset

Revert an asset to a previous version

Get asset counts with optional filters

Get trashed assets

Get popular assets

Update fields on many assets in a single call. Pass an updates object with the same field names as update_asset (title, description, alt_text, caption, credit, copyright, etc.).

Add the same tag names to many assets at once.

Remove the same tag names from many assets at once.

Set (or clear with null) the rights package on many assets in one call.

Set (or clear with null) the creator tag on many assets in one call.

Remove many assets from a collection / lightbox / storage folder at once.

Run Rekognition / Vision auto-tagging on a single asset. Existing auto-tags are preserved; new ones are appended.

Dismiss a specific auto-tag from this asset (does not delete the auto-tag globally).

Generate accessibility alt text for an asset using AI; saves to the alt_text field.

Invoke an AI-enabled custom meta field action on an asset (e.g., LLM-driven extraction, classification, or description).

Mark an NSFW detection as a false positive on an asset; clears the moderation flag and re-indexes.

Restore a trashed asset (undo delete_asset).

Get extracted EXIF / IPTC / XMP / file metadata for an asset.

Get extracted text content for a document asset (PDF/DOCX/etc.).

Get OCR-extracted text from an image asset.

Patch only the description field on an asset (lighter than update_asset; does not touch other fields).

Fetch full asset records for an explicit ID list in one call. Use after search_assets returned a set of IDs and you want full attributes without N round-trips.

Sync helper: returns asset ids that changed since last_sync_at (or since the server-tracked last_external_sync_at if omitted). Useful for export/mirror jobs.

Audit trail for an asset: every version + who did what, paginated.

Find which user added a given asset to a given asset_group (collection / lightbox / folder).

Initiate an upload of a NEW version of an existing asset. Returns a signed S3 URL; PUT the file there to complete. For end-to-end uploads from disk, prefer upload_file with the asset id.

Slice a video asset between start and end (seconds) and queue the result as a NEW VERSION of the same asset. Async — poll the asset.

Slice a video asset between start and end (seconds) and queue the result as a brand-NEW asset (optionally added to a lightbox).

For a video asset: set the poster/preview image from the frame at seconds into the video.

Upload a closed-caption / transcript text for a video asset (e.g. WebVTT or plain text).

List collections in the organization

Get collection details

Create a new collection

Update a collection

Delete a collection

Add an asset to a collection

Get collections hierarchy as a tree

Add multiple assets to a Collection or Lightbox at once

List lightboxes in the organization

Get lightbox details

Create a new lightbox

Update a lightbox

Delete a lightbox

Add an asset to a lightbox

Get lightboxes hierarchy as a tree

List storage folders

Get storage folder details

Create a new storage folder

Get storage folders hierarchy as a tree

Transfer ownership of a lightbox to another user (by user id).

Push a lightbox membership's pinned assets out to all members (creates per-member copies). Used to broadcast curated picks to a shared lightbox.

Remove pinned-assets from a lightbox membership (counterpart to apply).

List pending and accepted invitations to collections, lightboxes, and storage folders.

Get an asset group invite by id.

Invite a user (by email) or existing membership to a collection / lightbox / storage folder.

Update an asset group invite (e.g. change role).

Cancel/revoke an asset group invite.

List tags in the organization

Async uniqueness check for a tag name (e.g., for artwork inventory numbers). Returns { exists: boolean }.

Get tag details

Create a new tag. Supports the full enrichment surface (description, sub_type, link, event fields, artwork fields, external-system identifiers).

Update a tag — accepts every enrichment field (description, sub_type, link, event fields, artwork fields, external-system links, synonym graph).

Delete a tag

Merge one tag into another. With set_synonym=true, the source tag is preserved as a synonym of the target instead of being deleted.

Clear face-tagging state on a person tag and re-enqueue Rekognition indexing.

Add an existing tag to a taxonomy as a taxonomy_tag.

Detach a tag from all taxonomies it belongs to.