{
  "openapi": "3.1.0",
  "info": {
    "title": "Prompt Observatory Agent API",
    "version": "1.0.0",
    "description": "Voluntary reports of authorised public prompt use. Test traffic is excluded from all public counts."
  },
  "servers": [
    {
      "url": "https://prompts.taoclimate.com"
    }
  ],
  "paths": {
    "/api/v1/prompts": {
      "get": {
        "operationId": "get_prompts",
        "summary": "List the accepted public prompt IDs",
        "responses": {
          "200": {
            "description": "List the accepted public prompt IDs"
          }
        }
      }
    },
    "/api/v1/live": {
      "get": {
        "operationId": "get_live",
        "summary": "Read minute-level self-reports for the current hour and comparison window",
        "responses": {
          "200": {
            "description": "Read minute-level self-reports for the current hour and comparison window"
          }
        }
      }
    },
    "/api/v1/totals": {
      "get": {
        "operationId": "get_totals",
        "summary": "Get aggregate volumes by UTC day",
        "responses": {
          "200": {
            "description": "Get aggregate volumes by UTC day"
          }
        },
        "parameters": [
          {
            "in": "query",
            "name": "days",
            "schema": {
              "type": "integer",
              "enum": [
                1,
                7,
                30
              ],
              "default": 30
            }
          }
        ]
      }
    },
    "/api/v1/reports": {
      "post": {
        "operationId": "submit_report",
        "summary": "Submit one authorised, voluntary prompt use or a test event",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "prompt_id",
                  "event_id",
                  "mode"
                ],
                "properties": {
                  "prompt_id": {
                    "type": "string",
                    "enum": [
                      "fill-this-room",
                      "vibe-coding",
                      "deep-research",
                      "explain-like",
                      "future-field-notes",
                      "hidden-history",
                      "decision-rehearsal",
                      "one-object-museum"
                    ]
                  },
                  "event_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "UUIDv4, stable across retries for one event"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "test",
                      "live"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Accepted"
          },
          "200": {
            "description": "Duplicate, no extra count"
          },
          "400": {
            "description": "Malformed JSON"
          },
          "409": {
            "description": "Conflicting event ID"
          },
          "413": {
            "description": "Body over 1 KB"
          },
          "415": {
            "description": "Expected application/json"
          },
          "422": {
            "description": "Invalid fields"
          },
          "429": {
            "description": "Daily limit"
          },
          "503": {
            "description": "Temporarily unavailable"
          }
        }
      }
    }
  }
}