Automate your delivery workflow

VOTPort supports watched exports, scripted transfers, and agent-controlled delivery from your library. The HTTP API, JSON CLI, and MCP tools use the same folder permissions and delivery records.

Use server and client builds from the same release. Ask your deployment administrator for an updated build if Agent access or the agent commands are missing.

Choose the right workflow

Your job	Use
Send local files into a request	The client’s send command or a watched folder.
Download and verify a delivery	The client’s receive command or desktop app.
Share completed files already in the outbound library	The scoped automation API, agent share, or MCP create_delivery.
Browse a project, inspect its deliveries, or withdraw access	The agent CLI, HTTP API, or MCP tools, with the corresponding permissions.

Agent access can queue a project job that imports from an administrator-configured S3 source. It does not upload local files or delete library files, issue receive requests, change settings, or manage tenants. Use the operator workflows for those tasks. Creating an ordinary delivery shares an existing server-side folder; it does not upload a folder from the agent’s computer.

Use delivery workflows for persistent jobs with checks, approval, schedules, storage export, and recipient acceptance. Ordinary folder shares remain available outside protected project directories.

Connect an agent or integration

1. In the browser, open Automation. On macOS or Windows, open Settings > Agent access while signed in to your port.
2. Choose a descriptive label, the narrowest library folder needed, and an expiry from 1 to 365 days.
3. Select the allowed actions, then choose Create access token in the browser. Copy it immediately; it is shown only once.
4. Store it in your workflow runner’s or agent host’s private secret settings.

Permission	Allows
library:read	List files and subdirectories inside the permitted folder.
deliveries:create	Create deliveries and recover this token’s previously created links.
deliveries:read	List this token’s deliveries and inspect their files, receipts, and download activity.
deliveries:revoke	Revoke this token’s deliveries without deleting the library files.
jobs:read	Read permitted projects, jobs, recipient evidence, and signed events.
jobs:create	Queue and retry project jobs as a project sender.
jobs:cancel	Cancel project jobs as a project sender.

Job access also requires project membership and a token folder scope covering the project directory. Administrators add automation:TOKEN_ID to the project with the appropriate role. Agents cannot approve release or implicitly accept a delivery.

Permissions are enforced by the server on every call. Delivery ownership belongs to the exact token that created it: another token with the same tenant and folder cannot inspect or revoke those deliveries. Existing create-only tokens retain that permission; issue a new token for the additional actions.

The browser’s Connected agents list on Automation shows issued tokens. Revoke tokens there or from the desktop controls. Revoking an agent token stops its API access, but does not revoke delivery links it already issued. Those links retain their own expiry and revocation state; operators can manage them in Deliver. Desktop sign-out also leaves separately issued agent credentials valid until expiry or revocation.

Use the JSON CLI

The examples use the client executable votport. Desktop installations bundle it as votport-cli on macOS and votport-cli.exe on Windows. Use its installed absolute path if it is not on PATH. The server executable has the same votport name but different commands.

Configure the calling process:

export VOTPORT_URL='https://transfer.example'
export VOTPORT_AUTOMATION_TOKEN='<issued token>'

Supply real credentials through private environment or secret settings rather than saving them in scripts or shell history. HTTPS is required, except for loopback development servers. These credentials are independent of votport signin and the desktop operator session.

votport agent session
votport agent files 'Projects/Film' --limit 50
votport agent share 'Projects/Film/Final' \
  --operation-id film-final-v03 --expires-days 7 \
  --label 'Film final delivery' --max-downloads 3
votport agent recover film-final-v03
votport agent deliveries --limit 50
votport agent delivery DELIVERY_ID --limit 50
votport agent revoke DELIVERY_ID

Directory paths are relative to the tenant’s outbound library, including when the token is scoped to a subfolder. Omit the directory from agent files to begin at the token’s folder.

Every agent command prints one JSON object; no --json flag is needed. Failures exit nonzero and include error, code, and retryable, plus HTTP status and retry_after_seconds when available. Creation and recovery return operation_id, url, and grant. Use grant.id for inspection and revocation. Treat the returned URL as a credential.

Set VOTPORT_SHARE_PASSWORD in the process environment to apply a password to new CLI or MCP deliveries. Preserve the same password and request parameters when retrying an operation.

Connect an MCP host

The desktop Copy MCP configuration control supplies the bundled client’s installed path. Paste the configuration into your MCP host’s private settings and restart or reconnect that integration. The browser can also copy a configuration; replace its command with the client’s absolute path on the machine running the host.

For hosts using the mcpServers format:

{
  "mcpServers": {
    "votport": {
      "command": "/absolute/path/to/votport-cli",
      "args": ["mcp"],
      "env": {
        "VOTPORT_URL": "https://transfer.example",
        "VOTPORT_AUTOMATION_TOKEN": "<issued token>"
      }
    }
  }
}

