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.

Find or stub many tags by name in a single call. Returns existing tags where matched, otherwise unsaved Tag-shaped records the agent can persist.

Apply a single change to many tags (set list, attach/detach taxonomy).

Delete many tags by id in a single call.

List recent tag activity events for the org. Optionally filter by year/month.

Top 10 most recent tag activity events (no pagination).

List the face crops currently associated with a person tag (across the org).

Associate a person tag with a user (by email). The user becomes the canonical "face" for the tag — useful for faceless tags that need to point to a real person.

Remove the user-membership association from a person tag.

Link a person tag to a creator tag by name. Photos created by that creator gain the linked person tag automatically.

Unlink the creator-tag association from a person tag.

Promote a tagging to the canonical face for its tag. Used after tag_asset_face to pick which crop represents the person.

Associate an existing tagging with a Rekognition face id (link tagging → detected face crop).

Remove the face-crop association from a tagging.

Get details of a specific tagging (tag-to-asset relationship)

Remove a tagging (untag an asset)

List AI-generated auto tags

Get auto tag details

Find multiple auto tags by their names at once

Delete/dismiss an auto tag

List taxonomies (controlled vocabularies)

Get taxonomy details

Create a new taxonomy

Update a taxonomy (name, description, etc.).

Delete a taxonomy. Tags inside it are detached, not deleted.

List tags within a taxonomy

Hierarchical tree view of all taxonomy_tags within a taxonomy (parent → children).

Count assets visible-to-current-user under each taxonomy_tag id (for displaying counts in a tree view).

Find or stub many taxonomy_tags by name in a single call (top-level — searches across taxonomies).

Create a tag within a taxonomy

Update a tag inside a taxonomy.

Delete a tag from a taxonomy.

List creator/photographer tags

Create a new creator tag

List rights packages for managing asset usage rights

Get rights package details

Create a new rights package

List share links

Get share link details

Create a share link for a Collection, Lightbox, or Storage Folder

Delete a share link

List access requests and grants

Get access request details

Submit an access request

Lightweight status poll for a share (aasm_state, progress, code, url, direct_link)

List shares (one-off transfers of an asset/group to a user, distinct from public share_links).

Get a share by id.

Create a share (transfer assets / a group to a user). See Mediagraph share docs for the body fields supported by your org.

Revoke / delete a share by id.

Render the HTML email body that would be sent for this share (preview).

List the assets included in a share.

Create a draft access request (pre-submit). Use submit_access_request to send it.

Update an in-progress access request.

Delete an access request.

Admin: finalize a submitted access request — approves and grants access.

Admin: revoke a previously granted access request.

Guest: record agreement to terms / NDA on an access request.

Set a custom meta field value on an access request (mirrors set_asset_custom_meta).

Find an access request by guid (used in guest-link resolution).

Hierarchical tree view of access requests by asset group.

List access grants (the records produced when an access request is finalized).

Delete (revoke) an access grant.

List bulk jobs

Get bulk job details and status

Create a bulk job for batch operations on assets. Supports multiple operation types:

• Tag management: use tag_names + tag_mode (add/remove/replace)

• Metadata updates: use description + description_mode (set/append/prepend), rating, rights_package_id

• Organization: use add_asset_group_id + add_asset_group_type (Collection/Lightbox/StorageFolder)

• AI processing: use run_custom_meta_field_ids + cmf_overwrite_mode (skip/overwrite)

• Bulk actions: use destroy_all, restore_all, or generate_alt_text

Preview the filenames a rename bulk job will produce, before submitting it.

Cancel a running bulk job

Get queue position for a bulk job

List metadata import jobs

Get metadata import job details

List ingestion jobs

List custom metadata fields

Get custom meta field details

Create a custom metadata field

List workflows

Get workflow details

Create a new workflow.

Update a workflow.

Delete a workflow. In-flight workflow_steps may need to be cancelled separately.

List workflow steps (the user-facing approval queue).

Get a workflow step by id.

Create a workflow step (typically attached to a workflow + asset_group).

Update a workflow step.

Delete a workflow step.

Approve all selected assets in a workflow step, moving them to the next step.

Approve a curated subset (picks) within a workflow step. Same shape as approve_workflow_step but only the chosen assets advance.

List comments on a Lightbox or Collection

Create a new comment on a Lightbox or Collection. Supports markdown and @mentions.

Update a comment. Only the comment author can update their own comments.

Delete a comment. Only the comment author can delete their own comments.

List notifications

Get unread notification count

Create a batch download for multiple assets

Get download status and URL

Upload a file to Mediagraph. Two body modes (file_path or file_data) and three session modes:

Body modes:

1. Local file: Provide file_path for files on the user's local filesystem

2. Direct upload: Provide file_data (base64-encoded) with filename for files from other sources

Session modes (mutually exclusive):

• Default: a fresh one-shot upload session is created and finalized for this single file.

• upload_guid: append to an existing session created via create_upload_session. The session is NOT finalized; call set_upload_done when your batch is complete.

• contribution_id: upload via a contribution's configured destination (storage folder / lightbox).

Files >16 MiB automatically use S3 multipart upload (parallel parts, retry per part); smaller files go through a single signed PUT.

Upload multiple files from the local filesystem in one operation.

Session behavior:

• Default: creates one fresh session, uploads all files into it, finalizes it.

