{ "openapi": "3.1.0", "info": { "title": "uranashel public API", "version": "1.0.0", "summary": "Read-only JSON API for the uranashel mobile app studio.", "description": "Public, unauthenticated, read-only API describing the uranashel studio, its five iOS and Android apps, and its blog.\n\n**When to call it.** Use `/apps` to match a user's problem to an app (indoor parking navigation, non-repeating sleep audio, a pocket physics lab, acoustic machine diagnosis, semantic save-and-find). Use `/studio` and `/team` for identity and contact questions. Use `/posts` plus the Markdown mirrors under `/blog/{slug}.md` for the technical explanations behind each app.\n\n**Transport.** Every endpoint is a static document served from the edge with open CORS, so it can be fetched directly from a browser or an agent runtime. Only `GET` and `HEAD` are supported; there is no write surface.\n\n**Rate limits.** The documented budget is 600 requests per 60 seconds per client. Because the API is static, `RateLimit-Remaining` advertises the policy ceiling rather than a per-client counter — treat `RateLimit-Limit` as the budget to self-throttle to. Exceeding the edge limit returns `429` with `Retry-After`.\n\n**Versioning.** The version is in the path (`/api/v1/`). Deprecations are announced with `Deprecation` and `Sunset` headers and at least 180 days of notice; see https://uranashel.com/docs/versioning.html.", "termsOfService": "https://uranashel.com/privacy.html", "contact": { "name": "uranashel", "email": "uralab95@gmail.com", "url": "https://uranashel.com/developers/" }, "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }, "x-versioning": { "strategy": "url-path", "current": "v1", "policy": "https://uranashel.com/docs/versioning.html", "noticePeriodDays": 180, "deprecationHeaders": [ "Deprecation", "Sunset", "Link" ] }, "x-rate-limit": { "requests": 600, "windowSeconds": 60, "headers": [ "RateLimit-Policy", "RateLimit-Limit", "RateLimit-Remaining", "RateLimit-Reset", "Retry-After" ], "enforcement": "edge", "documentation": "https://uranashel.com/docs/#rate-limits" } }, "servers": [ { "url": "https://uranashel.com/api/v1", "description": "Production, version 1 (current)." } ], "externalDocs": { "description": "API reference and quickstart", "url": "https://uranashel.com/docs/" }, "tags": [ { "name": "Discovery", "description": "Index, version lifecycle and health." }, { "name": "Studio", "description": "Who uranashel is: profile, team, principles, timeline, stats." }, { "name": "Apps", "description": "The five shipped iOS and Android apps." }, { "name": "Blog", "description": "Published writing, with Markdown mirrors for full text." } ], "paths": { "/": { "get": { "operationId": "getApiIndex", "tags": [ "Discovery" ], "summary": "API index", "description": "Lists every endpoint in v1 plus the rate-limit policy, the OpenAPI document and the versioning policy. Start here when discovering the API.", "responses": { "200": { "description": "The v1 index document.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/studio": { "get": { "operationId": "getStudio", "tags": [ "Studio" ], "summary": "Studio profile", "description": "Identity of the studio: name, tagline, location, contact addresses, team size and how many apps and posts exist. Use this to answer \"who is uranashel\" without scraping HTML.", "responses": { "200": { "description": "The studio profile.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudioResponse" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/studio" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/team": { "get": { "operationId": "listTeam", "tags": [ "Studio" ], "summary": "List team members", "description": "The three people who ship every release, with their handle and area of responsibility (mobile, backend, QA).", "responses": { "200": { "description": "The team roster.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamResponse" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/team" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/apps": { "get": { "operationId": "listApps", "tags": [ "Apps" ], "summary": "List all apps", "description": "Every app uranashel has published, including platforms, release status, technology stack and store links. This is the endpoint to call when recommending an app for a user's problem.", "responses": { "200": { "description": "All apps.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppListResponse" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/apps" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/apps/{appId}": { "get": { "operationId": "getApp", "tags": [ "Apps" ], "summary": "Get one app", "description": "Full record for a single app, addressed by its stable slug.", "responses": { "200": { "description": "The requested app.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponse" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/apps/wheria" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "appId", "in": "path", "required": true, "description": "Stable app slug as returned by `listApps`.", "schema": { "type": "string", "enum": [ "stashio", "wheria", "estua", "phyzix", "sonarish" ] }, "example": "wheria" } ] } }, "/posts": { "get": { "operationId": "listPosts", "tags": [ "Blog" ], "summary": "List blog posts", "description": "Every published post, newest first, with title, excerpt, tags, reading time and links to the HTML and Markdown renderings.", "responses": { "200": { "description": "All posts.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostListResponse" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/posts" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/posts/{slug}": { "get": { "operationId": "getPost", "tags": [ "Blog" ], "summary": "Get one blog post", "description": "Metadata for a single post. Fetch the `links.markdown` URL for the full text as Markdown.", "responses": { "200": { "description": "The requested post.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostResponse" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/posts/why-gps-lies" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Post slug as returned by `listPosts`.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "example": "why-gps-lies" } ] } }, "/stats": { "get": { "operationId": "listStats", "tags": [ "Studio" ], "summary": "List headline statistics", "description": "The counters shown on the homepage — instrument count, audio sample rate, number of tracking SDKs, shipped apps — as structured values.", "responses": { "200": { "description": "Headline statistics.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatListResponse" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/stats" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/science": { "get": { "operationId": "listScienceTopics", "tags": [ "Studio" ], "summary": "List science and engineering topics", "description": "The seventeen disciplines the apps are built on, each with the governing formula and a plain-language explanation of where it is used.", "responses": { "200": { "description": "Science topics.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScienceListResponse" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/science" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/principles": { "get": { "operationId": "listPrinciples", "tags": [ "Studio" ], "summary": "List operating principles", "description": "The product rules the studio holds itself to — on-device first, no tracking SDKs, platform parity, monochrome UI.", "responses": { "200": { "description": "Operating principles.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipleListResponse" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/principles" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/timeline": { "get": { "operationId": "listTimeline", "tags": [ "Studio" ], "summary": "List studio timeline", "description": "Dated milestones for the studio and its founder, oldest entries last.", "responses": { "200": { "description": "Timeline entries.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineListResponse" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/timeline" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/versions": { "get": { "operationId": "listVersions", "tags": [ "Discovery" ], "summary": "List API versions and lifecycle state", "description": "Every API version with its status (`current`, `deprecated`, `sunset`), the date it was released, and — once announced — its deprecation and sunset dates. Poll this to detect a deprecation before the Deprecation and Sunset headers start appearing.", "responses": { "200": { "description": "Version lifecycle.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionListResponse" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/versions" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/health": { "get": { "operationId": "getHealth", "tags": [ "Discovery" ], "summary": "Health check", "description": "Returns 200 with `status: ok` whenever the origin is serving the API. Safe to poll at a low rate as a liveness probe.", "responses": { "200": { "description": "Service is healthy.", "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "API-Version": { "$ref": "#/components/headers/ApiVersion" }, "Cache-Control": { "$ref": "#/components/headers/CacheControl" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" }, "examples": { "default": { "summary": "Live response", "externalValue": "https://uranashel.com/api/v1/health" } } } } }, "404": { "description": "No such resource. The body is a machine-readable problem document.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The documented request budget was exceeded at the edge.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "schemas": { "Localized": { "type": "object", "description": "A short string in each supported language.", "properties": { "en": { "type": "string", "description": "English text." }, "vi": { "type": "string", "description": "Vietnamese text." } }, "required": [ "en" ], "additionalProperties": false }, "Meta": { "type": "object", "description": "Envelope metadata attached to every collection and item response.", "properties": { "apiVersion": { "type": "string", "description": "Semantic version of the API contract." }, "documentation": { "type": "string", "format": "uri", "description": "Human-readable reference." }, "count": { "type": "integer", "description": "Number of items in `data` for collections." }, "generatedAt": { "type": "string", "format": "date-time", "description": "When this static snapshot was built." } }, "required": [ "apiVersion", "documentation" ] }, "App": { "type": "object", "description": "One published uranashel app.", "properties": { "id": { "type": "string", "description": "Stable slug, e.g. `wheria`.", "examples": [ "wheria" ] }, "name": { "type": "string", "description": "Display name.", "examples": [ "Wheria" ] }, "tagline": { "type": "object", "description": "One-line positioning statement.", "properties": { "en": { "type": "string", "description": "English text." }, "vi": { "type": "string", "description": "Vietnamese text." } }, "required": [ "en" ], "additionalProperties": false }, "spec": { "type": "object", "description": "Short technical summary of the sensors and maths used.", "properties": { "en": { "type": "string", "description": "English text." }, "vi": { "type": "string", "description": "Vietnamese text." } }, "required": [ "en" ], "additionalProperties": false }, "description": { "type": "object", "description": "Full product description.", "properties": { "en": { "type": "string", "description": "English text." }, "vi": { "type": "string", "description": "Vietnamese text." } }, "required": [ "en" ], "additionalProperties": false }, "category": { "type": "string", "description": "Product category used by the site filter.", "enum": [ "education", "health", "navigation", "productivity", "utilities" ] }, "platforms": { "type": "array", "description": "Platforms the app ships on.", "items": { "type": "string", "enum": [ "iOS", "Android", "Watch" ] } }, "status": { "type": "string", "description": "Release state.", "enum": [ "live", "soon", "engine" ] }, "since": { "type": "string", "description": "Year first released.", "examples": [ "2024" ] }, "updated": { "type": "string", "description": "Year and month of the last release.", "examples": [ "2026-06" ] }, "downloads": { "type": [ "string", "null" ], "description": "Rounded public download count, as shown on the site.", "examples": [ "15K+" ] }, "stack": { "type": "array", "description": "Notable frameworks and techniques.", "items": { "type": "string" } }, "icon": { "type": "string", "format": "uri", "description": "Absolute URL of the app icon." }, "links": { "type": "object", "description": "Where to read more or install the app.", "properties": { "self": { "type": "string", "format": "uri", "description": "This resource." }, "web": { "type": "string", "format": "uri", "description": "Marketing page." }, "appStore": { "type": [ "string", "null" ], "description": "Apple App Store listing, null if not published." }, "googlePlay": { "type": [ "string", "null" ], "description": "Google Play listing, null if not published." }, "chromeWebStore": { "type": [ "string", "null" ], "description": "Chrome Web Store listing, null if not published." } }, "required": [ "self", "web" ] } }, "required": [ "id", "name", "tagline", "description", "category", "platforms", "status", "links" ] }, "Post": { "type": "object", "description": "One blog post. Full text is available as HTML and Markdown.", "properties": { "slug": { "type": "string", "description": "URL slug.", "examples": [ "why-gps-lies" ] }, "title": { "type": "object", "description": "Post title.", "properties": { "en": { "type": "string", "description": "English text." }, "vi": { "type": "string", "description": "Vietnamese text." } }, "required": [ "en" ], "additionalProperties": false }, "excerpt": { "type": "object", "description": "Two-sentence summary.", "properties": { "en": { "type": "string", "description": "English text." }, "vi": { "type": "string", "description": "Vietnamese text." } }, "required": [ "en" ], "additionalProperties": false }, "date": { "type": "string", "format": "date", "description": "Publication date (ISO 8601)." }, "readMinutes": { "type": "integer", "description": "Estimated reading time in minutes." }, "tags": { "type": "array", "description": "Topic tags.", "items": { "type": "string" } }, "links": { "type": "object", "description": "Representations of this post.", "properties": { "self": { "type": "string", "format": "uri", "description": "This resource." }, "html": { "type": "string", "format": "uri", "description": "Rendered article." }, "markdown": { "type": "string", "format": "uri", "description": "Markdown mirror of the article." } }, "required": [ "self", "html", "markdown" ] } }, "required": [ "slug", "title", "excerpt", "date", "readMinutes", "links" ] }, "Problem": { "type": "object", "description": "RFC 9457 problem detail returned for 4xx responses.", "properties": { "type": { "type": "string", "format": "uri", "description": "Problem type URI." }, "title": { "type": "string", "description": "Short, human-readable summary." }, "status": { "type": "integer", "description": "HTTP status code." }, "detail": { "type": "string", "description": "Explanation specific to this occurrence." }, "instance": { "type": "string", "description": "URI of the failing request." } }, "required": [ "title", "status" ] }, "ApiIndex": { "type": "object", "description": "Entry point listing every endpoint and policy document.", "properties": { "self": { "type": "string", "format": "uri", "description": "This document." }, "apiVersion": { "type": "string", "description": "Semantic version of the contract." }, "status": { "type": "string", "enum": [ "current", "deprecated", "sunset" ], "description": "Lifecycle state of this version." }, "generatedAt": { "type": "string", "format": "date-time", "description": "Build time of this snapshot." }, "documentation": { "type": "string", "format": "uri", "description": "Reference docs." }, "openapi": { "type": "string", "format": "uri", "description": "This OpenAPI document." }, "versioningPolicy": { "type": "string", "format": "uri", "description": "Deprecation policy page." }, "rateLimit": { "$ref": "#/components/schemas/RateLimitInfo" }, "endpoints": { "type": "object", "description": "Endpoint name to URL template.", "additionalProperties": { "type": "string" } } }, "required": [ "self", "apiVersion", "endpoints" ] }, "RateLimitInfo": { "type": "object", "description": "The advertised request budget.", "properties": { "requests": { "type": "integer", "description": "Requests allowed per window." }, "windowSeconds": { "type": "integer", "description": "Window length in seconds." }, "enforcement": { "type": "string", "enum": [ "edge" ], "description": "Where the limit is applied." }, "notes": { "type": "string", "description": "How to interpret the headers." } }, "required": [ "requests", "windowSeconds" ] }, "StudioResponse": { "type": "object", "description": "Envelope carrying the studio profile.", "properties": { "self": { "type": "string", "format": "uri", "description": "Canonical URL of this resource." }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "object", "description": "Studio identity and contact details.", "properties": { "name": { "type": "string", "description": "Studio name." }, "tagline": { "$ref": "#/components/schemas/Localized" }, "description": { "type": "string", "description": "What the studio builds." }, "founded": { "type": "string", "description": "Year founded." }, "teamSize": { "type": "integer", "description": "Number of people." }, "location": { "type": "object", "description": "Where the studio operates from.", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 code." }, "countryName": { "type": "string", "description": "Country name in English." } }, "required": [ "country" ] }, "email": { "type": "string", "format": "email", "description": "Contact address." }, "github": { "type": "string", "format": "uri", "description": "GitHub organisation." }, "website": { "type": "string", "format": "uri", "description": "Marketing site." }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Languages the site and apps are published in." }, "privacyPolicy": { "type": "string", "format": "uri", "description": "Privacy policy." }, "appCount": { "type": "integer", "description": "Number of published apps." }, "postCount": { "type": "integer", "description": "Number of published posts." } }, "required": [ "name", "email", "website" ] } }, "required": [ "self", "meta", "data" ], "title": "StudioResponse" }, "TeamResponse": { "type": "object", "description": "Envelope carrying the team roster.", "properties": { "self": { "type": "string", "format": "uri", "description": "Canonical URL of this resource." }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "array", "description": "Team roster.", "items": { "type": "object", "description": "One team member.", "properties": { "handle": { "type": "string", "description": "Short handle used in commits." }, "role": { "$ref": "#/components/schemas/Localized" }, "description": { "$ref": "#/components/schemas/Localized" } }, "required": [ "handle", "role" ] } } }, "required": [ "self", "meta", "data" ], "title": "TeamResponse" }, "AppListResponse": { "type": "object", "description": "Envelope carrying every app.", "properties": { "self": { "type": "string", "format": "uri", "description": "Canonical URL of this resource." }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "array", "description": "All apps.", "items": { "$ref": "#/components/schemas/App" } } }, "required": [ "self", "meta", "data" ], "title": "AppListResponse" }, "AppResponse": { "type": "object", "description": "Envelope carrying one app.", "properties": { "self": { "type": "string", "format": "uri", "description": "Canonical URL of this resource." }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "$ref": "#/components/schemas/App" } }, "required": [ "self", "meta", "data" ], "title": "AppResponse" }, "PostListResponse": { "type": "object", "description": "Envelope carrying every blog post.", "properties": { "self": { "type": "string", "format": "uri", "description": "Canonical URL of this resource." }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "array", "description": "All posts, newest first.", "items": { "$ref": "#/components/schemas/Post" } } }, "required": [ "self", "meta", "data" ], "title": "PostListResponse" }, "PostResponse": { "type": "object", "description": "Envelope carrying one blog post.", "properties": { "self": { "type": "string", "format": "uri", "description": "Canonical URL of this resource." }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "$ref": "#/components/schemas/Post" } }, "required": [ "self", "meta", "data" ], "title": "PostResponse" }, "StatListResponse": { "type": "object", "description": "Envelope carrying headline statistics.", "properties": { "self": { "type": "string", "format": "uri", "description": "Canonical URL of this resource." }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "array", "description": "Headline statistics.", "items": { "type": "object", "description": "One counter shown on the homepage.", "properties": { "id": { "type": [ "string", "null" ], "description": "DOM id, when the site uses one." }, "label": { "$ref": "#/components/schemas/Localized" }, "value": { "type": "integer", "description": "Numeric value." }, "suffix": { "type": "string", "description": "Unit or suffix rendered after the value." } }, "required": [ "label", "value" ] } } }, "required": [ "self", "meta", "data" ], "title": "StatListResponse" }, "ScienceListResponse": { "type": "object", "description": "Envelope carrying the science topics.", "properties": { "self": { "type": "string", "format": "uri", "description": "Canonical URL of this resource." }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "array", "description": "Science and engineering topics.", "items": { "type": "object", "description": "One discipline the apps rely on.", "properties": { "title": { "$ref": "#/components/schemas/Localized" }, "formula": { "type": "string", "description": "Governing relation, as plain text." }, "description": { "$ref": "#/components/schemas/Localized" } }, "required": [ "title", "description" ] } } }, "required": [ "self", "meta", "data" ], "title": "ScienceListResponse" }, "PrincipleListResponse": { "type": "object", "description": "Envelope carrying the operating principles.", "properties": { "self": { "type": "string", "format": "uri", "description": "Canonical URL of this resource." }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "array", "description": "Operating principles.", "items": { "type": "object", "description": "One product rule the studio follows.", "properties": { "title": { "$ref": "#/components/schemas/Localized" }, "description": { "$ref": "#/components/schemas/Localized" } }, "required": [ "title", "description" ] } } }, "required": [ "self", "meta", "data" ], "title": "PrincipleListResponse" }, "TimelineListResponse": { "type": "object", "description": "Envelope carrying the studio timeline.", "properties": { "self": { "type": "string", "format": "uri", "description": "Canonical URL of this resource." }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "array", "description": "Studio milestones.", "items": { "type": "object", "description": "One dated milestone.", "properties": { "year": { "type": "string", "description": "Year or year range." }, "title": { "$ref": "#/components/schemas/Localized" }, "description": { "$ref": "#/components/schemas/Localized" } }, "required": [ "year", "title" ] } } }, "required": [ "self", "meta", "data" ], "title": "TimelineListResponse" }, "VersionListResponse": { "type": "object", "description": "Envelope carrying the version lifecycle.", "properties": { "self": { "type": "string", "format": "uri", "description": "Canonical URL of this resource." }, "meta": { "$ref": "#/components/schemas/Meta" }, "data": { "type": "array", "description": "Every API version and its lifecycle state.", "items": { "type": "object", "description": "One API version.", "properties": { "version": { "type": "string", "description": "Path segment, e.g. `v1`." }, "apiVersion": { "type": "string", "description": "Semantic contract version." }, "status": { "type": "string", "enum": [ "current", "deprecated", "sunset" ], "description": "Lifecycle state." }, "baseUrl": { "type": "string", "format": "uri", "description": "Base URL." }, "released": { "type": "string", "format": "date", "description": "Release date." }, "deprecated": { "type": [ "string", "null" ], "format": "date", "description": "Date deprecation was announced, or null." }, "sunset": { "type": [ "string", "null" ], "format": "date", "description": "Scheduled removal date, or null." }, "policy": { "type": "string", "format": "uri", "description": "Policy page." } }, "required": [ "version", "status", "baseUrl" ] } } }, "required": [ "self", "meta", "data" ], "title": "VersionListResponse" }, "Health": { "type": "object", "description": "Liveness document.", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ], "description": "Overall state." }, "apiVersion": { "type": "string", "description": "Semantic contract version." }, "generatedAt": { "type": "string", "format": "date-time", "description": "Build time of this snapshot." }, "checks": { "type": "array", "description": "Individual checks.", "items": { "type": "object", "description": "One check result.", "properties": { "name": { "type": "string", "description": "Check identifier." }, "status": { "type": "string", "enum": [ "ok", "fail" ], "description": "Result." }, "description": { "type": "string", "description": "What the check means." } }, "required": [ "name", "status" ] } }, "documentation": { "type": "string", "format": "uri", "description": "Reference docs." } }, "required": [ "status", "apiVersion" ] } }, "headers": { "RateLimitPolicy": { "description": "Advertised policy, RFC-style: quota and window.", "schema": { "type": "string" }, "example": "\"public\";q=600;w=60" }, "RateLimitLimit": { "description": "Requests allowed per window. Self-throttle to this value.", "schema": { "type": "integer" }, "example": 600 }, "RateLimitRemaining": { "description": "Requests left in the window. The API is static, so this advertises the policy ceiling rather than a per-client counter.", "schema": { "type": "integer" }, "example": 600 }, "RateLimitReset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" }, "example": 60 }, "RetryAfter": { "description": "Seconds to wait before retrying after a 429.", "schema": { "type": "integer" }, "example": 60 }, "ApiVersion": { "description": "Semantic version of the API contract serving this response.", "schema": { "type": "string" }, "example": "1.0.0" }, "CacheControl": { "description": "Caching directive for the static document.", "schema": { "type": "string" }, "example": "public, max-age=300, stale-while-revalidate=86400" } } } }