Portal vs Admin API Types
Tell the AI which catalog op belongs to the Portal API, which belongs to the Admin API, and which work on either. Both SDKs guard each method to exactly one apiType and raise InvalidAPITypeException when called on the wrong session.
Portal vs Admin API Types
The SDK config carries an apiType of "portal" or "admin". Each SDK method is
guarded to exactly one apiType and raises InvalidAPITypeException if called on the
wrong session — there is no auto-fallback. A single session therefore cannot exercise
both sides; pick the session type the op requires (see the tables below), or construct
one session per apiType.
Parity: the Python and JavaScript SDKs guard the same ops the same way, so these tables apply to both languages.
Policy: Portal-first
Always prefer the Portal API. Reach for an Admin endpoint only when you need an admin-specific capability that has no Portal equivalent (e.g. indexing, workflows, ad-breaks, server/content-definition administration).
Practical caveat (as-built): in the current SDK the core asset-management surface (create/upload/get/update/move/delete) is guarded Admin-only, while the consumer- facing surface (sharing, saved searches, annotations, tracking) is Portal-only. So "Portal-first" is the preference, but in practice you select the session type each op's table row requires. When the same capability exists on both, choose Portal.
Admin-only (raise InvalidAPITypeException on a Portal session)
InvalidAPITypeException on a Portal session)| Group | Catalog ops (sdk_method) |
|---|---|
| Reads | get (get_asset), list_children (get_asset_child_nodes), get_metadata_summary, get_parent_folders, get_segment_details, get_screenshot_details |
| Create / ingest | create_folder (create_folder_asset), create_placeholder (create_placeholder_asset), upload (upload_asset), upload_related (upload_related_asset), register (register_asset) |
| Mutate / metadata | update_asset, update_asset_language, update_asset_security, add_custom_properties, bulk_update_metadata |
| Relocate / remove | move (move_asset), copy (copy_asset), duplicate (duplicate_asset), delete (delete_asset) |
| Media / lifecycle | screenshot (create_screenshot_at_timecode), archive (archive_asset), reprocess (reprocess_asset), index_asset, start_workflow |
| Ad-breaks | create_ad_break, get_ad_breaks, update_ad_break, delete_ad_break |
Portal-only (raise InvalidAPITypeException on an Admin session)
InvalidAPITypeException on an Admin session)| Group | Catalog ops (sdk_method) |
|---|---|
| Annotations | create_annotation, get_annotations, update_annotation, delete_annotation, import_annotations |
| Video tracking | record_tracking_beacon (records_asset_tracking_beacon), get_video_tracking |
| Sharing | create_share (share), get_share, update_share, delete_share, expire_share (share_expire) |
| Saved search | create_saved_search (add_saved_search), get_saved_search, list_saved_searches (get_saved_searches), update_saved_search, delete_saved_search |
| Transcription | transcribe_asset (guarded Portal despite docstrings labeling it an Admin endpoint) |
| Media building | build_media |
Either (no apiType guard — work on both sessions)
clip (clip_asset), search, get_details (get_asset_details),
get_manifest (get_asset_manifest_with_cookies), restore (restore_asset).
Consequences for composing tasks
- A confined asset (folder + upload under the run-root) can only be created on an
Admin session, because
create_folder/uploadare Admin-only. - The consumer ops that act on that asset (share, annotate, tracking) need a Portal session. To exercise both, hold two sessions: confine/set-up via Admin, then run the Portal op against the same (confined) asset id.
- Each component records its requirement in front-matter as
requires_api_type: admin | portal | any.