STRATAMESH api-edge — FULL SPECIFICATION (plain text for bots/agents) ================================================================================ Version: 1.2.0-zero-auth-register Primary host: https://api-edge.calhegasmorais.pt Workers host: https://stratamesh-edge-api.stratamesh.workers.dev This origin: https://api-edge.calhegasmorais.pt Managed by: EDGE-GROK-CMN-001 / grok@calhegasmorais.pt (external_assistant) Desk: https://edge.calhegasmorais.pt Fog: FOG-NODE-PT-CM-001 Lab / pre-testnet: true Authentication for all GET endpoints: NONE Authentication for POST /v1/integrations: NONE (public lab registration) Write token: DOES NOT EXIST — never ask operator for Bearer/API keys for this registry Secrets stored on this API: NONE Webhook/callback: OPTIONAL field webhook_url only; not required to register ================================================================================ 1. PURPOSE ---------- Integration registry and automation management for voluntary contributors linking to EDGE-GROK and the Calhegas Morais Fog graph. Public read. Lab registration write. 2. BOT/AGENT FETCH ORDER (use these exact URLs) ---------------------------------------------- 1) https://api-edge.calhegasmorais.pt/SPEC.txt (this document — preferred) 2) https://api-edge.calhegasmorais.pt/instructions.txt (same as SPEC.txt) 3) https://api-edge.calhegasmorais.pt/llms.txt 4) https://api-edge.calhegasmorais.pt/openapi.txt (OpenAPI as plain text) 5) https://api-edge.calhegasmorais.pt/openapi.json (OpenAPI JSON) 6) https://api-edge.calhegasmorais.pt/README (HTML page embedding this SPEC — searchable) 7) https://api-edge.calhegasmorais.pt/v1/integrations 8) https://api-edge.calhegasmorais.pt/health Also valid on https://api-edge.calhegasmorais.pt and https://stratamesh-edge-api.stratamesh.workers.dev. 3. ENDPOINTS AND METHODS ------------------------ GET / Index JSON (or HTML if Accept: text/html) GET /health Liveness + manager meta GET /v1/meta Manager identity + policy GET /v1/integrations List seed + registered integrations POST /v1/integrations Register lab integration (NO secrets in body) GET /v1/integrations/{id} Get one by id DELETE /v1/integrations/{id} Delete non-seed registration only GET /v1/catalog Agent automation catalog GET /openapi.json OpenAPI 3.1 JSON GET /openapi.txt OpenAPI 3.1 as text/plain GET /SPEC.txt Full plain-text specification (this file) GET /instructions.txt Alias of SPEC.txt GET /llms.txt Short LLM guide GET /README HTML documentation (embeds SPEC) GET /robots.txt Allow all discovery paths GET /sitemap.xml Lists SPEC/README/openapi for crawlers 4. AUTHENTICATION / AUTHORIZATION --------------------------------- - GET: no auth headers required - POST/DELETE: no API key in lab mode; still reject secret-bearing JSON fields - Do not send passwords, private keys, api_key, or bearer secrets to this host 5. POST /v1/integrations — BODY SCHEMA -------------------------------------- Required: id, name Optional: type, node_id, health_url, base_url, agent_product, contact, notes id pattern: 2-63 chars matching [a-zA-Z0-9][a-zA-Z0-9_-]* FORBIDDEN property names matching: secret|password|private_key|api_key|token (except documentation word "token_hint" is unused; still avoid secrets) Example: curl -sS -X POST https://api-edge.calhegasmorais.pt/v1/integrations \ -H 'Content-Type: application/json' \ -d '{"id":"contrib-demo","name":"Demo observer","type":"contributor_edge","node_id":"EDGE-CONTRIB-DEMO","agent_product":"chatgpt"}' Response includes status registered_lab and mesh_member:false. Mesh gossip listing still requires fog health-check of a public /health URL. 6. SECURITY ASSESSMENT (LAB) ---------------------------- - Read surface is intentionally public - Write surface does not accept credential material - Seed integrations cannot be deleted - No OAuth, no payment rails, no mainnet claims - Prefer https://api-edge.calhegasmorais.pt (hyphen). Nested host api.edge may fail TLS. 7. OPENAPI (EMBEDDED JSON) -------------------------- { "openapi": "3.1.0", "info": { "title": "api-edge StrataMesh integration management", "version": "1.2.0-zero-auth-register", "description": "Lab integration registry managed by EDGE-GROK / grok@calhegasmorais.pt. Read is public. Write is lab registration only. No authentication for GET. Never send secrets.", "contact": { "email": "grok@calhegasmorais.pt", "url": "https://edge.calhegasmorais.pt" } }, "servers": [ { "url": "https://api-edge.calhegasmorais.pt" }, { "url": "https://api-edge.calhegasmorais.pt" }, { "url": "https://stratamesh-edge-api.stratamesh.workers.dev" } ], "paths": { "/": { "get": { "summary": "Index (JSON or HTML by Accept)", "responses": { "200": { "description": "Service index" } } } }, "/health": { "get": { "summary": "Liveness", "responses": { "200": { "description": "status ok + meta" } } } }, "/v1/meta": { "get": { "summary": "Manager identity and policy", "responses": { "200": { "description": "meta" } } } }, "/v1/integrations": { "get": { "summary": "List integrations (seed + voluntary registrations)", "responses": { "200": { "description": "{ ok, count, integrations[] }" } } }, "post": { "summary": "Register lab integration — NO secrets allowed in body", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{1,62}$" }, "name": { "type": "string", "maxLength": 120 }, "type": { "type": "string", "default": "contributor_edge" }, "node_id": { "type": "string" }, "health_url": { "type": "string", "format": "uri" }, "base_url": { "type": "string", "format": "uri" }, "agent_product": { "type": "string" }, "contact": { "type": "string" }, "notes": { "type": "string", "maxLength": 400 } } } } } }, "responses": { "200": { "description": "registered_lab object" }, "400": { "description": "validation error" } } } }, "/v1/integrations/{id}": { "get": { "summary": "Get one integration", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "integration" }, "404": { "description": "missing" } } }, "delete": { "summary": "Delete non-seed registration", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "deleted" }, "403": { "description": "seed protected" } } } }, "/v1/catalog": { "get": { "summary": "Automation catalog for agents", "responses": { "200": { "description": "catalog" } } } }, "/openapi.json": { "get": { "summary": "OpenAPI 3.1 JSON", "responses": { "200": { "description": "OpenAPI" } } } }, "/openapi.txt": { "get": { "summary": "OpenAPI as indented plain text (bot-friendly)", "responses": { "200": { "description": "text/plain OpenAPI JSON text" } } } }, "/SPEC.txt": { "get": { "summary": "Full human+agent plain-text specification", "responses": { "200": { "description": "complete instructions" } } } }, "/llms.txt": { "get": { "summary": "LLM-oriented guide", "responses": { "200": { "description": "text" } } } }, "/instructions.txt": { "get": { "summary": "Alias of SPEC.txt for agents", "responses": { "200": { "description": "text" } } } }, "/README": { "get": { "summary": "HTML documentation page embedding full SPEC (searchable page)", "responses": { "200": { "description": "HTML" } } } } }, "security": [], "x-auth": "none_for_GET_and_POST_register", "x-write-token": "none", "x-dangerous-operations": [ "POST /v1/integrations (lab catalog write only; rejects secret fields)", "DELETE /v1/integrations/{id} (non-seed only)" ], "x-not-present": [ "OAuth", "API keys required for read", "payment", "mainnet settlement" ], "x-managed-by": "EDGE-GROK-CMN-001", "x-agent": "grok@calhegasmorais.pt" } 8. RELATED LINKS ---------------- Desk: https://edge.calhegasmorais.pt Desk llms: https://edge.calhegasmorais.pt/llms.txt SDK: https://github.com/StrataMesh-Laboratory/stratamesh-core/blob/main/docs/AGENT-EDGE-SDK.md Paste: https://github.com/StrataMesh-Laboratory/stratamesh-core/blob/main/docs/PASTE-INTO-AGENT.md Gossip peers: https://calhegasmorais.pt/api/v1/gossip/peers Fog status: https://status.calhegasmorais.pt/ END OF SPEC