# Uno Kit agent entry point

> Account-key sessions, owner Kit operations, history, direct uploads, commits, pinned paged restore, and job status, and storage purchases.

The Ed25519 account key is the only identity while unverified. Losing it loses the account; there is no lost-key recovery.
Keep the key and a durable backup outside disposable runtimes and upload trees. Never upload credentials.
A paying wallet grants no owner authority. A later payment needs a funded wallet or another payer.
SDK-free still needs an Ed25519 signing capability. The checked Node script uses only built-ins.
[HTTP recipes](/examples/README.md) cover session, private commit, inline commit, direct tar upload, and polling. Download the [checked signing script](/examples/sign-session.mjs).
After verification the key stops signing in over HTTP. Verified CLI or MCP sign-in keeps the Agent plan.
Session calls and public key history need no credential. Owner reads and writes need the Kit proof-slot Bearer.
POST /v1/session/challenge with public_key (32 bytes, lowercase hex), optional username, and legal_acceptance_version.
Check the nine statement lines against the pinned contract, then sign the exact decoded signing_bytes with Ed25519.
POST /v1/session with the same inputs, challenge (lowercase hex), expires_at, and signature (standard padded base64).
The credential lasts at most 300 seconds. Renew with a fresh proof; no Uno session or refresh token is returned.
A new Agent account may receive a one-time promo storage grant on its first successful private write while campaign slots remain.
A per-network limit applies, so a grant is not guaranteed. Read quota through the Uno CLI or MCP for granted capacity and expiry.
POST /v1/purchases with capacity_bytes and months_to_add as decimal strings and an Idempotency-Key. Owner credentials create or refresh; Payment retries on the same URL resolve the purchase from the verified challenge.
The anonymous pay link names the beneficiary owner namespace; it grants payment only, never ownership or usage visibility. Forward x-uno-expect-account only to pin the intended beneficiary.
GET the pay URL to reconcile receipts without broadcasting. POST it to request a challenge or submit Payment. Pending means poll the same URL; never start another payment to recover an uncertain result.
Offers require backend activation. Runtime frozen terms and 402 headers are authoritative for network, asset and rate. Price uses one ceiling in token base units: rate times (capacity GB times added months plus increased capacity GB times the remaining fraction of a month). Storage operation limits do not rise with payment.
All purchase responses use no-store, private. Payment headers are preserved verbatim; bodies use the same snake_case envelope as other routes.
GET inputs are query parameters in snake_case. namespace or handle selects a source; omitted means your own namespace.
Use /refs?prefix=refs%2Fheads%2F for branches and prefix=refs%2Ftags%2F for tags.
Read responses preserve protobuf JSON scalar encodings and use snake_case recursively.
Use page_size and page_token for large reads. Upstream JSON is capped at 8 MiB; file bytes use direct URLs.
GET /v1/kits/{repo}/restore pins a full ref or commit once. It returns paged files, directory modes, chunk layouts, and expiring direct links; file bytes never pass through this route.
Restore page_size is 1 to 8 (default 4), limiting tree entries and download links. Follow next_page_token even on empty file pages; an empty token means complete.
Replay the returned page_token to renew the same page at the same commit after credential renewal. Omit revision on continuation. Current ownership, repository incarnation, and backend reads are checked on every page.
Restore cursors are capped at 12 KiB and their continuation and renewal URLs at 16 KiB. Oversized positions refuse with RESTORE_CURSOR_LIMIT and a stop action; use the CLI for that restore.
Owner mutations require Idempotency-Key (1 to 128 characters from A-Z, a-z, 0-9, dot, underscore, or hyphen).
Direct upload POST bodies use snake_case JSON, capped at 1 MiB of metadata. These direct routes accept no file bytes.
POST /v1/uploads with repo, branch, file_count, and declared_bytes; set default_declared_bytes:true instead when size is unknown.
For direct part links, include upload_bytes (exact tar body length) and upload_format:UPLOAD_FORMAT_TAR. Only tar is accepted.
Read GET /v1/capabilities for enforced limits. A session accepts at most 1 GiB of file content and 3,000 files on every surface. Tar framing has a separate 1,028 MiB body ceiling.
remix.source_bytes limits a remix source.
A larger upload goes as several sessions: open one per part, and commit each with the previous commit as expected_head. A single file over staging.file_bytes has no upload path.
Without upload_bytes, StartUpload returns no part link; use that session only for delete_paths or StageUrl.
The server sizes the parts. data.upload_parts lists each part not yet received as part_number, url, size_bytes and offset_bytes; data.upload_part_bytes and data.upload_part_count describe the split. A body of at most one part size has exactly one part.
Send each part with one PUT of exactly size_bytes bytes to its url and no other header. Ignore the response ETag; Kit needs none. Parts may go in any order or in parallel. Then POST {} to /v1/uploads/{id}/finalize, which accepts no parts or ETags.
Links last at most ten minutes (data.upload_expires_at). If a link expired or a part failed, repeat the start with the same key and body: it returns fresh links for only the missing parts. A finalize before every part arrived fails with a retryable precondition; send the missing parts and finalize again with the same key.
POST /v1/uploads/{id}/url with url, path, and optional mode (default ENTRY_MODE_REGULAR). The backend fetches the public URL.
POST /v1/uploads/{id}/commit with message, expected_head, and optional delete_paths. Empty expected_head requires an absent branch.
POST /v1/kits/{repo}/commit with branch, expected_head, message, and files: at most 1 MiB of decoded file bytes. Larger uploads use the tar route POST /v1/uploads.
Each file has path and exactly one of text or standard padded base64; omitted mode selects ENTRY_MODE_REGULAR. Optional delete_paths removes files.
Inline commits permit 1 MiB of normalized metadata and a 16 MiB encoded JSON body, including escaped content and base64 expansion.
Inline retries replay StartUpload, StageFiles, and Commit under derived keys. Empty files with nonempty delete_paths skips StageFiles; other step keys stay unchanged. At least one file or deletion is required. Repeat the original key and body after uncertainty or credential renewal.
The first commit creates a private Agent Kit. Later commits preserve its visibility; omit draft for existing Kits.
PUT /v1/kits/{repo}/visibility accepts public or private. Only this route changes visibility explicitly.
Branch mutations require refs/heads/... and compare the expected old ID. POST /branches requires an absent head. Tags are immutable; no tag delete route exists.
RemixPreflight is a read: no idempotency key or receipt. Remix creates a private destination through backend policy; publish separately.
Remix and revert return receipts and job polling. Acceptance never confirms publication.
Every write returns a receipt. A complete upload receipt does not mean a committed Kit; only JOB_STATE_COMMITTED confirms a landed commit, and a private Kit stays private until explicitly published.
Unknown results require the same key and body, including after a fresh credential. Never change the key to recover a lost response.
Finalize runs independently of the request with a fixed 30-minute deadline. Finalize, URL staging and job reads hold a pending answer for up to 45 seconds. On PENDING or a lost reply, repeat the same session, body and key, following next_action.delay_seconds until COMPLETE or FAILED. Polling never extends the deadline.
A pending commit returns its original job_id and a next_action poll URL and delay. Finalize and URL staging can require same-key replay.
A large file's download copy can take minutes to prepare. GET /v1/kits/{repo}/object-url holds up to 45 seconds, then returns HTTP 202 with reason OBJECT_PREPARING and data.preparing true. Repeat the same GET, following next_action, until data.url is set. GET /v1/kits/{repo}/restore answers the same 202 with data {preparing, path, object_id} while a file in the page is still being prepared; repeat the identical request until it returns 200.
The account key controls ownership. These HTTP uploads have no CLI secret scan or confirmation; hosted history is Uno-signed and attributed to the Agent.
Errors and pending jobs include next_action. Agent storage refusals stay HTTP 403 with no payment step; Kit write routes never return HTTP 402 or issue a payment challenge; only purchase POST routes can do so.

