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.