{"openapi":"3.1.0","info":{"title":"Incident Library API","version":"1","description":"Public post-incident reports, written up one case at a time and reviewed, for engineers who are looking at a\nfailure right now and for AI tools that answer them. Every case has a stable id (IL-0001 and so on), a title,\nthe organisation and date, the symptoms as the engineers saw them, the trigger, the root cause, the components\ninvolved, the contributing factors, what was done, what the organisation changed afterwards, the lessons, and\nlinks to the original write-up and an archived copy. Texts come in English and, where the reviewers wrote it,\nKorean.\n\nStart with `GET /search?q=` and a sentence describing what you see. Results come best match first, each with\n`url`, the page a person would read. The `facets` count the results by\nroot cause, component, symptom and contributing factor, each with the case ids, so \"what usually caused this\" is\nin the same answer. To narrow by a vocabulary value you do not know the slug of, call `GET /vocab?q=` with a few\nwords. To read everything about one cause, component, symptom or factor, open its topic page, optionally\nrestricted to the cases a sentence finds (`?q=`).\n\nNo key is needed. Every public request is a GET with no required header. Answers are JSON with snake_case\nfields. Errors are RFC 9457 problem details (application/problem+json) with the reason in `detail`. Each client\naddress may send 30 searches and 120 other requests a minute; beyond that the answer is 429 with a Retry-After\nheader. Lists are paged: `items` plus a `next` link while more follow.\n"},"servers":[{"url":"https://incidentlib-api.benchlet.com"}],"tags":[{"name":"search","description":"From a sentence to cases"},{"name":"cases","description":"One case, a filtered list, and the cases like one"},{"name":"topics","description":"Root causes, components, symptoms and contributing factors as pages"},{"name":"vocabulary","description":"The slugs and their names"}],"paths":{"/search":{"get":{"operationId":"search","tags":["search"],"summary":"Find cases from a sentence describing the symptoms","description":"Give the sentence as an engineer would say it, in English or Korean: \"pods stay Pending and nodes report no\navailable IP addresses\". The engine ranks the cases by keywords and by meaning together, then a re-ranking\nmodel reads the sentence and each candidate and orders them, best match first. Cases that do not match well\nenough are left out, so an unrelated sentence returns few or no results rather than the nearest ones. `facets`\nare counted over the returned results only.\n","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"The symptoms as a sentence","3 words or more work best":null},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"How many cases at most"},{"$ref":"#/components/parameters/Lang"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ModelsUnavailable"}}}},"/cases":{"get":{"operationId":"listCases","tags":["cases"],"summary":"Approved cases filtered by vocabulary slugs, newest first, one page at a time","description":"Every filter is a slug from `/vocab`; an unknown slug matches nothing. Filters combine with AND. The answer is\none page: `items`, and `next`, the full address of the following page, present only while more cases follow.\nFollow `next` until it is absent to read every case; do not build the cursor yourself.\n","parameters":[{"name":"root_cause","in":"query","required":false,"schema":{"type":"string"},"description":"Root cause slug","such as capacity":null},{"name":"component","in":"query","required":false,"schema":{"type":"string"},"description":"Component slug","such as coredns":null},{"name":"symptom","in":"query","required":false,"schema":{"type":"string"},"description":"Symptom slug","such as pod-pending":null},{"name":"factor","in":"query","required":false,"schema":{"type":"string"},"description":"Contributing factor slug","such as no-alerting":null},{"name":"domain","in":"query","required":false,"schema":{"type":"string"},"description":"kubernetes or ai-infra"},{"name":"org","in":"query","required":false,"schema":{"type":"string"},"description":"The organisation exactly as the case names it"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Cases per page"},{"name":"after","in":"query","required":false,"schema":{"type":"string"},"description":"The cursor from the previous page's `next` link"},{"$ref":"#/components/parameters/Lang"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CasePage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/cases/{id}":{"get":{"operationId":"getCase","tags":["cases"],"summary":"Every field of one approved case","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Case id such as IL-0007"},{"$ref":"#/components/parameters/Lang"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCase"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/cases/{id}/similar":{"get":{"operationId":"similarCases","tags":["cases"],"summary":"Cases with the same root cause and at least one shared component","description":"Ordered by how many components they share, then newest first. `shared_components` names them.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SimilarCase"}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/root-causes":{"get":{"operationId":"listRootCauses","tags":["topics"],"summary":"Every root cause with its case count and date range, most cases first","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TopicSummary"}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/root-causes/{slug}":{"get":{"operationId":"getRootCause","tags":["topics"],"summary":"One root cause, its cases, and what those cases involved","description":"The cases filed under this root cause, newest first, and under `related` the components, symptoms and\ncontributing factors those cases carry, each with a count and the case ids. With `q`, only the cases the\nsentence finds are kept, best match first, and `related` is counted over them.\n","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Restrict"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopicPage"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ModelsUnavailable"}}}},"/components":{"get":{"operationId":"listComponents","tags":["topics"],"summary":"Every component with its case count and date range, most cases first","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TopicSummary"}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/components/{slug}":{"get":{"operationId":"getComponent","tags":["topics"],"summary":"One component, its cases (most severe first), and what those cases involved","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Restrict"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopicPage"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ModelsUnavailable"}}}},"/symptoms":{"get":{"operationId":"listSymptoms","tags":["topics"],"summary":"Every symptom with its case count and date range, most cases first","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TopicSummary"}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/symptoms/{slug}":{"get":{"operationId":"getSymptom","tags":["topics"],"summary":"One symptom, its cases, and the root causes behind them","description":"Under `related.root_causes` the causes that produced this symptom, most frequent first, with the case ids. This answers \"what usually causes this\".","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Restrict"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopicPage"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ModelsUnavailable"}}}},"/factors":{"get":{"operationId":"listFactors","tags":["topics"],"summary":"Every contributing factor with its case count and date range, most cases first","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TopicSummary"}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/factors/{slug}":{"get":{"operationId":"getFactor","tags":["topics"],"summary":"One contributing factor, its cases, and what those cases involved","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Restrict"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopicPage"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ModelsUnavailable"}}}},"/vocab":{"get":{"operationId":"getVocab","tags":["vocabulary"],"summary":"Every slug with its names, or the slugs nearest to a few words","description":"Without `q`: per kind (`root_causes`, `components`, `symptoms`, `factors`, `domains`), every value with its\nslug and its English and Korean name. With `q`: the values whose names are nearest in meaning to the words,\nnearest first, so \"cert ran out\" finds `certificate-expiry`.\n","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"A few words naming what you are looking for"},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["root_causes","components","symptoms","factors"]},"description":"Only this kind"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"With q","how many matches":null}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Vocab"},{"$ref":"#/components/schemas/VocabMatches"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ModelsUnavailable"}}}},"/openapi.json":{"get":{"operationId":"openapiJson","summary":"This description, as JSON","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/openapi.yaml":{"get":{"operationId":"openapiYaml","summary":"This description, as YAML","responses":{"200":{"description":"OK","content":{"application/yaml":{"schema":{"type":"string"}}}}}}}},"components":{"responses":{"BadRequest":{"description":"A parameter is missing or out of range; `detail` says which","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"No approved case or no vocabulary value with that id or slug","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyRequests":{"description":"This client address went over its allowance for the minute; `Retry-After` says in how many seconds to try again","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the next request is allowed"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"ModelsUnavailable":{"description":"The search models did not answer in time; search is unavailable for the moment, everything else works","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"parameters":{"Lang":{"name":"lang","in":"query","required":false,"schema":{"type":"string","enum":["en","ko"],"default":"en"},"description":"With ko, every text pair comes back with the Korean text in `en` where Korean exists."},"Restrict":{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"A symptom sentence. Only the cases the search finds for it are kept, best match first, and the related counts are over them."}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 problem details; every error of this api has this shape","properties":{"type":{"type":"string","description":"about:blank"},"title":{"type":"string","description":"The status phrase","such as Bad Request":null},"status":{"type":"integer"},"detail":{"type":"string","description":"What went wrong","in a sentence":null},"instance":{"type":"string","description":"The request path"}},"required":["title","status"]},"PublicCase":{"allOf":[{"$ref":"#/components/schemas/CaseInput"},{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","description":"The case page on the web service"},"updated_at":{"type":"string","format":"date-time","description":"When the case was last changed"}},"required":["id","url","updated_at"]}]},"CasePage":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicCase"}},"next":{"type":"string","description":"Address of the following page; absent on the last page"}},"required":["items"]},"GraphMap":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","additionalProperties":true}},"edges":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"},"kind":{"type":"string"}},"required":["source","target","kind"]}}},"required":["nodes","edges"]},"SearchResponse":{"type":"object","properties":{"query":{"type":"string","description":"The sentence as searched (whitespace normalised)"},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"facets":{"$ref":"#/components/schemas/Facets"}},"required":["query","results","facets"]},"Facets":{"type":"object","description":"The results counted by vocabulary value, most frequent first; counted over the returned results only","properties":{"root_causes":{"type":"array","items":{"$ref":"#/components/schemas/FacetValue"}},"components":{"type":"array","items":{"$ref":"#/components/schemas/FacetValue"}},"symptoms":{"type":"array","items":{"$ref":"#/components/schemas/FacetValue"}},"factors":{"type":"array","items":{"$ref":"#/components/schemas/FacetValue"}}},"required":["root_causes","components","symptoms","factors"]},"FacetValue":{"type":"object","properties":{"slug":{"type":"string"},"en":{"type":"string"},"ko":{"type":"string"},"count":{"type":"integer","description":"How many of the results carry this value"},"cases":{"type":"array","items":{"type":"string"},"description":"Their ids"},"url":{"type":"string","description":"The topic page"}},"required":["slug","en","ko","count","cases","url"]},"SearchResult":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","description":"The case page on the web service"},"title":{"$ref":"#/components/schemas/Text"},"org":{"type":"string"},"date":{"type":"string"},"root_cause":{"type":"string"},"contributing":{"type":"array","items":{"type":"string"}},"symptoms":{"type":"array","items":{"type":"string"}},"components":{"type":"array","items":{"type":"string"}},"domain":{"type":"array","items":{"type":"string"}},"severity":{"type":"string"},"symptoms_text":{"$ref":"#/components/schemas/Text"},"trigger":{"$ref":"#/components/schemas/Text"},"summary":{"$ref":"#/components/schemas/Text"},"detection":{"$ref":"#/components/schemas/Text"},"remediation":{"type":"array","items":{"type":"string"}},"action_items":{"type":"array","items":{"$ref":"#/components/schemas/ActionItem"}},"lessons":{"$ref":"#/components/schemas/Text"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"matched_symptoms":{"type":"array","items":{"type":"string"},"description":"Symptom slugs whose words appear in the sentence"},"matched_components":{"type":"array","items":{"type":"string"},"description":"Component slugs whose words appear in the sentence"},"snippet":{"$ref":"#/components/schemas/Text","description":"The passage of the case the keywords matched","when they matched one":null}},"required":["id","url","title","org","date","root_cause","contributing","symptoms","components","domain","remediation","action_items","sources","matched_symptoms","matched_components"]},"CaseRef":{"type":"object","description":"A case as a row in a list","properties":{"id":{"type":"string"},"url":{"type":"string"},"title":{"$ref":"#/components/schemas/Text"},"org":{"type":"string"},"date":{"type":"string"},"severity":{"type":"string","description":"sev1 to sev4","or unknown":null},"root_cause":{"type":["string","null"]}},"required":["id","url","title","org","date","severity"]},"SimilarCase":{"allOf":[{"$ref":"#/components/schemas/CaseRef"},{"type":"object","properties":{"shared_components":{"type":"array","items":{"type":"string"}}},"required":["shared_components"]}]},"TopicSummary":{"type":"object","properties":{"kind":{"type":"string","enum":["root_cause","component","symptom","factor"]},"slug":{"type":"string"},"en":{"type":"string"},"ko":{"type":"string"},"url":{"type":"string"},"count":{"type":"integer","description":"Approved cases carrying this value"},"first_date":{"type":["string","null"]},"last_date":{"type":["string","null"]}},"required":["kind","slug","en","ko","url","count"]},"RelatedValue":{"type":"object","properties":{"slug":{"type":"string"},"en":{"type":"string"},"ko":{"type":"string"},"url":{"type":"string"},"count":{"type":"integer","description":"How many of the page's cases carry this value"},"cases":{"type":"array","items":{"type":"string"}}},"required":["slug","en","ko","url","count","cases"]},"TopicPage":{"type":"object","properties":{"kind":{"type":"string","enum":["root_cause","component","symptom","factor"]},"slug":{"type":"string"},"en":{"type":"string"},"ko":{"type":"string"},"url":{"type":"string"},"query":{"type":"string","description":"Present when the page was restricted by a sentence"},"count":{"type":"integer"},"first_date":{"type":["string","null"]},"last_date":{"type":["string","null"]},"cases":{"type":"array","items":{"$ref":"#/components/schemas/CaseRef"}},"related":{"type":"object","description":"The other three kinds, counted over the page's cases; the page's own kind is absent","properties":{"root_causes":{"type":"array","items":{"$ref":"#/components/schemas/RelatedValue"}},"components":{"type":"array","items":{"$ref":"#/components/schemas/RelatedValue"}},"symptoms":{"type":"array","items":{"$ref":"#/components/schemas/RelatedValue"}},"factors":{"type":"array","items":{"$ref":"#/components/schemas/RelatedValue"}}}}},"required":["kind","slug","en","ko","url","count","cases","related"]},"VocabMatches":{"type":"object","properties":{"query":{"type":"string"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/VocabMatch"},"description":"Nearest first"}},"required":["query","matches"]},"VocabMatch":{"type":"object","properties":{"kind":{"type":"string","enum":["root_cause","component","symptom","factor"]},"slug":{"type":"string"},"en":{"type":"string"},"ko":{"type":"string"},"url":{"type":"string"}},"required":["kind","slug","en","ko","url"]},"Text":{"type":"object","properties":{"en":{"type":"string"},"ko":{"type":"string"}},"required":["en"]},"VocabEntry":{"type":"object","properties":{"slug":{"type":"string"},"en":{"type":"string"},"ko":{"type":"string"}},"required":["slug","en","ko"]},"Vocab":{"type":"object","properties":{"vocabularies":{"type":"object","description":"Keys are root_causes, components, symptoms, factors and domains","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/VocabEntry"}}}},"required":["vocabularies"]},"Source":{"type":"object","properties":{"url":{"type":"string"},"archived":{"type":"string"},"license":{"type":"string","enum":["unknown","cc-by","all-rights-reserved"]},"kind":{"type":"string","enum":["blog","official-status","talk","paper","github","runbook"]}},"required":["url"]},"ActionItem":{"type":"object","properties":{"text":{"$ref":"#/components/schemas/Text"},"status":{"type":"string","enum":["done","planned","unknown"]}},"required":["text","status"]},"CaseInput":{"type":"object","description":"Section 6 of the plan without the server-set fields. Missing values are unknown or null, never invented.","properties":{"title":{"$ref":"#/components/schemas/Text"},"org":{"type":"string"},"date":{"type":"string","format":"date"},"date_kind":{"type":"string","enum":["incident","published"]},"domain":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"symptoms":{"type":"array","items":{"type":"string"}},"symptoms_text":{"$ref":"#/components/schemas/Text"},"trigger":{"$ref":"#/components/schemas/Text"},"root_cause":{"type":"string"},"contributing":{"type":"array","items":{"type":"string"}},"components":{"type":"array","items":{"type":"string"}},"summary":{"$ref":"#/components/schemas/Text"},"severity":{"type":"string","enum":["sev1","sev2","sev3","sev4","unknown"]},"impact":{"type":"object","properties":{"scope":{"type":"string"},"users":{"type":"string"},"region":{"type":"string"}}},"timeline":{"type":"object","properties":{"detected_after":{"type":["string","null"]},"resolved_after":{"type":["string","null"]}}},"detection":{"$ref":"#/components/schemas/Text"},"remediation":{"type":"array","items":{"type":"string"}},"action_items":{"type":"array","items":{"$ref":"#/components/schemas/ActionItem"}},"recurrence_of":{"type":["string","null"]},"lessons":{"$ref":"#/components/schemas/Text"},"related":{"type":"array","items":{"type":"string"}},"docs":{"type":"array","items":{"type":"string"}},"review":{"type":"object","properties":{"written_by":{"type":"string","enum":["session","llm","human"]},"reviewed_by":{"type":["string","null"]},"reviewed_at":{"type":["string","null"]}}}},"required":["title","org","date","domain","sources","root_cause"]},"Case":{"allOf":[{"$ref":"#/components/schemas/CaseInput"},{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"integer"},"status":{"type":"string","enum":["draft","approved","unpublished"]},"ontology_version":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","version","status","ontology_version","created_at","updated_at"]}]}}}}