{
 "openapi": "3.1.0",
 "info": {
  "title": "Spike Intel Cloud API",
  "version": "20.3",
  "description": "Incident records with revisions, a replayable change feed, workspace dependency matching and delivery receipts. Public endpoints need no key; watch endpoints need a Spike Pro API key in the x-spike-key header."
 },
 "servers": [
  {
   "url": "https://spiketrendwatch.com"
  }
 ],
 "components": {
  "securitySchemes": {
   "key": {
    "type": "apiKey",
    "in": "header",
    "name": "x-spike-key"
   }
  },
  "schemas": {
   "Incident": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "provider": {
      "type": "string"
     },
     "title": {
      "type": "string"
     },
     "status": {
      "type": "string"
     },
     "open": {
      "type": "boolean"
     },
     "provider_impact": {
      "type": "string"
     },
     "severity": {
      "type": "integer",
      "description": "0-3, Spike's mapping of the provider's own level"
     },
     "services": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "regions": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "revision": {
      "type": "integer"
     },
     "clocks": {
      "type": "object",
      "properties": {
       "began": {
        "type": "string",
        "format": "date-time"
       },
       "published": {
        "type": "string",
        "format": "date-time"
       },
       "observed": {
        "type": "string",
        "format": "date-time"
       }
      }
     },
     "evidence": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "claim": {
         "type": "string"
        },
        "value": {
         "type": "string"
        },
        "by": {
         "type": "string"
        },
        "kind": {
         "type": "string",
         "enum": [
          "direct",
          "statement_as_reported",
          "actor_claim",
          "reporting"
         ]
        },
        "source": {
         "type": "string"
        },
        "url": {
         "type": "string"
        },
        "at": {
         "type": "integer"
        }
       }
      }
     }
    }
   },
   "Revision": {
    "type": "object",
    "properties": {
     "cursor": {
      "type": "integer"
     },
     "incident": {
      "type": "string"
     },
     "revision": {
      "type": "integer"
     },
     "changes": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "field": {
         "type": "string"
        },
        "from": {},
        "to": {},
        "summary": {
         "type": "string"
        }
       }
      }
     },
     "record": {
      "$ref": "#/components/schemas/Incident"
     }
    }
   }
  }
 },
 "paths": {
  "/api/v1/incidents": {
   "get": {
    "summary": "Current and recent incidents",
    "parameters": [
     {
      "name": "provider",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "since",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ]
   }
  },
  "/api/v1/incidents/{id}": {
   "get": {
    "summary": "One incident with every revision",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ]
   }
  },
  "/api/v1/changes": {
   "get": {
    "summary": "Change feed. Replay from any cursor.",
    "parameters": [
     {
      "name": "cursor",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "provider",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ]
   }
  },
  "/api/v1/watch/changes": {
   "get": {
    "summary": "Change feed filtered to your workspace's dependencies, with why each matched",
    "security": [
     {
      "key": []
     }
    ],
    "parameters": [
     {
      "name": "cursor",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ]
   }
  },
  "/api/v1/watch/deliveries": {
   "get": {
    "summary": "Delivery receipts with timing",
    "security": [
     {
      "key": []
     }
    ]
   }
  },
  "/api/v1/stream": {
   "get": {
    "summary": "Server-Sent Events: incident revisions, signals, alerts, cyber items. Reconnect with Last-Event-ID to replay missed incident revisions.",
    "security": [
     {
      "key": []
     }
    ]
   }
  },
  "/api/v1/briefs/{id}": {
   "get": {
    "summary": "Evidence Brief (schema spike.evidence-brief/1): what changed, claims with evidence, conflicts, open questions, late evidence, corrections and a handoff summary. Without as_of: the latest revision. With as_of=N: brief revision N, built only from what Spike had recorded at its cutoff, so it is the same every time (content_sha256). Brief revision N is the Nth material incident revision. New fields may be added within schema version 1; removed or renamed fields mean a new schema version.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^b[0-9a-f]{13}$"
      }
     },
     {
      "name": "as_of",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Brief"
     },
     "400": {
      "description": "bad_as_of: no such brief revision; the body gives revisions_total"
     },
     "404": {
      "description": "not_found"
     }
    }
   }
  },
  "/api/v1/watch/briefs/{id}": {
   "get": {
    "summary": "The same brief with this workspace's view: the dependency list version in force at the cutoff, which business services to check (direct_match or possible_exposure) and why, services that entered or left scope, deliveries and correction recipients. Never cached; visible only to the workspace's own API key.",
    "security": [
     {
      "key": []
     }
    ],
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "as_of",
      "in": "query",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Brief with workspace"
     },
     "400": {
      "description": "bad_as_of"
     },
     "401": {
      "description": "api_key_required"
     },
     "404": {
      "description": "not_found"
     }
    }
   }
  },
  "/api/v1/briefs/resolve": {
   "get": {
    "summary": "Find the brief for a Spike brief or incident ID, a Spike incident link, a provider status-page incident link Spike has recorded, or alert text that contains one. POST /api/v1/briefs with {\"ref\": \"…\"} does the same. Returns brief, url, api and matched_by (the provenance of the match).",
    "parameters": [
     {
      "name": "ref",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Matched"
     },
     "422": {
      "description": "unsupported_ref, with the supported inputs"
     }
    }
   }
  },
  "/api/v1/watch/intake": {
   "post": {
    "summary": "Send an alert (StatusGator webhook v3 or v2, an IsDown incident object, or {ref}) and follow the matching Evidence Brief. StatusGator and IsDown alerts carry no provider incident link, so they are matched by provider status page and title; the response says how (matched_by, confidence) or lists candidates (422 ambiguous). Returns the brief ID, a stable revision URL and the handoff text.",
    "security": [
     {
      "key": []
     }
    ],
    "responses": {
     "200": {
      "description": "Following"
     },
     "400": {
      "description": "unsupported_input"
     },
     "401": {
      "description": "api_key_required"
     },
     "422": {
      "description": "ambiguous, no_confident_match, not_recorded or unsupported_provider (with candidates where Spike has them)"
     }
    }
   }
  },
  "/api/v1/watch/handoffs": {
   "get": {
    "summary": "List handoff targets and followed briefs",
    "security": [
     {
      "key": []
     }
    ]
   },
   "post": {
    "summary": "Add a handoff target: {kind: incidentio|json|contract_sink, url, token}. Payload schema spike.handoff/2 with stable delivery IDs; see /developers. incidentio sends incident.io alert events (title, description, deduplication_key = brief ID, status firing|resolved, source_url = stable revision URL, metadata). Each material revision, corrections included, is sent once and retried up to 6 times.",
    "security": [
     {
      "key": []
     }
    ]
   },
   "delete": {
    "summary": "Remove a target (?id=)",
    "security": [
     {
      "key": []
     }
    ]
   }
  },
  "/api/v1/watch/test-sink": {
   "get": {
    "summary": "Deprecated alias of /api/v1/watch/receiver (kept for v20.7 clients)",
    "security": [
     {
      "key": []
     }
    ]
   }
  },
  "/api/v1/watch/receiver": {
   "get": {
    "summary": "This workspace's controlled receiver: a contract demonstration of incident.io alert-event semantics (one record per active deduplication_key; resolved closes it; a repeated delivery ID is ignored). Not incident.io. Returns records, log and last_cursor.",
    "security": [
     {
      "key": []
     }
    ]
   },
   "post": {
    "summary": "Control the receiver: {fail_next: n} refuses the next n deliveries with 503; {lose_ack_next: n} stores the next n and returns 503 (a lost acknowledgment); {reset: true} clears it.",
    "security": [
     {
      "key": []
     }
    ]
   }
  },
  "/api/v1/watch/handoffs/replay": {
   "post": {
    "summary": "Re-send every material revision after {cursor} to this workspace's handoff targets ({id} for one target), with the original delivery IDs. Returns results and next_cursor.",
    "security": [
     {
      "key": []
     }
    ],
    "responses": {
     "200": {
      "description": "Replayed"
     },
     "400": {
      "description": "cursor_required"
     }
    }
   }
  },
  "/api/v1/briefs/{id}/handoff": {
   "get": {
    "summary": "Handoff export, schema spike.handoff/2, public evidence only. format=json (default), incidentio (alert-event body) or text; as_of=N for an earlier revision. {id} may be 'demo'.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "format",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "json",
        "incidentio",
        "text"
       ]
      }
     },
     {
      "name": "as_of",
      "in": "query",
      "schema": {
       "type": "integer"
      }
     }
    ]
   }
  },
  "/api/v1/watch/briefs/{id}/handoff": {
   "get": {
    "summary": "Handoff export with this workspace's possible exposure (dependency list version, matches, entered and left scope).",
    "security": [
     {
      "key": []
     }
    ]
   }
  },
  "/taxii2/": {
   "get": {
    "summary": "TAXII 2.1 discovery"
   }
  }
 },
 "x-webhooks": {
  "incident.revision": {
   "description": "POSTed to workspace webhooks when a matching incident changes. JSON webhooks carry header Spike-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of '<t>.<raw body>' with your signing secret>. Reject if t is more than 5 minutes old. Spike-Cursor carries the revision cursor; deliveries are retried up to 6 times with growing delays (1, 2, 4, 8, 16 minutes), then dead-lettered; a workspace can send a dead-lettered delivery again. Spike-Delivery-Id is stable across retries of the same delivery: use it to ignore duplicates. Order: revisions of one incident carry increasing revision numbers and cursors; apply a revision only if its revision number is higher than the one you hold. Only material changes are pushed (opened, status, impact, services or regions added or removed, resolved, correction, retraction); every revision, material or not, is in the change feed. A workspace that received any revision of an incident also receives its later material revisions, corrections and retractions, even if the incident no longer matches its watched services. During signing-secret rotation, Spike-Signature carries two v1 values for 24 hours."
  }
 }
}