{
  "openapi": "3.1.0",
  "info": {
    "title": "AXIO Public API",
    "version": "1.0.0",
    "summary": "Read-only company information and contact intake for AXIO.",
    "description": "A small, public, keyless API surface for AI agents and developers integrating with AXIO — a Costa Rica–based AI solutions company building structured, auditable intelligent automation for finance, compliance, analytics, and agentic automation. The `/api/company` endpoint returns AXIO's machine-readable company profile; `/api/contact` accepts an inquiry. No authentication is required for reads. For richer tool-style access, see the MCP manifest at /.well-known/mcp/manifest.json.",
    "contact": {
      "name": "AXIO",
      "email": "axiostaging@proton.me",
      "url": "https://www.axiostaging.com/"
    }
  },
  "servers": [
    { "url": "https://www.axiostaging.com", "description": "Production" }
  ],
  "paths": {
    "/api/company": {
      "get": {
        "operationId": "getCompanyProfile",
        "summary": "Get AXIO's company profile",
        "description": "Returns AXIO's structured company profile — identity, description, founder, contact, service areas, and canonical external profiles (sameAs). Read-only, public, no authentication required. Responses include RFC-draft RateLimit headers so callers can self-throttle.",
        "tags": ["company"],
        "responses": {
          "200": {
            "description": "The AXIO company profile.",
            "headers": {
              "RateLimit-Limit": {
                "description": "Request quota for the current window.",
                "schema": { "type": "integer" }
              },
              "RateLimit-Remaining": {
                "description": "Requests remaining in the current window.",
                "schema": { "type": "integer" }
              },
              "RateLimit-Reset": {
                "description": "Seconds until the current window resets.",
                "schema": { "type": "integer" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CompanyProfile" }
              }
            }
          },
          "429": {
            "description": "Too many requests — retry after the interval in the Retry-After header.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": { "type": "integer" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "operationId": "submitContactInquiry",
        "summary": "Submit a contact inquiry",
        "description": "Sends an inquiry to AXIO and creates an external email side effect. Agents MUST obtain explicit user consent before calling this endpoint and MUST NOT submit autonomous or fabricated leads. Agents should send `Content-Type: application/json` (or `Accept: application/json`) to receive structured JSON responses; the same endpoint also accepts an HTML form submission from the website, which is answered with a 303 redirect instead of JSON.",
        "tags": ["contact"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ContactRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inquiry accepted and delivered.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ContactAccepted" }
              }
            }
          },
          "400": {
            "description": "Invalid request — missing or malformed fields.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "500": {
            "description": "Email delivery is not configured on the server.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "502": {
            "description": "Upstream email delivery failed.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/api/chat": {
      "get": {
        "operationId": "getChatAvailability",
        "summary": "Check assistant availability",
        "description": "Returns whether the AXIO site assistant is currently configured and available on the server. Read-only, public, no authentication required.",
        "tags": ["chat"],
        "responses": {
          "200": {
            "description": "Availability status.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatAvailability" }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postChatMessage",
        "summary": "Send a message to the AXIO assistant",
        "description": "Sends a conversation to the AXIO site assistant and streams the reply as Server-Sent Events (text/event-stream). Each data frame is a JSON object of the form {\"token\": \"...\"} and the stream ends with a [DONE] sentinel. Requires Content-Type: application/json. The client sends the full conversation each turn; the endpoint is stateless.",
        "tags": ["chat"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A Server-Sent Events stream of reply tokens.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE stream. Each `data:` frame is a JSON object {\"token\": string}; the stream terminates with a `[DONE]` frame."
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — malformed JSON body or no usable user message.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "429": {
            "description": "Rate limited — retry after a short interval.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "502": {
            "description": "Upstream model request failed.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "503": {
            "description": "The assistant is not configured or is unavailable.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    },
    "/a2a": {
      "post": {
        "operationId": "sendA2AReadOnlyMessage",
        "summary": "Send a read-only A2A discovery message",
        "description": "Legacy compatibility endpoint for direct read-only A2A service discovery. The canonical asynchronous gateway is https://axio-a2a-gateway.msvv11.workers.dev/a2a; it supports persistent task status and cancellation. Neither endpoint creates commercial, operational or irreversible actions.",
        "tags": ["a2a"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/A2AJsonRpcRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A JSON-RPC response containing a direct A2A agent message.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/A2AJsonRpcResponse" }
              }
            }
          },
          "400": {
            "description": "Malformed JSON-RPC request.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "405": {
            "description": "Only POST is supported by the public A2A beta."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CompanyProfile": {
        "type": "object",
        "description": "AXIO's machine-readable company profile.",
        "required": ["name", "url", "description"],
        "properties": {
          "name": { "type": "string", "example": "AXIO" },
          "legalName": { "type": "string", "example": "AXIO" },
          "url": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "slogan": { "type": "string" },
          "foundingDate": { "type": "string", "example": "2026" },
          "location": {
            "type": "object",
            "properties": {
              "locality": { "type": "string", "example": "Sarchí" },
              "region": { "type": "string", "example": "Alajuela" },
              "country": { "type": "string", "example": "CR" }
            }
          },
          "founder": {
            "type": "object",
            "properties": {
              "name": { "type": "string", "example": "Michael Vega" },
              "jobTitle": { "type": "string", "example": "Founder & CEO" }
            }
          },
          "email": { "type": "string", "format": "email" },
          "languages": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["en", "es"]
          },
          "areaServed": {
            "type": "array",
            "items": { "type": "string" }
          },
          "services": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "summary": { "type": "string" }
              }
            }
          },
          "sameAs": {
            "type": "array",
            "items": { "type": "string", "format": "uri" }
          }
        }
      },
      "ContactRequest": {
        "type": "object",
        "required": ["name", "email"],
        "properties": {
          "name": { "type": "string", "minLength": 1 },
          "email": { "type": "string", "format": "email" },
          "company": { "type": "string" },
          "message": { "type": "string" }
        }
      },
      "ContactAccepted": {
        "type": "object",
        "required": ["ok"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "message": { "type": "string" }
        }
      },
      "ChatAvailability": {
        "type": "object",
        "required": ["available"],
        "properties": {
          "available": {
            "type": "boolean",
            "description": "True when the assistant is configured and can accept messages."
          }
        }
      },
      "ChatRequest": {
        "type": "object",
        "required": ["messages"],
        "properties": {
          "messages": {
            "type": "array",
            "minItems": 1,
            "description": "The full conversation so far, oldest first.",
            "items": {
              "type": "object",
              "required": ["role", "content"],
              "properties": {
                "role": { "type": "string", "enum": ["user", "assistant"] },
                "content": { "type": "string" }
              }
            }
          }
        }
      },
      "A2AJsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "id", "method", "params"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "oneOf": [{ "type": "string" }, { "type": "integer" }] },
          "method": { "type": "string", "const": "SendMessage" },
          "params": {
            "type": "object",
            "required": ["message"],
            "properties": {
              "contextId": { "type": "string" },
              "message": {
                "type": "object",
                "required": ["role", "messageId", "parts"],
                "properties": {
                  "role": { "type": "string", "const": "ROLE_USER" },
                  "messageId": { "type": "string" },
                  "parts": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "required": ["text"],
                      "properties": { "text": { "type": "string", "maxLength": 4000 } }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "A2AJsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc", "id", "result"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "oneOf": [{ "type": "string" }, { "type": "integer" }] },
          "result": {
            "type": "object",
            "required": ["message"],
            "properties": {
              "message": {
                "type": "object",
                "required": ["role", "messageId", "parts"],
                "properties": {
                  "role": { "type": "string", "const": "ROLE_AGENT" },
                  "messageId": { "type": "string" },
                  "contextId": { "type": "string" },
                  "parts": { "type": "array", "items": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string" } } } }
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code.",
                "example": "invalid_request"
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation."
              },
              "hint": {
                "type": "string",
                "description": "Suggested way to resolve the error."
              }
            }
          }
        }
      }
    }
  }
}