# deactivateReport

mutation · in the family [Report](/reference/report/)

## What it does

Retire a saved report from use — it cannot run until reactivated.

Deactivate a Report by id; requires the unrestricted capability + the record's CURRENT revision. Deny-by-default + the referential_integrity / authority / occ guards. The optional reason rides the transition events.

## What happens

Reversible.

## Who may call it

Capability area: **Work and notes** — Tasks, notes, messages, dashboards and the everyday tools every staff member keeps.

- Owner
- System Administrator
- Manager
- Associate Manager
- Warehouse Associate
- Sales Associate
- Cashier
- An API key whose scope allows `api:deactivateReport`

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | [ID](/types/#scalars) `ID!` | yes | The id of the record. |
| `revision` | [ID](/types/#scalars) `ID!` | yes | The revision id you read on the record; the change is refused if an edit landed in the meantime. |
| `reason` | [String](/types/#scalars) | no | No further notes. |

## Returns

[Report](/types/Report/) `Report!` — A Report (📊; THE REPORT ENGINE, program 3 of THE OFFICE FIX PROGRAM 2): a SAVED REPORT DEFINITION — a validated ReportSpec (the reportRun grammar VERBATIM: a plan + columns, or a plan + groupBy/measures, an optional sort) kept as JSON text (specJson, at most 12288 characters) with its words (describeReport, at most 4096 characters) and the family its rows or groups are made of (terminalFamily). It stores NO result: every run executes as THE RUNNER under the runner's own list rights through reportRun(reportId) (rows on screen, now) or startExportJob(reportId, format) (a file, in the background); the saved spec is RE-VALIDATED at every run (a roster that moved since the save refuses in the teaching voice — edit the spec); only an active definition runs. The definition is the question, never an answer. NOT searchable (no filter roster until the report builder lands).

## Example request

```graphql
mutation ExampleDeactivateReport($id: ID!, $revision: ID!, $reason: String) {
  deactivateReport(id: $id, revision: $revision, reason: $reason) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    specJson
    words
    terminalFamily
    description
  }
}
```

Variables:

```json
{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "reason": "Correcting a miscount."
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

## Example response

```json
{
  "data": {
    "deactivateReport": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "RO-EXMP-0000-000F",
      "type": "Report",
      "caption": "Blue jeans",
      "status": "active",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "specJson": "<spec json>",
      "words": "<words>",
      "terminalFamily": "<terminal family>",
      "description": "Straight-cut, mid-rise, five pockets."
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

## Errors this call can answer

- `VALIDATION/INVALID` — Something in the request is not valid. ([VALIDATION](/errors/VALIDATION/))
- `AUTHN/REQUIRED` — Sign in to do this. ([AUTHN](/errors/AUTHN/))
- `AUTHZ/FORBIDDEN` — Your role does not allow this action. ([AUTHZ](/errors/AUTHZ/))
- `RATE_LIMIT/THROTTLED` — Too many requests in a short time. ([RATE_LIMIT](/errors/RATE_LIMIT/))
- `NOT_FOUND/*` — That record could not be found. ([NOT_FOUND](/errors/NOT_FOUND/))
- `CONFLICT/*` — The record’s state, or a change made in the meantime, does not allow this; the codes are on the CONFLICT page. ([CONFLICT](/errors/CONFLICT/))
- `VALIDATION/VERSION_REQUIRED` — The request did not say which app version it came from. ([VALIDATION](/errors/VALIDATION/))