{
 "openapi": "3.1.0",
 "info": {
  "title": "outage.me Agent API",
  "version": "1.3.0",
  "summary": "Live outage, reliability and exploited-vulnerability intelligence for cloud and SaaS, built from official provider status pages and CISA/FIRST/NVD.",
  "description": "Live outage, reliability and exploited-vulnerability intelligence for cloud and SaaS, built from official provider status pages and CISA/FIRST/NVD. See /llms.txt for orientation and /ai.txt for terms. MCP: https://outage.me/mcp needs no sign-in; https://outage.me/mcp/pro (OAuth sign-in, a free account works) adds the model-backed answer tool and history, and the Pro plan adds more. How to connect: https://outage.me/connect",
  "termsOfService": "https://outage.me/terms",
  "contact": {
   "name": "outage.me (Smart Signals LLC)",
   "url": "https://outage.me",
   "email": "privacy@outage.me"
  },
  "license": {
   "name": "Free with attribution to outage.me",
   "url": "https://outage.me/ai.txt"
  },
  "x-logo": {
   "url": "https://outage.me/logo-512.png",
   "backgroundColor": "#141c2b"
  }
 },
 "externalDocs": {
  "description": "Orientation for AI agents (llms.txt)",
  "url": "https://outage.me/llms.txt"
 },
 "servers": [
  {
   "url": "https://outage.me"
  }
 ],
 "tags": [
  {
   "name": "Layer 1 — open, no key",
   "description": "Deterministic facts; free, no key, cached at the edge."
  },
  {
   "name": "Layer 2 — API key",
   "description": "Model-backed answers with citations; free revocable key."
  },
  {
   "name": "Contribute — API key, opt-in",
   "description": "Report failures you observe; earns Ask credit. Reference: https://outage.me/agents/api"
  }
 ],
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "x-tarantula-api-key"
   }
  }
 },
 "paths": {
  "/api/reliability": {
   "get": {
    "tags": [
     "Layer 1 — open, no key"
    ],
    "summary": "Per-provider reliability index and median recovery time.",
    "description": "Deterministic aggregation over official provider status pages for the current window. Facts only — no model output, so this endpoint cannot hallucinate.\n\nReturns: providers[] {provider, incidents, weighted, index, median_recovery_hours}",
    "operationId": "reliability",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "as_of",
          "source",
          "license",
          "providers",
          "count"
         ],
         "properties": {
          "as_of": {
           "type": "string",
           "format": "date",
           "description": "Snapshot date (UTC)."
          },
          "source": {
           "type": "string",
           "description": "Where the facts come from."
          },
          "license": {
           "type": "string",
           "description": "Terms of reuse (attribution)."
          },
          "count": {
           "type": "integer",
           "description": "Rows in this response."
          },
          "window_days": {
           "type": "integer"
          },
          "providers": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "provider": {
              "type": "string"
             },
             "incidents": {
              "type": "integer"
             },
             "weighted": {
              "type": "number"
             },
             "index": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100,
              "description": "0 (worst) – 100 (no incidents), weighted by impact."
             },
             "median_recovery_hours": {
              "type": [
               "number",
               "null"
              ]
             }
            }
           }
          }
         }
        },
        "example": {
         "as_of": "2026-09-27",
         "source": "Official provider status pages, ingested and aggregated by outage.me. Facts only — no model output on this endpoint.",
         "license": "Free to use and quote with attribution to outage.me. See https://outage.me/ai.txt",
         "providers": [
          {
           "provider": "GitHub",
           "incidents": 15,
           "weighted": 19.0,
           "index": 0,
           "median_recovery_hours": null
          }
         ],
         "count": 1,
         "window_days": 7
        }
       }
      }
     }
    }
   }
  },
  "/api/incidents/active": {
   "get": {
    "tags": [
     "Layer 1 — open, no key"
    ],
    "summary": "Incidents providers are currently reporting as open.",
    "description": "Each incident is quoted from the provider's own status page and carries a link back to it.\n\nReturns: incidents[] {provider, impact, status, subject, components, started_at, url}",
    "operationId": "incidents_active",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "as_of",
          "source",
          "license",
          "incidents",
          "count"
         ],
         "properties": {
          "as_of": {
           "type": "string",
           "format": "date",
           "description": "Snapshot date (UTC)."
          },
          "source": {
           "type": "string",
           "description": "Where the facts come from."
          },
          "license": {
           "type": "string",
           "description": "Terms of reuse (attribution)."
          },
          "count": {
           "type": "integer",
           "description": "Rows in this response."
          },
          "incidents": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "provider": {
              "type": "string"
             },
             "impact": {
              "type": "string"
             },
             "status": {
              "type": "string"
             },
             "subject": {
              "type": "string"
             },
             "components": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "started_at": {
              "type": [
               "string",
               "null"
              ]
             },
             "url": {
              "type": [
               "string",
               "null"
              ]
             }
            }
           }
          }
         }
        },
        "example": {
         "as_of": "2026-09-27",
         "source": "Official provider status pages, ingested and aggregated by outage.me. Facts only — no model output on this endpoint.",
         "license": "Free to use and quote with attribution to outage.me. See https://outage.me/ai.txt",
         "incidents": [
          {
           "provider": "PlayStation Network",
           "impact": "critical",
           "status": "ongoing",
           "subject": "Issues reported: PlayStation Store (Russia)",
           "components": [
            "PlayStation Store"
           ],
           "started_at": "2026-08-26T05:14:55",
           "url": null
          }
         ],
         "count": 1
        }
       }
      }
     }
    }
   }
  },
  "/api/vulnerabilities/exploited": {
   "get": {
    "tags": [
     "Layer 1 — open, no key"
    ],
    "summary": "Actively exploited CVEs, ranked patch-first.",
    "description": "CISA KEV entries ranked by CVSS × EPSS exploitation probability × known ransomware use, with CISA due date and patch status. Open upstreams only (KEV public domain, FIRST EPSS, NIST NVD). Deterministic: no model in the loop.\n\nReturns: vulnerabilities[] {cve, title, score, tier, factors, due_date, patched, url}",
    "operationId": "vulnerabilities_exploited",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "as_of",
          "source",
          "license",
          "vulnerabilities",
          "count"
         ],
         "properties": {
          "as_of": {
           "type": "string",
           "format": "date",
           "description": "Snapshot date (UTC)."
          },
          "source": {
           "type": "string",
           "description": "Where the facts come from."
          },
          "license": {
           "type": "string",
           "description": "Terms of reuse (attribution)."
          },
          "count": {
           "type": "integer",
           "description": "Rows in this response."
          },
          "vulnerabilities": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "cve": {
              "type": "string"
             },
             "title": {
              "type": "string"
             },
             "score": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
             },
             "tier": {
              "type": "string",
              "enum": [
               "critical",
               "high",
               "medium",
               "low"
              ]
             },
             "factors": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "due_date": {
              "type": [
               "string",
               "null"
              ]
             },
             "patched": {
              "type": [
               "boolean",
               "null"
              ]
             },
             "url": {
              "type": [
               "string",
               "null"
              ]
             }
            }
           }
          }
         }
        },
        "example": {
         "as_of": "2026-09-27",
         "source": "CISA Known Exploited Vulnerabilities (public domain), FIRST EPSS and NIST NVD, ranked by outage.me. Facts only — no model output on this endpoint.",
         "license": "Free to use and quote with attribution to outage.me. See https://outage.me/ai.txt",
         "vulnerabilities": [
          {
           "cve": "CVE-2026-71362",
           "title": "Adobe Commerce and Magento Incorrect Authorization Vulnerability",
           "score": 100,
           "tier": "critical",
           "factors": [
            "actively exploited (KEV)"
           ],
           "due_date": "2026-09-27",
           "patched": true,
           "url": "https://www.cisa.gov/known-exploited-vulnerabilities-catalog"
          }
         ],
         "count": 1
        }
       }
      }
     }
    }
   }
  },
  "/api/examples": {
   "get": {
    "tags": [
     "Layer 1 — open, no key"
    ],
    "summary": "Worked question → call → answer-shape examples.",
    "description": "Regenerated from the live snapshot, so an example never cites an incident that has since stopped existing.\n\nReturns: examples[] {question, call, answer_shape}",
    "operationId": "examples",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "as_of",
          "source",
          "license",
          "examples",
          "count"
         ],
         "properties": {
          "as_of": {
           "type": "string",
           "format": "date",
           "description": "Snapshot date (UTC)."
          },
          "source": {
           "type": "string",
           "description": "Where the facts come from."
          },
          "license": {
           "type": "string",
           "description": "Terms of reuse (attribution)."
          },
          "count": {
           "type": "integer",
           "description": "Rows in this response."
          },
          "examples": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "question": {
              "type": "string"
             },
             "call": {
              "type": "object",
              "properties": {
               "method": {
                "type": "string"
               },
               "path": {
                "type": "string"
               }
              }
             },
             "answer_shape": {
              "type": "string"
             }
            }
           }
          }
         }
        },
        "example": {
         "as_of": "2026-09-27",
         "source": "Official provider status pages, ingested and aggregated by outage.me. Facts only — no model output on this endpoint.",
         "license": "Free to use and quote with attribution to outage.me. See https://outage.me/ai.txt",
         "examples": [
          {
           "question": "Which cloud and SaaS providers are having incidents right now?",
           "call": {
            "method": "GET",
            "path": "/api/incidents/active"
           },
           "answer_shape": "incidents[] with provider, impact, subject, started_at, url"
          }
         ],
         "count": 1
        }
       }
      }
     }
    }
   }
  },
  "/api/answer": {
   "post": {
    "tags": [
     "Layer 2 — API key"
    ],
    "summary": "Natural-language question against the live monitor, with citations.",
    "description": "A retrieval-grounded model call. Unlike the Layer 1 endpoints this CAN be wrong: check `confidence` and follow `citations` before repeating it. Free revocable key, quota-limited.\n\nReturns: {answer, intent, citations[], snapshot_as_of, confidence}",
    "operationId": "answer",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "answer"
         ],
         "properties": {
          "answer": {
           "type": "string"
          },
          "intent": {
           "type": "string"
          },
          "snapshot_as_of": {
           "type": "string"
          },
          "confidence": {
           "type": "string",
           "enum": [
            "high",
            "medium",
            "low"
           ]
          },
          "citations": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "Source URLs or source names the answer rests on."
          }
         }
        },
        "example": {
         "answer": "GitHub is reporting degraded performance for Actions; see the linked notice.",
         "intent": "provider_status",
         "citations": [
          "https://www.githubstatus.com/"
         ],
         "snapshot_as_of": "2026-09-27",
         "confidence": "high"
        }
       }
      }
     },
     "403": {
      "description": "Missing or revoked API key"
     },
     "429": {
      "description": "Daily quota exhausted"
     }
    },
    "security": [
     {
      "apiKey": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "q"
        ],
        "properties": {
         "q": {
          "type": "string",
          "description": "The question, in natural language."
         }
        }
       },
       "example": {
        "q": "Is GitHub having an outage right now?"
       }
      }
     }
    }
   }
  },
  "/v1/observations": {
   "post": {
    "tags": [
     "Contribute — API key, opt-in"
    ],
    "summary": "Report a failed call you observed to a public API host.",
    "description": "Counts once per organization, host and error class per 15 minutes. Shown publicly only when 3+ organizations report and the failure is confirmed; each confirmed report adds +5 Ask questions (max 50/day). Only hosts on /agent/hosts.json; the organization must turn on contributing. Reference: /agents/api",
    "operationId": "observations_report",
    "security": [
     {
      "apiKey": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
         "host",
         "error_class"
        ],
        "properties": {
         "host": {
          "type": "string",
          "maxLength": 253,
          "description": "Hostname from /agent/hosts.json only: no scheme, port, path or query."
         },
         "error_class": {
          "type": "string",
          "enum": [
           "http_5xx",
           "timeout",
           "connection_refused",
           "dns_failure",
           "tls_error"
          ]
         },
         "region": {
          "type": "string",
          "pattern": "^(aws|gcp|azure|oci|alibaba|other):[a-z0-9-]{2,32}$",
          "description": "Where your software runs. Never published."
         },
         "report_token": {
          "type": "string",
          "description": "Single-use token offered by a status answer (MCP)."
         }
        }
       },
       "example": {
        "host": "api.stripe.com",
        "error_class": "http_5xx"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Recorded (pending), already counted (duplicate) or paused (ignored)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "status"
         ],
         "properties": {
          "status": {
           "type": "string",
           "enum": [
            "pending",
            "duplicate",
            "ignored"
           ]
          },
          "host": {
           "type": "string"
          },
          "service": {
           "type": "string"
          },
          "window": {
           "type": "string"
          },
          "credit_on_confirmation": {
           "type": "integer"
          },
          "reason": {
           "type": "string"
          }
         }
        },
        "example": {
         "status": "pending",
         "host": "api.stripe.com",
         "service": "Stripe",
         "window": "2026-10-02T14:30",
         "credit_on_confirmation": 5
        }
       }
      }
     },
     "400": {
      "description": "Outside the closed set (host, class, field, region)"
     },
     "403": {
      "description": "Missing key, or contributing is off for the organization"
     },
     "404": {
      "description": "Contributions are switched off service-wide"
     }
    }
   }
  },
  "/v1/quota": {
   "get": {
    "tags": [
     "Contribute — API key, opt-in"
    ],
    "summary": "Your Ask quota, earned credit and report outcomes.",
    "description": "Daily limit plus credit from confirmed reports, and trust state.",
    "operationId": "quota_get",
    "security": [
     {
      "apiKey": []
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "limit",
          "remaining"
         ],
         "properties": {
          "daily": {
           "type": "integer"
          },
          "credit": {
           "type": "integer"
          },
          "limit": {
           "type": "integer"
          },
          "used": {
           "type": "integer"
          },
          "remaining": {
           "type": "integer"
          },
          "contributing": {
           "type": "boolean"
          },
          "earn": {
           "type": "string"
          },
          "rules": {
           "type": "string"
          },
          "trust": {
           "type": "string",
           "enum": [
            "earning",
            "not earning",
            "paused"
           ]
          },
          "reports": {
           "type": "object",
           "properties": {
            "pending": {
             "type": "integer"
            },
            "confirmed": {
             "type": "integer"
            },
            "rejected": {
             "type": "integer"
            },
            "capped": {
             "type": "integer"
            }
           }
          }
         }
        },
        "example": {
         "daily": 10,
         "credit": 5,
         "limit": 15,
         "used": 3,
         "remaining": 12,
         "reports": {
          "pending": 1,
          "confirmed": 1,
          "rejected": 0,
          "capped": 0
         },
         "trust": "earning",
         "contributing": true,
         "earn": "report_observation: +5 per confirmed report"
        }
       }
      }
     },
     "403": {
      "description": "Missing or revoked API key"
     },
     "404": {
      "description": "Contributions are switched off service-wide"
     }
    }
   }
  }
 }
}