# API administration



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



Accounts, invitations, and the settings of the installation. Only an administrator reaches these operations, and none of them reads a note.

## listAccounts

`GET /api/accounts`

List every account of the installation.

Only an administrator lists the accounts. The list holds names, addresses, states, activity, and usage, and never a note.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

### Responses

#### 200

Every account of the installation.

```json
{
  "description": "Every account of the installation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AccountList"
      }
    }
  }
}
```

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

#### 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).

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## updateAccount

`PATCH /api/accounts/{accountId}`

Change the role, the state, the limit, or the controls of one account.

Only an administrator changes an account. A change that would leave the installation with no enabled administrator is refused. A change of the controls names the revision that the administrator read, and an old revision answers 409 with the code controls_changed (record 0189).

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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 facts of the account to change.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AccountUpdateInput"
      }
    }
  }
}
```

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

### Responses

#### 200

One account as an administrator sees it.

```json
{
  "description": "One account as an administrator sees it.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AccountSummary"
      }
    }
  }
}
```

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

#### 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 requested resource does not exist.

```json
{
  "description": "The requested resource does not exist.",
  "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, with the code last_administrator, or the controls changed after the revision that the change names, with the code controls_changed. Nothing changed.

```json
{
  "description": "The change would leave the installation with no enabled administrator, with the code last_administrator, or the controls changed after the revision that the change names, with the code controls_changed. Nothing changed.",
  "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).

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## removeAccount

`DELETE /api/accounts/{accountId}`

Remove another account and every note it owns.

Only an administrator removes another account. The account, its workspaces, its sessions, and its settings go. An account removes itself through removeOwnAccount instead. The removal of the last enabled administrator is refused.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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).

#### 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 requested resource does not exist.

```json
{
  "description": "The requested resource does not exist.",
  "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).

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## getInstallation

`GET /api/installation`

Read the settings of the installation.

Only an administrator reads the settings of the installation.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

### Responses

#### 200

The settings of the installation.

```json
{
  "description": "The settings of the installation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Installation"
      }
    }
  }
}
```

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

#### 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).

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## updateInstallation

`PUT /api/installation`

Change the registration policy of the installation.

Only an administrator changes the settings. The server refuses open registration until the installation has a mail transport and its legal documents, and it refuses any change while the server environment names the policy.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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 settings of the installation to change.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/InstallationUpdateInput"
      }
    }
  }
}
```

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

### Responses

#### 200

The settings of the installation.

```json
{
  "description": "The settings of the installation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Installation"
      }
    }
  }
}
```

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

#### 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).

#### 409

The setting cannot change now. The code is setting_locked when the server environment sets it, and setting_required when open registration needs it. Nothing changed.

```json
{
  "description": "The setting cannot change now. The code is setting_locked when the server environment sets it, and setting_required when open registration needs it. Nothing changed.",
  "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).

#### 422

The installation cannot take open registration yet. The code is open_registration_unavailable, and the missing member lists each part that the installation lacks.

```json
{
  "description": "The installation cannot take open registration yet. The code is open_registration_unavailable, and the missing member lists each part that the installation lacks.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## getLegalDocumentSettings

`GET /api/installation/legal/{document}`

Read one legal document of the installation to change it.

Only an administrator reads the stored text or address of a document and the template of the document, with the facts that the server knows already filled in (record 0148).

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

#### document

```json
{
  "name": "document",
  "in": "path",
  "required": true,
  "style": "simple",
  "explode": false,
  "description": "Which legal document to read, the terms or the privacy notice.",
  "schema": {
    "type": "string",
    "enum": [
      "terms",
      "privacy"
    ]
  }
}
```

### Responses

#### 200

One legal document as the administrator changes it.

```json
{
  "description": "One legal document as the administrator changes it.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/LegalDocumentSettings"
      }
    }
  }
}
```

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

#### 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).

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## updateLegalDocument

`PUT /api/installation/legal/{document}`

Set one legal document of the installation.

Only an administrator sets a document: a Markdown text that this server serves, or an external address, and its version. The documents apply when both exist. A text that still holds a blank of the template is refused. A new version asks every account to accept again (record 0120).

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

#### document

```json
{
  "name": "document",
  "in": "path",
  "required": true,
  "style": "simple",
  "explode": false,
  "description": "Which legal document to read, the terms or the privacy notice.",
  "schema": {
    "type": "string",
    "enum": [
      "terms",
      "privacy"
    ]
  }
}
```

### Request body

```json
{
  "description": "The legal document to set.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/LegalDocumentInput"
      }
    }
  }
}
```

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

### Responses

#### 200

The settings of the installation.

```json
{
  "description": "The settings of the installation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Installation"
      }
    }
  }
}
```

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

#### 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).

#### 409

The setting cannot change now. The code is setting_locked when the server environment sets it, and setting_required when open registration needs it. Nothing changed.

```json
{
  "description": "The setting cannot change now. The code is setting_locked when the server environment sets it, and setting_required when open registration needs it. Nothing changed.",
  "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).

#### 422

The text still holds a blank of the template. The code is legal_document_unfinished, and the blanks member lists each one. Nothing changed.

```json
{
  "description": "The text still holds a blank of the template. The code is legal_document_unfinished, and the blanks member lists each one. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## removeLegalDocument

`DELETE /api/installation/legal/{document}`

Remove one legal document of the installation.

Only an administrator removes a document. The server refuses while the server environment sets the documents, and while open registration needs them (record 0114).

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

#### document

```json
{
  "name": "document",
  "in": "path",
  "required": true,
  "style": "simple",
  "explode": false,
  "description": "Which legal document to read, the terms or the privacy notice.",
  "schema": {
    "type": "string",
    "enum": [
      "terms",
      "privacy"
    ]
  }
}
```

### Responses

#### 200

The settings of the installation.

```json
{
  "description": "The settings of the installation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Installation"
      }
    }
  }
}
```

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

#### 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).

#### 409

The setting cannot change now. The code is setting_locked when the server environment sets it, and setting_required when open registration needs it. Nothing changed.

```json
{
  "description": "The setting cannot change now. The code is setting_locked when the server environment sets it, and setting_required when open registration needs it. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## updateMailSettings

`PUT /api/installation/mail`

Set the mail transport of the installation.

Only an administrator sets the mail transport (record 0148). A password that the body leaves out keeps the stored one, and no answer holds a password. The server refuses the change while the server environment sets the mail transport.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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 mail transport to set.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MailSettingsInput"
      }
    }
  }
}
```

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

### Responses

#### 200

The settings of the installation.

```json
{
  "description": "The settings of the installation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Installation"
      }
    }
  }
}
```

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

#### 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).

#### 409

The setting cannot change now. The code is setting_locked when the server environment sets it, and setting_required when open registration needs it. Nothing changed.

```json
{
  "description": "The setting cannot change now. The code is setting_locked when the server environment sets it, and setting_required when open registration needs it. Nothing changed.",
  "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).

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## removeMailSettings

`DELETE /api/installation/mail`

Remove the mail transport of the installation.

Only an administrator removes the mail transport. The server refuses while the server environment sets it, and while open registration needs it (record 0114).

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

### Responses

#### 200

The settings of the installation.

```json
{
  "description": "The settings of the installation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Installation"
      }
    }
  }
}
```

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

#### 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).

#### 409

The setting cannot change now. The code is setting_locked when the server environment sets it, and setting_required when open registration needs it. Nothing changed.

```json
{
  "description": "The setting cannot change now. The code is setting_locked when the server environment sets it, and setting_required when open registration needs it. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## sendTestMessage

`POST /api/installation/mail/test`

Send a test message to the address of the administrator.

Sends one message through the mail transport that applies now, to the address of the administrator who asks (record 0148). A failure names its kind and never the answer of the mail server.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

### Responses

#### 200

The test message went to the mail server.

```json
{
  "description": "The test message went to the mail server.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MailTestSent"
      }
    }
  }
}
```

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

#### 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).

#### 422

The test message did not go. The code is mail_failed, and the reason member names the kind of the failure.

```json
{
  "description": "The test message did not go. The code is mail_failed, and the reason member names the kind of the failure.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## listInvitations

`GET /api/invitations`

List the invitations that wait.

Only an administrator lists the invitations. A used or revoked invitation does not appear.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

### Responses

#### 200

The invitations that wait.

```json
{
  "description": "The invitations that wait.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/InvitationList"
      }
    }
  }
}
```

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

#### 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).

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## createInvitation

`POST /api/invitations`

Invite one address to make an account.

Only an administrator invites. The link goes by mail when the installation has a mail transport. Otherwise the answer holds the link once, for the administrator to copy.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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 address to invite.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/InvitationCreateInput"
      }
    }
  }
}
```

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

### Responses

#### 201

The new invitation.

```json
{
  "description": "The new invitation.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/InvitationCreated"
      }
    }
  }
}
```

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

#### 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).

#### 409

The address cannot take an invitation. The code is account_exists when an account already signs in with that address.

```json
{
  "description": "The address cannot take an invitation. The code is account_exists when an account already signs in with that address.",
  "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).

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## revokeInvitation

`DELETE /api/invitations/{invitationId}`

Revoke one invitation.

Only an administrator revokes an invitation. A revoked invitation opens nothing.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

#### invitationId

```json
{
  "name": "invitationId",
  "in": "path",
  "required": true,
  "style": "simple",
  "explode": false,
  "description": "Identifier of the invitation 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).

#### 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 requested resource does not exist.

```json
{
  "description": "The requested resource does not exist.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## listReports

`GET /api/reports`

List the open reports of published links.

Only an administrator reads the reports. A report names its link and the address to open it, and no fact of a note or of the workspace.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

### Responses

#### 200

The open reports of published links.

```json
{
  "description": "The open reports of published links.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/LinkReportList"
      }
    }
  }
}
```

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

#### 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).

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## dismissReport

`DELETE /api/reports/{reportId}`

Close one report and keep its link.

Only an administrator closes a report. The link stays as it is.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

#### reportId

```json
{
  "name": "reportId",
  "in": "path",
  "required": true,
  "style": "simple",
  "explode": false,
  "description": "Identifier of the report 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).

#### 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 requested resource does not exist.

```json
{
  "description": "The requested resource does not exist.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).

## takeDownReportedLink

`POST /api/reports/{reportId}/takedown`

Take down the link of one report.

Only an administrator takes a link down. The link stops at once, and every open report of it closes. The owner sees that an administrator took the link down and cannot make it live again. The administrator gets no membership, so no note of the workspace becomes readable.

### Authentication

Use one of these options:
- [sessionCookie](https://docs.tidynotebook.com/api-reference.md#sessioncookie)
- [personalApiKey](https://docs.tidynotebook.com/api-reference.md#personalapikey)

### 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._-]+$"
  }
}
```

#### reportId

```json
{
  "name": "reportId",
  "in": "path",
  "required": true,
  "style": "simple",
  "explode": false,
  "description": "Identifier of the report 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).

#### 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 requested resource does not exist.

```json
{
  "description": "The requested resource does not exist.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 423

The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.

```json
{
  "description": "The account is locked, and a locked account keeps only a fixed list of operations (record 0201). The code is account_locked. Nothing changed.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}
```

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

#### 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).