Skip to content

Incident records

Part of the API reference. Authentication, scopes, rate limits and errors are on the overview.

BitHive Reporting Desk API · 0.11.0

Incident records

GET`/v1/records`

List the incident records

Returns the incident records of the modules (NIS2, the GDPR, contract notification clocks) that the user who created the token sees, each with its modules (regimes) and its nearest running deadline. The token sees what its creator sees, checked again on every request: a module restricted to other users is left out, and a record whose obligations are all of such modules is not listed. A token whose creator left the account sees no record. Requires the scope records:read.

Scope: records:read

Responses

200 The records the token sees. RecordList

{
  "records": [
    {
      "id": "cf6df210-3d1f-43c6-8ecb-374831ed5118",
      "summary": "Ransomware encrypted the billing systems",
      "state": "open",
      "entered_at": "2026-10-12T06:25:31Z",
      "aware_at": "2026-10-12T06:10:00Z",
      "occurred_at": "2026-10-12T03:40:00Z",
      "regimes": [
        "nis2"
      ],
      "next_deadline": {
        "obligation": "nis2.bsig.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
        "stage": "early_warning",
        "due_at": "2026-10-13T06:10:00Z",
        "overdue": false
      }
    }
  ]
}

403 The API token does not carry the required scope, or, for a write, the account is suspended because a payment is outstanding or its subscription has ended. Reading continues in both cases. A write of a record is also refused when the token's creator may no longer work incidents, and a new record outside the beta or for a module the account no longer holds. The detail says which applies. Problem

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/records"

POST`/v1/records`

Create an incident record

Records an incident and opens what its parties owe: for each legal entity and contract, each obligation type of a module the account holds whose definition the record meets, with its suggested applicability and its deadlines. The account must be in the beta, the token's creator must still work incidents, and the modules (regimes), parties and definitions must be ones the creator sees. Every write takes an Idempotency-Key. The entries in the account's audit log name the token. Requires the scope records:write.

Scope: records:write

Parameters

Parameter	In	Type	Description
`Idempotency-Key` required	header	string	As for every write; the writes of the records require it.

Request body

application/json

{
  "summary": "Outage of the billing systems",
  "aware_at": "2026-10-12T09:30:00Z",
  "definitions": [
    "nis2.significant_incident"
  ],
  "legal_entities": [
    "2d244e39-9353-4652-b8bb-fde203139229"
  ],
  "answers": {
    "gdpr.risk": "high"
  }
}

Responses

201 The record, as the token sees it. Record

