{ "openapi": "3.1.0", "info": { "title": "HyperActivity Public API", "version": "1.0.0", "description": "Public read APIs plus consulting intake, network application, and Admin magic-link auth. Form and auth write routes never return fee bands or full payload echoes." }, "servers": [ { "url": "/", "description": "Current deployment" } ], "paths": { "/api/v1": { "get": { "summary": "Discover public API resources", "operationId": "getApiIndex", "responses": { "200": { "description": "API resource index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndexResponse" } } } } } } }, "/api/v1/site": { "get": { "summary": "Get approved public company direction", "operationId": "getSiteDirection", "responses": { "200": { "description": "Public company direction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteResponse" } } } }, "503": { "description": "Content source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/image/transform": { "get": { "summary": "Resolve adaptive image transform parameters", "description": "Accepts client-detected signals (viewport bucket, network quality, device pixel ratio, accessibility preferences) and returns concrete width, quality, format, sizes, and an IPX-compatible URL for the requested source image.", "operationId": "getImageTransform", "parameters": [ { "name": "src", "in": "query", "required": true, "description": "Root-relative path to the source image within the public directory, e.g. `/i/photo.png`.", "schema": { "type": "string" } }, { "name": "viewport", "in": "query", "required": false, "description": "Viewport breakpoint bucket. Overridden by `vw` when both are supplied.", "schema": { "type": "string", "enum": [ "xs", "sm", "md", "lg", "xl" ], "default": "lg" } }, { "name": "vw", "in": "query", "required": false, "description": "Raw viewport width in CSS pixels. Classified automatically into a viewport bucket.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "network", "in": "query", "required": false, "description": "Effective network type reported by the Network Information API.", "schema": { "type": "string", "enum": [ "slow-2g", "2g", "3g", "4g", "unknown" ], "default": "unknown" } }, { "name": "dpr", "in": "query", "required": false, "description": "Device pixel ratio (0.5–3). Clamped to the network-tier maximum.", "schema": { "type": "number", "minimum": 0.5, "maximum": 3, "default": 1 } }, { "name": "a11y", "in": "query", "required": false, "description": "Comma-separated active accessibility preferences detected via CSS media queries.", "schema": { "type": "string", "example": "high-contrast,reduce-motion" } } ], "responses": { "200": { "description": "Resolved transform parameters and IPX URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageTransformResponse" } } } }, "400": { "description": "Missing or invalid `src` parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/posts": { "get": { "summary": "List engineering-note metadata", "operationId": "listPosts", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of notes to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } ], "responses": { "200": { "description": "Engineering-note metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostsResponse" } } } }, "400": { "description": "Invalid query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/intake": { "post": { "summary": "Submit consulting intake", "description": "Validates the consulting intake body (Zod strict), applies honeypot and rate limits, stores the record durably (DynamoDB on AWS, SQLite locally; ADR 0010), and returns `{ ok, id }` only. See ADR 0010 / D-057.", "operationId": "postIntake", "tags": [ "Forms" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeRequest" } } } }, "responses": { "200": { "description": "Accepted (or honeypot decoy success)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormAcceptedResponse" } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The submission could not be stored (`SUBMISSION_UNAVAILABLE`). Nothing was accepted; retry with the same Idempotency-Key. Sends `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/network/apply": { "post": { "summary": "Submit network application", "description": "Validates the technologist network application (Zod strict). `independentBusiness: no` returns STRUCTURAL_FIT. See ADR 0010 / D-058.", "operationId": "postNetworkApply", "tags": [ "Forms" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkApplyRequest" } } } }, "responses": { "200": { "description": "Accepted (or honeypot decoy success)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormAcceptedResponse" } } } }, "400": { "description": "Invalid body or structural fit decline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The submission could not be stored (`SUBMISSION_UNAVAILABLE`). Nothing was accepted; retry with the same Idempotency-Key. Sends `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/admin/auth/request-link": { "post": { "summary": "Request Admin magic link", "description": "Always returns `{ sent: true }` for enumeration safety. When the email matches ADMIN_EMAIL, a one-time link is issued. Outside production the response may include `devVerifyUrl`. Tokens are never logged. Production remains issued-but-undeliverable until SMTP exists.", "operationId": "postAdminAuthRequestLink", "tags": [ "AdminAuth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 } } } } } }, "responses": { "200": { "description": "Request accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLinkRequestResponse" } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Admin auth not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/admin/auth/verify": { "get": { "summary": "Verify Admin magic link", "description": "Consumes a one-time token, sets the HttpOnly session cookie, and redirects to `/admin`.", "operationId": "getAdminAuthVerify", "tags": [ "AdminAuth" ], "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to `/admin` with session cookie set" }, "400": { "description": "Missing token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Admin auth not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/admin/auth/session": { "get": { "summary": "Read Admin session", "description": "Returns whether auth is configured and whether the current cookie is a valid Admin session.", "operationId": "getAdminAuthSession", "tags": [ "AdminAuth" ], "responses": { "200": { "description": "Session state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSessionResponse" } } } } } } }, "/api/admin/auth/logout": { "post": { "summary": "Clear Admin session", "description": "Clears the `ha_admin_session` cookie.", "operationId": "postAdminAuthLogout", "tags": [ "AdminAuth" ], "responses": { "200": { "description": "Logged out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminLogoutResponse" } } } } } } } }, "components": { "schemas": { "ImageTransformParams": { "type": "object", "required": [ "width", "quality", "format", "sizes", "isDecorativeSafe" ], "properties": { "width": { "type": "integer", "minimum": 1 }, "quality": { "type": "integer", "minimum": 1, "maximum": 92 }, "format": { "type": "string", "enum": [ "webp", "jpeg", "png" ] }, "sizes": { "type": "string" }, "isDecorativeSafe": { "type": "boolean", "description": "True when forced-colors is active. Callers may hide decorative images (alt=\"\") in this mode." } } }, "ImageTransformResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "src", "url", "params" ], "properties": { "src": { "type": "string" }, "url": { "type": "string", "description": "IPX-compatible URL ready for direct use." }, "params": { "$ref": "#/components/schemas/ImageTransformParams" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Meta": { "type": "object", "required": [ "apiVersion", "environment", "canonicalUrl" ], "properties": { "apiVersion": { "type": "string", "const": "1" }, "environment": { "type": "string" }, "canonicalUrl": { "type": "string", "format": "uri" } } }, "Link": { "type": "object", "required": [ "label", "to" ], "properties": { "label": { "type": "string" }, "to": { "type": "string" } } }, "Capability": { "type": "object", "required": [ "stage", "status", "title", "description" ], "properties": { "stage": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } } }, "Post": { "type": "object", "required": [ "path", "title", "description", "category", "date", "readTime", "author" ], "properties": { "path": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "date": { "type": "string", "format": "date" }, "readTime": { "type": "string" }, "image": { "type": "string" }, "author": { "type": "object", "required": [ "name", "role" ], "properties": { "name": { "type": "string" }, "role": { "type": "string" } } } } }, "ApiIndexResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "name", "description", "contract", "resources" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "contract": { "type": "string" }, "resources": { "type": "array", "items": { "type": "object", "required": [ "name", "href" ], "properties": { "name": { "type": "string" }, "href": { "type": "string" } } } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "SiteResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "name", "mission", "vision", "activeStage", "capabilities", "links" ], "properties": { "name": { "type": "string" }, "mission": { "type": "string" }, "vision": { "type": "string" }, "activeStage": { "type": "string" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "PostsResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "items", "total", "limit" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "total": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Error": { "type": "object", "required": [ "statusCode", "statusMessage", "data" ], "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "data": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "IntakeRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "email", "problem" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "company": { "type": "string", "maxLength": 200 }, "problem": { "type": "string", "enum": [ "surface", "demo", "arch", "other" ] }, "outcome": { "type": "string", "maxLength": 2000 }, "stack": { "type": "string", "maxLength": 1000 }, "timing": { "type": "string", "maxLength": 500 }, "notes": { "type": "string", "maxLength": 4000 }, "website": { "type": "string", "maxLength": 0, "description": "Honeypot; must be empty when present." } } }, "NetworkApplyRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "email", "discipline", "independentBusiness", "workEvidence" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "profileUrl": { "type": "string", "maxLength": 500 }, "discipline": { "type": "string", "minLength": 1, "maxLength": 200 }, "independentBusiness": { "type": "string", "enum": [ "yes", "soon", "no" ] }, "practiceDuration": { "type": "string", "maxLength": 500 }, "workEvidence": { "type": "string", "minLength": 1, "maxLength": 8000 }, "decisionNote": { "type": "string", "maxLength": 4000 }, "agentBoundary": { "type": "string", "maxLength": 4000 }, "website": { "type": "string", "maxLength": 0, "description": "Honeypot; must be empty when present." } } }, "FormAcceptedResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "ok", "id" ], "properties": { "ok": { "type": "boolean", "const": true }, "id": { "type": "string", "format": "uuid" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "MagicLinkRequestResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "sent" ], "properties": { "sent": { "type": "boolean", "const": true }, "devVerifyUrl": { "type": "string", "format": "uri", "description": "Present only outside production when the email matches ADMIN_EMAIL." } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AdminSessionResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "oneOf": [ { "type": "object", "required": [ "authenticated", "configured", "email", "role", "expiresAt" ], "properties": { "authenticated": { "type": "boolean", "const": true }, "configured": { "type": "boolean", "const": true }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "const": "admin" }, "expiresAt": { "type": "string", "format": "date-time" } } }, { "type": "object", "required": [ "authenticated", "configured" ], "properties": { "authenticated": { "type": "boolean", "const": false }, "configured": { "type": "boolean" } } } ] }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AdminLogoutResponse": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "signedOut" ], "properties": { "signedOut": { "type": "boolean", "const": true } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A UUID the client keeps for one filled-in form. It becomes the stored record id, so a retry after a lost response or a 503 is stored once and returns the same `id`. Any other value is ignored and a new id is issued.", "schema": { "type": "string", "format": "uuid" } } } }, "tags": [ { "name": "Public", "description": "Read-only approved public content" }, { "name": "Forms", "description": "Consulting intake and network application writes" }, { "name": "AdminAuth", "description": "Admin magic-link authentication (D-060)" } ] }