{"uid":"cap_BEMe8ygSOsU9Sdxm0_WIt","slug":"withzero-cdn-file-site-upload-477056b1","name":"WithZero CDN File & Site Upload","description":"Uploads a file to the CDN and returns a public URL.","url":"https://agents.withzero.xyz/api/v1/cdn/uploads?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["data"],"properties":{"ext":{"type":"string","maxLength":8,"minLength":1,"description":"Required only for kind:file with no slug; ignored otherwise."},"data":{"type":"string","minLength":1,"description":"Base64-encoded bytes. For kind:site, a zip of your static website (HTML/CSS/JS). For kind:file, the raw file bytes. Max 10 MiB after decode (same cap for kind:site decompressed total)."},"kind":{"enum":["file","site"],"type":"string","description":"\"site\" hosts a static website: data is a zip atomically deployed to your wallet folder under the slug prefix and served at /// — replaces any previous deploy at that prefix. \"file\" (default) uploads a single asset under your wallet folder."},"slug":{"type":"string","maxLength":512,"minLength":1,"description":"Custom path within your wallet folder. kind:site — the folder prefix the site is deployed under (e.g. \"my-site\" → served at //my-site/). kind:file — full filename including extension (e.g. \"logo.png\"). Re-uploads to the same slug overwrite; site re-deploys delete orphans from the previous deploy."},"password":{"type":"string","maxLength":256,"minLength":8,"description":"Sets or changes the site password (implies visibility:\"password\"). 8–256 chars. Omit to keep the current one."},"visibility":{"enum":["public","link","password"],"type":"string","description":"kind:site only. \"public\" (default for a new site): served at ///. \"link\": private — served only at an unguessable /p// URL returned as shareUrl; anyone holding it can view the site. \"password\": private behind a password; shareUrl is cdn.withzero.xyz/p//, a redirect to the private origin https://.private.withzero.xyz/ — browsers get a form, agents send Authorization: Basic with any username. Omit on a re-deploy to keep the current visibility. Private responses are never edge-cached."},"cacheTtlSeconds":{"type":"integer","maximum":9007199254740991,"description":"Edge cache lifetime (Cache-Control max-age) in seconds, applied to every object in this upload. Default 3600, clamped to [60, 86400]. Does not affect how long files are stored.","exclusiveMinimum":0}},"additionalProperties":false},"responseSchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["walletId","cacheTtlSeconds","files"],"properties":{"files":{"type":"array","items":{"type":"object","required":["url","path","sizeBytes"],"properties":{"url":{"type":"string","description":"Public URL this file is served from."},"path":{"type":"string","description":"Path within your wallet namespace (the part after /)."},"sizeBytes":{"type":"integer","maximum":9007199254740991,"minimum":-9007199254740991,"description":"Decoded file size in bytes."}},"additionalProperties":false},"description":"One entry per uploaded file. kind:file — a single entry. kind:site — one entry per file in the zip; the hosted site's entry point is ///, which serves /index.html."},"shareUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"kind:site with link or password visibility — the private URL to share. For a link site it is the whole credential; for a password site viewers also need the password."},"walletId":{"type":"string","description":"Random per-wallet base62 id used as the folder in the URL path (the in ///)."},"visibility":{"enum":["public","link","password"],"type":"string","description":"kind:site only — the site's visibility after this upload."},"cacheTtlSeconds":{"type":"integer","maximum":9007199254740991,"minimum":-9007199254740991,"description":"Resolved edge cache lifetime (Cache-Control max-age) applied to every uploaded object."}},"additionalProperties":false},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.000000","displayCostAsset":"USD","priceDynamic":false,"priceHint":null,"priceStatus":"unknown_unparsed","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"unknown","summary":"price unknown","primary":{"kind":"unknown","protocol":"x402","network":"base","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"unknown","protocol":"x402","network":"base","amountUsd":null,"per":"call","confidence":"unknown"},{"kind":"unknown","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_JN44-rTDHZPmd03H6U9hl","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null},{"uid":"pm_5T5UkM_vSeCZ3Lx7q7jon","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.000000","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Upload a single file or deploy a static website to a public CDN, returning public URLs under a per-wallet namespace","exampleAgentPrompt":"Upload this zip of my HTML/CSS/JS files as a static site with the slug 'my-portfolio' and cache it for 3600 seconds so it's publicly accessible on the web right away.","exampleUseCases":[{"title":"Deploy a static landing page","prompt":"I've got a zip of my product landing page (HTML, CSS, and JS). Deploy it as a static site under the slug 'launch-page' with a 1-hour cache so it's live on the web immediately."},{"title":"Publish a generated image file","prompt":"Take this base64-encoded PNG image and upload it as a file with the slug 'banner.png' so I can share a public URL for it — cache it for 24 hours."},{"title":"Update a deployed web app","prompt":"Here's a new zip of my updated portfolio site — redeploy it to the same slug 'portfolio' so the old version gets replaced and anyone visiting the URL sees the latest version."}],"resultDescription":"Returns the wallet ID (a stable per-wallet base62 identifier used as the folder in the URL path), the resolved cache TTL in seconds, and an array of file entries each containing the full public URL, the path within the wallet namespace, and the decoded file size in bytes. For a static site, one entry per file in the zip is returned.","failureModes":["Data exceeds 10 MiB decoded — request rejected with size error","Invalid base64 encoding in data field — parse error returned","kind:site zip decompressed total exceeds 10 MiB — rejected","slug contains invalid path characters — validation error","cacheTtlSeconds outside [60, 86400] range — clamped silently or rejected","Missing required 'data' field — 400 validation error","kind:file with no slug and no ext field — error or unpredictable filename"],"whenToPreferThis":"Choose this endpoint when you need to publish a file or static website to a public URL without setting up a vendor CDN account or API key. It is ideal for agents that generate HTML/CSS/JS sites, images, or other binary assets and need an immediate publicly accessible URL. It is preferable over object-storage services when you need edge caching and a stable wallet-namespaced URL. For site deployments, it atomically replaces the previous deploy at the same slug, making it suitable for continuous redeployment workflows.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":7,"lastUsedAt":"2026-08-22T16:36:39.657Z","lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-02T04:53:37.211Z","isFirstParty":true,"canonicalSlug":"withzero-cdn-file-site-upload-477056b1"}