{
  "id": "cf6df210-3d1f-43c6-8ecb-374831ed5118",
  "summary": "Ransomware encrypted the billing systems",
  "detail": "The billing systems are encrypted and offline. Network operation is not affected.",
  "state": "open",
  "entered_at": "2026-10-12T06:25:31Z",
  "aware_at": "2026-10-12T06:10:00Z",
  "occurred_at": "2026-10-12T03:40:00Z",
  "regimes": [
    "nis2"
  ],
  "next_deadline": {
    "obligation": "nis2.bsig.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
    "stage": "early_warning",
    "due_at": "2026-10-13T06:10:00Z",
    "overdue": false
  },
  "definitions": [
    "nis2.significant_incident"
  ],
  "answers": {
    "nis2.kritis": "no"
  },
  "items": [
    {
      "kind": "legal_entity",
      "name": "Example Netz GmbH"
    }
  ],
  "obligations": [
    {
      "key": "nis2.bsig.recipient_information:2d244e39-9353-4652-b8bb-fde203139229",
      "regime": "nis2",
      "type": "nis2.bsig.recipient_information",
      "party": {
        "kind": "legal_entity",
        "id": "2d244e39-9353-4652-b8bb-fde203139229"
      },
      "party_name": "Example Netz GmbH",
      "applicability": "required",
      "suggested": "required",
      "reason": "",
      "decided_by": "api-token:ac564834-c28c-4705-9129-6b7be8701c21",
      "decided_at": "2026-10-12T06:25:31Z",
      "stages": [
        {
          "id": "recipient_information",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": "requested"
        }
      ]
    },
    {
      "key": "nis2.bsig.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
      "regime": "nis2",
      "type": "nis2.bsig.significant_incident",
      "party": {
        "kind": "legal_entity",
        "id": "2d244e39-9353-4652-b8bb-fde203139229"
      },
      "party_name": "Example Netz GmbH",
      "applicability": "required",
      "suggested": "required",
      "reason": "",
      "decided_by": "api-token:ac564834-c28c-4705-9129-6b7be8701c21",
      "decided_at": "2026-10-12T06:25:31Z",
      "stages": [
        {
          "id": "early_warning",
          "closed": false,
          "due_at": "2026-10-13T06:10:00Z",
          "met_at": null,
          "rule": "nis2.bsig.early_warning",
          "rule_version": 1,
          "waiting_for": ""
        },
        {
          "id": "notification",
          "closed": false,
          "due_at": "2026-10-15T06:10:00Z",
          "met_at": null,
          "rule": "nis2.bsig.notification",
          "rule_version": 1,
          "waiting_for": ""
        },
        {
          "id": "intermediate_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": "requested"
        },
        {
          "id": "final_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": "submitted:notification"
        },
        {
          "id": "progress_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": "submitted:notification"
        },
        {
          "id": "final_report_after_progress",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": "closed"
        }
      ]
    },
    {
      "key": "nis2.enwg.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
      "regime": "nis2",
      "type": "nis2.enwg.significant_incident",
      "party": {
        "kind": "legal_entity",
        "id": "2d244e39-9353-4652-b8bb-fde203139229"
      },
      "party_name": "Example Netz GmbH",
      "applicability": "not_applicable",
      "suggested": "not_applicable",
      "reason": "answers",
      "decided_by": "api-token:ac564834-c28c-4705-9129-6b7be8701c21",
      "decided_at": "2026-10-12T06:25:31Z",
      "stages": [
        {
          "id": "early_warning",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        },
        {
          "id": "notification",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        },
        {
          "id": "intermediate_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        },
        {
          "id": "final_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        },
        {
          "id": "progress_report",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        },
        {
          "id": "final_report_after_progress",
          "closed": false,
          "due_at": null,
          "met_at": null,
          "rule": "",
          "rule_version": 0,
          "waiting_for": ""
        }
      ]
    }
  ]
}

400 A body is not the JSON object the contract names, or a write of the records has no Idempotency-Key. Problem

403 The API token does not carry the required scope, or, for a write, the account is suspended because a payment is outstanding or its subscription has ended. Reading continues in both cases. A write of a record is also refused when the token's creator may no longer work incidents, and a new record outside the beta or for a module the account no longer holds. The detail says which applies. Problem

409 The stage's report is recorded as submitted already, its obligation is closed, a request with the same Idempotency-Key is still running, or the answer of the write done under it is being settled. Problem

422 A record or a report is refused in words, or the Idempotency-Key was sent with another request. Problem

Example

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @new-record.json \
  "https://app.bithive-it.com/v1/records"

GET`/v1/records/{recordId}`

Read one incident record with its obligations and deadlines

Returns the record with the obligations its token's creator sees: per obligation its key, type, party, applicability and stages, and per stage its stored deadline (due and met times, rule and version) or the moment it waits for. A record of another account, one the creator sees none of, and a case of another kind are reported as not found. Requires the scope records:read.

Scope: records:read

Parameters

Parameter	In	Type	Description
`recordId` required	path	string (uuid)	Identifier of the incident record.

Responses

200 The record. Record

403 The API token does not carry the required scope, or, for a write, the account is suspended because a payment is outstanding or its subscription has ended. Reading continues in both cases. A write of a record is also refused when the token's creator may no longer work incidents, and a new record outside the beta or for a module the account no longer holds. The detail says which applies. Problem

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/records/$RECORDID"

POST`/v1/records/{recordId}/submissions`

Record a stage's report as submitted

Records that a stage's report was submitted: the report's fields in one of its template's languages, when and by whom it was submitted, the channel it went over to each recipient it went to, and why it did not go to the others. The submission copy is kept with its text's SHA-256 in the audit log, the stage's deadline is met and the stages that run from it are scheduled. It is refused while a field is missing, before the stages it follows are recorded, and for a stage already recorded or an obligation that is closed (409). An obligation that is still open takes its reports after the account's regime, or its part in the beta, has ended. Every write takes an Idempotency-Key. Requires the scope records:write.

Scope: records:write

Parameters

Parameter	In	Type	Description
`recordId` required	path	string (uuid)	Identifier of the incident record.
`Idempotency-Key` required	header	string	As for every write; the writes of the records require it.

Request body

application/json

{
  "obligation": "nis2.bsig.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
  "stage": "early_warning",
  "language": "de",
  "values": {
    "description": "Die Abrechnungssysteme sind ausgefallen.",
    "malicious": "unknown",
    "cross_border": "no"
  },
  "submitted_at": "2026-10-12T14:52:00Z",
  "submitted_by": "Security operations",
  "reference": "2026-104233",
  "sent": {
    "bsi": "bsi_portal"
  }
}

Responses

201 The submission copy. Submission

{
  "record": "cf6df210-3d1f-43c6-8ecb-374831ed5118",
  "obligation": "nis2.bsig.significant_incident:2d244e39-9353-4652-b8bb-fde203139229",
  "stage": "early_warning",
  "submitted_at": "2026-10-12T14:52:00Z",
  "recorded_at": "2026-10-12T14:55:12Z",
  "submitted_by": "Security operations",
  "reference": "2026-104233",
  "channel": "bsi_portal",
  "recipient": "bsi",
  "sent": [
    {
      "recipient": "bsi",
      "channel": "bsi_portal"
    }
  ],
  "not_sent": [],
  "template": "nis2.bsig.early_warning",
  "template_version": 1,
  "language": "de",
  "sha256": "6b1f0c2d9e8a7b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f7a8b9c0d1e2"
}

400 A body is not the JSON object the contract names, or a write of the records has no Idempotency-Key. Problem

403 The API token does not carry the required scope, or, for a write, the account is suspended because a payment is outstanding or its subscription has ended. Reading continues in both cases. A write of a record is also refused when the token's creator may no longer work incidents, and a new record outside the beta or for a module the account no longer holds. The detail says which applies. Problem

409 The stage's report is recorded as submitted already, its obligation is closed, a request with the same Idempotency-Key is still running, or the answer of the write done under it is being settled. Problem

422 A record or a report is refused in words, or the Idempotency-Key was sent with another request. Problem

Example

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @new-submission.json \
  "https://app.bithive-it.com/v1/records/$RECORDID/submissions"

POST`/v1/contracts/{contractId}/archive`

Archive a contract

Takes a contract out of use: it no longer counts against the size of the contract notification clocks and cannot be named by a new incident record, while every record that names it keeps it. A contract under which a notification duty is open is refused (409), and the detail names the records that hold one. Archiving an archived contract changes nothing. Like a report of an open obligation, archiving needs neither a module held nor the beta: an account that kept only the CRA can still archive a contract it kept. Requires the scope records:write and a token whose creator may work incidents and is an Owner or an Admin.

Scope: records:write

Parameters

Parameter	In	Type	Description
`contractId` required	path	string (uuid)	Identifier of the contract.

Responses

200 The contract as it now is. ContractState

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "kind": "notice_clause",
  "counterparty": "Kunde AG",
  "archived_at": "2026-10-26T09:12:00Z"
}

403 The API token does not carry the required scope, or, for a write, the account is suspended because a payment is outstanding or its subscription has ended. Reading continues in both cases. A write of a record is also refused when the token's creator may no longer work incidents, and a new record outside the beta or for a module the account no longer holds. The detail says which applies. Problem

409 A notification duty under the contract is open, so it cannot be archived; or the size of the contract notification clocks has no contract free, so it cannot be restored. The detail says which applies. Problem

Example

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/contracts/$CONTRACTID/archive"

POST`/v1/contracts/{contractId}/restore`

Restore an archived contract

Puts an archived contract back in use. A notice clause is refused while the size of the contract notification clocks has no contract free (409). Restoring a contract in use changes nothing. Requires the scope records:write, a token whose creator may work incidents and is an Owner or an Admin, and a beta account.

Scope: records:write

Parameters

Parameter	In	Type	Description
`contractId` required	path	string (uuid)	Identifier of the contract.

Responses

200 The contract as it now is. ContractState

403 The API token does not carry the required scope, or, for a write, the account is suspended because a payment is outstanding or its subscription has ended. Reading continues in both cases. A write of a record is also refused when the token's creator may no longer work incidents, and a new record outside the beta or for a module the account no longer holds. The detail says which applies. Problem

409 A notification duty under the contract is open, so it cannot be archived; or the size of the contract notification clocks has no contract free, so it cannot be restored. The detail says which applies. Problem

Example

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/contracts/$CONTRACTID/restore"

The contract itself. This page is built from the OpenAPI document of the service. It is published as a file, so a client generator can read the same contract this page describes. Download openapi.yaml

Start free 14-day trial