{"components":{"headers":{"TinyCycleLimitUnits":{"description":"Units included in the account's current UTC calendar-month cycle.","schema":{"minimum":1,"type":"integer"}},"TinyCycleRemainingUnits":{"description":"Included units left in the current cycle; never negative.","schema":{"minimum":0,"type":"integer"}},"TinyCycleResetSeconds":{"description":"Whole seconds until the current cycle resets.","schema":{"minimum":0,"type":"integer"}},"TinyCycleState":{"description":"within_limit below 80% of the allowance, approaching_limit from 80%, over_limit at or above 100%.","schema":{"enum":["within_limit","approaching_limit","over_limit"],"type":"string"}}},"responses":{"Problem":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"RFC 9457 problem detail."}},"schemas":{"Account":{"properties":{"billing_status":{"enum":["active","past_due","suspended"],"type":"string"},"cycle":{"$ref":"#/components/schemas/Cycle"},"cycle_limit_units":{"description":"Retained; equal to `cycle.limit_units`.","minimum":1,"type":"integer"},"cycle_usage_units":{"description":"Retained; equal to `cycle.usage_units`.","minimum":0,"type":"integer"},"email":{"format":"email","type":"string"},"id":{"type":"string"},"pricing":{"$ref":"#/components/schemas/Pricing"},"services":{"items":{"type":"string"},"type":"array"}},"required":["id","email","billing_status","services","cycle_usage_units","cycle_limit_units","cycle","pricing"],"type":"object"},"Catalogue":{"description":"The service catalogue. Mirrors the published JSON Schema at\n`/.well-known/tiny-catalogue.schema.json`, which is authoritative.\n`token_endpoint` and `jwks_uri` are retained from catalogue 1.0 and are\nalways equal to their counterparts in `authentication`.\n","properties":{"$schema":{"description":"Absolute URL of the JSON Schema this document validates against.","format":"uri","type":"string"},"authentication":{"$ref":"#/components/schemas/CatalogueAuthentication"},"catalogue_version":{"description":"Major bumps may remove or repurpose a member; minor and patch bumps are additive only.","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+$","type":"string"},"centre":{"$ref":"#/components/schemas/CatalogueEntry"},"issuer":{"format":"uri","type":"string"},"jwks_uri":{"format":"uri","type":"string"},"metering":{"$ref":"#/components/schemas/CatalogueMetering"},"services":{"items":{"$ref":"#/components/schemas/CatalogueEntry"},"minItems":1,"type":"array"},"token_endpoint":{"format":"uri","type":"string"}},"required":["$schema","catalogue_version","issuer","token_endpoint","jwks_uri","authentication","metering","centre","services"],"type":"object"},"CatalogueApiKeyFormat":{"description":"How the one-time API key becomes HTTP Basic credentials.","properties":{"client_id":{"minLength":1,"type":"string"},"client_secret":{"minLength":1,"type":"string"},"format":{"const":"{client_id}.{client_secret}","type":"string"},"issued_by":{"format":"uri","type":"string"},"presented_as":{"const":"http_basic","type":"string"},"separator":{"const":".","type":"string"},"split":{"const":"first","type":"string"}},"required":["issued_by","format","separator","split","client_id","client_secret","presented_as"],"type":"object"},"CatalogueAuthentication":{"properties":{"api_key":{"$ref":"#/components/schemas/CatalogueApiKeyFormat"},"audience_parameter":{"const":"audience","type":"string"},"grant_types_supported":{"items":{"type":"string"},"minItems":1,"type":"array"},"jwks_uri":{"format":"uri","type":"string"},"kind":{"const":"oauth2_client_credentials","type":"string"},"scopes_supported":{"items":{"type":"string"},"minItems":1,"type":"array"},"token_endpoint":{"format":"uri","type":"string"},"token_endpoint_auth_methods_supported":{"items":{"type":"string"},"minItems":1,"type":"array"}},"required":["kind","token_endpoint","jwks_uri","grant_types_supported","token_endpoint_auth_methods_supported","audience_parameter","scopes_supported","api_key"],"type":"object"},"CatalogueEntry":{"properties":{"audience":{"description":"Value to send as the `audience` form field at the token endpoint. Always equal to `base_url`.","format":"uri","type":"string"},"base_url":{"description":"Origin every operation path in the entry's OpenAPI document resolves against.","format":"uri","type":"string"},"description":{"minLength":1,"type":"string"},"name":{"minLength":1,"type":"string"},"openapi":{"description":"Absolute URL of the entry's OpenAPI document.","format":"uri","type":"string"},"serving":{"description":"Entries with `serving: false` are advertised but must not be generated against.","type":"boolean"},"slug":{"description":"Stable identifier, safe as a generated module or CLI sub-command name.","pattern":"^[a-z][a-z0-9-]{0,39}$","type":"string"}},"required":["slug","name","serving","base_url","openapi","audience","description"],"type":"object"},"CatalogueMetering":{"description":"Where to find what usage costs and what an account has used. Pointers and identifiers only; the price and the breakdown are described by their own operations in this document.","properties":{"cycle":{"minLength":1,"type":"string"},"meter":{"minLength":1,"type":"string"},"pricing":{"format":"uri","type":"string"},"usage":{"format":"uri","type":"string"}},"required":["meter","cycle","pricing","usage"],"type":"object"},"Charging":{"description":"Whether a published rate is currently turned into an invoice. Separate from `status`, which only says what a unit costs.","properties":{"description":{"type":"string"},"usage_export":{"description":"True when this deployment forwards billable usage to a billing provider. False means usage is measured and reported at the published rate and kept in the centre's ledger, and nothing is invoiced. True is not itself a claim that an invoice is produced - that also requires a product and price at the provider, which the centre cannot see.","type":"boolean"}},"required":["usage_export","description"],"type":"object"},"Cycle":{"description":"The account's current metering cycle. Cycles are UTC calendar months.\nThe limit is measured and reported, not enforced by rejection.\n","properties":{"limit_units":{"minimum":1,"type":"integer"},"remaining_units":{"minimum":0,"type":"integer"},"resets_at":{"format":"date-time","type":"string"},"started_at":{"format":"date-time","type":"string"},"state":{"enum":["within_limit","approaching_limit","over_limit"],"type":"string"},"usage_units":{"minimum":0,"type":"integer"}},"required":["usage_units","limit_units","remaining_units","started_at","resets_at","state"],"type":"object"},"DelegatedTokenRequest":{"additionalProperties":false,"properties":{"account_id":{"description":"The account that owns every resource the token may touch.","maxLength":128,"minLength":1,"type":"string"},"audience":{"description":"Exactly one service origin, from a catalogue entry's `audience`.","format":"uri","type":"string"},"grants":{"$ref":"#/components/schemas/ServiceGrants"},"request_id":{"description":"Idempotency key; a retry replays the same token while it lives.","format":"uuid","type":"string"},"scope":{"description":"Space-delimited subset of api:read and api:write.","type":"string"},"ttl_seconds":{"default":300,"description":"How long the minted token lives, and therefore how long its grants stay in force whatever changes behind it - a token already issued is never re-checked. Shortening this shortens the window in which a withdrawn grant is still usable; it does not affect how quickly a change reaches the next exchange, which is tiny Auth's contract.","maximum":600,"minimum":60,"type":"integer"},"user_id":{"description":"Stable auth user id; becomes the token's `sub`.","maxLength":128,"minLength":1,"type":"string"}},"required":["request_id","account_id","user_id","audience","scope","grants"],"type":"object"},"DemoToken":{"properties":{"access_token":{"type":"string"},"expires_in":{"const":300,"type":"integer"},"rate_limit_per_minute":{"const":3,"type":"integer"},"scope":{"const":"api:read","type":"string"},"token_type":{"const":"Bearer","type":"string"}},"required":["access_token","token_type","expires_in","scope","rate_limit_per_minute"],"type":"object"},"FieldError":{"properties":{"field":{"type":"string"},"in":{"type":"string"},"reason":{"type":"string"}},"required":["field","reason"],"type":"object"},"FileGrants":{"additionalProperties":false,"properties":{"grants":{"items":{"additionalProperties":false,"properties":{"actions":{"description":"`capability` is never sufficient alone - minting a download\ncapability also needs `read` over that exact object. `admin`\nis valid only with an empty `key_prefix`: bucket\nadministration is never inferred from a key prefix.\n","items":{"enum":["read","write","capability","admin"],"type":"string"},"minItems":1,"type":"array"},"bucket":{"maxLength":63,"minLength":3,"type":"string"},"key_prefix":{"default":"","description":"Literal object key prefix; empty means the whole bucket. Unicode is allowed and literal; `\\\\`, `//`, `.` and `..` segments are refused.","maxLength":1024,"type":"string"}},"required":["bucket","actions"],"type":"object"},"maxItems":32,"type":"array"},"service":{"const":"files","type":"string"}},"required":["service","grants"],"type":"object"},"Health":{"properties":{"status":{"enum":["ok"],"type":"string"}},"required":["status"],"type":"object"},"Jwk":{"properties":{"alg":{"const":"EdDSA","type":"string"},"crv":{"const":"Ed25519","type":"string"},"kid":{"type":"string"},"kty":{"const":"OKP","type":"string"},"use":{"const":"sig","type":"string"},"x":{"type":"string"}},"required":["kty","crv","use","alg","kid","x"],"type":"object"},"JwkSet":{"properties":{"keys":{"items":{"$ref":"#/components/schemas/Jwk"},"minItems":1,"type":"array"}},"required":["keys"],"type":"object"},"KvGrants":{"additionalProperties":false,"properties":{"grants":{"items":{"additionalProperties":false,"properties":{"actions":{"items":{"enum":["read","write"],"type":"string"},"minItems":1,"type":"array"},"prefix":{"default":"","description":"Literal key prefix; empty means the whole account. Must be a possible tiny-kv key prefix, so `/`, `%` and non-ASCII are refused.","maxLength":128,"type":"string"}},"required":["actions"],"type":"object"},"maxItems":32,"type":"array"},"service":{"const":"kv","type":"string"}},"required":["service","grants"],"type":"object"},"Pricing":{"description":"What a metered unit costs. `unit_price` is absent exactly when `status`\nis `unpublished`; absent means no rate is configured, not zero.\n","properties":{"cap":{"$ref":"#/components/schemas/SpendCap"},"charging":{"$ref":"#/components/schemas/Charging"},"cycle":{"description":"The period included units are counted over.","type":"string"},"default_included_units":{"description":"Units included in a new account's cycle. An account's own allowance is `cycle.limit_units`.","minimum":1,"type":"integer"},"enforcement":{"description":"What happens at and beyond the included allowance.","type":"string"},"meter":{"description":"The meter every usage event is recorded against.","type":"string"},"status":{"enum":["published","unpublished"],"type":"string"},"unit":{"description":"What one unit is.","type":"string"},"unit_price":{"$ref":"#/components/schemas/UnitPrice"},"unpublished_reason":{"description":"Present only when `status` is `unpublished`.","type":"string"},"zero_rated_operations":{"description":"Every operation that costs nothing, in full.","items":{"$ref":"#/components/schemas/ZeroRatedOperation"},"type":"array"}},"required":["status","meter","unit","cycle","default_included_units","cap","enforcement","charging","zero_rated_operations"],"type":"object"},"Problem":{"properties":{"code":{"type":"string"},"detail":{"type":"string"},"errors":{"items":{"$ref":"#/components/schemas/FieldError"},"type":"array"},"instance":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"format":"uri","type":"string"}},"required":["type","title","status","detail","instance","code","request_id"],"type":"object"},"QueueGrants":{"additionalProperties":false,"properties":{"grants":{"items":{"additionalProperties":false,"properties":{"actions":{"items":{"enum":["publish","consume","manage","deadletter"],"type":"string"},"minItems":1,"type":"array"},"queue_prefix":{"default":"","description":"Literal queue-name prefix; empty means every queue in the account.","maxLength":63,"type":"string"}},"required":["actions"],"type":"object"},"maxItems":32,"type":"array"},"service":{"const":"queue","type":"string"}},"required":["service","grants"],"type":"object"},"ServiceGrants":{"description":"The resources a user principal may touch, for the one service its token\naddresses. Every prefix is a literal UTF-8 prefix: `%` and `_` are\nordinary characters and never reach a pattern match. At most 32 grants,\nand at most 4096 bytes once serialized.\n","discriminator":{"mapping":{"files":"#/components/schemas/FileGrants","kv":"#/components/schemas/KvGrants","queue":"#/components/schemas/QueueGrants"},"propertyName":"service"},"oneOf":[{"$ref":"#/components/schemas/KvGrants"},{"$ref":"#/components/schemas/FileGrants"},{"$ref":"#/components/schemas/QueueGrants"}]},"Signup":{"description":"Returned once, under `Cache-Control: no-store`. `client_id` and\n`client_secret` are the HTTP Basic credentials for `POST /v1/tokens`.\n`api_key` is the same credential as one string,\n`{client_id}.{client_secret}`, split on the first `.`; it is retained for\nclients that already store a single opaque key.\n","properties":{"account_id":{"format":"uuid","type":"string"},"api_key":{"readOnly":true,"type":"string"},"client_id":{"readOnly":true,"type":"string"},"client_secret":{"readOnly":true,"type":"string"},"email":{"format":"email","type":"string"},"services":{"examples":[["weather","kv","queue","auth","files","realtime","ledger"]],"items":{"type":"string"},"minItems":7,"type":"array"}},"required":["account_id","email","api_key","client_id","client_secret","services"],"type":"object"},"SpendCap":{"description":"The per-cycle monetary ceiling, if one is configured.","properties":{"amount_minor":{"minimum":1,"type":"integer"},"currency":{"pattern":"^[A-Z]{3}$","type":"string"},"description":{"type":"string"},"enforced":{"description":"False means no monetary ceiling is in effect for this deployment.","type":"boolean"}},"required":["enforced","description"],"type":"object"},"Token":{"properties":{"access_token":{"type":"string"},"expires_in":{"const":600,"type":"integer"},"scope":{"type":"string"},"token_type":{"const":"Bearer","type":"string"}},"required":["access_token","token_type","expires_in","scope"],"type":"object"},"UnitPrice":{"description":"A rate stated in integer minor units, quoted per `per_units` metered units.","properties":{"amount_minor":{"description":"Minor units charged per `per_units` metered units.","minimum":1,"type":"integer"},"currency":{"description":"ISO 4217.","pattern":"^[A-Z]{3}$","type":"string"},"per_units":{"minimum":1,"type":"integer"}},"required":["currency","amount_minor","per_units"],"type":"object"},"Usage":{"properties":{"cycle":{"$ref":"#/components/schemas/Cycle"},"data":{"items":{"$ref":"#/components/schemas/UsageRow"},"type":"array"},"from":{"format":"date","type":"string"},"group_by":{"items":{"enum":["service","operation","day"],"type":"string"},"type":"array"},"next_cursor":{"description":"Present and non-null when another page follows.","type":["string","null"]},"pricing":{"$ref":"#/components/schemas/Pricing"},"to":{"description":"Inclusive.","format":"date","type":"string"},"totals":{"$ref":"#/components/schemas/UsageTotals"}},"required":["from","to","group_by","data","totals","cycle","pricing"],"type":"object"},"UsageBatch":{"additionalProperties":false,"properties":{"events":{"items":{"$ref":"#/components/schemas/UsageEvent"},"maxItems":1000,"minItems":1,"type":"array"}},"required":["events"],"type":"object"},"UsageEvent":{"additionalProperties":false,"properties":{"account_id":{"type":"string"},"id":{"description":"The request or idempotency-operation UUID. Both observers and every retry must use the same value.","format":"uuid","type":"string"},"occurred_at":{"format":"date-time","type":"string"},"operation":{"pattern":"^[a-z][a-z0-9_.-]{0,79}$","type":"string"},"service":{"pattern":"^[a-z][a-z0-9-]{0,39}$","type":"string"},"source":{"enum":["edge","service"],"type":"string"},"units":{"const":1,"type":"integer"}},"required":["id","account_id","service","operation","units","occurred_at","source"],"type":"object"},"UsageIngestResult":{"properties":{"accepted":{"description":"Receipts whose ID had not been recorded before.","minimum":0,"type":"integer"},"duplicates":{"description":"Receipts whose ID was already recorded. Never charged twice.","minimum":0,"type":"integer"}},"required":["accepted","duplicates"],"type":"object"},"UsageRow":{"description":"One aggregated bucket. A grouping key the request did not ask for is\nabsent rather than null.\n","properties":{"day":{"description":"UTC day, present when `day` was grouped.","format":"date","type":"string"},"operation":{"description":"Present when `operation` was grouped.","type":"string"},"operations":{"description":"Every receipt recorded in this bucket, charged or not. The exact operation count.","minimum":0,"type":"integer"},"service":{"description":"Present when `service` was grouped.","type":"string"},"units":{"description":"Units charged to the account in this bucket.","minimum":0,"type":"integer"},"zero_rated_operations":{"description":"Receipts in this bucket the metering contract charges nothing for. `operations - zero_rated_operations` is what was chargeable.","minimum":0,"type":"integer"}},"required":["units","operations","zero_rated_operations"],"type":"object"},"UsageTotals":{"description":"Totals for the whole requested window, independent of paging.","properties":{"distinct_operations":{"description":"Distinct service/operation pairs seen over the window.","minimum":0,"type":"integer"},"operations":{"description":"Every receipt recorded over the window, charged or not.","minimum":0,"type":"integer"},"units":{"description":"Units charged over the window.","minimum":0,"type":"integer"},"zero_rated_operations":{"description":"Receipts over the window that cost nothing.","minimum":0,"type":"integer"}},"required":["units","operations","zero_rated_operations","distinct_operations"],"type":"object"},"ZeroRatedOperation":{"properties":{"operation":{"type":"string"},"service":{"type":"string"}},"required":["service","operation"],"type":"object"}},"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"A centre-signed access token. `api:read` and `api:write` are the\ncustomer scopes. `tokens:delegate` is held only by the tiny-auth\nservice principal and only authorises `POST /v1/delegated-tokens`.\n","scheme":"bearer","type":"http"},"clientCredentials":{"description":"client_id as the user, client_secret as the password.","scheme":"basic","type":"http"}}},"info":{"description":"Accounts, access-token issuance, usage reporting, and metering intake for tiny services.\n\n**Bootstrapping.** A generated client needs one input: this deployment's base\nURL. `GET /.well-known/tiny-services.json` returns the service catalogue,\nwhich carries its own JSON Schema URL, the token endpoint, how to\nauthenticate to it, and for every service a base URL, an absolute OpenAPI URL\nand the canonical token audience. No service endpoint ever has to be\ncompiled into a client.\n\n**Credentials.** `POST /v1/accounts` returns `client_id` and `client_secret`\nonce. `api_key` is the same credential as one string, `{client_id}.{client_secret}`,\nsplit on the first `.`; prefer the separate members. Present them as HTTP\nBasic at `POST /v1/tokens` together with the `audience` of the service you\nare about to call.\n\n**Metering.** One unit is one authenticated public API operation that\ncompleted `2xx`. Health, OpenAPI, discovery, token issuance, rejected\nauthentication, `3xx`, `4xx`, `5xx` and idempotent replays cost nothing.\nUnits are counted over the UTC calendar month. `GET /v1/usage` breaks the\ncurrent or a past window down by service, operation and day, and every\ncustomer-authenticated response carries the remaining allowance in\n`Tiny-Cycle-*` headers.\n\n**Limit semantics.** `cycle_limit_units` is measured and reported, not\nenforced by rejection: crossing it neither fails requests nor stops token\nissuance in this release. `cycle.state` moves to `approaching_limit` at 80%\nand `over_limit` at 100% so an integration can act before anything does.\n\n**Price.** `GET /v1/pricing` is public and unauthenticated, and is the single\nsource of truth for what a unit costs. The same document is embedded in\n`GET /v1/account` and `GET /v1/usage`, so the three can never disagree. When\nno rate is configured for a deployment it reports `status: \"unpublished\"`\nwith the reason and omits `unit_price` entirely, rather than quoting a zero\nor a guess.\n\n**A published rate is not a claim that anyone is being invoiced.** Those are\nseparate facts. `charging.usage_export` says whether this deployment\nforwards billable usage to a billing provider; whether that becomes an\ninvoice additionally requires a product and price at the provider, which the\ncentre cannot see and never asserts. A deployment can publish a rate, meter\naccurately against it, and invoice nothing.\n","title":"tiny centre API","version":"1.2.0"},"openapi":"3.1.0","paths":{"/.well-known/jwks.json":{"get":{"operationId":"jwks","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JwkSet"}}},"description":"Active and retiring Ed25519 verification keys.","headers":{"Cache-Control":{"description":"Public cache lifetime for the key set.","schema":{"type":"string"}}}}},"security":[],"summary":"Ed25519 verification keys for tokens signed by this issuer."}},"/.well-known/tiny-catalogue.schema.json":{"get":{"description":"JSON Schema 2020-12. Its `$id` is this URL, and every catalogue this\ndeployment serves points at it through `$schema`.\n","operationId":"catalogueSchema","responses":{"200":{"content":{"application/schema+json":{"schema":{"description":"A JSON Schema 2020-12 document.","properties":{"$id":{"format":"uri","type":"string"},"$schema":{"format":"uri","type":"string"},"type":{"const":"object","type":"string"}},"required":["$id","$schema","type"],"type":"object"}}},"description":"The catalogue schema.","headers":{"Access-Control-Allow-Origin":{"description":"The schema is readable from any origin.","schema":{"const":"*","type":"string"}},"Cache-Control":{"description":"Public cache lifetime for the schema.","schema":{"type":"string"}}}}},"security":[],"summary":"The JSON Schema the service catalogue validates against."}},"/.well-known/tiny-services.json":{"get":{"description":"The single bootstrap input for generated clients. Locates and\nauthenticates contracts; it never restates them. OpenAPI remains\nauthoritative for operations, schemas and errors.\n\nAdditive members may appear within catalogue major version 1; consumers\nmust ignore members they do not recognise.\n","operationId":"discoverServices","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalogue"}}},"description":"The currently serving tiny service catalogue.","headers":{"Access-Control-Allow-Origin":{"description":"The catalogue is readable from any origin.","schema":{"const":"*","type":"string"}},"Cache-Control":{"description":"Public cache lifetime for the catalogue.","schema":{"type":"string"}}}}},"security":[],"summary":"Discover tiny services and their environment-specific API descriptions."}},"/health/live":{"get":{"operationId":"live","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}},"description":"Process is alive."}},"security":[],"summary":"Liveness probe."}},"/health/ready":{"get":{"operationId":"ready","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}},"description":"Required datastore is ready."},"503":{"$ref":"#/components/responses/Problem"}},"security":[],"summary":"Readiness probe."}},"/openapi.json":{"get":{"operationId":"openapi","responses":{"200":{"content":{"application/json":{"schema":{"description":"An OpenAPI 3.1 document.","properties":{"info":{"type":"object"},"openapi":{"type":"string"},"paths":{"type":"object"}},"required":["openapi","info","paths"],"type":"object"}}},"description":"This OpenAPI 3.1 document, represented as JSON."}},"security":[],"summary":"This OpenAPI 3.1 document, represented as JSON."}},"/v1/account":{"get":{"operationId":"account","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}},"description":"Authenticated account and current cycle usage.","headers":{"Tiny-Cycle-Limit-Units":{"$ref":"#/components/headers/TinyCycleLimitUnits"},"Tiny-Cycle-Remaining-Units":{"$ref":"#/components/headers/TinyCycleRemainingUnits"},"Tiny-Cycle-Reset-Seconds":{"$ref":"#/components/headers/TinyCycleResetSeconds"},"Tiny-Cycle-State":{"$ref":"#/components/headers/TinyCycleState"}}},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":["api:read"]}],"summary":"The authenticated account, its entitlements, and its current cycle."}},"/v1/accounts":{"post":{"operationId":"createAccount","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"email":{"format":"email","type":"string"}},"required":["email"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Signup"}}},"description":"Account created. The credential is not returned again.","headers":{"Cache-Control":{"description":"Always `no-store`; the secret must not be cached.","schema":{"const":"no-store","type":"string"}}}},"400":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"}},"security":[],"summary":"Create a developer account for every serving API and issue its API key once."}},"/v1/delegated-tokens":{"post":{"description":"Private. Only the configured tiny-auth service principal may call this,\nholding a centre token with the `tokens:delegate` scope and this issuer\nas its audience. Centre does not trust browser-supplied identity: Auth\nresolves the account and the user from the session server-side.\n\nThe result is one short-lived token for exactly one service audience,\ncarrying `principal_type: user`, the account in `account_id`, the Auth\nuser id in `sub`, and that service's grants in `tiny_grants`. A service\nvalidates it locally against this issuer's JWKS and never calls back.\n\nRevocation is the lifetime. Grants are read at mint time and baked in,\nso a token this endpoint returns cannot be narrowed, withdrawn or\nrecalled by anything except its own expiry - `ttl_seconds`, 300 s by\ndefault and 600 s at most.\n\nHow quickly a change in a user's authority reaches the *next* token is\ntiny Auth's contract rather than this one. Withdrawing a grant or\ndisabling the user takes effect on the following exchange; revoking a\nsession or resetting a password does not stop an exchange, because the\nuser's access token outlives the session it came from. See tiny Auth\nfor those bounds.\n\n`request_id` makes a retry safe: the same key replays the same token for\nas long as that token is alive. It is *at most once while the token\nlives*, not exactly once forever - a retry arriving after the token has\nexpired mints a new one.\n","operationId":"exchangeDelegatedToken","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegatedTokenRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Token"}}},"description":"Signed user-principal access token for one service.","headers":{"Cache-Control":{"description":"Always `no-store`; the token must not be cached.","schema":{"const":"no-store","type":"string"}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":["tokens:delegate"]}],"summary":"Exchange an authenticated end user for one grant-bearing service token."}},"/v1/demo-tokens":{"post":{"description":"Non-billable, weather-audience, read-only, rate limited per token.","operationId":"issueDemoToken","responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoToken"}}},"description":"Five-minute weather token limited to three calls per minute.","headers":{"Cache-Control":{"description":"Always `no-store`; the token must not be cached.","schema":{"const":"no-store","type":"string"}}}},"429":{"$ref":"#/components/responses/Problem"}},"security":[],"summary":"Mint a narrow, short-lived weather demo token."}},"/v1/pricing":{"get":{"description":"Public and unauthenticated, so the cost of the tail can be evaluated\nbefore an account exists. The single source of truth for price: the same\ndocument is embedded in `GET /v1/account` and `GET /v1/usage`.\n\n`unit_price` is quoted per `per_units` metered units rather than per\nunit, because a per-unit rate can be a fraction of a minor unit and\ncould not then be stated exactly in integers.\n\nWhen `status` is `unpublished`, `unit_price` is absent and\n`unpublished_reason` says why. Absent means no rate is configured and\nusage is not converted to money - it does not mean free-forever, and it\nmust not be read as zero.\n\n`status: \"published\"` says what a unit costs. It does not say anyone is\nbeing charged: read `charging.usage_export` for that, and note that even\n`true` is not a claim that an invoice is produced.\n","operationId":"pricing","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pricing"}}},"description":"The published price of a metered unit.","headers":{"Access-Control-Allow-Origin":{"description":"The price is readable from any origin.","schema":{"const":"*","type":"string"}},"Cache-Control":{"description":"Public cache lifetime for the price.","schema":{"type":"string"}}}}},"security":[],"summary":"What a metered unit costs."}},"/v1/tokens":{"post":{"description":"HTTP Basic, where the user is `client_id` and the password is\n`client_secret` from `POST /v1/accounts`. If you hold the credential as\nthe single `api_key` string, split it on the **first** `.`: everything\nbefore is the client id, everything after is the secret.\n\n`audience` is the `audience` member of a catalogue entry - the origin of\nthe service you are about to call, or this issuer for centre calls. A\ntoken is valid only for that audience. Token issuance is never metered.\n\nFor a customer client the response also carries the account's remaining\ncycle allowance, so an integration learns its budget on the one call it\nalready makes.\n\n**Retry this call.** It is the single hard dependency of every other tiny\ncall, so a moment of unavailability here fails work that would otherwise\nhave succeeded - a centre rolling restart has produced `504`s at this\nendpoint in production. Minting a token has no side effect to undo and is\nnever metered, so retrying is safe.\n\nRetry `502`, `503`, `504` and transport failures with a short bounded\nbackoff; two retries covers a rolling restart. Do **not** retry `400`,\n`401` or `403`: those are answers, not blips, and repeating them wastes\ntime and can trip lockouts. On `429`, honour `Retry-After` rather than\nretrying immediately. Cache the token until shortly before `expires_in`\nso this call is rare in the first place.\n","operationId":"issueToken","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"additionalProperties":false,"properties":{"audience":{"description":"A catalogue entry's `audience`.","format":"uri","type":"string"},"grant_type":{"const":"client_credentials","type":"string"},"scope":{"description":"Space-delimited subset of the client's grants. Customer clients receive api:read and api:write; demo tokens remain api:read only.","type":"string"}},"required":["grant_type","audience"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Token"}}},"description":"Signed access token.","headers":{"Tiny-Cycle-Limit-Units":{"$ref":"#/components/headers/TinyCycleLimitUnits"},"Tiny-Cycle-Remaining-Units":{"$ref":"#/components/headers/TinyCycleRemainingUnits"},"Tiny-Cycle-Reset-Seconds":{"$ref":"#/components/headers/TinyCycleResetSeconds"},"Tiny-Cycle-State":{"$ref":"#/components/headers/TinyCycleState"}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"502":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"},"504":{"$ref":"#/components/responses/Problem"}},"security":[{"clientCredentials":[]}],"summary":"Exchange an API client ID and secret for a short-lived access token."}},"/v1/usage":{"get":{"description":"Reads the account's own usage ledger. The account is taken from the\nvalidated token subject and cannot be supplied by the caller.\n\n`from` and `to` are whole UTC days and both are inclusive, so\n`from=2026-09-01&to=2026-09-30` aggregates\n`[2026-09-01T00:00:00Z, 2026-10-01T00:00:00Z)`. They default to the\ncurrent cycle so far and may span at most 62 days.\n\n`units` is what was charged. `operations` counts every receipt recorded,\ncharged or not, so zero-rated operations such as token issuance are\nvisible with `units: 0`.\n\nResults are ordered by day, then service, then operation. When\n`next_cursor` is present, pass it back as `cursor` for the next page;\npages are stable because the ordering key is the grouping key.\n\n`totals` covers the whole requested window regardless of paging, so a\nclient does not have to walk every page to learn what the window cost.\n`pricing` is the same document `GET /v1/pricing` returns.\n","operationId":"usage","parameters":[{"description":"First UTC day to include, inclusive. Defaults to the first day of the current cycle.","in":"query","name":"from","required":false,"schema":{"format":"date","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","type":"string"}},{"description":"Last UTC day to include, inclusive. Defaults to today.","in":"query","name":"to","required":false,"schema":{"format":"date","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","type":"string"}},{"description":"Comma-separated subset of `service`, `operation`, `day`. Order does not matter. An empty value returns one total row. Defaults to all three.","in":"query","name":"group_by","required":false,"schema":{"default":"service,operation,day","type":"string"}},{"description":"Maximum aggregated rows in one page.","in":"query","name":"limit","required":false,"schema":{"default":200,"maximum":1000,"minimum":1,"type":"integer"}},{"description":"Opaque keyset cursor returned as `next_cursor` by the previous page.","in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}},"description":"The requested breakdown and the account's current cycle.","headers":{"Tiny-Cycle-Limit-Units":{"$ref":"#/components/headers/TinyCycleLimitUnits"},"Tiny-Cycle-Remaining-Units":{"$ref":"#/components/headers/TinyCycleRemainingUnits"},"Tiny-Cycle-Reset-Seconds":{"$ref":"#/components/headers/TinyCycleResetSeconds"},"Tiny-Cycle-State":{"$ref":"#/components/headers/TinyCycleState"}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":["api:read"]}],"summary":"Metered usage for the authenticated account, broken down by service, operation and day."}},"/v1/usage-events":{"post":{"description":"Idempotently records edge or service completion receipts. Requires a\nservice-principal token with `meter:write` and the centre audience.\n\nA receipt is identified by `id`, so the two observers and any retry\nconverge on one ledger row. A receipt is charged to a cycle exactly once,\non the first observation from an observer the deployment charges on;\nlater observations are recorded for reconciliation and never charged\nagain. Operations the metering contract rates at zero are recorded and\nnever charged.\n","operationId":"ingestUsage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageBatch"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageIngestResult"}}},"description":"Batch accepted; duplicates are reported, not re-counted."},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"403":{"$ref":"#/components/responses/Problem"},"409":{"$ref":"#/components/responses/Problem"},"422":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":["meter:write"]}],"summary":"Record edge or service completion receipts."}}},"servers":[{"url":"https://tiny.kjuulh.io"}]}