{"components":{"parameters":{"IdempotencyKey":{"description":"Replays the first response for 24 h (keyed by caller). A different request under the same key is 422.","in":"header","name":"Idempotency-Key","schema":{"maxLength":128,"type":"string"}}},"responses":{"ErrorResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}},"description":"Error envelope (schemas §6.9); the status code is the error's HTTP status."}},"schemas":{"AccessToken":{"description":"A serving token. Append it as ?token= to the file's public_url or any render URL in its scope.","properties":{"expires_at":{"description":"Null = never expires.","format":"date-time","nullable":true,"type":"string"},"render_url_template":{"description":"path tokens: the render template with the token appended; fill {op}/{params}/{name}.","nullable":true,"type":"string"},"scope":{"properties":{"audiences":{"items":{"type":"string"},"type":"array"},"constraints":{"additionalProperties":{"type":"string"},"description":"Limits on renders: width \u003c=N, height \u003c=N, blur \u003e=N.","type":"object"},"path":{"description":"The one file the token opens, e.g. /photos/cat.png.","type":"string"},"prefix":{"description":"The folder the token opens, e.g. /photos; / = the whole app.","type":"string"}},"required":["audiences"],"type":"object"},"token":{"type":"string"},"url":{"description":"path tokens: the file's URL with the token appended.","nullable":true,"type":"string"}},"required":["token","expires_at","scope"],"type":"object"},"Action":{"description":"One next step. Switch on id (stable); title may change. An HTTP step has method + href (or template); a step on the developer's machine has local instead.","properties":{"after_seconds":{"description":"Wait this long first.","type":"integer"},"audience":{"description":"human: relay to the person (the agent cannot do it). Omitted = agent.","enum":["agent","human"],"type":"string"},"body":{"additionalProperties":true,"description":"Example request body.","type":"object"},"docs":{"type":"string"},"examples":{"additionalProperties":{"type":"string"},"description":"image.render: operation (fill, fit, crop, convert) → ready URL.","type":"object"},"headers":{"additionalProperties":{"type":"string"},"type":"object"},"href":{"description":"Fully resolved URL.","type":"string"},"id":{"enum":["trial.create","key.store","agent.login","account.claim","docs.open","upload.create","upload.put","upload.poll","upload.get","upload.abort","upload.list","file.get","file.list","file.serve","file.delete","image.render","access.token","usage.get","quota.warning","quota.upgrade","retry","job.poll"],"type":"string"},"local":{"$ref":"#/components/schemas/LocalStep"},"method":{"type":"string"},"recommended":{"description":"The step to take now; at most one per list.","type":"boolean"},"remind_every_seconds":{"description":"quota.warning: tell the human at most this often.","type":"integer"},"template":{"description":"URL with {placeholders} to fill.","type":"string"},"title":{"type":"string"}},"required":["id","title"],"type":"object"},"AdminUser":{"description":"A user as the staff console lists it (Admin operations only).","properties":{"apps":{"description":"Live applications.","type":"integer"},"created_at":{"format":"date-time","type":"string"},"email":{"description":"Null until claimed.","nullable":true,"type":"string"},"is_staff":{"type":"boolean"},"last_activity_at":{"format":"date-time","nullable":true,"type":"string"},"staff_by":{"description":"Who granted it: user:\u003cuser_id\u003e of the staff member, or seed:AMPS_STAFF_EMAIL; null when not staff.","nullable":true,"type":"string"},"staff_since":{"description":"When the staff role was granted; null when not staff.","format":"date-time","nullable":true,"type":"string"},"status":{"enum":["trial","active","suspended","deleting","deleted"],"type":"string"},"suspended_reason":{"nullable":true,"type":"string"},"user_id":{"type":"string"}},"required":["user_id","email","status","is_staff","created_at","last_activity_at","suspended_reason","apps"],"type":"object"},"AdminUserList":{"properties":{"next_cursor":{"nullable":true,"type":"string"},"users":{"items":{"$ref":"#/components/schemas/AdminUser"},"type":"array"}},"required":["users","next_cursor"],"type":"object"},"AdminUserView":{"description":"One user for the staff console: the user, plan and serving state, apps and current-window usage.","properties":{"apps":{"items":{"$ref":"#/components/schemas/App"},"type":"array"},"compensations":{"description":"Provider actions billing owed this user: a second subscription that went live while the first ran is canceled at the provider (retried by billing-sync until done); its charge is refunded by hand.","items":{"$ref":"#/components/schemas/Compensation"},"type":"array"},"limit_overrides":{"items":{"$ref":"#/components/schemas/LimitOverride"},"type":"array"},"max_apps":{"type":"integer"},"plan":{"type":"string"},"serving":{"$ref":"#/components/schemas/Serving"},"subscription":{"$ref":"#/components/schemas/Subscription"},"trial_source":{"$ref":"#/components/schemas/TrialSource"},"usage":{"$ref":"#/components/schemas/Usage"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["user","plan","max_apps","serving","apps","usage","limit_overrides"],"type":"object"},"AgentLoginDecision":{"properties":{"app_id":{"description":"approve: the app the key is for.","type":"string"},"approve":{"type":"boolean"},"user_code":{"maxLength":16,"type":"string"}},"required":["user_code","approve"],"type":"object"},"AgentLoginStarted":{"properties":{"device_code":{"description":"The agent's secret for polling; never show it to the person.","type":"string"},"expires_in":{"description":"Seconds.","type":"integer"},"interval":{"description":"Seconds between polls of POST /agent/login/token.","type":"integer"},"user_code":{"description":"XXXX-XXXX: the person checks it on the approval page.","type":"string"},"verification_url":{"description":"Give it to the person: {console}/link?code=XXXX-XXXX.","type":"string"}},"required":["device_code","user_code","verification_url","expires_in","interval"],"type":"object"},"AgentLoginTokenRequest":{"properties":{"device_code":{"maxLength":128,"type":"string"}},"required":["device_code"],"type":"object"},"ApiKey":{"description":"A key as listed: the displayed prefix, never the secret.","properties":{"app_id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"grace_until":{"description":"Set on a key rotated out: it still works until then. Null for an active key.","format":"date-time","nullable":true,"type":"string"},"key_id":{"type":"string"},"label":{"type":"string"},"last_used_at":{"format":"date-time","nullable":true,"type":"string"},"prefix":{"description":"amps_live_ab12cd34: the first characters of the secret, to tell keys apart.","type":"string"}},"required":["key_id","app_id","prefix","label","created_at","last_used_at","grace_until"],"type":"object"},"App":{"properties":{"app_id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"is_default":{"type":"boolean"},"keys":{"type":"integer"},"name":{"type":"string"},"next":{"description":"What to do next (design/agent-hints.md). Omitted with Prefer: return=minimal.","items":{"$ref":"#/components/schemas/Action"},"type":"array"},"private":{"description":"A private app's files are served only with a serving token (GET /access/token); a public app's files are readable by URL. Chosen when the app is created and never changed.","type":"boolean"},"usage":{"additionalProperties":{"$ref":"#/components/schemas/AppMeterUsage"},"description":"GET /apps/{app_id} only: this app's share of the current window, the five cost meters (storage, cpu, bandwidth, ingress, invalidations).","type":"object"},"user_id":{"type":"string"},"webhook_secret":{"description":"Signs this app's webhooks (X-Amps-Signature, see POST /uploads callback_url). Present for the key's own app and for the owner's session; absent for sibling apps. Keep it on your server; rotate with POST /apps/{app_id}/webhook-secret/rotate.","type":"string"}},"required":["app_id","user_id","name","is_default","private","created_at","keys"],"type":"object"},"AppCreateRequest":{"properties":{"name":{"description":"Unique among your apps, case-insensitively.","maxLength":64,"minLength":1,"type":"string"},"private":{"default":false,"description":"true creates a private app: every file in it is served only with a serving token (GET /access/token). false (the default) creates a public app: its files are readable by URL. The choice is for the app's life; private apps need a claimed account.","type":"boolean"}},"required":["name"],"type":"object"},"AppCreated":{"properties":{"app":{"$ref":"#/components/schemas/App"},"key":{"$ref":"#/components/schemas/CreatedKey"},"next":{"description":"What to do next; the first step stores the key. Omitted with Prefer: return=minimal.","items":{"$ref":"#/components/schemas/Action"},"type":"array"}},"required":["app","key"],"type":"object"},"AppList":{"properties":{"apps":{"items":{"$ref":"#/components/schemas/App"},"type":"array"}},"required":["apps"],"type":"object"},"AppMeterUsage":{"description":"Per-app usage carries the five cost meters with used and unit only; limits and windows live on the user.","properties":{"reserved":{"description":"storage only","format":"int64","type":"integer"},"unit":{"type":"string"},"used":{"format":"int64","type":"integer"}},"required":["used","unit"],"type":"object"},"AppRequest":{"properties":{"name":{"description":"Unique among your apps, case-insensitively.","maxLength":64,"minLength":1,"type":"string"}},"required":["name"],"type":"object"},"AuditEntry":{"description":"One audit log entry (Admin operations only).","properties":{"action":{"type":"string"},"actor":{"description":"session:\u003cid\u003e, key:\u003cid\u003e, ops:\u003cwho\u003e, billing.sync or billing.webhook.","type":"string"},"app_id":{"nullable":true,"type":"string"},"at":{"format":"date-time","type":"string"},"detail":{"additionalProperties":{"type":"string"},"type":"object"},"id":{"type":"string"},"request_id":{"description":"The API request that wrote it; null outside a request (aggregator, ops).","nullable":true,"type":"string"},"user_id":{"description":"The user the action was about; null for actions on no one user (a search).","nullable":true,"type":"string"}},"required":["id","at","actor","user_id","app_id","action","request_id","detail"],"type":"object"},"AuditEntryList":{"properties":{"entries":{"items":{"$ref":"#/components/schemas/AuditEntry"},"type":"array"},"next_cursor":{"nullable":true,"type":"string"}},"required":["entries","next_cursor"],"type":"object"},"Capabilities":{"properties":{"capabilities":{"items":{"properties":{"id":{"description":"e.g. file.upload, image.manipulate, file.download, file.private.","type":"string"},"licensed":{"description":"The caller's plan grants it.","type":"boolean"},"meters":{"description":"The meters that bound it, as GET /usage names them.","items":{"type":"string"},"type":"array"}},"required":["id","licensed","meters"],"type":"object"},"type":"array"},"plan":{"$ref":"#/components/schemas/PlanTier"}},"required":["plan","capabilities"],"type":"object"},"ClaimCompleteRequest":{"properties":{"nonce":{"description":"The claim nonce of this browser (console cookie).","maxLength":128,"minLength":1,"type":"string"},"oauth":{"$ref":"#/components/schemas/OAuthCode"}},"required":["oauth","nonce"],"type":"object"},"ClaimCreated":{"properties":{"claim_url":{"description":"Give this URL to the person; it is shown once.","type":"string"},"expires_at":{"format":"date-time","type":"string"},"next":{"description":"What to do next, ordered; at most one is recommended (design/agent-hints.md). Omitted with Prefer: return=minimal.","items":{"$ref":"#/components/schemas/Action"},"type":"array"}},"required":["claim_url","expires_at"],"type":"object"},"ClaimRequest":{"properties":{"email":{"description":"Optional pre-fill for the claim page's form; never mailed.","format":"email","type":"string"}},"type":"object"},"ClaimStartRequest":{"properties":{"email":{"format":"email","type":"string"},"nonce_hash":{"description":"Hex SHA-256 of the browser's claim nonce.","pattern":"^[0-9a-f]{64}$","type":"string"}},"required":["email","nonce_hash"],"type":"object"},"ClaimState":{"description":"The caller's own claim: open (a claim URL is waiting, until expires_at) or claimed (by the masked address, at).","properties":{"at":{"format":"date-time","nullable":true,"type":"string"},"email":{"description":"claimed: the masked address, e.g. b***@x.com.","nullable":true,"type":"string"},"expires_at":{"format":"date-time","nullable":true,"type":"string"},"status":{"enum":["open","claimed"],"type":"string"}},"required":["status"],"type":"object"},"ClaimSummary":{"properties":{"apps":{"description":"Names of the trial's apps.","items":{"type":"string"},"type":"array"},"bytes":{"description":"Stored bytes.","format":"int64","type":"integer"},"created_at":{"description":"When the trial was created.","format":"date-time","type":"string"},"expires_at":{"description":"When the claim URL stops working.","format":"date-time","type":"string"},"files":{"description":"Number of files; null while no file count is kept.","format":"int64","nullable":true,"type":"integer"},"prefill_email":{"nullable":true,"type":"string"}},"required":["apps","files","bytes","created_at","expires_at"],"type":"object"},"Compensation":{"properties":{"attempts":{"description":"Failed cancel attempts so far.","type":"integer"},"created_at":{"format":"date-time","type":"string"},"done_at":{"description":"When the provider confirmed the cancel; null while billing still owes it.","format":"date-time","nullable":true,"type":"string"},"last_error":{"type":"string"},"reason":{"description":"duplicate_subscription: the second one was charged, refund by hand; duplicate_unpaid: it was unpaid, nothing to refund.","enum":["duplicate_subscription","duplicate_unpaid"],"type":"string"},"subscription_ref":{"description":"The provider's subscription that was (or is being) canceled.","type":"string"}},"required":["reason","subscription_ref","attempts","created_at"],"type":"object"},"CostLines":{"properties":{"cdn_egress":{"format":"int64","type":"integer"},"cdn_requests":{"format":"int64","type":"integer"},"origin_egress":{"format":"int64","type":"integer"},"overhead":{"format":"int64","type":"integer"},"payment_fee":{"format":"int64","type":"integer"},"renders":{"format":"int64","type":"integer"},"storage":{"format":"int64","type":"integer"}},"required":["storage","cdn_egress","cdn_requests","origin_egress","renders","payment_fee","overhead"],"type":"object"},"CreatedKey":{"properties":{"app_id":{"type":"string"},"key_id":{"type":"string"},"secret":{"type":"string"},"shown_once":{"type":"boolean"}},"required":["key_id","app_id","secret","shown_once"],"type":"object"},"DeleteAccountRequest":{"properties":{"confirm":{"description":"The account's user_id (GET /me), typed back.","type":"string"}},"required":["confirm"],"type":"object"},"DigestRequest":{"properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"type":"object"},"DownloadUrl":{"properties":{"expires_at":{"description":"When the token expires; null without a token or expiry.","format":"date-time","nullable":true,"type":"string"},"url":{"description":"The file's URL; a private file's carries ?token=.","type":"string"}},"required":["url","expires_at"],"type":"object"},"EmailRequest":{"properties":{"email":{"format":"email","type":"string"}},"required":["email"],"type":"object"},"Error":{"properties":{"code":{"enum":["quota_exhausted","rate_limited","feature_not_licensed","payment_required","unauthorized","forbidden","not_found","conflict","already_claimed","invalid_request","invalid_callback_url","idempotency_mismatch","payload_too_large","upstream_error","gone","length_required","client_closed","billing_unavailable","authorization_pending","slow_down","access_denied","expired_token","internal"],"type":"string"},"hint":{"description":"What to do next, when not obvious from the code. Storage quota with reserved bytes: list open uploads (GET /uploads), abort stuck ones (DELETE /uploads/{upload_id}).","type":"string"},"limit":{"format":"int64","type":"integer"},"message":{"type":"string"},"meter":{"type":"string"},"next":{"description":"What to do next, ordered; at most one is recommended (design/agent-hints.md). Omitted with Prefer: return=minimal.","items":{"$ref":"#/components/schemas/Action"},"type":"array"},"request_id":{"type":"string"},"reserved":{"description":"storage only: bytes held by open upload sessions (omitted when 0); the gate compares used + reserved with limit","format":"int64","type":"integer"},"retry_after":{"description":"Seconds, rate_limited only. A rate_limited error also names the limit it hit: meter (rate.requests per key, rate.upload / rate.token / rate.purge per app), limit and unit (e.g. 30 per minute).","nullable":true,"type":"integer"},"unit":{"type":"string"},"upgrade_url":{"type":"string"},"used":{"format":"int64","type":"integer"},"window":{"type":"string"}},"required":["code","message","request_id"],"type":"object"},"ErrorEnvelope":{"properties":{"error":{"$ref":"#/components/schemas/Error"}},"required":["error"],"type":"object"},"File":{"description":"A stored file, or a folder (type dir: size 0, empty mime_type and hash, null URLs).","properties":{"acl":{"enum":["public","private"],"type":"string"},"created_at":{"format":"date-time","type":"string"},"hash":{"type":"string"},"mime_type":{"type":"string"},"next":{"description":"What to do next, ordered; at most one is recommended (design/agent-hints.md). Omitted with Prefer: return=minimal.","items":{"$ref":"#/components/schemas/Action"},"type":"array"},"path":{"description":"Path in the app, rooted at /, e.g. /photos/cat.png (a folder: /photos).","type":"string"},"public_url":{"description":"Null for private files and folders.","nullable":true,"type":"string"},"render_url_template":{"description":"Serving URL plus /v1/{op}/{params}/{name}; copy it whole (it carries internal ids). Null for folders.","nullable":true,"type":"string"},"size":{"format":"int64","type":"integer"},"type":{"enum":["file","dir"],"type":"string"}},"required":["path","type","size","mime_type","acl","hash","created_at","public_url","render_url_template"],"type":"object"},"FileList":{"properties":{"files":{"items":{"$ref":"#/components/schemas/File"},"type":"array"},"next_cursor":{"description":"Pass as ?cursor= for the next page; null on the last page.","nullable":true,"type":"string"}},"required":["files","next_cursor"],"type":"object"},"FilesPurgeRequest":{"description":"Exactly one of paths or prefix.","properties":{"paths":{"description":"Files in the app, e.g. [\"/photos/cat.png\"].","items":{"maxLength":1024,"type":"string"},"maxItems":100,"type":"array"},"prefix":{"description":"Any folder of the app, / included: purges every cached copy of the application.","maxLength":1024,"type":"string"}},"type":"object"},"Invoice":{"description":"One of the payment provider's invoices (schemas §6.8a).","properties":{"amount_minor":{"format":"int64","type":"integer"},"currency":{"type":"string"},"hosted_url":{"description":"The provider's page for the invoice.","type":"string"},"invoice_id":{"type":"string"},"number":{"type":"string"},"period_end":{"format":"date-time","type":"string"},"period_start":{"format":"date-time","type":"string"},"status":{"enum":["draft","open","paid","void","uncollectible"],"type":"string"}},"required":["invoice_id","number","period_start","period_end","amount_minor","currency","status","hosted_url"],"type":"object"},"InvoiceList":{"properties":{"invoices":{"items":{"$ref":"#/components/schemas/Invoice"},"type":"array"},"next_cursor":{"nullable":true,"type":"string"}},"required":["invoices","next_cursor"],"type":"object"},"Job":{"description":"An asynchronous operation (schemas §6.7a). The webhook body for job.done / job.failed is this object without next.","properties":{"app_id":{"type":"string"},"callback":{"description":"Null without callback_url. The last webhook attempt once one was made.","nullable":true,"properties":{"attempts":{"type":"integer"},"delivered_at":{"format":"date-time","nullable":true,"type":"string"},"last_error":{"nullable":true,"type":"string"},"last_status":{"nullable":true,"type":"integer"},"url":{"type":"string"}},"required":["url","attempts","last_status","last_error","delivered_at"],"type":"object"},"created_at":{"format":"date-time","type":"string"},"error":{"description":"Why it failed (status failed), else null.","nullable":true,"type":"string"},"job_id":{"type":"string"},"next":{"description":"What to do next (poll again, or move on). Omitted with Prefer: return=minimal.","items":{"$ref":"#/components/schemas/Action"},"type":"array"},"progress":{"format":"float","type":"number"},"status":{"enum":["queued","running","done","failed"],"type":"string"},"type":{"enum":["app.delete","user.delete","tree.delete","cdn.purge"],"type":"string"},"updated_at":{"format":"date-time","type":"string"}},"required":["job_id","type","app_id","status","progress","error","created_at","updated_at","callback"],"type":"object"},"JobList":{"properties":{"jobs":{"items":{"$ref":"#/components/schemas/Job"},"type":"array"},"next_cursor":{"nullable":true,"type":"string"}},"required":["jobs","next_cursor"],"type":"object"},"KeyList":{"properties":{"keys":{"items":{"$ref":"#/components/schemas/ApiKey"},"type":"array"}},"required":["keys"],"type":"object"},"KeyRequest":{"properties":{"label":{"description":"Free text to tell keys apart (ci, laptop, prod).","maxLength":64,"type":"string"}},"type":"object"},"LedgerCDNHour":{"properties":{"app_id":{"type":"string"},"bytes":{"format":"int64","type":"integer"},"hit_bytes":{"format":"int64","type":"integer"},"hits":{"format":"int64","type":"integer"},"hour":{"format":"date-time","type":"string"},"miss_bytes":{"format":"int64","type":"integer"},"misses":{"format":"int64","type":"integer"},"status_2xx":{"format":"int64","type":"integer"},"status_4xx":{"format":"int64","type":"integer"}},"required":["hour","app_id","bytes","hit_bytes","miss_bytes","hits","misses","status_2xx","status_4xx"],"type":"object"},"LedgerDay":{"properties":{"cdn":{"items":{"$ref":"#/components/schemas/LedgerCDNHour"},"type":"array"},"from":{"format":"date-time","type":"string"},"next_cursor":{"description":"The month's next day, YYYY-MM-DD; null after its last.","nullable":true,"type":"string"},"to":{"format":"date-time","type":"string"},"usage":{"items":{"$ref":"#/components/schemas/LedgerUsageHour"},"type":"array"},"window":{"type":"string"}},"required":["window","from","to","usage","cdn","next_cursor"],"type":"object"},"LedgerUsageHour":{"properties":{"app_id":{"description":"Empty for a row of the user as a whole.","type":"string"},"delta":{"format":"int64","type":"integer"},"hour":{"format":"date-time","type":"string"},"meter":{"type":"string"},"window":{"description":"The month, or standing for storage.","type":"string"}},"required":["hour","app_id","meter","window","delta"],"type":"object"},"LimitOverride":{"properties":{"actor":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"limit":{"format":"int64","type":"integer"},"meter":{"type":"string"},"permanent":{"type":"boolean"},"reason":{"type":"string"},"until":{"description":"When a window override lapses; null when permanent.","format":"date-time","nullable":true,"type":"string"}},"required":["meter","limit","permanent","until","reason","actor","created_at"],"type":"object"},"LimitRequest":{"properties":{"limit":{"description":"The new limit in the meter's unit (bytes for storage, bandwidth and ingress; renders for cpu; a count otherwise).","format":"int64","minimum":1,"type":"integer"},"permanent":{"description":"True: until cleared. False or omitted: the current usage window only.","type":"boolean"},"reason":{"description":"Why; written to the audit log.","maxLength":500,"minLength":1,"type":"string"}},"required":["limit","reason"],"type":"object"},"LiveCounters":{"properties":{"apps":{"additionalProperties":{"additionalProperties":{"$ref":"#/components/schemas/LiveMeter"},"type":"object"},"type":"object"},"meters":{"additionalProperties":{"$ref":"#/components/schemas/LiveMeter"},"type":"object"},"serving":{"$ref":"#/components/schemas/Serving"},"uploads":{"items":{"$ref":"#/components/schemas/UploadStatus"},"type":"array"},"window":{"type":"string"}},"required":["window","meters","apps","serving","uploads"],"type":"object"},"LiveMeter":{"properties":{"reserved":{"description":"storage: bytes held by open upload sessions; 0 for the others","format":"int64","type":"integer"},"used":{"format":"int64","type":"integer"}},"required":["used","reserved"],"type":"object"},"LocalStep":{"description":"A step on the developer's machine: write content to a file with mode (`~` is the home directory); gitignore true = also git-ignore its folder (a project file).","properties":{"content":{"type":"string"},"gitignore":{"type":"boolean"},"mode":{"type":"string"},"write":{"type":"string"}},"required":["write","content"],"type":"object"},"ManageLink":{"properties":{"url":{"type":"string"}},"required":["url"],"type":"object"},"MeterUsage":{"properties":{"limit":{"format":"int64","nullable":true,"type":"integer"},"reserved":{"description":"storage only: bytes held by open upload sessions; the gate compares used + reserved","format":"int64","type":"integer"},"unit":{"type":"string"},"used":{"format":"int64","type":"integer"},"window":{"type":"string"}},"required":["used","limit","unit","window"],"type":"object"},"OAuthCode":{"properties":{"code":{"description":"The provider's authorization code, from the console's callback.","type":"string"},"provider":{"enum":["google"],"type":"string"}},"required":["provider","code"],"type":"object"},"Pending":{"properties":{"status":{"enum":["pending"],"type":"string"}},"required":["status"],"type":"object"},"Plan":{"description":"A plan: its fixed price per period, its limits and what it allows (schemas §6.8). Usage never changes the price; it only meets these limits.","properties":{"capabilities":{"description":"What the plan allows, e.g. file.upload, image.manipulate, file.download, file.private (private files).","items":{"type":"string"},"type":"array"},"id":{"$ref":"#/components/schemas/PlanTier"},"limits":{"$ref":"#/components/schemas/PlanLimits"},"max_apps":{"type":"integer"},"price":{"$ref":"#/components/schemas/PlanPrice"},"upgrade_url":{"description":"The console's Plans page, where the person compares and changes plans.","type":"string"}},"required":["id","price","max_apps","capabilities","limits","upgrade_url"],"type":"object"},"PlanChange":{"description":"checkout_url when payment is needed (open it in a browser; the plan changes when the payment completes); confirm_url when an API key asked to change a paid plan (nothing changed: the person confirms it in the console, since the price changes); else the subscription as changed.","properties":{"checkout_url":{"type":"string"},"confirm_url":{"description":"The console's Plans page with the plan asked for; give it to the person.","type":"string"},"subscription":{"$ref":"#/components/schemas/Subscription"}},"type":"object"},"PlanLimits":{"description":"The plan's own limits (a staff override may change one user's). Bytes for storage, bandwidth and ingress; storage is standing, the rest per calendar month (UTC).","properties":{"bandwidth":{"format":"int64","type":"integer"},"concurrent_uploads":{"type":"integer"},"cpu":{"description":"Image renders per month.","format":"int64","type":"integer"},"ingress":{"description":"Null: uploads are not capped by volume.","format":"int64","nullable":true,"type":"integer"},"invalidations":{"format":"int64","type":"integer"},"rate.jobs_poll":{"$ref":"#/components/schemas/PlanRate"},"rate.purge":{"$ref":"#/components/schemas/PlanRate"},"rate.requests":{"$ref":"#/components/schemas/PlanRate"},"rate.token":{"$ref":"#/components/schemas/PlanRate"},"rate.upload":{"$ref":"#/components/schemas/PlanRate"},"storage":{"format":"int64","type":"integer"}},"required":["storage","cpu","bandwidth","ingress","invalidations","concurrent_uploads","rate.requests","rate.jobs_poll","rate.upload","rate.token","rate.purge"],"type":"object"},"PlanList":{"description":"GET /plans: every plan, cheapest first (schemas §6.8).","properties":{"payments_enabled":{"description":"False where payments are off: the plans apply (staff grants), but POST /upgrade answers 503 billing_unavailable.","type":"boolean"},"plans":{"items":{"$ref":"#/components/schemas/Plan"},"type":"array"}},"required":["plans","payments_enabled"],"type":"object"},"PlanMove":{"description":"current: the plan in force (409 if asked). upgrade: a higher price, at once and prorated with a paid subscription, else a checkout. downgrade: a lower price, at current_period_end (a paid subscription only). cancel: trial from a paid plan, the cancel (at current_period_end; unpaid: at once). none: refused from here (payments off, past_due or unpaid: pay first, trial without a paid plan, or a plan a complimentary plan already covers: 409).","enum":["current","upgrade","downgrade","cancel","none"],"type":"string"},"PlanOption":{"description":"One plan as the account may choose it (POST /upgrade {plan}).","properties":{"checkout":{"description":"The move answers checkout_url: a new paid subscription, paid on the provider's page (no paid subscription yet).","type":"boolean"},"move":{"$ref":"#/components/schemas/PlanMove"},"plan":{"$ref":"#/components/schemas/PlanTier"},"scheduled":{"description":"A scheduled downgrade or cancel moves the subscription to this plan at current_period_end.","type":"boolean"}},"required":["plan","move","checkout","scheduled"],"type":"object"},"PlanPrice":{"properties":{"amount_minor":{"description":"Minor units (cents); 0 for trial.","format":"int64","type":"integer"},"currency":{"type":"string"},"period":{"enum":["month"],"type":"string"}},"required":["amount_minor","currency","period"],"type":"object"},"PlanRate":{"description":"A rate limit: per_sec or per_min requests, with a burst.","properties":{"burst":{"type":"integer"},"per_min":{"type":"integer"},"per_sec":{"type":"integer"}},"required":["burst"],"type":"object"},"PlanRequest":{"properties":{"plan":{"$ref":"#/components/schemas/PlanTier"},"reason":{"description":"Why; written to the audit log and kept on the grant.","maxLength":500,"minLength":1,"type":"string"}},"required":["plan","reason"],"type":"object"},"PlanTier":{"enum":["trial","starter","pro","business"],"type":"string"},"PurgeAccepted":{"properties":{"job_id":{"description":"The cdn.purge job.","type":"string"}},"required":["job_id"],"type":"object"},"PurgeRequest":{"properties":{"app_id":{"description":"Purge this application's objects only; omit for the whole user.","type":"string"},"reason":{"description":"Why; written to the audit log.","maxLength":500,"minLength":1,"type":"string"}},"required":["reason"],"type":"object"},"RotateKeyRequest":{"properties":{"grace_seconds":{"default":3600,"description":"How long the old key keeps working; 0 = stops now.","maximum":604800,"minimum":0,"type":"integer"}},"type":"object"},"Serving":{"properties":{"reason":{"nullable":true,"type":"string"},"since":{"format":"date-time","nullable":true,"type":"string"},"state":{"enum":["allow","suspended"],"type":"string"}},"required":["state","reason","since"],"type":"object"},"SessionInfo":{"properties":{"expires_at":{"format":"date-time","type":"string"},"kind":{"enum":["user","staff"],"type":"string"},"token":{"description":"amps_sess_… bearer (Authorization: Bearer); the API sets no cookie.","type":"string"}},"required":["token","kind","expires_at"],"type":"object"},"SessionRequest":{"properties":{"code":{"description":"Magic-link code.","type":"string"},"nonce":{"description":"The claim nonce of the browser that started a claim (console cookie). A claim link completes only with it; otherwise 409.","maxLength":128,"type":"string"},"oauth":{"$ref":"#/components/schemas/OAuthCode"}},"type":"object"},"SessionResult":{"properties":{"app":{"$ref":"#/components/schemas/App"},"key":{"$ref":"#/components/schemas/CreatedKey"},"session":{"$ref":"#/components/schemas/SessionInfo"},"user":{"$ref":"#/components/schemas/User"}},"required":["session","user"],"type":"object"},"SnapshotCost":{"description":"What serving the user for the month cost AMPS, from design/plan-economics.md §2 (planning numbers, not a bill), in the month's currency, minor units.","properties":{"cost_minor":{"description":"The sum of the lines.","format":"int64","type":"integer"},"lines":{"$ref":"#/components/schemas/CostLines"},"margin_minor":{"description":"price_minor less cost_minor; negative when the user cost more than it paid.","format":"int64","type":"integer"}},"required":["cost_minor","margin_minor","lines"],"type":"object"},"SnapshotMeter":{"properties":{"limit":{"description":"The limit in force at the month's end; null = none.","format":"int64","nullable":true,"type":"integer"},"unit":{"type":"string"},"used":{"format":"int64","type":"integer"}},"required":["used","limit","unit"],"type":"object"},"StaffRequest":{"properties":{"is_staff":{"type":"boolean"},"reason":{"description":"Why; written to the audit log.","maxLength":500,"minLength":1,"type":"string"}},"required":["is_staff","reason"],"type":"object"},"StaffUsageHistory":{"properties":{"next_cursor":{"nullable":true,"type":"string"},"snapshots":{"items":{"$ref":"#/components/schemas/StaffUsageSnapshot"},"type":"array"}},"required":["snapshots","next_cursor"],"type":"object"},"StaffUsageSnapshot":{"description":"A month with what it cost AMPS (staff only).","properties":{"cost":{"$ref":"#/components/schemas/SnapshotCost"},"snapshot":{"$ref":"#/components/schemas/UsageSnapshot"}},"required":["snapshot","cost"],"type":"object"},"Subscription":{"description":"The plan in force and its payment (schemas §6.8b). No subscription: plan trial, status active, provider null. paying, can_cancel, can_resume and plan_options are what the account may do from here, by billing's rule: read them instead of deciding from status and prices.","properties":{"can_cancel":{"description":"DELETE /subscription is accepted (a paid or unpaid subscription; payments on).","type":"boolean"},"can_resume":{"description":"POST /subscription/resume is accepted (a cancel or a downgrade is scheduled).","type":"boolean"},"cancel_at_period_end":{"type":"boolean"},"currency":{"type":"string"},"current_period_end":{"description":"When the next renewal, a scheduled downgrade or a cancel applies; null without a paid subscription.","format":"date-time","nullable":true,"type":"string"},"current_period_start":{"format":"date-time","nullable":true,"type":"string"},"paying":{"description":"A paid subscription that has not ended (active or past_due). False for a trial, a complimentary plan, unpaid and canceled.","type":"boolean"},"pending_plan":{"description":"A downgrade that applies at current_period_end.","nullable":true,"type":"string"},"plan":{"$ref":"#/components/schemas/PlanTier"},"plan_options":{"description":"Every plan of GET /plans, in its order: what POST /upgrade does with it from this subscription.","items":{"$ref":"#/components/schemas/PlanOption"},"type":"array"},"price_minor":{"description":"The fixed price per period in minor units; 0 for trial and complimentary plans.","format":"int64","type":"integer"},"provider":{"description":"complimentary, or the payment provider (stripe; mockpay in test); null for a trial.","nullable":true,"type":"string"},"status":{"description":"past_due: a renewal failed and is being retried (plan and serving unchanged); unpaid: the retries stopped, trial limits until the open invoice is paid (POST /billing/manage), which brings the plan back; canceled: ended, trial limits.","enum":["active","past_due","unpaid","canceled","incomplete"],"type":"string"}},"required":["plan","status","price_minor","currency","current_period_start","current_period_end","cancel_at_period_end","pending_plan","provider","paying","can_cancel","can_resume","plan_options"],"type":"object"},"SubscriptionResult":{"properties":{"subscription":{"$ref":"#/components/schemas/Subscription"}},"required":["subscription"],"type":"object"},"SuspendRequest":{"properties":{"reason":{"description":"Why; written to the audit log, never sent to the user.","maxLength":500,"minLength":1,"type":"string"}},"required":["reason"],"type":"object"},"TrialCreated":{"properties":{"app":{"$ref":"#/components/schemas/App"},"key":{"$ref":"#/components/schemas/CreatedKey"},"next":{"description":"What to do next, ordered; at most one is recommended (design/agent-hints.md). Omitted with Prefer: return=minimal.","items":{"$ref":"#/components/schemas/Action"},"type":"array"},"user":{"$ref":"#/components/schemas/User"}},"required":["user","app","key"],"type":"object"},"TrialSource":{"description":"Where the account was created as a trial (staff only): personal data.","properties":{"fingerprint":{"description":"The server-side fingerprint of POST /trial (User-Agent, Accept-Language, the IP's /24 or /48).","type":"string"},"ip":{"description":"The client IP of POST /trial.","type":"string"}},"type":"object"},"UnsubscribeRequest":{"properties":{"token":{"maxLength":64,"type":"string"},"user_id":{"maxLength":64,"type":"string"}},"required":["user_id","token"],"type":"object"},"UnsuspendRequest":{"properties":{"reason":{"description":"Why; written to the audit log.","maxLength":500,"minLength":1,"type":"string"}},"required":["reason"],"type":"object"},"UpgradeRequest":{"properties":{"plan":{"$ref":"#/components/schemas/PlanTier"}},"required":["plan"],"type":"object"},"UploadList":{"properties":{"uploads":{"items":{"$ref":"#/components/schemas/UploadStatus"},"type":"array"}},"required":["uploads"],"type":"object"},"UploadRequest":{"properties":{"acl":{"description":"Optional: a file's privacy is its application's (POST /apps private). Leave it out; if sent it must be the application's (private in a private application, public in a public one), else 400. private from a trial is 402 feature_not_licensed.","enum":["public","private"],"type":"string"},"callback_url":{"description":"Optional webhook: AMPS will POST upload.completed / upload.expired (signed, system/api/contract.md §10) from the aggregator (Pub/Sub, up to 8 attempts, 10 s–10 min backoff; built 2026-10-21). https and a public DNS name; otherwise 400 invalid_callback_url. Without it, poll GET /uploads/{upload_id}.","maxLength":2048,"type":"string"},"mime_type":{"default":"application/octet-stream","type":"string"},"path":{"description":"Path in the app, e.g. /photos/cat.png (the leading / is optional; folders are created implicitly).","maxLength":1024,"type":"string"},"protocol":{"default":"put","description":"put: one PUT of the whole body to upload_url. tus: TUS 1.0.0 (core, creation, termination) on the same upload_url, resumable: PATCH chunks of at most 64 MiB, each but the last a multiple of 256 KiB; HEAD gives the offset to resume from.","enum":["put","tus"],"type":"string"},"size":{"description":"Declared size in bytes; binding.","format":"int64","minimum":1,"type":"integer"}},"required":["path","size"],"type":"object"},"UploadSession":{"properties":{"expires_at":{"format":"date-time","type":"string"},"next":{"description":"What to do next, ordered; at most one is recommended (design/agent-hints.md). Omitted with Prefer: return=minimal.","items":{"$ref":"#/components/schemas/Action"},"type":"array"},"path":{"description":"Path in the app, rooted at /, e.g. /photos/cat.png.","type":"string"},"protocol":{"enum":["put","tus"],"type":"string"},"reserved_bytes":{"format":"int64","type":"integer"},"upload_id":{"type":"string"},"upload_url":{"description":"On the Upload Proxy; the URL is the capability. put: PUT the bytes here. tus: the TUS upload URL (POST here for creation, or PATCH from offset 0 at once).","type":"string"}},"required":["upload_id","upload_url","protocol","expires_at","path","reserved_bytes"],"type":"object"},"UploadStatus":{"properties":{"acl":{"enum":["public","private"],"type":"string"},"app_id":{"type":"string"},"callback_url":{"nullable":true,"type":"string"},"created_at":{"format":"date-time","type":"string"},"expires_at":{"format":"date-time","type":"string"},"file":{"$ref":"#/components/schemas/File"},"mime_type":{"description":"The session's upload parameters, as POST /uploads received them.","type":"string"},"next":{"description":"What to do next, ordered; at most one is recommended (design/agent-hints.md). Omitted with Prefer: return=minimal.","items":{"$ref":"#/components/schemas/Action"},"type":"array"},"path":{"description":"Path in the app, rooted at /, e.g. /photos/cat.png.","type":"string"},"protocol":{"enum":["put","tus"],"type":"string"},"received_bytes":{"description":"Bytes WixMP confirmed stored.","format":"int64","type":"integer"},"reserved_bytes":{"description":"Declared size; held against the storage quota while open.","format":"int64","type":"integer"},"status":{"enum":["open","completed","expired","aborted"],"type":"string"},"streamed_at":{"description":"When the full declared size was last streamed to storage (null = not yet).","format":"date-time","nullable":true,"type":"string"},"stuck":{"description":"Open sessions only: true when the session will not complete on its own (past expires_at, or its full size was streamed more than 2 minutes ago without completing). Repeat the same POST /uploads first (a file that landed is settled); abort with DELETE /uploads/{upload_id} only to start over.","type":"boolean"},"upload_id":{"type":"string"}},"required":["upload_id","app_id","path","status","reserved_bytes","received_bytes","created_at","expires_at","stuck","streamed_at","callback_url"],"type":"object"},"Usage":{"properties":{"apps":{"additionalProperties":{"additionalProperties":{"$ref":"#/components/schemas/AppMeterUsage"},"type":"object"},"description":"A live answer lists every app with all five cost meters (storage, cpu, bandwidth, ingress, invalidations). A frozen answer lists none: the month's record keeps the account's totals, not each app's.","type":"object"},"frozen":{"description":"True when the numbers are the month's frozen record (its usage snapshot, written once just after the month ended) and not live counters: every window older than the previous month that has a record. A frozen answer never changes.","type":"boolean"},"frozen_at":{"description":"When the month's record was written; only in a frozen answer.","format":"date-time","type":"string"},"meters":{"additionalProperties":{"$ref":"#/components/schemas/MeterUsage"},"description":"A live answer has the five cost meters and apps. A frozen one has the five cost meters only, each with the month as its window: used is the month's total (storage: the bytes stored at the month's end), limit the one in force at the month's end.","type":"object"},"resets_at":{"format":"date-time","type":"string"},"serving":{"$ref":"#/components/schemas/Serving"},"window":{"type":"string"}},"required":["window","resets_at","serving","meters","apps","frozen"],"type":"object"},"UsageHistory":{"properties":{"next_cursor":{"nullable":true,"type":"string"},"snapshots":{"items":{"$ref":"#/components/schemas/UsageSnapshot"},"type":"array"}},"required":["snapshots","next_cursor"],"type":"object"},"UsageSnapshot":{"description":"One closed month (schemas §6.8a'), written once at the month's end from the ledger; a CloudFront log that lands later corrects the ledger, never the month.","properties":{"created_at":{"format":"date-time","type":"string"},"currency":{"type":"string"},"meters":{"additionalProperties":{"$ref":"#/components/schemas/SnapshotMeter"},"description":"The five cost meters (storage, cpu, bandwidth, ingress, invalidations). storage.used is the bytes stored at the month's end.","type":"object"},"plan":{"$ref":"#/components/schemas/PlanTier"},"price_minor":{"description":"What the plan charged for the month: 0 on trial and on a complimentary plan.","format":"int64","type":"integer"},"storage_average":{"description":"Bytes stored, averaged over the month's hours.","format":"int64","type":"integer"},"window":{"YYYY-MM.":null,"description":"The month","type":"string"}},"required":["window","plan","price_minor","currency","meters","storage_average","created_at"],"type":"object"},"User":{"properties":{"apps":{"type":"integer"},"claim":{"$ref":"#/components/schemas/ClaimState"},"created_at":{"format":"date-time","type":"string"},"digest_enabled":{"description":"Claimed accounts: the weekly usage digest mail is on (PUT /account/digest).","type":"boolean"},"email":{"nullable":true,"type":"string"},"email_verified_at":{"format":"date-time","nullable":true,"type":"string"},"max_apps":{"type":"integer"},"plan":{"type":"string"},"serving":{"$ref":"#/components/schemas/Serving"},"status":{"enum":["trial","active","suspended","deleting","deleted"],"type":"string"},"user_id":{"type":"string"}},"required":["user_id","status","email","email_verified_at","plan","created_at","apps","max_apps","serving"],"type":"object"},"WebhookSecret":{"properties":{"webhook_secret":{"type":"string"}},"required":["webhook_secret"],"type":"object"}},"securitySchemes":{"BearerAuth":{"description":"`Authorization: Bearer \u003cAPI key\u003e` (`amps_live_…`) or a session token (`amps_sess_…`).","scheme":"bearer","type":"http"}}},"info":{"description":"Agent-first Media Processing and Storage.\nAuthenticate with `Authorization: Bearer \u003cAPI key\u003e` (`amps_live_…`) or a session token (`amps_sess_…`).\nErrors use one envelope (`Error`).\nRetries are safe: `POST /uploads` is idempotent by path (repeat it and you get the same open session back);\nother authenticated POST and DELETE calls accept `Idempotency-Key` (24 h replay, a reused key with a different\nrequest is `422 idempotency_mismatch`), except the calls that mint a secret (`POST /apps`, `POST /apps/{id}/keys`,\n`POST /apps/{id}/keys/{kid}/rotate`, `POST /apps/{id}/webhook-secret/rotate`): the header is ignored there and a\nrepeat is a new mint.\n","title":"AMPS API","version":"0.1.0"},"openapi":"3.0.3","paths":{"/access/token":{"get":{"description":"Mint a token your server appends to the URLs of a private application's files as ?token= (the file, and every render of it). Scope it to one path, a folder prefix, or the whole app (prefix=/). Mint on your server, never in a browser: the API key must not reach clients. Tokens are signed and cannot be revoked before they expire, so cache one per folder with a long ttl for ordinary private content, and use a short ttl only for sensitive links, minting the next token before the last expires: an expired token answers 403. Trials have no private files (402 feature_not_licensed).","operationId":"GetAccessToken","parameters":[{"description":"One file, e.g. /photos/cat.png. Pass path or prefix, not both.","in":"query","name":"path","schema":{"maxLength":1024,"type":"string"}},{"description":"A folder, e.g. /photos (every file under it); / = the whole app.","in":"query","name":"prefix","schema":{"maxLength":1024,"type":"string"}},{"description":"Seconds until it expires; 0 = never. Default one year.","in":"query","name":"ttl","schema":{"default":31536000,"maximum":315360000,"minimum":0,"type":"integer"}},{"description":"What the token allows, comma-separated: file.download (the file itself), image.operations (renders). Default both.","explode":false,"in":"query","name":"audiences","schema":{"items":{"enum":["file.download","image.operations"],"type":"string"},"type":"array"},"style":"form"},{"description":"Renders at most this wide (px); 0 = no limit.","in":"query","name":"max_width","schema":{"minimum":0,"type":"integer"}},{"description":"Renders at most this tall (px); 0 = no limit.","in":"query","name":"max_height","schema":{"minimum":0,"type":"integer"}},{"description":"Renders must blur at least this much (blur_N), e.g. for previews; 0 = no requirement.","in":"query","name":"blur_min","schema":{"minimum":0,"type":"integer"}},{"description":"Download file name (Content-Disposition).","in":"query","name":"filename","schema":{"maxLength":255,"type":"string"}},{"description":"With filename: display inline instead of downloading.","in":"query","name":"inline","schema":{"type":"boolean"}},{"description":"Required with a session; a key may only name its own app.","in":"query","name":"app_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessToken"}}},"description":"The token and what it allows."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Get a serving token for private files","tags":["Access"]}},"/account/claim":{"post":{"description":"Get a claim URL to give the person: they open it in a browser, prove their e-mail there, and the trial becomes their account (same user, keys keep working). Valid 24 h, single use; a new call replaces the open URL. Nothing is mailed, so do not ask the person for an e-mail; `email` only pre-fills the page. Trial key only; 409 already_claimed if the trial already has an owner (409 conflict if it is suspended). GET /me then shows `claim`.","operationId":"ClaimAccount","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimRequest"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimCreated"}}},"description":"The claim URL (the token in it is shown once)."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Get a claim URL for this trial","tags":["Account"]}},"/account/digest":{"put":{"description":"For the console's Account page: the weekly usage mail (Mondays, meters at 50 % or more). Session only. The 85 % and 100 % limit mails cannot be turned off.","operationId":"SetDigest","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DigestRequest"}}},"required":true},"responses":{"204":{"description":"Saved."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Turn the weekly usage digest on or off","tags":["Account"]}},"/admin/audit":{"get":{"description":"Staff session only. Entries matching every given filter, newest first, paginated; no filter lists the whole log. actor, action and user_id are exact matches and combine freely (each combination has its Datastore index); from keeps entries at or after that time. A from that is neither RFC 3339 nor a YYYY-MM-DD date (UTC midnight) is 400. The read is itself audited (admin.audit.read, with the filters).","operationId":"AdminSearchAudit","parameters":[{"description":"Who acted, as written: session:\u003cid\u003e, key:\u003cid\u003e, ops:\u003cwho\u003e, billing.sync, billing.webhook.","in":"query","name":"actor","schema":{"maxLength":256,"type":"string"}},{"description":"e.g. admin.users.limit, billing.subscription, user.delete.","in":"query","name":"action","schema":{"maxLength":128,"type":"string"}},{"in":"query","name":"user_id","schema":{"maxLength":64,"type":"string"}},{"description":"RFC 3339 time or YYYY-MM-DD (UTC).","in":"query","name":"from","schema":{"type":"string"}},{"description":"Leave out admin.audit.read entries (the reads of this log itself). Ignored when action names that action.","in":"query","name":"hide_reads","schema":{"type":"boolean"}},{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEntryList"}}},"description":"One page of entries."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Search the audit log (staff)","tags":["Admin"]}},"/admin/trials/suspicious":{"get":{"description":"Staff session only. The unclaimed trials created from one source: a client IP (ip) or a server-side fingerprint (fingerprint), exactly one of the two (400 otherwise). Ordered by user id, paginated. The source of one user is on GET /admin/users/{id} (trial_source). Audited, with the kind of source and not its value.","operationId":"AdminSuspiciousTrials","parameters":[{"in":"query","name":"ip","schema":{"maxLength":64,"type":"string"}},{"in":"query","name":"fingerprint","schema":{"maxLength":64,"type":"string"}},{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserList"}}},"description":"One page of trials."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Unclaimed trials from one source (staff)","tags":["Admin"]}},"/admin/users":{"get":{"description":"Staff session only (keys and user sessions get 403 forbidden). The term decides the lookup: empty lists every claimed user by e-mail; a user id or an app id answers that user; amps_… is a key prefix; anything else is an e-mail prefix. Paginated; audited.","operationId":"AdminSearchUsers","parameters":[{"in":"query","name":"q","schema":{"maxLength":256,"type":"string"}},{"in":"query","name":"cursor","schema":{"type":"string"}},{"description":"true lists every staff account instead (q and cursor are ignored; one page).","in":"query","name":"staff","schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserList"}}},"description":"One page of users."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Search users (staff)","tags":["Admin"]}},"/admin/users/{user_id}":{"get":{"description":"Staff session only. The user with its staff-facing facts, plan and serving state, its apps, and its usage in the current window. Audited.","operationId":"AdminGetUser","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminUserView"}}},"description":"The user."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"One user (staff)","tags":["Admin"]},"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}]},"/admin/users/{user_id}/audit":{"get":{"description":"Staff session only. The audit entries about this user (staff actions on it, its billing changes, an ops delete), newest first, paginated. The read is itself audited (admin.audit.read).","operationId":"AdminUserAudit","parameters":[{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEntryList"}}},"description":"One page of entries."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"A user's audit trail (staff)","tags":["Admin"]},"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}]},"/admin/users/{user_id}/jobs":{"get":{"description":"Staff session only. The user's jobs, newest first, paginated, each as GET /jobs/{job_id} shows it (with its last webhook attempt). Audited (admin.users.jobs).","operationId":"AdminUserJobs","parameters":[{"in":"query","name":"status","schema":{"enum":["queued","running","done","failed"],"type":"string"}},{"in":"query","name":"type","schema":{"enum":["app.delete","user.delete","tree.delete","cdn.purge"],"type":"string"}},{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobList"}}},"description":"One page of jobs."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"A user's jobs (staff)","tags":["Admin"]},"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}]},"/admin/users/{user_id}/ledger":{"get":{"description":"Staff session only. The user's usage ledger for one month, one UTC day a page: the hourly rows (UsageHour: what each app added to each meter in each hour; bandwidth rows are CDN hits, bandwidth_miss rows origin misses, storage rows are standing) and the CloudFront hours (CDNHour). next_cursor is the next day of the month. Audited (admin.users.ledger).","operationId":"AdminUserLedger","parameters":[{"description":"The month, YYYY-MM; default the current one.","in":"query","name":"window","schema":{"pattern":"^[0-9]{4}-[0-9]{2}$","type":"string"}},{"description":"The day to read, YYYY-MM-DD, as next_cursor gave it; default the month's first day.","in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerDay"}}},"description":"One day of the ledger."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"A user's ledger rows (staff)","tags":["Admin"]},"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}]},"/admin/users/{user_id}/limits/{meter}":{"delete":{"description":"Staff session only. Removes the override on this meter and rechecks the user's serving state at once, as PUT does. Audited with the reason.","operationId":"AdminClearLimit","parameters":[{"in":"query","name":"reason","required":true,"schema":{"maxLength":500,"minLength":1,"type":"string"}}],"responses":{"204":{"description":"Cleared."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Put a user's plan limit back (staff)","tags":["Admin"]},"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}},{"in":"path","name":"meter","required":true,"schema":{"enum":["storage","cpu","bandwidth","ingress","invalidations","concurrent_uploads","apps"],"type":"string"}}],"put":{"description":"Staff session only. Replaces the plan limit on one meter for this user: for the current usage window (UTC month; it lapses at the start of the next one) or permanently (until cleared). One override per meter; a second replaces the first. Takes effect within a minute on every replica. The user's serving state is rechecked at once: a raised limit lifts a hard_limit restriction, a lowered one applies it. Locked reasons (abuse, trial_expired, past_due) are never lifted here: POST /admin/users/{id}/unsuspend does that. Audited with the reason.","operationId":"AdminSetLimit","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitRequest"}}},"required":true},"responses":{"204":{"description":"Applied."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Change one limit of a user (staff)","tags":["Admin"]}},"/admin/users/{user_id}/live":{"get":{"description":"Staff session only. The user's counters as the live store holds them now, for the current month: every meter (bandwidth is CDN hits + origin misses, bandwidth_miss the origin part), reserved storage, per app; the serving state; the open upload sessions with their live progress. The ledger is the history; these lead it by up to a flush. Audited (admin.users.live).","operationId":"AdminUserLive","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveCounters"}}},"description":"The live counters."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"A user's live counters (staff)","tags":["Admin"]},"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}]},"/admin/users/{user_id}/plan":{"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}],"put":{"description":"Staff session only. A complimentary plan (nothing is charged), or trial to remove one; never over a paid subscription (409 conflict). The limits change within a minute on every replica and the serving state is rechecked at once. A Google sign-in from an internal domain grants AMPS_INTERNAL_PLAN again. Audited with the reason.","operationId":"AdminSetPlan","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanRequest"}}},"required":true},"responses":{"204":{"description":"Applied."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Put a user on a plan without payment (staff)","tags":["Admin"]}},"/admin/users/{user_id}/purge":{"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}],"post":{"description":"Staff session only. Queues a CDN invalidation by cache tag (the user's, or the application's when app_id is given) for every cached object of the user or app; the aggregator runs the job at once and it is not charged to the user (without it, objects leave the edge only at the edge TTL). Takedowns and abuse. Audited with the reason.","operationId":"AdminPurgeUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurgeRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurgeAccepted"}}},"description":"Queued."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Purge a user's files from the CDN (staff)","tags":["Admin"]}},"/admin/users/{user_id}/staff":{"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}],"put":{"description":"Staff session only. The flag applies at the user's next Google sign-in from the staff hosted domain; a live session of that user loses or gains the staff principal within a minute. Staff cannot revoke their own role. Audited with the reason.","operationId":"AdminSetStaff","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffRequest"}}},"required":true},"responses":{"204":{"description":"Applied."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Grant or revoke the staff role (staff)","tags":["Admin"]}},"/admin/users/{user_id}/suspend":{"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}],"post":{"description":"Staff session only. Sets the serving state to suspended, reason abuse, which the usage recompute never lifts: only POST /admin/users/{id}/unsuspend does. Serving stops at the next CDN miss, and the user's cached copies are purged by cache tag (one cdn.purge job per suspension, at once, not charged). The API then refuses the account's uploads, file deletes, new applications and serving tokens (403). A user already suspended stays so and keeps when that suspension began: the call is safe to repeat and answers the same job. The suspension is recorded on the account (a staff hold) before anything else, and a background task keeps it in force every 5 minutes: it survives a loss of the live store, and nothing is left to repeat. The owner is mailed once per suspension when the account has an e-mail. 400 for the caller's own account, 409 for a staff account (revoke the role first), 502 when the hold is recorded but serving could not be stopped now or the purge could not be queued (both follow within 5 minutes without another call). Audited with the reason.","operationId":"AdminSuspendUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuspendRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurgeAccepted"}}},"description":"Suspended; the purge of the user's cached copies is queued."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Suspend a user's serving (staff)","tags":["Admin"]}},"/admin/users/{user_id}/unsuspend":{"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}],"post":{"description":"Staff session only. Lifts the staff hold a suspend recorded, then sets the serving state to allow (reason staff_unsuspend), whatever the reason was, locked ones (abuse, trial_expired, past_due) included. If the user is still over a limit, the next CDN usage ingest tightens again. 404 for an unknown user. Audited with the reason.","operationId":"AdminUnsuspend","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsuspendRequest"}}},"required":true},"responses":{"204":{"description":"Applied."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Lift a user's serving restriction (staff)","tags":["Admin"]}},"/admin/users/{user_id}/usage-snapshots":{"get":{"description":"Staff session only. The user's closed months, newest first, paginated, each with what serving it cost AMPS by line (design/plan-economics.md §2) and the margin (the price charged less the cost). Never shown to the user. Audited (admin.users.usage_snapshots).","operationId":"AdminUserUsageSnapshots","parameters":[{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffUsageHistory"}}},"description":"One page of months."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"A user's past months with cost and margin (staff)","tags":["Admin"]},"parameters":[{"in":"path","name":"user_id","required":true,"schema":{"type":"string"}}]},"/agent/login":{"post":{"description":"For an agent with no key, when the person already has an AMPS account (skill §1). Show the person `user_code` and `verification_url`; they approve it in the console, signed in, and pick the app. Then poll POST /agent/login/token with `device_code` every `interval` seconds; it returns a new key of that app once. Expires after `expires_in` seconds. Rate-limited per IP (rate.agent_login).","operationId":"StartAgentLogin","responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLoginStarted"}}},"description":"A pending login."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"security":[],"summary":"Start a device login","tags":["Account"]}},"/agent/login/decision":{"post":{"description":"For the console's /link page, not for agents: the signed-in owner approves the login with this user code for one of their apps, or denies it. Session only. 404 for an unknown or expired code; 409 when it was already decided.","operationId":"DecideAgentLogin","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLoginDecision"}}},"required":true},"responses":{"204":{"description":"Decided."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Approve or deny a device login","tags":["Account"]}},"/agent/login/token":{"post":{"description":"Poll with the `device_code` from POST /agent/login, no faster than `interval`. 428 authorization_pending until the person approves; 429 slow_down when polled too fast; 403 access_denied when the person denied it; 410 expired_token when it expired or was already collected. On approval: 201 with a new key of the app the person picked, shown once (labelled \"agent login \u003cdate\u003e\"; it appears on the app's keys page).","operationId":"CollectAgentLogin","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLoginTokenRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedKey"}}},"description":"The key, shown once."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"security":[],"summary":"Collect a device login's key","tags":["Account"]}},"/apps":{"get":{"description":"List the caller's applications.","operationId":"ListApps","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppList"}}},"description":"Applications."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"List applications","tags":["Applications"]},"post":{"description":"Add an application (its own folder, keys and webhook secret) and return it with its first key, shown once. Counts against the plan's app cap (402 quota_exhausted, meter apps). An unclaimed trial keeps one app until it is claimed (402 feature_not_licensed); a suspended account cannot create (403). `private: true` creates a private app, whose files are served only with a serving token; a trial account cannot (402 feature_not_licensed). 409 conflict when the name is taken. Not stored by the Idempotency-Key store (the secret must not be replayable): a repeated call with the same name is a 409.","operationId":"CreateApp","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppCreateRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppCreated"}}},"description":"The application and its first key."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Create an application","tags":["Applications"]}},"/apps/{app_id}":{"delete":{"description":"Delete an application: it disappears from GET /apps at once (its keys stop, its name is free), and a background job empties its folder and purges the CDN. Session only. The account's last application cannot be deleted (409 conflict): delete the account instead. Returns the job: poll GET /jobs/{job_id} until done or failed, or pass callback_url (https, public host) to be POSTed the same document, signed with this app's webhook secret.","operationId":"DeleteApp","parameters":[{"description":"Optional webhook for job.done / job.failed (same rules as POST /uploads callback_url).","in":"query","name":"callback_url","schema":{"maxLength":2048,"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"description":"Deletion started."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Delete an application","tags":["Applications"]},"get":{"description":"One of the caller's applications with its usage in the current window (the five cost meters). webhook_secret as in GET /apps. Unknown or foreign ids are 404.","operationId":"GetApp","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/App"}}},"description":"The application."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"One application","tags":["Applications"]},"parameters":[{"in":"path","name":"app_id","required":true,"schema":{"type":"string"}}],"patch":{"description":"Rename. The owner's session or the app's own key; a sibling app's key gets 404. 409 conflict when the name is taken.","operationId":"UpdateApp","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/App"}}},"description":"The application."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Rename an application","tags":["Applications"]}},"/apps/{app_id}/keys":{"get":{"description":"The app's keys: prefixes and labels, never secrets (which key am I?). The owner's session or the app's own key. A key rotated out but still in its grace is listed with grace_until; revoking it ends the grace at once.","operationId":"ListKeys","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyList"}}},"description":"Keys."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"List API keys","tags":["Applications"]},"parameters":[{"in":"path","name":"app_id","required":true,"schema":{"type":"string"}}],"post":{"description":"Mint another key for the app, shown once. Session only: a leaked key must not be able to mint keys (403 with a key). Not stored by the Idempotency-Key store: a repeated call mints another key; revoke the extra one.","operationId":"CreateKey","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRequest"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedKey"}}},"description":"The key, shown once."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Create an API key","tags":["Applications"]}},"/apps/{app_id}/keys/{key_id}":{"delete":{"description":"End a key now. Session only. The app's last active key cannot be revoked (409 conflict): rotate it instead, or delete the app.","operationId":"RevokeKey","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"204":{"description":"Revoked."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Revoke an API key","tags":["Applications"]},"parameters":[{"in":"path","name":"app_id","required":true,"schema":{"type":"string"}},{"in":"path","name":"key_id","required":true,"schema":{"type":"string"}}]},"/apps/{app_id}/keys/{key_id}/rotate":{"parameters":[{"in":"path","name":"app_id","required":true,"schema":{"type":"string"}},{"in":"path","name":"key_id","required":true,"schema":{"type":"string"}}],"post":{"description":"Mint a replacement, shown once; the old key keeps working for grace_seconds (default 3600, 0 = stops now, max 604800 = 7 days), then stops. Session only. Not stored by the Idempotency-Key store: a repeated call rotates again.","operationId":"RotateKey","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateKeyRequest"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedKey"}}},"description":"The replacement key, shown once."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Rotate an API key","tags":["Applications"]}},"/apps/{app_id}/webhook-secret/rotate":{"parameters":[{"in":"path","name":"app_id","required":true,"schema":{"type":"string"}}],"post":{"description":"Replace the app's webhook signing secret and return the new one. The old secret stops signing immediately, including webhooks queued but not yet delivered: update your receiver first, then rotate. A key may rotate only its own app's secret.","operationId":"RotateWebhookSecret","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSecret"}}},"description":"The new secret."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Rotate the webhook secret","tags":["Applications"]}},"/billing/manage":{"post":{"description":"Session only. A short-lived link to update the card and see receipts; it returns to the console. 409 before a first checkout.","operationId":"ManageBilling","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManageLink"}}},"description":"The link."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"The provider's card and receipts page","tags":["Billing"]}},"/capabilities":{"get":{"description":"Every capability AMPS has, whether the caller's plan grants it (licensed), and the meters that bound it: their use and limits are in GET /usage. A capability that is not licensed answers 402 feature_not_licensed; compare plans with GET /plans.","operationId":"GetCapabilities","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}},"description":"The capabilities."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"What the plan allows","tags":["Usage"]}},"/claims/{token}":{"get":{"description":"For the console's claim page, not for agents: what the trial behind a claim URL holds. The token is the credential. Unknown, expired, replaced and used tokens are all 404.","operationId":"GetClaim","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimSummary"}}},"description":"The trial being claimed."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"security":[],"summary":"What a claim URL claims","tags":["Account"]},"parameters":[{"description":"The token of a claim URL ({console}/claim/{token}).","in":"path","name":"token","required":true,"schema":{"maxLength":128,"type":"string"}}]},"/claims/{token}/complete":{"parameters":[{"in":"path","name":"token","required":true,"schema":{"maxLength":128,"type":"string"}}],"post":{"description":"For the console's claim page, not for agents: complete the claim with the Google identity's verified e-mail, from the console's Google callback with the browser's claim nonce. The trial becomes the account of that e-mail and the Google sign-in. 404 for an unusable token; 403 if Google did not verify the e-mail; 409 if the e-mail or the Google account already has an AMPS account.","operationId":"CompleteClaim","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimCompleteRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResult"}}},"description":"Claimed and signed in."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"security":[],"summary":"Complete a claim with Google","tags":["Account"]}},"/claims/{token}/start":{"parameters":[{"in":"path","name":"token","required":true,"schema":{"maxLength":128,"type":"string"}}],"post":{"description":"For the console's claim page, not for agents: mail a magic link bound to this claim and to the hash of the browser's claim nonce. The link completes the claim only through POST /session with that nonce. 409 if the address already has an AMPS account; 404 for an unusable token.","operationId":"StartClaim","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimStartRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pending"}}},"description":"A claim link was sent."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"security":[],"summary":"Prove an e-mail for a claim","tags":["Account"]}},"/download/{path}":{"get":{"description":"The URL of one file, e.g. GET /download/photos/cat.png for /photos/cat.png: in a private application with a serving token for that path appended (as GET /access/token?path=, with its defaults, rules and rate.token; a trial is 402 feature_not_licensed), in a public one its public URL as it is. The file is not looked up. A suspended account is 403. Mint on your server: the URL of a private file is a credential.","operationId":"GetDownloadUrl","parameters":[{"description":"Path in the app without its leading /, e.g. photos/cat.png.","in":"path","name":"path","required":true,"schema":{"maxLength":1024,"type":"string"}},{"description":"A private file's token: seconds until it expires; 0 = never. Default one year.","in":"query","name":"ttl","schema":{"default":31536000,"maximum":315360000,"minimum":0,"type":"integer"}},{"description":"Required with a session; a key may only name its own app.","in":"query","name":"app_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadUrl"}}},"description":"The URL."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"One file's URL, ready to fetch","tags":["Access"]}},"/files":{"delete":{"description":"Delete a folder of the app and every file under it, e.g. DELETE /files?prefix=/photos/2026. Returns a tree.delete job at once: poll GET /jobs/{job_id} until done or failed, or pass callback_url to be POSTed the same document (job.done / job.failed, signed with the app's webhook secret). The job deletes page by page; storage goes down as it goes. Uploads under the folder are refused while it runs (409). The rules of a single delete apply: rate.purge (one token), 402 quota_exhausted when the month's invalidations are spent, and the CDN copies are purged by the hourly purge run, by the application's cache tag (every cached copy of this application refills from the origin): one invalidation per hourly run that purged for you. 404 when the folder does not exist, 400 for a file (DELETE /files/{path}) or the app root (the owner deletes the whole application with DELETE /apps/{app_id}), 409 while an upload is open under the folder or the folder is already being deleted. A key deletes in its own app; a session must pass app_id.","operationId":"DeleteTree","parameters":[{"description":"The folder in the app, e.g. /photos/2026 (a trailing / is optional; / alone is refused).","in":"query","name":"prefix","required":true,"schema":{"maxLength":1024,"type":"string"}},{"description":"Required with a session; a key may only name its own app.","in":"query","name":"app_id","schema":{"type":"string"}},{"description":"Optional webhook for job.done / job.failed (same rules as POST /uploads callback_url).","in":"query","name":"callback_url","schema":{"maxLength":2048,"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"description":"Deletion started."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Delete a folder and everything in it","tags":["Files"]},"get":{"description":"List the direct children of a folder in the app (the app root is /): files as type file, sub-folders as type dir, sorted by path. The listing is storage's own index (WixMP), so a file appears as soon as its upload completed. A key lists its own app; a session must pass app_id.","operationId":"ListFiles","parameters":[{"description":"Folder in the app, e.g. /photos (empty or / = the app root; the leading / is optional). Direct children only.","in":"query","name":"prefix","schema":{"maxLength":1024,"type":"string"}},{"description":"next_cursor of the previous page.","in":"query","name":"cursor","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},{"description":"Required with a session; a key may only name its own app.","in":"query","name":"app_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileList"}}},"description":"One page of the folder."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"List a folder","tags":["Files"]}},"/files/purge":{"post":{"description":"Ask for the CDN copies of some of your files to be purged: paths (files, at most 100) or prefix (every cached copy of the application: cache tags name files and applications, not folders). Nothing is sent at once: the purge is sent by the next hourly purge run that finds the request at least 6 minutes old, like a delete's, and one invalidation is counted per hourly run that purged for you, however many purges it sent. Past 10 files in one run the whole account's copies are purged. rate.purge (one token per call); 402 quota_exhausted when the month's invalidations are spent. You rarely need it: deletes purge their own files, and new content takes a new path. A key purges in its own app; a session must pass app_id.","operationId":"PurgeFiles","parameters":[{"description":"Required with a session; a key may only name its own app.","in":"query","name":"app_id","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilesPurgeRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pending"}}},"description":"The purge waits for the hourly run."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Purge cached copies from the CDN","tags":["Files"]}},"/files/{path}":{"delete":{"description":"Delete a file now, e.g. DELETE /files/photos/cat.png. Storage goes down by its size. It takes rate.purge and needs one invalidation left in the window (402 quota_exhausted when spent): the CDN copy is purged by the next hourly purge run that finds the delete at least 6 minutes old, so the URL can keep answering for up to about an hour, and one invalidation is counted per hourly run that purged for the user, however many files, only once the CDN accepts the purge. Do not reuse the path for new content inside that window. A folder is deleted only when it is empty (no files, no open uploads); a non-empty folder is 409. An open upload on the path is 409: wait for it or abort it. A key deletes in its own app; a session must pass app_id.","operationId":"DeleteFile","parameters":[{"description":"Path in the app without its leading /, e.g. photos/cat.png.","in":"path","name":"path","required":true,"schema":{"maxLength":1024,"type":"string"}},{"description":"Required with a session; a key may only name its own app.","in":"query","name":"app_id","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Delete one file or an empty folder","tags":["Files"]},"get":{"description":"One entry of the app by its path, e.g. GET /files/photos/cat.png for /photos/cat.png (slashes are part of the path). A file comes back with its size, hash, access and URLs; a folder comes back as type dir with no URLs. Unknown paths are 404 not_found. A key reads its own app; a session must pass app_id.","operationId":"GetFile","parameters":[{"description":"Path in the app without its leading /, e.g. photos/cat.png. A trailing / is ignored.","in":"path","name":"path","required":true,"schema":{"maxLength":1024,"type":"string"}},{"description":"Required with a session; a key may only name its own app.","in":"query","name":"app_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}},"description":"The file, or the folder as type dir."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Get one file","tags":["Files"]}},"/invoices":{"get":{"description":"Session only. The payment provider's invoices of the account, newest first: the plan's fixed price each period, and a prorated charge per upgrade. Empty before a first checkout.","operationId":"ListInvoices","parameters":[{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceList"}}},"description":"One page."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Invoices","tags":["Billing"]}},"/jobs/{job_id}":{"get":{"description":"The state of an asynchronous operation returned with 202 (DELETE /apps/{app_id}, DELETE /files). A key sees its own app's jobs, a session every job of the account; anything else is 404. The same JSON is what callback_url receives; callback reports the last delivery attempt.","operationId":"GetJob","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"description":"The job."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Poll a job","tags":["Applications"]},"parameters":[{"in":"path","name":"job_id","required":true,"schema":{"type":"string"}}]},"/me":{"delete":{"description":"Delete the caller's account and everything in it, for good: every application's files (WixMP and the CDN), keys, sessions, the subscription (canceled at the payment provider) and the account's records. The owner's session only (an API key is 403); confirm must be the account's user_id (400 otherwise); a staff account is 409 (another staff member revokes the role first). Returns the user.delete job at once; a background job does the work, and its first step stops every key and session of the account, so the job cannot be polled with them afterwards. There is no callback: the account's webhook secrets go with it. A repeat while the job is queued or running returns the same job.","operationId":"DeleteMe","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAccountRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"description":"Deletion started."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Delete the account","tags":["Account"]},"get":{"description":"Return the caller's user, plan and serving state (usage is GET /usage), and `claim` when a claim URL is open or the trial was claimed.","operationId":"GetMe","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}},"description":"The caller."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Who am I","tags":["Account"]}},"/plans":{"get":{"description":"Public: no key needed. Every plan, cheapest first, with its price per month, limits and capabilities. Compare it with GET /usage to say which plan fits; the person changes plans at upgrade_url (the console's Plans page) or you call POST /upgrade for a claimed account. payments_enabled is false where payments are off.","operationId":"ListPlans","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanList"}}},"description":"The plan table."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"security":[],"summary":"The plans, their prices and limits","tags":["Billing"]}},"/register":{"post":{"description":"Start an e-mail login: unknown e-mail gets a registration link, known e-mail a sign-in link; both answer 202.","operationId":"Register","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pending"}}},"description":"A magic link was sent."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"security":[],"summary":"Start e-mail sign-in or registration","tags":["Account"]}},"/session":{"delete":{"description":"End the current session.","operationId":"DeleteSession","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"204":{"description":"Signed out."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Sign out","tags":["Account"]},"post":{"description":"Exchange a magic-link code or an OAuth code for a session. The token is in the body; send it as `Authorization: Bearer amps_sess_…` (the API sets no cookie; the console keeps it server-side).","operationId":"CreateSession","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResult"}}},"description":"Signed in (session or claim purpose)."},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResult"}}},"description":"Registered: user, default app and first key (shown once) plus the session."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"security":[],"summary":"Exchange a code for a session","tags":["Account"]}},"/subscription":{"delete":{"description":"Session only. The plan stays until current_period_end, then the trial limits apply (no data is deleted). Undo with POST /subscription/resume. 409 without a paid subscription; 503 billing_unavailable where payments are off.","operationId":"CancelSubscription","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResult"}}},"description":"The subscription, cancel scheduled."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Cancel at the end of the period","tags":["Billing"]},"get":{"description":"The plan in force (trial without a subscription), its status and period, a scheduled change. past_due: the last renewal failed and the payment provider retries the card (Stripe: Smart Retries, up to about two weeks; MockPay in test: day 1, 3 and 5); the plan and serving stay until it gives up (then unpaid: trial limits until the open invoice is paid; cancel ends it).","operationId":"GetSubscription","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}},"description":"The subscription."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"The plan and its payment state","tags":["Billing"]}},"/subscription/checkout/settle":{"post":{"description":"Session only: the console calls it when the person returns from the provider's checkout page. While a checkout of the account was started in the last 3 days and its subscription is not known here yet, the provider is asked once for the customer's live subscriptions and the plan is written from what it says, so a payment whose events were lost shows at once (billing-sync makes the same look every hour). Otherwise nothing is asked and nothing changes. Answers the subscription as it stands after the look. At most 6 looks an hour per user, burst 3 (429 rate_limited, meter rate.checkout_settle); 503 billing_unavailable where payments are off.","operationId":"SettleCheckout","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResult"}}},"description":"The subscription after the look."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Look for a paid checkout","tags":["Billing"]}},"/subscription/resume":{"post":{"description":"Session only. 409 when nothing is scheduled or there is no paid subscription.","operationId":"ResumeSubscription","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResult"}}},"description":"The subscription."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Undo a scheduled cancel or downgrade","tags":["Billing"]}},"/trial":{"post":{"description":"Create an anonymous trial user with a default app and its first key.","operationId":"CreateTrial","requestBody":{"content":{"application/json":{"schema":{"properties":{"name":{"description":"Default app name","maxLength":64,"type":"string"}},"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialCreated"}}},"description":"Trial created. The key secret is shown once."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"security":[],"summary":"Create a trial","tags":["Account"]}},"/unsubscribe":{"post":{"description":"For the console's one-click unsubscribe page, not for agents: the user id and the secret from the digest mail's link. 404 for a link that is not valid.","operationId":"Unsubscribe","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsubscribeRequest"}}},"required":true},"responses":{"204":{"description":"The digest is off."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"security":[],"summary":"Turn the weekly usage digest off from its mail","tags":["Account"]}},"/upgrade":{"post":{"description":"Every plan change. Without a paid subscription: checkout_url (a plan priced above the one in force; a complimentary plan's equal or cheaper ones are 409 conflict: it covers them), the provider's hosted payment page for the person (an agent hands it over). With one and an API key: nothing changes, the answer is confirm_url, the console page where the person confirms (an agent never changes what the person pays). With one and a session: a higher plan applies at once, the difference charged pro rata; a lower plan applies at the end of the period (pending_plan); trial cancels at the end of the period. A claimed account only (an unclaimed trial key gets 402 feature_not_licensed: claim first). 409 conflict on the current plan, or while a subscription the provider started is not yet known here; 402 payment_required while a renewal is past due (except plan trial: canceling needs no payment) or when the card refuses the prorated charge, which leaves the subscription as it was, a scheduled cancel included (hint: the card page, which returns to the console's billing page).","operationId":"Upgrade","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanChange"}}},"description":"A checkout to pay, or the changed subscription."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Change plan","tags":["Billing"]}},"/uploads":{"get":{"description":"List open upload sessions (the reservations that occupy storage quota). A key lists its app's sessions; a session lists every app of the user.","operationId":"ListUploads","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadList"}}},"description":"Open sessions, newest first."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"List open uploads","tags":["Uploads"]},"post":{"callbacks":{"uploadEvent":{"{$request.body#/callback_url}":{"post":{"description":"POSTed once the upload completed (the stored file is in `file`) or expired. Verify `X-Amps-Signature` before trusting the body: `v1` = hex(HMAC-SHA256(webhook_secret, t + \".\" + raw body)), reject when |now − t| \u003e 5 min. Answer 2xx within 5 s; a 4xx (not 429) stops delivery, a 5xx, 429 or timeout is retried with backoff (10 s → 10 min) up to 8 times.","parameters":[{"in":"header","name":"X-Amps-Event","required":true,"schema":{"enum":["upload.completed","upload.expired"],"type":"string"}},{"description":"One id per event; repeated on redelivery.","in":"header","name":"X-Amps-Event-Id","required":true,"schema":{"type":"string"}},{"in":"header","name":"X-Amps-Upload-Id","required":true,"schema":{"type":"string"}},{"description":"t=\u003cunix\u003e,v1=\u003chex HMAC-SHA256\u003e","in":"header","name":"X-Amps-Signature","required":true,"schema":{"type":"string"}},{"in":"header","name":"User-Agent","schema":{"enum":["amps-webhook/1"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadStatus"}}},"required":true},"responses":{"2XX":{"description":"Delivered."},"4XX":{"description":"Refused by the receiver; not retried (429 is retried)."},"5XX":{"description":"Retried with backoff, dead-lettered after 8 attempts."}},"summary":"upload.completed / upload.expired"}}}},"description":"Reserve storage and open an upload session on the Upload Proxy. Idempotent by path (one open session per app path); an Idempotency-Key header is accepted and ignored. A key uploads into its own app; a session must pass app_id (the console's playground); staff sessions are read-only (403).","operationId":"CreateUpload","parameters":[{"description":"Required with a session; a key may only name its own app.","in":"query","name":"app_id","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadSession"}}},"description":"Upload session opened."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Open an upload session","tags":["Uploads"]}},"/uploads/{upload_id}":{"delete":{"description":"Abort an upload session and release its reservation. If the bytes already reached storage but the upload never completed (stuck), the stored file is removed too; upload again to retry.","operationId":"AbortUpload","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"204":{"description":"Aborted."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Abort an upload","tags":["Uploads"]},"get":{"description":"Check an upload session's progress and state. Read-only: the state changes when storage confirms the file (AMPS's own callback) or the session expires, never because it was read.","operationId":"GetUpload","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadStatus"}}},"description":"Upload status."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Upload status","tags":["Uploads"]},"parameters":[{"in":"path","name":"upload_id","required":true,"schema":{"type":"string"}}]},"/usage":{"get":{"description":"The account's usage of one month against its limits. This month and the previous one are the live counters. A month older than the previous one is answered from that month's frozen record (the month as GET /usage/history lists it), in the same shape with frozen true: the five cost meters with the limits in force at the month's end, storage as the bytes stored at the month's end, no per-app numbers and no apps meter. An older month with no record yet answers as an empty month does (frozen false).","operationId":"GetUsage","parameters":[{"description":"Billing window YYYY-MM; default current.","in":"query","name":"window","schema":{"pattern":"^[0-9]{4}-[0-9]{2}$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}},"description":"Usage."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Usage and limits","tags":["Usage"]}},"/usage/history":{"get":{"description":"The account's closed months, newest first, paginated: each month's plan, its price, and every cost meter's total against the limit in force at the month's end (storage: bytes stored at the end, and storage_average over the month). Written once, just after the month ends, from the usage ledger; the current month is GET /usage. Empty until the first month closed.","operationId":"GetUsageHistory","parameters":[{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageHistory"}}},"description":"One page of months."},"default":{"$ref":"#/components/responses/ErrorResponse"}},"summary":"Past months","tags":["Usage"]}}},"security":[{"BearerAuth":[]}],"servers":[{"url":"https://api.amps.media"}],"tags":[{"description":"Trials, e-mail and Google sign-in, sessions.","name":"Account"},{"name":"Applications"},{"description":"Reserve storage, stream bytes to the Upload Proxy, track and abort sessions.","name":"Uploads"},{"description":"Each app's files, rooted at /: list folders, read one file, delete a file or a folder, purge cached copies.","name":"Files"},{"description":"Serving tokens for private files, appended to their URLs as ?token=.","name":"Access"},{"name":"Usage"},{"description":"The plan and its payment: a fixed price per period, charged by the payment provider (billing-model.md); usage never changes the price.","name":"Billing"},{"description":"Staff console only (api/contract.md §7a): a staff session, never a key. Not part of the agent-facing API.","name":"Admin","x-internal":true}]}