openapi: 3.1.0
info:
  title: Sightmap HTTP API
  summary: Public read-only HTTP API for the Sightmap site and Atlas catalog
  description: "Machine-readable surface of https://sightmap.org. No authentication. Errors are JSON objects with error.code, error.message, and error.hint."
  version: 1.0.0
  license:
    name: MIT
    identifier: MIT
    url: "https://github.com/sightmap/sightmap/blob/main/LICENSE"
  contact:
    name: Sightmap
    url: "https://github.com/sightmap/sightmap"
servers:
  - url: "https://sightmap.org"
    description: Sightmap production
tags:
  - name: Atlas
    description: Community-contributed sightmaps of live sites
  - name: Discovery
    description: Site index and specification documents
paths:
  "/openapi.json":
    get:
      tags:
        - Discovery
      summary: OpenAPI specification
      operationId: getOpenApi
      responses:
        "200":
          description: OpenAPI 3.1 document
          content:
            application/json:
              schema:
                type: object
  "/api/openapi.yaml":
    get:
      tags:
        - Discovery
      summary: OpenAPI specification (YAML)
      operationId: getOpenApiYaml
      responses:
        "200":
          description: OpenAPI 3.1 document in YAML
          content:
            application/yaml:
              schema:
                type: string
  "/api/atlas":
    get:
      tags:
        - Atlas
      summary: List published Atlas entries
      operationId: listAtlas
      responses:
        "200":
          description: Atlas catalog
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AtlasCatalog"
        "404":
          "$ref": "#/components/responses/NotFound"
  "/api/atlas/{slug}":
    get:
      tags:
        - Atlas
      summary: Get one Atlas entry
      operationId: getAtlasEntry
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: "Atlas entry slug, e.g. airbnb"
      responses:
        "200":
          description: One Atlas entry plus machine-twin URLs
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/AtlasEntry"
        "404":
          "$ref": "#/components/responses/NotFound"
  "/llms.txt":
    get:
      tags:
        - Discovery
      summary: Agent site index (llmstxt.org)
      operationId: getLlmsTxt
      responses:
        "200":
          description: Plain-text site index
          content:
            text/plain:
              schema:
                type: string
  "/atlas/index.json":
    get:
      tags:
        - Atlas
      summary: Vendored Atlas index (full gallery record)
      operationId: getAtlasIndex
      responses:
        "200":
          description: Full Atlas index.json
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    Error:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
            - hint
            - status
          properties:
            code:
              type: string
              examples:
                - not_found
            message:
              type: string
            hint:
              type: string
              description: Where an agent should look next to recover.
            status:
              type: integer
    AtlasEntry:
      type: object
      required:
        - slug
        - name
        - domains
        - html
        - markdown
        - archive
      properties:
        slug:
          type: string
        name:
          type: string
        site_url:
          type: string
          format: uri
        domains:
          type: array
          items:
            type: string
        description:
          type: string
        categories:
          type: array
          items:
            type: string
        updated:
          type: string
        last_verified:
          type: string
        stats:
          type: object
          properties:
            views:
              type: integer
            components:
              type: integer
            requests:
              type: integer
        html:
          type: string
          format: uri
        markdown:
          type: string
          format: uri
        archive:
          type: string
          format: uri
    AtlasCatalog:
      type: object
      required:
        - schema_version
        - entries
      properties:
        schema_version:
          type: integer
        entries:
          type: array
          items:
            "$ref": "#/components/schemas/AtlasEntry"
  responses:
    NotFound:
      description: Structured JSON error
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Error"