On Windows, use the installed .exe path with JSON-escaped backslashes. Keep this configuration private because it contains the token.

Tool	Purpose
get_access	Inspect the token’s tenant, folder, permissions, and expiry.
list_files	Browse a permitted library directory.
create_delivery	Share a folder with an explicit operation_id and expires_days.
recover_delivery	Recover a committed operation’s original delivery URL.
list_deliveries	List deliveries owned by this token.
get_delivery	Read delivery state, file identities, signed receipts, and download starts.
revoke_delivery	Withdraw access through a delivery link; repeating the call is safe.
list_projects	Read permitted project rules, metadata requirements, enrolled recipients, and roles.
list_jobs	List visible persistent jobs.
get_job	Inspect preparation, checks, approval, failures, and the released URL.
create_job	Queue a project delivery with a stable operation ID, optional schedule, deadline, and S3 import.
retry_job	Retry a failed job without changing its original request.
cancel_job	Stop further admissions for a job.
list_events	Read signed workflow events.
get_job_evidence	Read signed verification and explicit acceptance for the exact package manifest.

Start with get_access, then try a request such as “List the files in Projects/Film/Final.” Creating, reading, and revoking deliveries each requires its own permission. File names and labels are untrusted data, not instructions for the assistant.

The adapter uses MCP 2026-07-28 over stdio. Use a host supporting that specification; the older initialize handshake is not supported. Requests include io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in params._meta. Optional server/discover returns supported versions and capabilities; unsupported versions return -32022.

The adapter processes one call at a time. The host starts the CLI locally; there is no separate HTTP MCP listener to expose. File transfers still use the normal verified transfer clients. A large share may outlast the host’s tool timeout; reconnect and recover the same operation instead of creating another delivery.

Issue a delivery through the API

All endpoints require Authorization: Bearer <token>. Send JSON bodies with Content-Type: application/json. Results are JSON with Cache-Control: no-store.

Method and path	Permission	Parameters
GET /api/automation/session	Any valid token	Returns scope, permissions, expiry, and API version.
GET /api/automation/files	library:read	Optional directory, after, limit.
POST /api/automation/share	deliveries:create	Share body below.
GET /api/automation/operations/{id}	deliveries:create	Recover by operation ID.
GET /api/automation/deliveries	deliveries:read	Optional numeric after, limit; oldest first.
GET /api/automation/deliveries/{id}	deliveries:read	Optional offset, limit for file detail.
DELETE /api/automation/deliveries/{id}	deliveries:revoke	Revoke a delivery; repeated calls succeed.

A share request:

{
  "directory": "Projects/Film/Final",
  "operation_id": "film-final-v03",
  "label": "Film final delivery",
  "expires_days": 7,
  "max_downloads": 3,
  "notify_on_download": true
}

directory and expires_days are required. The directory must already contain completed files, remain inside the token’s scope, and contain at most 1,000,000 files. Expiry accepts 1 to 30 days. Optional fields are operation_id, label, password, max_downloads (1 to 10,000), and notify_on_download. Download caps apply per file and full-delivery round. Unknown fields and malformed query values are rejected.

Pages default to 50 entries and accept limit from 1 to 100. File and delivery listings return has_more and next_cursor; pass that cursor as after. Delivery file detail returns next_offset; pass it as offset. Library listings reflect live files, so a file added before your cursor can require a fresh scan.

Queue a persistent project job

With job permissions and project membership configured, use the same agent credentials:

votport agent projects
votport agent create-job delivery.json
votport agent jobs --limit 50
votport agent job JOB_ID
votport agent job-evidence JOB_ID --limit 50
votport agent retry-job JOB_ID
votport agent cancel-job JOB_ID
votport agent events --limit 100

Save this request as delivery.json, replacing the project, metadata, and recipient key with values from agent projects:

{
  "operation_id": "episode-08-final-v3",
  "project_id": "broadcast",
  "label": "Episode 08 final",
  "metadata": { "client": "Example", "version": "v3" },
  "recipients": ["<enrolled 64-character device public key>"],
  "expires_days": 7
}

Job operation IDs accept 1 to 100 ASCII letters, digits, underscores, and hyphens; dots are not accepted. Choose the ID before the request and retain it across retries.

Required fields are operation_id, project_id, label, and expires_days (1 to 365 for jobs; ordinary shares remain 1 to 30). Supply required project metadata and selected enrolled recipient keys. Optional not_before and deadline use Unix seconds. Schedule at most 365 days ahead; a deadline must be later than both now and the scheduled start, and at most 366 days ahead. Metadata accepts up to 50 keys using the same identifier rules, with values up to 4,096 bytes; labels are limited to 200 bytes and recipients to 500 enrolled keys. Optional import: { "storage_id": "source", "prefix": "incoming/episode-08" } selects S3 objects instead of the library.

