openapi: 3.0.0
info:
  title: SpaceAPI Collector
  description: >-
    The SpaceAPI Collector is a central directory API that aggregates endpoints from
    hackerspaces, makerspaces, fablabs, and similar community spaces around the world
    that implement the SpaceAPI standard. It returns a list of all registered spaces
    with their status endpoint URLs, validity status, names, and last-seen timestamps.
  version: 0.0.1
  contact:
    email: spaceapi-team@chaospott.de
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://spaceapi.io/daemon/terms
externalDocs:
  description: Find out more about SpaceAPI
  url: https://spaceapi.io
servers:
  - url: https://collector.spaceapi.io
    description: SpaceAPI Collector production server
tags:
  - name: Directory
    description: SpaceAPI directory listing operations
paths:
  /:
    get:
      operationId: listSpaces
      summary: List All Spaces
      description: >-
        Returns the full SpaceAPI directory — a list of all registered hackerspaces,
        makerspaces, and fablabs that implement the SpaceAPI standard. Each entry
        includes the space endpoint URL, validity status, space name, last-seen timestamp,
        and any error messages for unreachable endpoints.
      tags:
        - Directory
      responses:
        '200':
          description: Successful operation — returns the full directory of registered spaces
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryEntry'
              example:
                items:
                  - url: https://hackerspace.example.org/spaceapi.json
                    valid: true
                    space: Example Hackerspace
                    lastSeen: 1714652400
                  - url: https://makerspace.example.com/status.json
                    valid: false
                    space: Example Makerspace
                    lastSeen: 1714500000
                    errMsg: Connection timeout
        '500':
          description: Internal server error
components:
  schemas:
    DirectoryEntry:
      description: Internal SpaceAPI Directory entry containing all registered spaces
      type: object
      properties:
        items:
          description: List of directory entries for all registered spaces
          type: array
          items:
            $ref: '#/components/schemas/SpaceEntry'
    SpaceEntry:
      description: A single space registered in the SpaceAPI directory
      type: object
      required:
        - url
        - valid
      properties:
        url:
          description: URL to the space's SpaceAPI JSON endpoint
          type: string
          format: uri
          example: https://hackerspace.example.org/spaceapi.json
        valid:
          description: Indicates whether the space's endpoint provides a valid SpaceAPI JSON file
          type: boolean
          example: true
        space:
          description: The name of the hackerspace or makerspace
          type: string
          example: Example Hackerspace
        lastSeen:
          description: >-
            Unix timestamp of the last time the endpoint was reachable and provided
            valid JSON (does not require it to have been valid SpaceAPI)
          type: number
          format: int64
          example: 1714652400
        errMsg:
          description: Error message if an issue was found with the specific endpoint
          type: string
          example: Connection timeout
        data:
          description: Raw JSON from the last successful scraping of the space's endpoint
          type: object