# API reference



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



This document is the authoritative HTTP interface of notesapp. Every application HTTP call in the web app and the sync engine uses an operation generated from this document. Errors use RFC 9457 problem details with a stable application code.

[Download OpenAPI JSON](https://docs.tidynotebook.com/api/openapi.json).

## Server address

This is a placeholder address. Use the HTTPS origin of your own installation in your client or API tool. Replace the placeholder before you send a request. The generated client takes the address from its configuration.

```json
{
  "url": "https://notes.invalid",
  "description": "This is a placeholder address. Use the HTTPS origin of your own installation in your client or API tool. Replace the placeholder before you send a request. The generated client takes the address from its configuration."
}
```

## Authentication

### personalApiKey

A personal API key gives full access to its enabled account through the Authorization header. Use HTTPS. Keys expire and can be revoked at once. Never put a key in a URL. An invalid bearer never falls back to a cookie.

```json
{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "Personal API key",
  "description": "A personal API key gives full access to its enabled account through the Authorization header. Use HTTPS. Keys expire and can be revoked at once. Never put a key in a URL. An invalid bearer never falls back to a cookie."
}
```

```http
Authorization: Bearer <key>
```

### sessionCookie

Browser session cookie. The cookie is HttpOnly and SameSite, and a cookie authenticated write also needs an origin check. A deployment whose origin is https serves the same cookie under the reserved name __Secure-notesapp_session and adds the Secure attribute, as the cookie prefix rules require.

```json
{
  "type": "apiKey",
  "in": "cookie",
  "name": "notesapp_session",
  "description": "Browser session cookie. The cookie is HttpOnly and SameSite, and a cookie authenticated write also needs an origin check. A deployment whose origin is https serves the same cookie under the reserved name __Secure-notesapp_session and adds the Secure attribute, as the cookie prefix rules require."
}
```

### operatorToken

The one secret of the operator of the installation, from NOTESAPP_OPERATOR_TOKEN or from the file that NOTESAPP_OPERATOR_TOKEN_FILE names (records 0190 and 0207). A service of the operator sends it on each operator operation. The server compares it in constant time, and the attempt counters bound the failures. With no secret, every operator operation answers 404 with the code operator_off.

```json
{
  "type": "http",
  "scheme": "bearer",
  "description": "The one secret of the operator of the installation, from NOTESAPP_OPERATOR_TOKEN or from the file that NOTESAPP_OPERATOR_TOKEN_FILE names (records 0190 and 0207). A service of the operator sends it on each operator operation. The server compares it in constant time, and the attempt counters bound the failures. With no secret, every operator operation answers 404 with the code operator_off."
}
```

```http
Authorization: Bearer <key>
```


## Operations

- [API service](https://docs.tidynotebook.com/api-reference-service.md)
- [API accounts](https://docs.tidynotebook.com/api-reference-accounts.md)
- [API administration](https://docs.tidynotebook.com/api-reference-administration.md)
- [API workspaces](https://docs.tidynotebook.com/api-reference-workspaces.md)
- [API files](https://docs.tidynotebook.com/api-reference-files.md)
- [API publishing](https://docs.tidynotebook.com/api-reference-publishing.md)
- [API published](https://docs.tidynotebook.com/api-reference-published.md)
- [API legal](https://docs.tidynotebook.com/api-reference-legal.md)
- [API auth](https://docs.tidynotebook.com/api-reference-auth.md)
- [API operator](https://docs.tidynotebook.com/api-reference-operator.md)

[API schemas](https://docs.tidynotebook.com/api-schemas.md).