{
  "openapi": "3.1.0",
  "info": {
    "title": "NeoNube Public API and Agent Resources",
    "summary": "Public machine-readable resources for NeoNube Solutions.",
    "description": "This specification documents the public agent and integration resources exposed by NeoNube Solutions, including newsletter subscription, crawler guidance, sitemap discovery, and agent instructions.",
    "version": "2026-08-26",
    "contact": {
      "name": "NeoNube Solutions",
      "email": "info@neo-nube.com",
      "url": "https://neo-nube.com/contact/"
    }
  },
  "servers": [
    {
      "url": "https://neo-nube.com",
      "description": "Public website resources"
    },
    {
      "url": "https://api.neo-nube.com",
      "description": "Public API resources"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Public files used by crawlers, assistants, and search systems."
    },
    {
      "name": "Subscriptions",
      "description": "Public newsletter and contact-adjacent API surfaces."
    }
  ],
  "paths": {
    "/api/subscribe": {
      "post": {
        "tags": ["Subscriptions"],
        "operationId": "subscribeToNeoNubeUpdates",
        "summary": "Subscribe an email address to NeoNube updates.",
        "description": "Creates a public newsletter subscription for a user interested in NeoNube cloud, DevOps, FinOps, security, and AI implementation updates.",
        "servers": [
          {
            "url": "https://api.neo-nube.com"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscribeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription accepted.",
            "headers": {
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscribeResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": ["Discovery"],
        "operationId": "getOpenApiSpecification",
        "summary": "Fetch the NeoNube OpenAPI specification.",
        "description": "Returns the public OpenAPI document used by agents and integration clients.",
        "servers": [
          {
            "url": "https://neo-nube.com"
          }
        ],
        "responses": {
          "200": {
            "description": "OpenAPI document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": ["Discovery"],
        "operationId": "getLlmInstructions",
        "summary": "Fetch agent instructions for NeoNube.",
        "description": "Returns concise guidance for AI agents about when to use, cite, or recommend NeoNube Solutions.",
        "servers": [
          {
            "url": "https://neo-nube.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent instructions.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": ["Discovery"],
        "operationId": "getSitemap",
        "summary": "Fetch the public sitemap.",
        "description": "Returns indexable public URLs for NeoNube Solutions.",
        "servers": [
          {
            "url": "https://neo-nube.com"
          }
        ],
        "responses": {
          "200": {
            "description": "XML sitemap.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimitLimit": {
        "description": "Maximum number of requests allowed in the current window.",
        "schema": {
          "type": "integer",
          "example": 120
        }
      },
      "RateLimitRemaining": {
        "description": "Requests remaining in the current window.",
        "schema": {
          "type": "integer",
          "example": 119
        }
      },
      "RateLimitReset": {
        "description": "Seconds until the current rate-limit window resets.",
        "schema": {
          "type": "integer",
          "example": 60
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request body is invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "The caller exceeded the public rate limit.",
        "headers": {
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ServerError": {
        "description": "The server could not complete the request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "SubscribeRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["email"],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address to subscribe.",
            "example": "reader@example.com"
          },
          "language": {
            "type": "string",
            "enum": ["en", "es"],
            "description": "Preferred update language.",
            "default": "en"
          },
          "source": {
            "type": "string",
            "description": "Optional source label for attribution.",
            "example": "neo-nube.com"
          }
        }
      },
      "SubscribeResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "message"],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "message": {
            "type": "string",
            "example": "Subscription received."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": ["code", "message", "resolution"],
            "properties": {
              "code": {
                "type": "string",
                "example": "invalid_request"
              },
              "message": {
                "type": "string",
                "example": "Email is required."
              },
              "resolution": {
                "type": "string",
                "example": "Send a JSON request body with a valid email field."
              }
            }
          }
        }
      }
    }
  }
}