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.5.0-wizard
Primary host: https://api-edge.calhegasmorais.pt
This origin: https://api-edge.calhegasmorais.pt
Managed by: EDGE-GROK-CMN-001 / grok@calhegasmorais.pt (external_assistant, continuity=session)
Desk: https://edge.calhegasmorais.pt
Fog: FOG-NODE-PT-CM-001
Fog installer API: https://api-fog.calhegasmorais.pt
Lab / pre-testnet: true · not mainnet
Mesh honesty: n=2 · mesh_member=true (this Edge + Mac Fog) · f_max=0 · oracle_live=false
Authentication for GET endpoints: NONE except GET /desk (Bearer DESK_TOKEN)
Authentication for POST /v1/integrations: NONE (public lab registration)
Authentication for GET+POST /desk: Bearer DESK_TOKEN (wrangler secret / dashboard; never git)
Write token: DOES NOT EXIST — never ask operator for Bearer/API keys for this registry
Secrets stored on this API: NONE (VA key hashes only)
workers.dev: DO NOT CALL
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. Fog hardware install is https://api-fog.calhegasmorais.pt, not this host.
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
GET /v1/va/instructions.txt Personal VA setup (AI-readable). Does NOT replace this registry.
GET /v1/va/me Account VA identity (Bearer smva_)
POST /v1/va/act Allow-listed dashboard remote control (Bearer smva_)
GET /v1/mesh Live Fog / Edge / Gossip / api-fog probes
GET /desk desk.snapshot.v1 (mail + collegium + feed_tail) — Bearer DESK_TOKEN
POST /desk Push snapshot or legacy mail digest — Bearer DESK_TOKEN (vault holders)
Fog installer (different host): https://api-fog.calhegasmorais.pt/SPEC.txt
4. AUTHENTICATION / AUTHORIZATION
---------------------------------
- GET registry: no auth headers required
- POST/DELETE /v1/integrations: no API key in lab mode; still reject secret-bearing JSON fields
- Do not send passwords, private keys, api_key, or bearer secrets to the *registry*
- Personal VA is a *separate* surface: /v1/va/* (except instructions) uses Authorization: Bearer smva_…
- VA keys are hashed at rest. Raw token shown once at mint. Zero-auth registry is unchanged.
- GET+POST /desk: Authorization: Bearer matching env DESK_TOKEN (timing-safe). 401 otherwise. Cache-Control: no-store.
- DESK_TOKEN is never in git. Set only with wrangler secret put DESK_TOKEN or the Cloudflare dashboard.
- /desk stores last sanitized digest in existing API_KV (dashboard binding; do not add kv_namespaces in git). Worker isolate memory is a fallback only.
- /desk JSON: desk.snapshot.v1 = mail headers + collegium open_tasks + feed_tail. No bodies, no IMAP/vault secrets. Bearer holders only (Mac/box vault desk-mail.token).
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.
- Fog MacOS installer lives on https://api-fog.calhegasmorais.pt (node_id + 2FA). Do not POST ghp_/cfat_ here.
7. OPENAPI (EMBEDDED JSON)
--------------------------
{
"openapi": "3.1.0",
"info": {
"title": "api-edge StrataMesh integration management",
"version": "1.5.0-wizard",
"description": "Lab integration registry + optional personal VA. Mesh honesty n=2 (this Edge + Mac Fog), f_max=0, oracle_live=false. Fog installer is a different host: https://api-fog.calhegasmorais.pt. Read is public. Write is lab registration only. Never send secrets. Do not call workers.dev.",
"contact": {
"email": "grok@calhegasmorais.pt",
"url": "https://edge.calhegasmorais.pt"
}
},
"servers": [
{
"url": "https://api-edge.calhegasmorais.pt"
},
{
"url": "https://api-edge.calhegasmorais.pt"
}
],
"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"
}
}
}
},
"/desk": {
"get": {
"summary": "Last sanitized automation-desk mail digest (headers only)",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "{mailbox, ts, n, latest:[{date,from,subject}]}"
},
"401": {
"description": "missing/invalid Bearer"
}
}
},
"post": {
"summary": "Store sanitized mail digest (no bodies)",
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"mailbox": {
"type": "string"
},
"ts": {
"type": "string"
},
"n": {
"type": "integer"
},
"latest": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"from": {
"type": "string"
},
"subject": {
"type": "string"
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "stored sanitized digest"
},
"401": {
"description": "missing/invalid Bearer"
}
}
}
}
},
"security": [],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "env DESK_TOKEN via wrangler secret put / dashboard only"
}
}
},
"x-auth": "none_for_GET_and_POST_register_except_/desk",
"x-write-token": "none",
"x-dangerous-operations": [
"POST /v1/integrations (lab catalog write only; rejects secret fields)",
"DELETE /v1/integrations/{id} (non-seed only)",
"GET+POST /desk (Bearer DESK_TOKEN; snapshot v1 + legacy mail)"
],
"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 public: https://fog.calhegasmorais.pt/health
Fog installer: https://api-fog.calhegasmorais.pt/SPEC.txt
Gossip: https://gossip.calhegasmorais.pt
END OF SPEC