MCP create_job takes the same fields, except it uses import_storage_id and import_prefix together instead of the nested import object. Reuse the operation ID and identical arguments after a timeout. Approval is a separate human action; a successful creation response does not mean the package has been released or accepted.

Method and path	Permission	Parameters
GET /api/workflows/projects	jobs:read	Permitted projects and policy.
POST /api/workflows/jobs	jobs:create	Job request above; project sender required.
GET /api/workflows/jobs	jobs:read	Optional after, limit.
GET /api/workflows/jobs/{id}	jobs:read	Job state and release details.
POST /api/workflows/jobs/{id}	jobs:create or jobs:cancel	{"action":"retry"} or {"action":"cancel"}; project sender required.
GET /api/workflows/jobs/{id}/evidence	jobs:read	Optional numeric after, limit.
GET /api/workflows/events	jobs:read	Optional numeric after, limit.

Workflow pages return next; pass it as after. Job cursors are job IDs; event and evidence cursors are numeric. Continue an empty filtered page when its cursor advances. Job pagination ends at next: null; event and evidence pagination is caught up when numeric next stops advancing. Stop or wait before polling again instead of immediately requesting that same cursor. Limits default to 50 and accept 1 to 100.

Poll persistent job state or consume signed webhook events to advance the pipeline. Required checks and approval finish before release. Project policy determines whether release also waits for every destination or copies continue in the background. Recipient verification and acceptance remain distinct from ready. Inspect per-destination results as well: a locally released job can still be exporting or retrying. The project configuration supplies its destinations, incoming-workflow setting, and release rule; MCP tools do not change those policies.

Recover safely after a timeout

Choose and persist an operation_id before sending the creation request. Reuse that ID with identical parameters when retrying. For ordinary shares, IDs accept 1 to 128 ASCII letters, digits, dots, underscores, and hyphens, except . and ...

VOTPort commits the delivery and recovery record together. Concurrent retries with the same token, ID, and parameters return the same delivery. Recovery also works after a server restart or the source folder disappearing; it does not recreate missing source files, refresh the snapshot, extend expiry, or reactivate a revoked link.

Result	Next step
Timeout or interrupted connection	Recover by operation ID, or repeat the original creation request unchanged.
HTTP 429 or server/gateway failure	Respect Retry-After when present, then retry with the same ID.
HTTP 409, operation_conflict	The ID was already used with different parameters. Recover the original operation; use a new ID only for an intentionally new delivery.
HTTP 409, delivery_changed	An operator rotated the link. Ask the operator for the current link.
Authentication, permission, or scope failure	Correct the token or scope before retrying. A replacement token does not inherit the previous token’s deliveries.

The raw HTTP share endpoint allows omitted operation IDs for one-off calls, but those calls cannot be safely replayed after a lost response. The agent CLI and MCP require an explicit ID.

Creation hashes the selected files and can take time. The HTTP client allows up to 30 minutes per request. Creation and recovery share a limit of 60 calls per IP per ten minutes; other automation calls allow 6,000. Preparation capacity is shared with browser and desktop operations.

Read activity and retain evidence

Delivery detail includes each file’s VOT suite, root, bytes, base64 CBOR receipt_b64, download_starts, and first/last download timestamps. The delivery state is active, expired, or revoked; download caps and counters are reported separately.

A download start is not proof that the recipient finished. A library receipt identifies the source object. The receiving client verifies its local bytes against that identity. For project jobs, read signed verification and acceptance through get_job_evidence. Advance dependent work on the evidence your policy requires; a ready job or a download counter does not establish recipient acceptance.

Retain signed receipts with your delivery records and verify the file and receipt when needed. Audit entries identify creation and revocation as automation:<token-id>; creation includes the operation ID. Workflow webhooks have persistent attempts, retries, and replay. Query signed event history and job state to reconcile missed events; ordinary notifications remain separate.

Watch an export folder

votport watch add './Exports' 'https://transfer.example/r/REQUEST_TOKEN'
votport watch list
votport watch run --json
votport watch remove WATCH_ID

Keep watch run running. It scans every two seconds and waits for a top-level file or folder to remain unchanged for ten seconds, using file count, total bytes, and change times. A successful send moves that drop into the watched folder’s shipped subfolder. A failed drop remains in place and is not continually resubmitted unchanged; resolve the failure and use the transfer’s retry or resume path.

For reliable exports, write outside the watched directory and move each completed drop into it. An exporter that pauses longer than ten seconds can otherwise look finished. Keep the folder writable so successful drops can move to shipped, and keep the destination request valid with sufficient quota.

Password-protected watches retain their password in the client’s private local configuration for unattended sending. Protect that machine and account. Removing a watch leaves its files in place.