# API operator



This page is for the person who connects a program to the API.



Operations of a service of the operator, such as a billing service (record 0190). They take the operator token and no session, set no cookie, and never read or write a note, a workspace or a published link.

## findOperatorAccount

`GET /api/operator/accounts`

Find one account by its sign-in address.

A service of the operator finds an account by its address and reads its controls with their revision and its usage (record 0190). The answer holds no note, no workspace and no published link.

### Authentication

Use one of these options:
- [operatorToken](https://docs.tidynotebook.com/api-reference.md#operatortoken)

### Parameters

#### x-request-id

```json
{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}
```

#### address

```json
{
  "name": "address",
  "in": "query",
  "required": true,
  "style": "form",
  "explode": true,
  "description": "The sign-in address of the account to find. The server compares it in its one written form, in lower case.",
  "schema": {
    "$ref": "#/components/schemas/EmailAddress"
  }
}
```

Schemas: [EmailAddress](https://docs.tidynotebook.com/api-schemas.md#emailaddress).

### Responses

#### 200

One account as a service of the operator reads it.

```json
{
  "description": "One account as a service of the operator reads it.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OperatorAccount"
      }
    }
  }
}
```

Schemas: [OperatorAccount](https://docs.tidynotebook.com/api-schemas.md#operatoraccount).

#### 400

The request did not match the contract.

```json
{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 401

The request carries no usable session.

```json
{
  "description": "The request carries no usable session.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 404

The operator API is off, with the code operator_off, or the request names no account or no valid handoff, with the code not_found.

```json
{
  "description": "The operator API is off, with the code operator_off, or the request names no account or no valid handoff, with the code not_found.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 429

Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.

```json
{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails), [UsageLimit](https://docs.tidynotebook.com/api-schemas.md#usagelimit).

#### 500

The service failed to complete the request.

```json
{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

## readOperatorAccount

`GET /api/operator/accounts/{accountId}`

Read the controls and the usage of one account.

A service of the operator reads the controls of one account with their revision, and its usage (record 0190). A later write of the controls names that revision.

### Authentication

Use one of these options:
- [operatorToken](https://docs.tidynotebook.com/api-reference.md#operatortoken)

### Parameters

#### x-request-id

```json
{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}
```

#### accountId

```json
{
  "name": "accountId",
  "in": "path",
  "required": true,
  "style": "simple",
  "explode": false,
  "description": "Identifier of the account that the operation acts on.",
  "schema": {
    "$ref": "#/components/schemas/Uuid"
  }
}
```

Schemas: [Uuid](https://docs.tidynotebook.com/api-schemas.md#uuid).

### Responses

#### 200

One account as a service of the operator reads it.

```json
{
  "description": "One account as a service of the operator reads it.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OperatorAccount"
      }
    }
  }
}
```

Schemas: [OperatorAccount](https://docs.tidynotebook.com/api-schemas.md#operatoraccount).

#### 400

The request did not match the contract.

```json
{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 401

The request carries no usable session.

```json
{
  "description": "The request carries no usable session.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 404

The operator API is off, with the code operator_off, or the request names no account or no valid handoff, with the code not_found.

```json
{
  "description": "The operator API is off, with the code operator_off, or the request names no account or no valid handoff, with the code not_found.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 429

Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.

```json
{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails), [UsageLimit](https://docs.tidynotebook.com/api-schemas.md#usagelimit).

#### 500

The service failed to complete the request.

```json
{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

## removeOperatorAccount

`DELETE /api/operator/accounts/{accountId}`

Remove one account and every note it owns.

A service of the operator removes one account through the one removal of record 0111. The account, its workspaces, its sessions and its settings go, and a tombstone stays. The removal of the last enabled administrator is refused.

### Authentication

Use one of these options:
- [operatorToken](https://docs.tidynotebook.com/api-reference.md#operatortoken)

### Parameters

#### x-request-id

```json
{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}
```

#### accountId

```json
{
  "name": "accountId",
  "in": "path",
  "required": true,
  "style": "simple",
  "explode": false,
  "description": "Identifier of the account that the operation acts on.",
  "schema": {
    "$ref": "#/components/schemas/Uuid"
  }
}
```

Schemas: [Uuid](https://docs.tidynotebook.com/api-schemas.md#uuid).

### Responses

#### 200

The named record no longer exists.

```json
{
  "description": "The named record no longer exists.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Removed"
      }
    }
  }
}
```

Schemas: [Removed](https://docs.tidynotebook.com/api-schemas.md#removed).

#### 400

The request did not match the contract.

```json
{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 401

The request carries no usable session.

```json
{
  "description": "The request carries no usable session.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 404

The operator API is off, with the code operator_off, or the request names no account or no valid handoff, with the code not_found.

```json
{
  "description": "The operator API is off, with the code operator_off, or the request names no account or no valid handoff, with the code not_found.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 409

The change would leave the installation with no enabled administrator. The code is last_administrator. Nothing changed.

```json
{
  "description": "The change would leave the installation with no enabled administrator. The code is last_administrator. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 429

Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.

```json
{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails), [UsageLimit](https://docs.tidynotebook.com/api-schemas.md#usagelimit).

#### 500

The service failed to complete the request.

```json
{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

## setOperatorAccountControls

`PATCH /api/operator/accounts/{accountId}/controls`

Change the controls of one account.

A service of the operator changes the controls of one account with the revision that it read (record 0189). A write that names an old revision answers 409 with the code controls_changed and changes nothing, so a write that was made from an old state cannot replace a newer one.

### Authentication

Use one of these options:
- [operatorToken](https://docs.tidynotebook.com/api-reference.md#operatortoken)

### Parameters

#### x-request-id

```json
{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}
```

#### accountId

```json
{
  "name": "accountId",
  "in": "path",
  "required": true,
  "style": "simple",
  "explode": false,
  "description": "Identifier of the account that the operation acts on.",
  "schema": {
    "$ref": "#/components/schemas/Uuid"
  }
}
```

Schemas: [Uuid](https://docs.tidynotebook.com/api-schemas.md#uuid).

### Request body

```json
{
  "description": "The change of the controls and the revision that it read.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AccountControlsInput"
      }
    }
  }
}
```

Schemas: [AccountControlsInput](https://docs.tidynotebook.com/api-schemas.md#accountcontrolsinput).

### Responses

#### 200

One account as a service of the operator reads it.

```json
{
  "description": "One account as a service of the operator reads it.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OperatorAccount"
      }
    }
  }
}
```

Schemas: [OperatorAccount](https://docs.tidynotebook.com/api-schemas.md#operatoraccount).

#### 400

The request did not match the contract.

```json
{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 401

The request carries no usable session.

```json
{
  "description": "The request carries no usable session.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 403

The actor may not perform this operation.

```json
{
  "description": "The actor may not perform this operation.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 404

The operator API is off, with the code operator_off, or the request names no account or no valid handoff, with the code not_found.

```json
{
  "description": "The operator API is off, with the code operator_off, or the request names no account or no valid handoff, with the code not_found.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 409

The controls changed after the revision that the write names. The code is controls_changed. Nothing changed, and the writer reads the controls again.

```json
{
  "description": "The controls changed after the revision that the write names. The code is controls_changed. Nothing changed, and the writer reads the controls again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 413

The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.

```json
{
  "description": "The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 415

The request media type is not supported.

```json
{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 429

Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.

```json
{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails), [UsageLimit](https://docs.tidynotebook.com/api-schemas.md#usagelimit).

#### 500

The service failed to complete the request.

```json
{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

## listOperatorAccountEvents

`GET /api/operator/events`

List the account events after a cursor.

A service of the operator reads the events of the accounts after its own cursor, oldest first: an account was made, its address was verified, or it was removed (record 0190). The core sends nothing out, so the service asks. The positions follow the order of the commits, so a reader that continues after the last position misses no event.

### Authentication

Use one of these options:
- [operatorToken](https://docs.tidynotebook.com/api-reference.md#operatortoken)

### Parameters

#### x-request-id

```json
{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}
```

#### after

```json
{
  "name": "after",
  "in": "query",
  "required": false,
  "style": "form",
  "explode": true,
  "description": "The position of the last event that the reader already read. The answer holds the events after it, oldest first. The server uses 0 when the parameter is absent, which reads from the first event.",
  "schema": {
    "$ref": "#/components/schemas/AccountEventCursor"
  }
}
```

Schemas: [AccountEventCursor](https://docs.tidynotebook.com/api-schemas.md#accounteventcursor).

#### limit

```json
{
  "name": "limit",
  "in": "query",
  "required": false,
  "style": "form",
  "explode": true,
  "description": "Largest number of entries in one page. The server uses 100 when the parameter is absent and never returns more than 500.",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 500
  }
}
```

### Responses

#### 200

The account events after a cursor.

```json
{
  "description": "The account events after a cursor.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AccountEventList"
      }
    }
  }
}
```

Schemas: [AccountEventList](https://docs.tidynotebook.com/api-schemas.md#accounteventlist).

#### 400

The request did not match the contract.

```json
{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 401

The request carries no usable session.

```json
{
  "description": "The request carries no usable session.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 404

The installation names no operator token, so the operator API is off (record 0190). The code is operator_off.

```json
{
  "description": "The installation names no operator token, so the operator API is off (record 0190). The code is operator_off.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 429

Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.

```json
{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails), [UsageLimit](https://docs.tidynotebook.com/api-schemas.md#usagelimit).

#### 500

The service failed to complete the request.

```json
{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

## redeemAccountHandoff

`POST /api/operator/handoffs`

Redeem the token of one portal handoff.

The account portal of the operator redeems the token that it received and learns the account and its address (record 0190). A token works once and for 60 seconds. A used, an expired and an unknown token all answer 404 with the code not_found.

### Authentication

Use one of these options:
- [operatorToken](https://docs.tidynotebook.com/api-reference.md#operatortoken)

### Parameters

#### x-request-id

```json
{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}
```

### Request body

```json
{
  "description": "The token of the handoff.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/HandoffRedeemInput"
      }
    }
  }
}
```

Schemas: [HandoffRedeemInput](https://docs.tidynotebook.com/api-schemas.md#handoffredeeminput).

### Responses

#### 200

The account that opened the portal.

```json
{
  "description": "The account that opened the portal.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/HandoffAccount"
      }
    }
  }
}
```

Schemas: [HandoffAccount](https://docs.tidynotebook.com/api-schemas.md#handoffaccount).

#### 400

The request did not match the contract.

```json
{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 401

The request carries no usable session.

```json
{
  "description": "The request carries no usable session.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 404

The operator API is off, with the code operator_off, or the request names no account or no valid handoff, with the code not_found.

```json
{
  "description": "The operator API is off, with the code operator_off, or the request names no account or no valid handoff, with the code not_found.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 413

The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.

```json
{
  "description": "The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 415

The request media type is not supported.

```json
{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 429

Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.

```json
{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails), [UsageLimit](https://docs.tidynotebook.com/api-schemas.md#usagelimit).

#### 500

The service failed to complete the request.

```json
{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

## readOperatorTotals

`GET /api/operator/totals`

Read the totals of the installation for one month.

A service of the operator reads the totals of the whole installation for one calendar month in UTC: the published transfer, the downloads, and the calls to the object store (record 0193). A month with no count answers zero for each total.

### Authentication

Use one of these options:
- [operatorToken](https://docs.tidynotebook.com/api-reference.md#operatortoken)

### Parameters

#### x-request-id

```json
{
  "name": "x-request-id",
  "in": "header",
  "required": false,
  "style": "simple",
  "explode": false,
  "description": "Optional caller supplied correlation identifier. The server echoes the value and generates a UUID when the header is absent. A value outside the pattern below is rejected with a 400 problem.",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 128,
    "pattern": "^[A-Za-z0-9._-]+$"
  }
}
```

#### month

```json
{
  "name": "month",
  "in": "query",
  "required": false,
  "style": "form",
  "explode": true,
  "description": "The calendar month in UTC of the totals. The server uses the current month when the parameter is absent.",
  "schema": {
    "$ref": "#/components/schemas/UsageMonth"
  }
}
```

Schemas: [UsageMonth](https://docs.tidynotebook.com/api-schemas.md#usagemonth).

### Responses

#### 200

The totals of the installation for one month.

```json
{
  "description": "The totals of the installation for one month.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/OperatorTotals"
      }
    }
  }
}
```

Schemas: [OperatorTotals](https://docs.tidynotebook.com/api-schemas.md#operatortotals).

#### 400

The request did not match the contract.

```json
{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 401

The request carries no usable session.

```json
{
  "description": "The request carries no usable session.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 404

The installation names no operator token, so the operator API is off (record 0190). The code is operator_off.

```json
{
  "description": "The installation names no operator token, so the operator API is off (record 0190). The code is operator_off.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).

#### 429

Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.

```json
{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails), [UsageLimit](https://docs.tidynotebook.com/api-schemas.md#usagelimit).

#### 500

The service failed to complete the request.

```json
{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails).