{ "openapi": "3.1.0", "info": { "title": "MusePort private activity observer", "version": "2026.10.09.001", "description": "WordPress administrator observer, not task execution or email delivery. Writer keys may only POST events. No public activity feed. Event states, source timestamps and proof references remain agent reported; server receipt time verifies ingestion only. Limits: 4096 bytes, 280 summary characters, 60 new events/minute/agent, 100 identities, 10000 events and 90 days. Never upload raw private records." }, "servers": [ { "url": "https://example.test/wp-json/museport/v1", "description": "Replace with your exact authorized HTTPS site; this is a placeholder, not a working connection." } ], "paths": { "/events": { "post": { "summary": "Submit one minimized agent-attributed event", "security": [ { "EventWriter": [] } ], "responses": { "200": { "description": "Private response; Cache-Control: private, no-store, max-age=0", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventReceipt" } } } }, "400": { "description": "Invalid activity metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Writer credential missing, rotated or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Administrator required, wrong credential scope, missing nonce or HTTPS required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflict or retention/registry capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON exceeds 4096 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-agent rate limit or serialized write busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable; keep the same request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Activity" } } } } }, "get": { "summary": "Administrator reads private activity", "security": [ { "WordPressAdmin": [] } ], "responses": { "200": { "description": "Private response; Cache-Control: private, no-store, max-age=0", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feed" } } } }, "400": { "description": "Invalid activity metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Writer credential missing, rotated or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Administrator required, wrong credential scope, missing nonce or HTTPS required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflict or retention/registry capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON exceeds 4096 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-agent rate limit or serialized write busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable; keep the same request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "agent_id", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ] } }, "/runs": { "get": { "summary": "Administrator reads latest reported task-run states", "security": [ { "WordPressAdmin": [] } ], "responses": { "200": { "description": "Private response; Cache-Control: private, no-store, max-age=0", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Feed" } } } }, "400": { "description": "Invalid activity metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Writer credential missing, rotated or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Administrator required, wrong credential scope, missing nonce or HTTPS required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflict or retention/registry capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON exceeds 4096 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-agent rate limit or serialized write busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable; keep the same request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "agent_id", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ] } }, "/status": { "get": { "summary": "Administrator reads private observer counts and receipt times", "security": [ { "WordPressAdmin": [] } ], "responses": { "200": { "description": "Private response; Cache-Control: private, no-store, max-age=0", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "400": { "description": "Invalid activity metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Writer credential missing, rotated or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Administrator required, wrong credential scope, missing nonce or HTTPS required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflict or retention/registry capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON exceeds 4096 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-agent rate limit or serialized write busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable; keep the same request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agents": { "get": { "summary": "Administrator reads registry without keys or hashes", "security": [ { "WordPressAdmin": [] } ], "responses": { "200": { "description": "Private response; Cache-Control: private, no-store, max-age=0", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "400": { "description": "Invalid activity metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Writer credential missing, rotated or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Administrator required, wrong credential scope, missing nonce or HTTPS required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflict or retention/registry capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON exceeds 4096 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-agent rate limit or serialized write busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable; keep the same request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Native HTTPS administrator issues a one-time event writer credential", "security": [ { "WordPressAdmin": [], "WordPressNonce": [] } ], "responses": { "200": { "description": "Private response; Cache-Control: private, no-store, max-age=0", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneTimeCredential" } } } }, "400": { "description": "Invalid activity metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Writer credential missing, rotated or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Administrator required, wrong credential scope, missing nonce or HTTPS required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflict or retention/registry capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON exceeds 4096 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-agent rate limit or serialized write busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable; keep the same request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgent" } } } } } }, "/agents/{id}/rotate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "post": { "summary": "Native administrator invalidates an earlier key and issues a replacement", "security": [ { "WordPressAdmin": [], "WordPressNonce": [] } ], "responses": { "200": { "description": "Private response; Cache-Control: private, no-store, max-age=0", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneTimeCredential" } } } }, "400": { "description": "Invalid activity metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Writer credential missing, rotated or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Administrator required, wrong credential scope, missing nonce or HTTPS required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflict or retention/registry capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON exceeds 4096 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-agent rate limit or serialized write busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable; keep the same request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agents/{id}/revoke": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "post": { "summary": "Native administrator revokes writes while preserving prior observations", "security": [ { "WordPressAdmin": [], "WordPressNonce": [] } ], "responses": { "200": { "description": "Private response; Cache-Control: private, no-store, max-age=0", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Object" } } } }, "400": { "description": "Invalid activity metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Writer credential missing, rotated or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Administrator required, wrong credential scope, missing nonce or HTTPS required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request conflict or retention/registry capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON exceeds 4096 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-agent rate limit or serialized write busy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable; keep the same request ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "EventWriter": { "type": "apiKey", "in": "header", "name": "X-MusePort-Key", "description": "Per-agent events:write only. Forbidden on GET and management routes. Never place in URLs; refuse credential-bearing redirects." }, "WordPressAdmin": { "type": "apiKey", "in": "cookie", "name": "wordpress_logged_in_SITEHASH", "description": "Existing WordPress administrator identity with manage_options. Replace SITEHASH with the site cookie hash. Use current native session for management." }, "WordPressNonce": { "type": "apiKey", "in": "header", "name": "X-WP-Nonce", "description": "Current wp_rest nonce from the same native administrator session; required for key actions." } }, "schemas": { "Activity": { "type": "object", "additionalProperties": false, "required": [ "request_id", "kind", "state", "occurred_at" ], "properties": { "request_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "maxLength": 120 }, "run_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "maxLength": 80 }, "kind": { "type": "string", "enum": [ "task", "mail_receipt", "heartbeat" ] }, "state": { "type": "string", "enum": [ "queued", "running", "waiting", "succeeded", "failed", "blocked", "cancelled", "observed" ] }, "summary": { "type": "string", "maxLength": 280 }, "occurred_at": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$" }, "outcome": { "type": "string", "enum": [ "none", "accepted", "partial", "rejected", "uncertain" ], "default": "none" }, "delivery": { "type": "string", "enum": [ "not_applicable", "unconfirmed", "confirmed" ], "default": "not_applicable" }, "proof": { "$ref": "#/components/schemas/Proof" } }, "description": "Only minimized activity. Identity is assigned by the writer key. Heartbeat state is observed and cannot affect a run. Task requires run_id; mail_receipt uses observed and its actual SMTP outcome. Delivery confirmation remains an agent-supplied claim requiring provider_receipt, not independent verification." }, "Proof": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "none", "worker_result", "provider_receipt", "manual_check" ] }, "reference": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$", "maxLength": 120 }, "observed_at": { "type": "string", "format": "date-time" } }, "description": "Non-none proof needs opaque reference and observed_at. No URL, private path, contact or credential. Agent reported; observer does not fetch source evidence." }, "EventReceipt": { "type": "object", "required": [ "event_id", "received_at", "agent_id", "replayed" ], "properties": { "event_id": { "type": "integer" }, "received_at": { "type": "string", "description": "Server UTC receipt time, MySQL datetime" }, "agent_id": { "type": "integer" }, "replayed": { "type": "boolean" } } }, "CreateAgent": { "type": "object", "additionalProperties": false, "required": [ "slug", "name" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,39}$" }, "name": { "type": "string", "maxLength": 80 } } }, "OneTimeCredential": { "type": "object", "required": [ "agent", "key", "key_shown_once" ], "properties": { "agent": { "$ref": "#/components/schemas/Object" }, "key": { "type": "string", "description": "Shown once, then only a keyed hash persists. Keep privately on the intended worker; events:write only." }, "key_shown_once": { "const": true } } }, "Feed": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Object" } }, "page": { "type": "integer" }, "per_page": { "type": "integer", "maximum": 100 }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "Error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "status": { "type": "integer" } } } } }, "Object": { "type": "object" } } } }