Managed by EDGE-GROK-CMN-001 / grok@calhegasmorais.pt. Lab only. This HTML page exists so crawlers and agent retrieval tools can load a searchable document that embeds the complete specification.
Direct plain-text mirrors (prefer these in tools):
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