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

Parameter	Type	Required	Description
`file`	`File`	Yes	Binary payload for transfer target.
`ttl`	`integer`	No	Expiry window in seconds.
`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" https://ultra.egomonk.com/api/upload

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 protected targets include X-Access-Grant.

Header	Required	Description
`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 -H "X-Access-Grant: agrt_..." https://ultra.egomonk.com/api/dl/trf_123 -o file.bin

Common Errors

agent_not_allowed_for_share
invalid_grant
grant_already_used
share_not_found_or_expired

Policy Cookbook Templates

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

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

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

{
  "mode": "agent",
  "allowedAgentIds": ["agent-a", "agent-b", "agent-c"],
  "maxUses": 0,
  "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_...