Record Lifecycle & Edit Sessions
Tools for the record editing lifecycle — drafts, edit sessions, checkout and check-in, record locks, and record deletion.
This page covers 16 tools, all of them available on request rather than in the default tool list, and 2 destructive.
- Status — In the default tool list means the tool is one of the ~200 Aprimo advertises to every agent out of the box, so the agent discovers and calls it on its own. Available on request means the tool is registered and fully callable, but sits outside that default list — call it by name, or ask Aprimo to extend the list your tenant is served.
- Both statuses work identically when called. Status affects discovery, not capability or authorization.
- Visibility is not authorization. Every tool call executes as the authenticated user, and any tool can return an authorization error if that user lacks rights to the record, task, or file. See the MCP Tool Permission Map.
- Destructive tools are labelled as such. They delete or irreversibly overwrite data, and will not act unless the call sets both
confirmedandconfirmedDestructivetotrue. - Activity and Project labels vary by tenant. Where this page says Activity or Project, your tenant's own configured terminology is substituted at runtime.
Aprimo's MCP Server exposes far more tools than most MCP clients handle well — many degrade or truncate their tool list well below the full catalogue. Rather than let a client truncate arbitrarily, Aprimo advertises a curated set of roughly 200 tools covering the tasks customers most commonly automate. Everything outside that set remains fully supported and callable by name; it simply isn't offered up front. If your integration leans on a tool that is available on request, talk to your Aprimo Customer Success Manager about extending the advertised list for your tenant.
Tools at a Glance
| Tool | Status | What it does |
|---|---|---|
apply_and_save_record_edit | On request | Applies changes to an Aprimo record edit session and saves (commits) them -- by default this closes the session; set keep_edit_open=true to keep it open for further apply calls instead. |
apply_record_edit | On request | Applies a partial update to an Aprimo record edit session without closing it -- the session stays open for further apply_record_edit/apply_and_save_record_edit calls, so use this to build up changes across multiple calls before finally committing with apply_and_save_record_edit. |
cancel_record_checkout | On request | Destructive. Undoes/cancels an Aprimo record checkout, releasing its lock -- this is the execute step for the undo-checkout flow (there is no separate execute op; see prepare_undo_record_checkout's own description). |
cancel_record_edit_session | On request | Cancels/discards an Aprimo record edit session, releasing any lock it holds, without saving any changes made during it. |
create_record_draft | On request | Step 1 of the Aprimo record edit-session workflow for a new record, optionally copied from an existing record used as a template (copy_from). |
delete_record | On request | Destructive. Permanently and irreversibly deletes an Aprimo record -- all its files, versions, metadata, and history are gone. |
execute_record_checkin | On request | Step 2 of 2 for checking in a new file version: finalizes the check-in using the operation_token from prepare_record_checkin, after the new file's bytes have been uploaded to that call's sasUrl. |
execute_record_checkout | On request | Step 2 of 2 for checking out a record: starts the checkout using the operation_token from prepare_record_checkout. |
get_record_checkout_status | On request | Checks the status of an Aprimo record checkout started by execute_record_checkout (which creates an asynchronous download order) -- pass the same operation_token used there. |
get_record_edit_session | On request | Reads the current state of an Aprimo record edit session: whether it has outstanding validation errors and a deep link to the record it's editing. |
list_record_locks | On request | Lists every lock currently held on an Aprimo record: who/what holds each lock (integrationId), why (reason), an optional reference uri, and when it was taken. |
lock_record | On request | Creates a lock on an Aprimo record, preventing it from being modified by others until the lock is released. |
prepare_record_checkin | On request | Step 1 of 2 for checking in a new file version on an Aprimo record: requests an upload location (sasUrl) and registers the previews/publication items to generate once the upload completes. |
prepare_record_checkout | On request | Step 1 of 2 for checking out an Aprimo record: reserves the checkout and returns an operation_token. |
prepare_undo_record_checkout | On request | Step 1 of 2 for undoing an existing checkout on an Aprimo record: reserves the undo and returns an operation_token. |
start_record_edit_session | On request | Step 1 of the Aprimo record edit-session workflow: starts a session for a brand-new, blank record -- DAM's schema for this endpoint carries no record id anywhere, so this can only start a session for a record that doesn't exist yet (use create_record_draft instead to start one copied from an existing record/template, or update_record_metadata_field/apply_record_bulk_edit to edit an already-existing record). |
apply_and_save_record_edit
Available on request
Applies changes to an Aprimo record edit session and saves (commits) them -- by default this closes the session; set keep_edit_open=true to keep it open for further apply calls instead. Pass the edit_token from start_record_edit_session/create_record_draft. This modifies data -- confirm with the user before calling. If the response reports validation errors, review them -- fix the change and call again, or cancel_record_edit_session to discard the session. disable_validations=true is high-risk -- confirm it explicitly with the user before calling.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
editToken | string | Yes | The edit token returned when the session was started. |
status | string | No | Optional: lifecycle status to set on the record. |
contentType | string | No | Optional: content type to set on the record. |
tag | string | No | Optional: a tag to distinguish or categorize the record. |
fieldsAddOrUpdate | object (map of string) | No | Field values to add or update. JSON object mapping field name to its new string value. |
fieldsRemove | array of string | No | Field names whose value should be cleared. |
keepEditOpen | boolean | No | Optional: when true, keeps the edit session open after committing instead of closing it, allowing further apply_record_edit/apply_and_save_record_edit calls with the same edit_token. |
disableValidations | boolean | No | High-risk: when true, skips DAM's field and business rule validations for this commit. |
immediateSearchIndexUpdate | boolean | No | Optional: when true, updates the search index immediately instead of waiting for the next scheduled update. |
Returns:
| Field | Type | Description |
|---|---|---|
editToken | string | |
recordLink | string (optional) | /// Deep link to the record this session is editing (Tenant.DamUiBaseUri/contentitems/{id}), resolved from the record id embedded in DAM's _links.record.href -- null if DAM omitted that link; falls back to the raw href if a record id can't be parsed out of it (see RecordEditSessionTools.ExtractRecordIdFromHref). |
hasValidationErrors | boolean | |
validationErrors | array of string |
apply_record_edit
Available on request
Applies a partial update to an Aprimo record edit session without closing it -- the session stays open for further apply_record_edit/apply_and_save_record_edit calls, so use this to build up changes across multiple calls before finally committing with apply_and_save_record_edit. Pass the edit_token from start_record_edit_session/create_record_draft. This modifies data (uncommitted, held in the session) -- confirm with the user before calling. disable_validations=true is high-risk -- confirm it explicitly with the user before calling.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
editToken | string | Yes | The edit token returned when the session was started. |
status | string | No | Optional: lifecycle status to set on the record. |
contentType | string | No | Optional: content type to set on the record. |
tag | string | No | Optional: a tag to distinguish or categorize the record. |
fieldsAddOrUpdate | object (map of string) | No | Field values to add or update. JSON object mapping field name to its new string value. |
fieldsRemove | array of string | No | Field names whose value should be cleared. |
disableValidations | boolean | No | High-risk: when true, skips DAM's field and business rule validations for this partial update. |
immediateSearchIndexUpdate | boolean | No | Optional: when true, updates the search index immediately instead of waiting for the next scheduled update. |
Returns:
| Field | Type | Description |
|---|---|---|
editToken | string | |
recordLink | string (optional) | /// Deep link to the record this session is editing (Tenant.DamUiBaseUri/contentitems/{id}), resolved from the record id embedded in DAM's _links.record.href -- null if DAM omitted that link; falls back to the raw href if a record id can't be parsed out of it (see RecordEditSessionTools.ExtractRecordIdFromHref). |
hasValidationErrors | boolean | |
validationErrors | array of string |
cancel_record_checkout
Available on request · Destructive
Undoes/cancels an Aprimo record checkout, releasing its lock -- this is the execute step for the undo-checkout flow (there is no separate execute op; see prepare_undo_record_checkout's own description). Call prepare_undo_record_checkout first to get an operation_token for the record, then pass it here. This cannot be undone (any changes made to a checked-out copy outside DAM are not reconciled by this call). Requires both confirmed=true and confirmedDestructive=true, after explicitly confirming the exact record/operation with the user.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
operationToken | string | Yes | The operation token returned by prepare_undo_record_checkout for the record whose checkout to cancel. |
confirmed | boolean | No | Must be true to proceed. Set to false (or omit) to get a confirmation gate error, then call again with confirmed=true after the user has explicitly confirmed the exact record/operation. |
confirmedDestructive | boolean | No | Must also be true (in addition to confirmed) -- undoing a checkout cannot be undone. Set only after stating the exact record/operation to the user and getting explicit go-ahead. |
Returns:
| Field | Type | Description |
|---|---|---|
operationToken | string | |
cancelled | boolean |
This tool deletes or irreversibly overwrites data in the live tenant; the change cannot be rolled back through the API. It will not act unless the call sets both confirmed and confirmedDestructive to true.
cancel_record_edit_session
Available on request
Cancels/discards an Aprimo record edit session, releasing any lock it holds, without saving any changes made during it. Use to clean up a session you decided not to continue. Low-consequence -- an uncommitted draft/edit is simply discarded and can be re-started with start_record_edit_session/create_record_draft. Confirm-gated: call again with confirmed=true after telling the user which session will be discarded.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
editToken | string | Yes | The edit token of the session to discard. |
confirmed | boolean | No | Must be true to proceed. Confirm with the user which session to discard, then call again with confirmed=true. |
Returns:
| Field | Type | Description |
|---|---|---|
editToken | string | |
cancelled | boolean |
create_record_draft
Available on request
Step 1 of the Aprimo record edit-session workflow for a new record, optionally copied from an existing record used as a template (copy_from). Without copy_from this behaves like start_record_edit_session (a blank new-record draft); With copy_from, DAM copies that record's field values/settings/files into the new draft -- set make_file_names_unique=true to avoid file-name collisions with the source, and copy_relationship_field to link the new record back to the source via a OneParentManyChildren record-link field. Returns an edit_token -- thread it through get_record_edit_session/apply_record_edit/apply_and_save_record_edit/cancel_record_edit_session same as start_record_edit_session. This modifies data -- confirm with the user before calling. disable_validations=true is high-risk -- confirm it explicitly with the user before calling.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
copyFrom | string | No | Optional: the id of an existing record to copy field values/settings/files from. |
makeFileNamesUnique | boolean | No | Optional: when true, makes copied file names unique (e.g. "Copy 1") instead of colliding with copy_from's file names. Only applies when copy_from is set. |
copyRelationshipField | string | No | Optional: the name of a record-link field to relate the new draft back to copy_from (OneParentManyChildren -- copy_from becomes the parent). Only applies when copy_from is set. |
status | string | No | Optional: lifecycle status to set on the new record. |
contentType | string | No | Optional: content type to set on the new record. |
tag | string | No | Optional: a tag to distinguish or categorize the new record. |
fieldsAddOrUpdate | object (map of string) | No | Field values to set on the new record (overrides any value copied from copy_from). JSON object mapping field name to its new string value. |
fieldsRemove | array of string | No | Field names to explicitly clear. |
disableValidations | boolean | No | High-risk: when true, skips DAM's field and business rule validations for this session. |
immediateSearchIndexUpdate | boolean | No | Optional: when true, updates the search index immediately once this session is later committed, instead of waiting for the next scheduled update. |
Returns:
| Field | Type | Description |
|---|---|---|
editToken | string | |
recordLink | string (optional) | /// Deep link to the record this session is editing (Tenant.DamUiBaseUri/contentitems/{id}), resolved from the record id embedded in DAM's _links.record.href -- null if DAM omitted that link; falls back to the raw href if a record id can't be parsed out of it (see RecordEditSessionTools.ExtractRecordIdFromHref). |
hasValidationErrors | boolean | |
validationErrors | array of string |
delete_record
Available on request · Destructive
Permanently and irreversibly deletes an Aprimo record -- all its files, versions, metadata, and history are gone. This is the most destructive, least recoverable operation in this entire API -- there is no undo. Requires both confirmed=true and confirmedDestructive=true, after explicitly stating the exact record (id, and title if known from get_record_metadata) to the user and getting unambiguous go-ahead. forceDelete additionally overrides a usage lock on the record (requires the caller to hold DAM's 'Override Delete Usage Lock' permission) -- only set it when the user has explicitly asked to force past a lock.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
recordId | string | Yes | The record id (32-char hex / GUID) to permanently delete. |
confirmed | boolean | No | Must be true to proceed. Set to false (or omit) to get a confirmation gate error, then call again with confirmed=true after the user has explicitly confirmed the exact record. |
confirmedDestructive | boolean | No | Must also be true (in addition to confirmed) -- deleting a record is permanent and cannot be undone. Set only after stating the exact record to the user and getting explicit go-ahead. |
forceDelete | boolean | No | Optional: when true, force-deletes the record even if it is locked by a usage lock. Requires the caller to hold the 'Override Delete Usage Lock' permission. Only set when the user explicitly asked to force past a lock. |
immediateSearchIndexUpdate | boolean | No | Optional: when true, updates the search index immediately instead of waiting for the next scheduled update. |
Returns:
| Field | Type | Description |
|---|---|---|
recordId | string | |
deleted | boolean | |
forceDeleted | boolean |
This tool deletes or irreversibly overwrites data in the live tenant; the change cannot be rolled back through the API. It will not act unless the call sets both confirmed and confirmedDestructive to true.
execute_record_checkin
Available on request
Step 2 of 2 for checking in a new file version: finalizes the check-in using the operation_token from prepare_record_checkin, after the new file's bytes have been uploaded to that call's sasUrl. This modifies data -- make sure the user has already confirmed this check-in (at the prepare step or now).
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
operationToken | string | Yes | The operation token returned by prepare_record_checkin. |
Returns:
| Field | Type | Description |
|---|---|---|
operationToken | string | |
completed | boolean |
execute_record_checkout
Available on request
Step 2 of 2 for checking out a record: starts the checkout using the operation_token from prepare_record_checkout. This creates an asynchronous download order -- poll get_record_checkout_status with the same operation_token to see when it's ready and get the delivered file(s). This modifies data -- make sure the user has already confirmed this checkout (at the prepare step or now).
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
operationToken | string | Yes | The operation token returned by prepare_record_checkout. |
Returns:
| Field | Type | Description |
|---|---|---|
operationToken | string | |
completed | boolean |
get_record_checkout_status
Available on request
Checks the status of an Aprimo record checkout started by execute_record_checkout (which creates an asynchronous download order) -- pass the same operation_token used there. Pending/Queued/Executing/Scheduled/AsyncPending/AsyncExecuting are normal in-progress states, not errors -- tell the user it's still processing and offer to check again shortly. deliveredFiles lists the file name(s)/URI(s) the order has produced once status is Success. Note: DAM's spec does not explicitly document how this endpoint is scoped to one checkout order -- modeled here as requiring the operation_token, for consistency with the rest of this checkin/checkout family; unverified against a live tenant.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
operationToken | string | Yes | The operation token returned by prepare_record_checkout (the same one passed to execute_record_checkout). |
Returns:
| Field | Type | Description |
|---|---|---|
operationToken | string | |
status | string | |
deliveredFiles | array of string |
get_record_edit_session
Available on request
Reads the current state of an Aprimo record edit session: whether it has outstanding validation errors and a deep link to the record it's editing. Use to check a session started by start_record_edit_session/create_record_draft before deciding whether to save or cancel it.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
editToken | string | Yes | The edit token returned when the session was started (start_record_edit_session/create_record_draft). |
Returns:
| Field | Type | Description |
|---|---|---|
editToken | string | |
recordLink | string (optional) | /// Deep link to the record this session is editing (Tenant.DamUiBaseUri/contentitems/{id}), resolved from the record id embedded in DAM's _links.record.href -- null if DAM omitted that link; falls back to the raw href if a record id can't be parsed out of it (see RecordEditSessionTools.ExtractRecordIdFromHref). |
hasValidationErrors | boolean | |
validationErrors | array of string |
list_record_locks
Available on request
Lists every lock currently held on an Aprimo record: who/what holds each lock (integrationId), why (reason), an optional reference uri, and when it was taken. Any user with read permission on the record can see its locks. Use before lock_record, or to check whether a record is already locked by another integration before attempting to modify it.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
recordId | string | Yes | The record id (32-char hex / GUID). |
Returns:
| Field | Type | Description |
|---|---|---|
recordId | string | |
count | integer | |
items | array of RecordLockPayload | |
items[].lockId | string | |
items[].integrationId | string (optional) | |
items[].uri | string (optional) | |
items[].reason | string (optional) | |
items[].lockedOn | string (optional) |
lock_record
Available on request
Creates a lock on an Aprimo record, preventing it from being modified by others until the lock is released. This modifies data -- confirm with the user which record to lock and why before calling. There is no unlock/release tool in this API surface; locks are released by the integration that owns them through DAM's own mechanisms.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
recordId | string | Yes | The record id (32-char hex / GUID) to lock. |
integrationId | string | Yes | Identifier of the integration/system that owns this lock. Required -- confirmed live that DAM 400s ("ArgumentException: integrationId") without it, despite the OpenAPI snapshot not marking it required. |
reason | string | Yes | A human-readable reason for the lock. Required -- confirmed live that DAM 400s ("ArgumentException: reason") without it, despite the OpenAPI snapshot not marking it required. |
uri | string | No | Optional: a URI associated with the lock, e.g. a link back to the external system holding it. |
Returns:
| Field | Type | Description |
|---|---|---|
recordId | string | |
lockId | string |
prepare_record_checkin
Available on request
Step 1 of 2 for checking in a new file version on an Aprimo record: requests an upload location (sasUrl) and registers the previews/publication items to generate once the upload completes. The caller must then upload the new file's bytes to the returned sasUrl (a direct-to-Azure-Storage upload, outside this API), then call execute_record_checkin with the returned operation_token to finalize the check-in. This modifies data (reserves an upload session) -- confirm with the user before calling.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
recordId | string | Yes | The record id (32-char hex / GUID) to check a new file version in on. |
uploadServiceUrl | string | No | Optional: the URL of the upload service that will host the new file version. |
fileName | string | No | Optional: the name of the file being checked in. |
versionLabel | string | No | Optional: a version label to apply to the new file version. |
comment | string | No | Optional: a comment to associate with the new file version. |
previews | array of DamModels.UploadPreviewModel | No | Optional: previews to generate for the new file version, each { fileName, name, pageNumber }. |
publicationItems | array of DamModels.PublicationItemModel | No | Optional: publication items to associate with the new file version, each { targetFileVersionId, pageNumber }. |
authorizationHeader | string | No | Optional: the authorization header to use when uploading to uploadServiceUrl. |
Returns:
| Field | Type | Description |
|---|---|---|
recordId | string | |
operationToken | string | |
sasUrl | string (optional) | |
previewUploadUrls | array of string |
prepare_record_checkout
Available on request
Step 1 of 2 for checking out an Aprimo record: reserves the checkout and returns an operation_token. Call execute_record_checkout next with this operation_token to actually start the checkout (which creates an asynchronous download order -- poll get_record_checkout_status with the same token). This modifies data -- confirm with the user before calling.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
recordId | string | Yes | The record id (32-char hex / GUID) to check out. |
Returns:
| Field | Type | Description |
|---|---|---|
recordId | string | |
operationToken | string |
prepare_undo_record_checkout
Available on request
Step 1 of 2 for undoing an existing checkout on an Aprimo record: reserves the undo and returns an operation_token. Call cancel_record_checkout next with this operation_token to actually undo the checkout and release its lock (there is no dedicated execute step for undo -- cancel_record_checkout is that step; see its own description). This modifies data -- confirm with the user before calling.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
recordId | string | Yes | The record id (32-char hex / GUID) whose checkout to undo. |
Returns:
| Field | Type | Description |
|---|---|---|
recordId | string | |
operationToken | string |
start_record_edit_session
Available on request
Step 1 of the Aprimo record edit-session workflow: starts a session for a brand-new, blank record -- DAM's schema for this endpoint carries no record id anywhere, so this can only start a session for a record that doesn't exist yet (use create_record_draft instead to start one copied from an existing record/template, or update_record_metadata_field/apply_record_bulk_edit to edit an already-existing record). Returns an edit_token -- thread it through get_record_edit_session (inspect), apply_record_edit (PATCH, partial update, keeps the session open), apply_and_save_record_edit (POST, applies changes and commits/saves -- closes the session unless keep_edit_open=true), or cancel_record_edit_session (discard). This modifies data (opens a session) -- confirm with the user before calling. disable_validations=true is high-risk -- confirm it explicitly with the user before calling.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | Optional: lifecycle status to set on the new record. |
contentType | string | No | Optional: content type to set on the new record. |
tag | string | No | Optional: a tag to distinguish or categorize the new record. |
fieldsAddOrUpdate | object (map of string) | No | Field values to set on the new record. JSON object mapping field name to its new string value. |
fieldsRemove | array of string | No | Field names to explicitly clear (rarely needed on a brand-new record). |
disableValidations | boolean | No | High-risk: when true, skips DAM's field and business rule validations for this session. |
immediateSearchIndexUpdate | boolean | No | Optional: when true, updates the search index immediately once this session is later committed, instead of waiting for the next scheduled update. |
Returns:
| Field | Type | Description |
|---|---|---|
editToken | string | |
recordLink | string (optional) | /// Deep link to the record this session is editing (Tenant.DamUiBaseUri/contentitems/{id}), resolved from the record id embedded in DAM's _links.record.href -- null if DAM omitted that link; falls back to the raw href if a record id can't be parsed out of it (see RecordEditSessionTools.ExtractRecordIdFromHref). |
hasValidationErrors | boolean | |
validationErrors | array of string |
Related
- Aprimo MCP Server — configuration, connection details, and authentication
- MCP Tool Permission Map — the Aprimo permissions that make each tool visible to your agent
- REST API vs. MCP — choosing the right integration approach for your agent