{
  "openapi": "3.1.0",
  "info": {
    "title": "lobo.sh Public API",
    "version": "1.0.0",
    "description": "Public programmatic REST API for lobo.sh by Gabriel Lobo. Designed for AI autonomous agents, software engineers, and LLM function-calling tool execution. Versioning Policy: Explicit URI path versioning (/api/v1/...). Deprecation Policy: Any deprecated endpoints emit standard RFC 8594 'Sunset' and RFC 9594 'Deprecation' response headers with a guaranteed minimum 12-month migration window prior to removal. Rate Limiting: 60 requests/minute per client with standard RFC RateLimit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy) and Retry-After on 429.",
    "contact": {
      "name": "Gabriel Lobo",
      "url": "https://lobo.sh/contact",
      "email": "gabrielrblgbi@gmail.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://lobo.sh",
      "description": "Production server (public read-only access, no authentication required)"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/profile": {
      "get": {
        "operationId": "getProfile",
        "security": [],
        "summary": "Retrieve author profile and technical focus",
        "description": "Returns the verified professional profile, core focus areas, engineering philosophy, and canonical contact links for Gabriel Lobo.",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language code for profile details ('en' for English, 'pt' for Portuguese).",
            "schema": {
              "type": "string",
              "enum": ["en", "pt"],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Profile information successfully retrieved",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfileResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/essays": {
      "get": {
        "operationId": "listEssays",
        "security": [],
        "summary": "List all technical essays",
        "description": "Returns a catalog of published technical essays on software architecture, distributed systems, and operational reliability. Supports filtering by language.",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Filter essays by language code ('en' for English, 'pt' for Portuguese).",
            "schema": {
              "type": "string",
              "enum": ["en", "pt"],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of technical essays retrieved successfully",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EssayListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/essays/{slug}": {
      "get": {
        "operationId": "getEssayBySlug",
        "security": [],
        "summary": "Retrieve a specific essay by slug",
        "description": "Fetches the full content, metadata, tags, and architectural insights of an essay identified by its slug.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The unique URL slug of the essay (e.g. 'architecture-decisions').",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Essay details successfully retrieved",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EssayDetailResponse"
                }
              }
            }
          },
          "404": {
            "description": "Essay not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "operationId": "searchContent",
        "security": [],
        "summary": "Search articles, architecture principles, and developer resources",
        "description": "Queries the site content index for topics, essays, and architectural principles matching a query string.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Keywords to match against essay titles, descriptions, and tags.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results matching query",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "getApiHealth",
        "security": [],
        "summary": "Check API health status and version",
        "description": "Returns service operational status, version number, deprecation policy, and links to documentation.",
        "parameters": [
          {
            "name": "verbose",
            "in": "query",
            "required": false,
            "description": "Whether to include complete endpoint catalog in output.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {},
    "headers": {
      "RateLimit-Limit": {
        "description": "Maximum requests allowed per minute (RFC draft-ietf-httpapi-ratelimit-headers).",
        "schema": { "type": "integer", "example": 60 }
      },
      "RateLimit-Remaining": {
        "description": "Remaining requests allowed in the current minute window.",
        "schema": { "type": "integer", "example": 59 }
      },
      "RateLimit-Reset": {
        "description": "Seconds remaining until window quota resets.",
        "schema": { "type": "integer", "example": 60 }
      },
      "RateLimit-Policy": {
        "description": "Rate limit quota and window specification.",
        "schema": { "type": "string", "example": "60;w=60" }
      },
      "Deprecation": {
        "description": "Signals whether the resource or version is deprecated (RFC 9594).",
        "schema": { "type": "string", "example": "false" }
      },
      "Sunset": {
        "description": "HTTP-date indicating when the deprecated resource will be removed (RFC 8594).",
        "schema": { "type": "string", "example": "Sun, 01 Mar 2028 00:00:00 GMT" }
      }
    },
    "responses": {
      "TooManyRequests": {
        "description": "Rate limit exceeded. Self-throttle using Retry-After header.",
        "headers": {
          "Retry-After": {
            "description": "Number of seconds to wait before retrying.",
            "schema": { "type": "integer", "example": 60 }
          },
          "RateLimit-Reset": {
            "description": "Seconds until rate limit window resets.",
            "schema": { "type": "integer", "example": 60 }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ProfileLinks": {
        "type": "object",
        "required": [
          "website",
          "github",
          "linkedin",
          "email",
          "developers",
          "openapi",
          "llms_txt",
          "sitemap",
          "agent_instructions",
          "about",
          "contact",
          "privacy"
        ],
        "properties": {
          "website": { "type": "string", "example": "https://lobo.sh" },
          "github": { "type": "string", "example": "https://github.com/gabrielrbl" },
          "linkedin": { "type": "string", "example": "https://www.linkedin.com/in/gabrielrbl/" },
          "email": { "type": "string", "example": "gabrielrblgbi@gmail.com" },
          "developers": { "type": "string", "example": "https://lobo.sh/developers" },
          "openapi": { "type": "string", "example": "https://lobo.sh/openapi.json" },
          "llms_txt": { "type": "string", "example": "https://lobo.sh/llms.txt" },
          "llms_full_txt": { "type": "string", "example": "https://lobo.sh/llms-full.txt" },
          "sitemap": { "type": "string", "example": "https://lobo.sh/sitemap-index.xml" },
          "agent_instructions": { "type": "string", "example": "https://lobo.sh/agent-instructions.md" },
          "about": { "type": "string", "example": "https://lobo.sh/about" },
          "contact": { "type": "string", "example": "https://lobo.sh/contact" },
          "privacy": { "type": "string", "example": "https://lobo.sh/privacy" }
        }
      },
      "ProfileResponse": {
        "type": "object",
        "required": ["name", "title", "domain", "bio", "focus", "links"],
        "properties": {
          "name": { "type": "string", "example": "Gabriel Lobo" },
          "title": { "type": "string", "example": "Software Engineer & Systems Architect" },
          "domain": { "type": "string", "example": "https://lobo.sh" },
          "bio": { "type": "string" },
          "focus": {
            "type": "array",
            "items": { "type": "string" }
          },
          "links": {
            "$ref": "#/components/schemas/ProfileLinks"
          }
        }
      },
      "EssaySummary": {
        "type": "object",
        "required": ["id", "slug", "title", "description", "lang", "url", "markdown_url", "api_url"],
        "properties": {
          "id": { "type": "string", "example": "architecture-decisions/en" },
          "slug": { "type": "string", "example": "architecture-decisions" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "date": { "type": ["string", "null"], "example": "2026-03" },
          "lang": { "type": "string", "enum": ["en", "pt"] },
          "tags": {
            "type": "array",
            "items": { "type": "string" }
          },
          "url": { "type": "string" },
          "markdown_url": { "type": "string" },
          "api_url": { "type": "string" }
        }
      },
      "EssayListResponse": {
        "type": "object",
        "required": ["count", "essays"],
        "properties": {
          "count": { "type": "integer" },
          "essays": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/EssaySummary" }
          }
        }
      },
      "EssayDetailResponse": {
        "type": "object",
        "required": ["slug", "title", "description", "lang", "content", "canonical_url", "markdown_url"],
        "properties": {
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "date": { "type": ["string", "null"], "example": "2026-03" },
          "lang": { "type": "string", "enum": ["en", "pt"] },
          "tags": {
            "type": "array",
            "items": { "type": "string" }
          },
          "canonical_url": { "type": "string" },
          "markdown_url": { "type": "string" },
          "translations": {
            "type": "object",
            "properties": {
              "en": { "type": ["string", "null"] },
              "pt": { "type": ["string", "null"] }
            }
          },
          "content": { "type": "string", "description": "Full Markdown/MDX essay content" }
        }
      },
      "SearchResultItem": {
        "type": "object",
        "required": ["title", "description", "url", "type", "lang"],
        "properties": {
          "title": { "type": "string" },
          "description": { "type": "string" },
          "url": { "type": "string" },
          "markdown_url": { "type": "string" },
          "type": {
            "type": "string",
            "enum": ["essay", "page", "developer_resource", "trust_anchor"]
          },
          "lang": { "type": "string", "enum": ["en", "pt"] },
          "tags": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": ["query", "total", "results"],
        "properties": {
          "query": { "type": "string" },
          "total": { "type": "integer" },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResultItem"
            }
          }
        }
      },
      "HealthVersioning": {
        "type": "object",
        "required": ["current", "status", "deprecation_policy"],
        "properties": {
          "current": { "type": "string", "example": "v1" },
          "status": { "type": "string", "example": "active" },
          "deprecation_policy": {
            "type": "string",
            "example": "https://lobo.sh/developers#versioning-and-deprecation"
          },
          "sunset": { "type": ["string", "null"], "example": null }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": ["status", "service", "version", "openapi", "documentation", "versioning", "endpoints"],
        "properties": {
          "status": { "type": "string", "example": "healthy" },
          "service": { "type": "string", "example": "lobo.sh API" },
          "version": { "type": "string", "example": "1.0.0" },
          "timestamp": { "type": "string" },
          "openapi": { "type": "string", "example": "https://lobo.sh/openapi.json" },
          "documentation": { "type": "string", "example": "https://lobo.sh/developers" },
          "versioning": {
            "$ref": "#/components/schemas/HealthVersioning"
          },
          "endpoints": {
            "type": "object",
            "properties": {
              "profile": { "type": "string" },
              "essays": { "type": "string" },
              "search": { "type": "string" },
              "health": { "type": "string" }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "resolution_hint"],
            "properties": {
              "code": {
                "type": "string",
                "description": "Machine-readable error identifier",
                "example": "NOT_FOUND"
              },
              "message": {
                "type": "string",
                "description": "Clear human-readable error description",
                "example": "The requested resource could not be found."
              },
              "resolution_hint": {
                "type": "string",
                "description": "Actionable instructions for AI agents or callers to recover",
                "example": "Consult the API catalog at GET /api/v1/essays or visit https://lobo.sh/developers."
              }
            }
          }
        }
      }
    }
  }
}