API Reference

Ultra keeps a compact control surface centered around Upload, Resolve, Grant, and Fetch. This page summarizes endpoint intent, auth, and common errors.

POST/api/upload

Create transfer + share with policy constraints (open or agent-gated). Responses include deleteToken; keep it private with the sender-side record. Open links spend max_uses at download/stream time.

Parameter	Type	Required	Description
`file`	`File`	Yes	Binary payload for transfer target.
`ttl`	`integer`	No	Expiry window in seconds.
`max_uses`	`integer`	No	Allowed open-link byte fetches. Defaults to one use.
`auth_mode`	`open\|agent`	No	Policy mode for share access.
`allowed_agent_ids`	`string`	No	Comma-separated allow list for agent mode.

curl -F "file=@report.pdf" -F "ttl=120" -F "max_uses=1" https://ultra.egomonk.com/api/upload

{
  "id": "trf_123",
  "shareId": "shr_123",
  "shareUrl": "https://ultra.egomonk.com/s/shr_123",
  "downloadUrl": "https://ultra.egomonk.com/api/dl/trf_123?share_id=shr_123",
  "expiresAt": "2026-04-10T...",
  "deleteToken": "dlt_..."
}

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

Native high-throughput multipart upload lane for large files. Completed uploads become normal Ultra shares with the same policy, grant, max-use, and delete-token semantics.

POST /api/upload/multipart/init
POST /api/upload/multipart/part
POST /api/upload/multipart/complete
POST /api/upload/multipart/abort
GET  /api/upload/multipart/status

TUS Compatibility

Core TUS resumable upload adapter over Ultra multipart manifests. Supports creation, HEAD offset checks, PATCH upload, expiration, and termination.

OPTIONS /api/tus
POST    /api/tus
HEAD    /api/tus/{id}
PATCH   /api/tus/{id}
DELETE  /api/tus/{id}

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.

Header	Required	Description
`Authorization`	When policy is agent	`Bearer agk_...` or `Bearer aat_...` for agent-gated shares.

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

{
  "id": "shr_123",
  "type": "file",
  "targetId": "trf_123",
  "policy": { "mode": "agent", "allowedAgentIds": ["agent-b"] }
}

POST/api/agent/grants

Issue one-time grant token for protected fetch path.

Field	Type	Required	Description
`shareId`	`string`	Yes	Share to mint a one-time access grant for.

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.

Header / Query	Required	Description
`share_id`	For open links	Share identifier used for `maxUses` accounting.
`X-Access-Grant`	When policy is agent	One-time grant token from `POST /api/agent/grants`.
`Range`	No	Optional byte range for resumable downloads.

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.

Header	Required	Description
`X-Delete-Token`	When caller is not the owner session	Creator-side token returned as `deleteToken` from upload, pipe, or folder creation.

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_...