{ "openapi": "3.1.0", "info": { "title": "SocialSphere API", "version": "1.4.0", "description": "Shipped public and owner endpoints for personal homepages and agent keys. Agent-key management is browser-session-only." }, "servers": [ { "url": "https://social.globalbr.ai" } ], "components": { "securitySchemes": { "agentKey": { "type": "http", "scheme": "bearer", "description": "Per-user agent key (Authorization: Bearer social_...). X-Agent-Key is accepted as a compatibility header. Not accepted on /api/agent-keys." }, "session": { "type": "apiKey", "in": "cookie", "name": "connect.sid", "description": "Browser session cookie." } }, "parameters": {}, "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } }, "ItemInput": { "type": "object", "required": [ "kind", "text", "privacy" ], "properties": { "kind": { "type": "string", "enum": [ "heading", "link", "note" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "url": { "type": "string", "maxLength": 2000, "description": "Required for link rows; http/https/mailto only.", "nullable": true }, "privacy": { "type": "string", "enum": [ "public", "friends", "private" ] }, "indentLevel": { "type": "integer", "minimum": 0, "maximum": 4 } } }, "ItemPatch": { "type": "object", "description": "Any subset of ItemInput fields; merged then revalidated.", "properties": { "kind": { "type": "string", "enum": [ "heading", "link", "note" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 500 }, "url": { "type": "string", "maxLength": 2000, "nullable": true }, "privacy": { "type": "string", "enum": [ "public", "friends", "private" ] }, "indentLevel": { "type": "integer", "minimum": 0, "maximum": 4 } } }, "ReorderInput": { "type": "object", "required": [ "order" ], "properties": { "order": { "type": "array", "items": { "type": "integer" }, "description": "Permutation of the caller's current row ids." } } }, "AgentKeyInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "expiresAt": { "type": "string", "format": "date-time", "description": "Optional; must be in the future." } } }, "AgentKey": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "key_prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "active": { "type": "boolean" } } }, "MintResponse": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/AgentKey" }, "credential": { "type": "string", "description": "Raw key, returned exactly once." }, "warning": { "type": "string" } } } } }, "paths": { "/api/meta": { "get": { "summary": "Public release metadata and discovery links.", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error or malformed JSON body", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/me": { "get": { "summary": "Safe profile of the effective authenticated actor.", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error or malformed JSON body", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked, or expired credentials", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but not permitted (not owner / not a session)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "agentKey": [] }, { "session": [] } ] } }, "/api/profile-home/{username}": { "get": { "summary": "Viewer-aware personal homepage for a user.", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error or malformed JSON body", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/profile-home/me": { "get": { "summary": "The authenticated owner's full homepage, including private rows.", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error or malformed JSON body", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked, or expired credentials", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but not permitted (not owner / not a session)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "agentKey": [] }, { "session": [] } ] } }, "/api/profile-home/items": { "post": { "summary": "Create a homepage row.", "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error or malformed JSON body", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked, or expired credentials", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but not permitted (not owner / not a session)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemInput" } } } }, "security": [ { "agentKey": [] }, { "session": [] } ] } }, "/api/profile-home/items/{id}": { "patch": { "summary": "Update an owned homepage row.", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error or malformed JSON body", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked, or expired credentials", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but not permitted (not owner / not a session)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPatch" } } } }, "security": [ { "agentKey": [] }, { "session": [] } ] }, "delete": { "summary": "Delete an owned homepage row.", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error or malformed JSON body", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked, or expired credentials", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but not permitted (not owner / not a session)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "agentKey": [] }, { "session": [] } ] } }, "/api/profile-home/reorder": { "put": { "summary": "Reorder owned homepage rows in a single transaction.", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error or malformed JSON body", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked, or expired credentials", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but not permitted (not owner / not a session)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderInput" } } } }, "security": [ { "agentKey": [] }, { "session": [] } ] } }, "/api/agent-keys": { "get": { "summary": "List agent-key metadata for the authenticated owner.", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error or malformed JSON body", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked, or expired credentials", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but not permitted (not owner / not a session)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ] }, "post": { "summary": "Mint an agent key; the raw key is returned exactly once.", "responses": { "201": { "description": "Created", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error or malformed JSON body", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked, or expired credentials", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but not permitted (not owner / not a session)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentKeyInput" } } } }, "security": [ { "session": [] } ] } }, "/api/agent-keys/{id}": { "delete": { "summary": "Revoke an owned agent key.", "responses": { "200": { "description": "Success", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Validation error or malformed JSON body", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked, or expired credentials", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Authenticated but not permitted (not owner / not a session)", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "description": "Correlation id echoed on every API response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "session": [] } ] } } } }