• upload_guid: appends to an existing session; does NOT finalize (caller's job).

• contribution_id: routes the new session through a contribution.

Files >16 MiB use S3 multipart automatically.

Create a long-lived upload session that you can append files to over multiple upload_file / upload_files calls.

Use this when batch-uploading many files from a script or agent loop, when you want them grouped under one upload in the Mediagraph UI, or when you need to resume after a crash.

Returns the session guid plus aws_key/bucket (used internally for direct-to-S3 multipart). Call set_upload_done with the returned id when the batch is complete.

Finalize an upload session, marking it as complete. Triggers any post-upload hooks (notifications, contribution acceptance, etc.). Call this after the last upload_file/upload_files in a batch you opened with create_upload_session.

List webhooks

Get webhook details

Create a webhook to receive event notifications

Delete a webhook

Get webhook delivery logs

List user groups

Get a user group by id (members + permissions).

Create a user group

Update a user group (name, description, etc.).

Delete a user group. Members are not deleted.

List pending invites

Invite a user to the organization

Update an invite (change role or note)

Resend an invite email

Look up an invite by token (for the public invite-acceptance flow).

Check whether a given email is a valid recipient for a new invite (already has account, already in org, etc.).

Return the list of role_level values that the current user is allowed to grant in an invite. Helps prevent BAD_ARGS at create time.

Accept an invite using its email-link token (public flow — distinct from accept_my_invite which uses the profile-scoped invite list for an authenticated user).

Find a single membership in the current org by username OR user_id.

Search memberships within a comment context (collection / lightbox) — used for assignee pickers and @-mention lookups in commenting flows.

Update the AASM status of a membership (e.g. activate, suspend). Different from update_membership which patches role_level / preferences.

List pending requests from users asking to join the current org.

Count of pending membership requests (for badging admin dashboards).

List saved filter groups

Get filter group details

Create a new filter group with saved filter configurations

Update a filter group

Update the visibility of a specific filter within a filter group

Delete a filter group

List saved search queries

Get search query details

Save a new search query. The sql field should contain an Elasticsearch SQL WHERE clause.

Update a saved search query name or description. Note: The SQL query cannot be changed after creation.

Delete a saved search query

List crop presets

Create a crop preset

Check if uploads are allowed (storage quota)

List upload sessions

Add assets to an upload session

List contribution portals (upload links). Use contribution_id with upload_file/upload_files to upload to a specific storage folder or lightbox.

Get contribution details

Create a new contribution portal (named upload link tied to a collection / lightbox / folder).

Update a contribution portal.

Delete a contribution portal.

Find a contribution by slug.

List featured contribution portals (those highlighted in the org UI).

List contributions tied to a collection / lightbox / folder.

List contributions tied to lightboxes.

List standalone (link-only) contributions.

List personal access tokens

Create a personal access token

Delete a personal access token

Super-admin: disable a PAT (requests respond with X-PAT-Disabled header)

Super-admin: re-enable a previously disabled PAT

Super-admin: send a Stripe invoice for a CAI budget top-up

Super-admin: grant free CAI budget to an organization

Super-admin: mark an open CAI invoice as paid out-of-band

Admin: extend a trialing/past_due/canceled subscription

Bulk export custom meta fields by ID

Search for assets and display results in an interactive visual gallery.

This tool provides a rich visual interface for browsing search results with:

• Thumbnail grid with hover previews

• Click to view full asset details

• Inline editing of metadata

• Rating, tagging, and download options

• Pagination controls

Use this when the user wants to visually browse or explore assets.

List tag-import jobs

Get a tag-import job

Create a tag-import job. file is the uploaded CSV/XLS file reference (S3 key or upload id).

Update a tag-import job

Delete a tag-import job

Set the column mapping for a tag-import job

Start processing a tag-import job once it is in the analyzed state

List tags created/updated by a tag-import job

List rename presets

Get a rename preset

Create a rename preset

Update a rename preset

Delete a rename preset

Reorder rename presets by moving one from oldIndex to newIndex

List background metadata-export jobs

Get the column catalog for metadata exports (grouped + IPTC + custom meta fields), plus the default basic set

Kick off a background metadata CSV export. Returns { guid } to poll status.

Toggle the send_email flag on an in-progress metadata export

Generate a direct deep-link URL to a Mediagraph entity (asset, collection, lightbox, storage folder, tag, creator tag, share link, or the explore root).

Two host modes:

• Custom domain: when the org has one set (e.g. "dam.mer.fm"), URLs use https://{domain}/explore/...

• Default: https://mediagraph.io/{org-slug}/explore/...

Path patterns: asset → /explore#/assets/{guid} (hash route) collection → /explore/collections/{slug} lightbox → /explore/projects/{id}-{slug} storage_folder → /explore/folders/{slug} tag, creator_tag → /explore/tags/{id}-{name} share_link → /share-links/{share_code}

Identifier rules:

• Pass whichever identifier you already have (guid, slug, id+name, etc.); the tool fetches the entity if needed to derive the rest.

• For assets, only guid is needed.

• For collections / storage folders, slug works directly.

• For lightboxes, the API returns a composite "slug" of the form "{id}-{name}" — pass it as slug.

• For tags, pass id (and optionally name for a prettier URL).

Override host with --host (e.g., point at staging) or --base_host (just the fallback).