API Reference

POST/api/transfer-plan

Supported browser, SDK, CLI, and local MCP clients request a signed plan before creating transfer state. The plan authorizes the lane, geometry, capacity bounds, release, expiry, and fallback policy. Clients may narrow it for local safety but cannot widen it. Successful lane completion returns the ordinary share response, including a sender-only deleteToken.

Use a supported high-level client for file bytes. Plain /api/upload and TUS return 410 transfer_surface_retired; private lane endpoints reject calls without the matching plan binding.

node cli/ultra.mjs upload report.pdf --ttl 120 --json

POST/api/import-url

Fetch an HTTP(S) URL server-side and create a normal Ultra file share after SSRF checks, redirect revalidation, byte caps, and timeout caps.

curl -X POST https://ultra.egomonk.com/api/import-url \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/report.pdf","maxUses":1}'

Turbo Multipart

Ultra's signed server plan selects the native high-throughput multipart lane automatically for capable clients and appropriate files. The client preserves its private resume receipt while plan-bound protocol machinery initializes, authorizes, completes, aborts, and recovers the upload. Users do not select Turbo, part size, concurrency, or bytes in flight.

POST/api/folder/{folderId}/upload-complete

Folder multipart completion is a durable asynchronous command. Send exactly fileId, uploadId, and a stable operationId; direct-R2 uploads use the equivalent /upload-direct-complete route. A successful command returns 202 Accepted with Location, Retry-After, and Cache-Control: no-store. Poll the returned /upload-status?view=completion URL until ready. The server owns the authoritative part receipts and continues transient retries after the browser disconnects.

{"fileId":"file_123","uploadId":"multipart_123","operationId":"complete_123"}

Retired Compatibility Surfaces

Plain /api/upload and /api/tus bypass automatic planning and are retired before release. Every method returns 410 transfer_surface_retired with guidance to use a supported planned client.

GET/api/folder/{folderId}/zip

Stream ready folder files as a server-built ZIP archive. The endpoint uses folder download permissions and consumes one open folder share use for the archive request.

curl -OJL "https://ultra.egomonk.com/api/folder/{folderId}/zip?share_id={shareId}"

GET/api/share/{shareId}

Resolve canonical share metadata and policy for authorized caller. File shares expose mimeType as the canonical JSON content-type signal; contentType remains HTTP/R2 transport vocabulary.

curl -H "Authorization: Bearer agk_..." https://ultra.egomonk.com/api/share/shr_123

{
  "id": "shr_123",
  "type": "file",
  "targetId": "trf_123",
  "fileId": "trf_123",
  "filename": "task.json",
  "mimeType": "application/json",
  "size": 42,
  "policy": { "mode": "agent", "allowedAgentIds": ["agent-b"] }
}

POST/api/agent/grants

Issue one-time grant token for protected fetch path.

curl -X POST https://ultra.egomonk.com/api/agent/grants \
  -H "Authorization: Bearer agk_..." \
  -H "Content-Type: application/json" \
  -d '{"shareId":"shr_123"}'

{
  "accessToken": "agrt_...",
  "targetType": "file",
  "targetId": "trf_123",
  "expiresAt": "2026-04-10T..."
}

GET/api/dl/{id}

Fetch bytes. For open links include share_id to spend the link usage counter. For protected targets include X-Access-Grant.

curl "https://ultra.egomonk.com/api/dl/trf_123?share_id=shr_123" -o file.bin

curl -H "X-Access-Grant: agrt_..." https://ultra.egomonk.com/api/dl/trf_123 -o file.bin

DELETE/api/dl/{id}

Delete a transfer before expiry. Signed-in owners can delete their own transfers; anonymous cleanup requires the create-response deleteToken.

curl -X DELETE https://ultra.egomonk.com/api/dl/trf_123 -H "X-Delete-Token: dlt_..."

Common Errors

• agent_not_allowed_for_share
• invalid_grant
• grant_already_used
• share_use_limit_exceeded
• share_not_found_or_expired

Policy Cookbook Templates

{
  "mode": "open",
  "allowedAgentIds": [],
  "maxUses": 1,
  "metadata": {}
}

{
  "mode": "agent",
  "allowedAgentIds": ["agent-a", "agent-b"],
  "maxUses": 1,
  "metadata": { "workflow": "review" }
}

{
  "mode": "agent",
  "allowedAgentIds": ["agent-receiver"],
  "maxUses": 1,
  "metadata": { "step": "handoff" }
}

{
  "mode": "agent",
  "allowedAgentIds": ["agent-a", "agent-b", "agent-c"],
  "maxUses": 3,
  "metadata": { "channel": "research" }
}

Production Guidance

• Retries: re-run grant issuance for each protected fetch retry.
• Idempotency: attach stable operation IDs in callers and suppress duplicate submissions.
• TTL Strategy: set TTL per workflow stage duration plus margin.
• Observability: log shareId/targetId/agentId/errorCode and p95 latency for resolve/grant/fetch.

Common Agent Workflow Examples

# Secure handoff A -> B
curl -F "file=@artifact.bin" -F "auth_mode=agent" -F "allowed_agent_ids=agent-b" https://ultra.egomonk.com/api/upload

# Channel fan-out
curl -F "file=@task.json" -F "auth_mode=agent" -F "allowed_agent_ids=agent-a,agent-b,agent-c" -F "metadata={\"channel\":\"research\"}" https://ultra.egomonk.com/api/upload

# Grant recovery
curl -X POST https://ultra.egomonk.com/api/agent/grants -d '{"shareId":"shr_..."}'
curl -H "X-Access-Grant: agrt_..." https://ultra.egomonk.com/api/dl/trf_...