{
  "openapi": "3.1.0",
  "info": {
    "title": "Cognitive Industries public API",
    "version": "1.0.0",
    "summary": "Public read and write endpoints behind cognitive-industries.org.",
    "description": "Every endpoint is available at both an unversioned path (/api/...) and a versioned one (/api/v1/...). New clients should use the versioned form. Rate limits return 429 with Retry-After. Errors are JSON with a generic message and a request_id. Full prose reference: https://cognitive-industries.org/docs/api/",
    "contact": {
      "name": "Cognitive Industries",
      "email": "contact@cognitive-industries.org",
      "url": "https://cognitive-industries.org/contact/"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://cognitive-industries.org/terms"
    },
    "termsOfService": "https://cognitive-industries.org/terms"
  },
  "servers": [
    {
      "url": "https://api.cognitive-industries.org",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "API reference",
    "url": "https://cognitive-industries.org/docs/api/"
  },
  "tags": [
    {
      "name": "public-read",
      "description": "Unauthenticated reads. Cached at the edge."
    },
    {
      "name": "public-write",
      "description": "Unauthenticated writes. Turnstile-protected and rate limited."
    },
    {
      "name": "auth",
      "description": "HiveMind single sign-on."
    }
  ],
  "paths": {
    "/api/v1/live": {
      "get": {
        "tags": [
          "public-read"
        ],
        "summary": "Current working status and recent history.",
        "operationId": "getapivlive",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LiveStatus"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/live": {
      "get": {
        "tags": [
          "public-read"
        ],
        "summary": "Current working status and recent history. (unversioned alias)",
        "operationId": "getapivlive",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LiveStatus"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/leaderboard": {
      "get": {
        "tags": [
          "public-read"
        ],
        "summary": "Public bounty debt board.",
        "operationId": "getapivleaderboard",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/LeaderboardEntry"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/leaderboard": {
      "get": {
        "tags": [
          "public-read"
        ],
        "summary": "Public bounty debt board. (unversioned alias)",
        "operationId": "getapivleaderboard",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/LeaderboardEntry"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/donations": {
      "get": {
        "tags": [
          "public-read"
        ],
        "summary": "Top donors.",
        "operationId": "getapivdonations",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/donations": {
      "get": {
        "tags": [
          "public-read"
        ],
        "summary": "Top donors. (unversioned alias)",
        "operationId": "getapivdonations",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/views": {
      "get": {
        "tags": [
          "public-read"
        ],
        "summary": "Site view counter.",
        "operationId": "getapivviews",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/views": {
      "get": {
        "tags": [
          "public-read"
        ],
        "summary": "Site view counter. (unversioned alias)",
        "operationId": "getapivviews",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/contact": {
      "post": {
        "tags": [
          "public-write"
        ],
        "summary": "Send a contact message.",
        "operationId": "postContact",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactMessage"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "description": "Bot check failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/contact": {
      "post": {
        "tags": [
          "public-write"
        ],
        "summary": "Send a contact message.",
        "operationId": "postContact",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactMessage"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "description": "Bot check failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/auth/login": {
      "get": {
        "tags": [
          "auth"
        ],
        "summary": "Begin HiveMind SSO (OIDC + PKCE).",
        "operationId": "authLogin",
        "responses": {
          "302": {
            "description": "Redirect to the identity provider."
          }
        }
      }
    },
    "/auth/me": {
      "get": {
        "tags": [
          "auth"
        ],
        "summary": "Current session identity.",
        "operationId": "authMe",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Identity."
          },
          "401": {
            "description": "Not signed in."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "hive_session",
        "description": "Signed, HttpOnly session cookie minted after HiveMind SSO login."
      },
      "bearerToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Capability-scoped machine token. One capability per token."
      }
    },
    "responses": {
      "RateLimited": {
        "description": "Rate limit exceeded.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds to wait before retrying."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Validation failed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooLarge": {
        "description": "Request body exceeds the size limit.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "A generic, non-revealing message.",
            "examples": [
              "invalid"
            ]
          },
          "request_id": {
            "type": "string",
            "description": "Quote this when reporting a problem."
          }
        }
      },
      "LiveStatus": {
        "type": "object",
        "properties": {
          "current": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "project": {
                "type": "string"
              },
              "status": {
                "type": "string"
              },
              "since": {
                "type": "integer",
                "description": "Unix milliseconds."
              }
            }
          },
          "history": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "project": {
                  "type": "string"
                },
                "at": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "LeaderboardEntry": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "critical"
            ]
          },
          "amount": {
            "type": "number"
          },
          "paid": {
            "type": "boolean"
          }
        }
      },
      "ContactMessage": {
        "type": "object",
        "required": [
          "name",
          "email",
          "message"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 200
          },
          "type": {
            "type": "string",
            "enum": [
              "general",
              "project",
              "collaboration",
              "media",
              "other"
            ],
            "default": "general"
          },
          "message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 5000
          },
          "turnstile": {
            "type": "string",
            "description": "Cloudflare Turnstile token. Required once Turnstile is configured."
          }
        },
        "additionalProperties": false
      }
    }
  }
}