{
  "openapi": "3.1.0",
  "info": {
    "title": "Talent Risk API",
    "version": "1",
    "summary": "Job cuts at the largest employers in the UK, the US and Europe: every announcement with its sources, and each employer's label under one published rule.",
    "description": "Free, no key, CC BY 4.0. Event-level data is 7 days behind; same-day delivery is the paid Feed (https://talentrisk.com/data). Labels (Cutting, Signs, Quiet) are our opinion, reached by applying one published rule (https://talentrisk.com/methodology) to the sources listed. CC BY 4.0 — credit \"Talent Risk\" with a link to talentrisk.com. Sources inside the record keep their own terms: see attribution, and https://talentrisk.com/data#licences-h.",
    "contact": {
      "name": "Talent Risk",
      "url": "https://talentrisk.com/data",
      "email": "editor@talentrisk.com"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://talentrisk.com"
    }
  ],
  "externalDocs": {
    "description": "Data & API",
    "url": "https://talentrisk.com/data"
  },
  "paths": {
    "/v1/events.json": {
      "get": {
        "operationId": "listEvents",
        "summary": "Every announcement in the last 12 months, 7 days behind, newest first",
        "responses": {
          "200": {
            "description": "The events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "updated": {
                      "type": "string"
                    },
                    "delay_days": {
                      "type": "integer"
                    },
                    "licence": {
                      "type": "string"
                    },
                    "attribution": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "n": {
                      "type": "integer"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/employers/{slug}.json": {
      "get": {
        "operationId": "getEmployer",
        "summary": "One employer: its label and rule line, counts and latest announcement (live), identifiers, reported workforce, and its events (delayed)",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "As in https://talentrisk.com/companies/{slug}"
          }
        ],
        "responses": {
          "200": {
            "description": "The employer",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No employer with a record under that slug"
          }
        }
      }
    },
    "/v1/ledger.json": {
      "get": {
        "operationId": "getLedger",
        "summary": "The announcement ledger: every id ever issued, its reports and the dated history of what changed",
        "responses": {
          "200": {
            "description": "The ledger",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/archive.json": {
      "get": {
        "operationId": "getArchiveIndex",
        "summary": "The daily archive: one snapshot per day with its SHA-256",
        "responses": {
          "200": {
            "description": "The archive index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/identifiers.json": {
      "get": {
        "operationId": "getIdentifiers",
        "summary": "Standard identifiers (LEI, SEC CIK, ISIN, Companies House number, Wikidata) for every employer covered",
        "responses": {
          "200": {
            "description": "Identifiers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/index.json": {
      "get": {
        "operationId": "getIndex",
        "summary": "The Index today: every rated employer's label, rule line and counts (live)",
        "responses": {
          "200": {
            "description": "The Index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/data/index.csv": {
      "get": {
        "operationId": "getIndexCsv",
        "summary": "The Index as CSV",
        "responses": {
          "200": {
            "description": "CSV",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/data/employers.json": {
      "get": {
        "operationId": "searchList",
        "summary": "Every employer covered, compactly: [slug, name, ticker, aliases]",
        "responses": {
          "200": {
            "description": "Employers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/feeds/{market}.xml": {
      "get": {
        "operationId": "getFeed",
        "summary": "RSS of announcements",
        "parameters": [
          {
            "name": "market",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "uk",
                "us",
                "europe"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "RSS 2.0",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Event": {
        "type": "object",
        "description": "One announcement at one employer: a round of job cuts, a consultation, a buyout offer, a reported plan or a sign of cuts. Its id never changes.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable id; the announcement's page is https://talentrisk.com/cuts/{id}"
          },
          "employer": {
            "type": "string",
            "description": "Employer slug; its page is https://talentrisk.com/companies/{employer}"
          },
          "name": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "description": "Employer HQ country, ISO 3166-1 alpha-2"
          },
          "market": {
            "type": "string",
            "enum": [
              "uk",
              "us",
              "europe"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "cuts_announced",
              "voluntary_exit",
              "consultation",
              "restructuring_charge",
              "hiring_freeze",
              "ai_efficiency",
              "exec_language",
              "considering",
              "reorg",
              "retraining",
              "hiring"
            ]
          },
          "label": {
            "type": "string"
          },
          "first_reported": {
            "type": "string",
            "format": "date"
          },
          "last_reported": {
            "type": "string",
            "format": "date"
          },
          "jobs": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The largest figure any report gives"
          },
          "jobs_counted": {
            "type": "boolean",
            "description": "Whether the figure is in Talent Risk totals (confirmed by the employer, a formal notice or two reports; counted once per round)"
          },
          "count_reason": {
            "type": "string"
          },
          "ai_linked": {
            "type": "boolean"
          },
          "roles_cut": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "roles_hired": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Where the jobs are, as the sources state (ISO-2)"
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "method": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "complete_by": {
            "type": [
              "string",
              "null"
            ]
          },
          "sites": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reason_quote": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "text": {
                "type": "string"
              },
              "english": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "publisher": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            }
          },
          "moved_to": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              }
            }
          },
          "hired_from": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                }
              }
            }
          },
          "best_source_tier": {
            "type": "integer",
            "description": "1 official (the employer, a formal notice), 2 major outlet, 3 trade press, 4 other"
          },
          "best_source": {
            "type": "string"
          },
          "outlets": {
            "type": "integer"
          },
          "major_outlets": {
            "type": "integer"
          },
          "figure_reports": {
            "type": "integer"
          },
          "figure_official": {
            "type": "boolean"
          },
          "audit": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "reports_checked": {
                "type": "integer"
              },
              "held": {
                "type": "integer"
              },
              "last_checked": {
                "type": "string"
              }
            }
          },
          "summary": {
            "type": "string",
            "description": "Machine-written one-line summary of the best source; the source is what counts"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "tier": {
                  "type": "integer"
                },
                "audited_on": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "audit_held": {
                  "type": [
                    "boolean",
                    "null"
                  ]
                }
              }
            }
          },
          "url": {
            "type": "string"
          }
        }
      }
    }
  }
}