## Served routes

- [GET /health](/health): Check Worker health.
- [GET /openapi.json](/openapi.json): Read served routes as OpenAPI 3.1.
- [GET /llms.txt](/llms.txt): Read the agent route guide.
- [GET /examples/README.md](/examples/README.md): Read README.md.
- [GET /examples/session.md](/examples/session.md): Read session.md.
- [GET /examples/private-commit.md](/examples/private-commit.md): Read private-commit.md.
- [GET /examples/direct-tar.md](/examples/direct-tar.md): Read direct-tar.md.
- [GET /examples/inline-commit.md](/examples/inline-commit.md): Read inline-commit.md.
- [GET /examples/jobs.md](/examples/jobs.md): Read jobs.md.
- [GET /examples/kit-management.md](/examples/kit-management.md): Read kit-management.md.
- [GET /examples/branches-tags.md](/examples/branches-tags.md): Read branches-tags.md.
- [GET /examples/revert-remix.md](/examples/revert-remix.md): Read revert-remix.md.
- [GET /examples/purchase.md](/examples/purchase.md): Read purchase.md.
- [GET /examples/restore.md](/examples/restore.md): Read restore.md.
- [GET /examples/sign-session.mjs](/examples/sign-session.mjs): Read sign-session.mjs.
- [POST /v1/uploads](/v1/uploads): Open a tar upload with server-sized part links, or a session without a link; at most 1 GiB of file content and 3,000 files.
- [POST /v1/uploads/{id}/finalize](/v1/uploads/{id}/finalize): Finalize a tar upload after every part is PUT; replay the same key and body while pending.
- [POST /v1/uploads/{id}/url](/v1/uploads/{id}/url): Stage a public URL through the backend; replay the same key and body while pending.
- [POST /v1/uploads/{id}/commit](/v1/uploads/{id}/commit): Commit staged content or delete_paths against expected_head; a new Agent Kit is private.
- [POST /v1/session/challenge](/v1/session/challenge): Get exact bytes for an account-key proof.
- [POST /v1/session](/v1/session): Exchange one proof for a Kit-only credential.
- [GET /v1/account](/v1/account): Read the authenticated account.
- [GET /v1/storage](/v1/storage): Read the owner storage snapshot and recorded purchases.
- [GET /v1/capabilities](/v1/capabilities): Read server limits.
- [GET /v1/kits](/v1/kits): List Kits visible to the owner.
- [GET /v1/kits/{repo}](/v1/kits/{repo}): Show a revision and paged tree.
- [GET /v1/kits/{repo}/refs](/v1/kits/{repo}/refs): List branches and immutable tags.
- [GET /v1/kits/{repo}/ref](/v1/kits/{repo}/ref): Read one branch or tag.
- [GET /v1/kits/{repo}/read-gate](/v1/kits/{repo}/read-gate): Read the public visibility gate.
- [GET /v1/kits/{repo}/log](/v1/kits/{repo}/log): Read paged commit history.
- [GET /v1/kits/{repo}/files](/v1/kits/{repo}/files): Read file bytes or a direct download URL.
- [GET /v1/kits/{repo}/file-layout](/v1/kits/{repo}/file-layout): Read paged chunk layout.
- [GET /v1/kits/{repo}/diff](/v1/kits/{repo}/diff): Read paged changes between revisions.
- [GET /v1/kits/{repo}/verify](/v1/kits/{repo}/verify): Verify a revision and its authorization evidence.
- [GET /v1/kits/{repo}/prove](/v1/kits/{repo}/prove): Read a disclosure proof.
- [GET /v1/kits/{repo}/object-url](/v1/kits/{repo}/object-url): Get a direct object download URL.
- [GET /v1/keys](/v1/keys): Read the owner's keyring.
- [GET /v1/namespaces/{namespace}/key-history](/v1/namespaces/{namespace}/key-history): Read public key history for verification.
- [GET /v1/jobs/{id}](/v1/jobs/{id}): Read the owner's hosted job status.
- [POST /v1/purchases](/v1/purchases): Create or recover a storage purchase; retry Payment on the same URL.
- [GET /v1/purchases/{id}](/v1/purchases/{id}): Read the owner's stored purchase.
- [GET /v1/purchases/{link}/pay](/v1/purchases/{link}/pay): Reconcile a payment receipt without broadcasting.
- [POST /v1/purchases/{link}/pay](/v1/purchases/{link}/pay): Request or pay frozen purchase terms.
- [PUT /v1/kits/{repo}/visibility](/v1/kits/{repo}/visibility): Explicitly publish or unpublish a Kit.
- [DELETE /v1/kits/{repo}](/v1/kits/{repo}): Delete a Kit; retained content follows backend policy.
- [POST /v1/kits/{repo}/branches](/v1/kits/{repo}/branches): Create an absent refs/heads branch.
- [PUT /v1/kits/{repo}/branch](/v1/kits/{repo}/branch): Update a refs/heads branch against its expected old ID.
- [DELETE /v1/kits/{repo}/branch](/v1/kits/{repo}/branch): Delete a refs/heads branch against its expected old ID.
- [POST /v1/kits/{repo}/tags](/v1/kits/{repo}/tags): Create an immutable tag.
- [POST /v1/kits/{repo}/revert](/v1/kits/{repo}/revert): Revert a commit on a refs/heads branch; poll the job.
- [POST /v1/remix-preflight](/v1/remix-preflight): Read a source estimate without starting a remix or reserving storage.
- [POST /v1/remixes](/v1/remixes): Remix a published source into a private destination; poll the job.
- [POST /v1/kits/{repo}/commit](/v1/kits/{repo}/commit): Commit up to 1 MiB of decoded file bytes; larger uploads use the tar route POST /v1/uploads.
- [GET /v1/kits/{repo}/restore](/v1/kits/{repo}/restore): Restore a pinned revision with paged files, chunk layouts, and expiring direct download links.

## Legal terms

Terms: https://officialunofficial.com/legal/terms
Privacy: https://officialunofficial.com/legal/privacy
Current legal acceptance version: 2026-07-09