# API auth This page is for the person who connects a program to the API. Authentication protocol endpoints. Better Auth implements them; the contract records their shapes so the generated client owns every call. ## getAuthSession `GET /api/auth/get-session` Report the current session. Reports the session that the request cookie names, or null when there is none. ### Authentication No security scheme is declared. See the operation description. ### Responses #### 200 The current session, or null. ```json { "description": "The current session, or null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCurrentSession" } } } } ``` Schemas: [AuthCurrentSession](https://docs.tidynotebook.com/api-schemas.md#authcurrentsession). #### 400 The request did not match the endpoint. ```json { "description": "The request did not match the endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 401 The credential was refused. ```json { "description": "The credential was refused.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 403 The request did not come from the configured origin. ```json { "description": "The request did not come from the configured origin.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 404 The named record does not exist. ```json { "description": "The named record does not exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 429 Too many attempts. Try again later. ```json { "description": "Too many attempts. Try again later.", "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). ## requestPasswordReset `POST /api/auth/request-password-reset` Ask for a password reset message. Sends a reset link to the address when a mail transport is configured. The link opens the reset page of the application. A deployment without one uses the operator recovery command instead. The answer never says whether the address exists, and the messages to one address count against its mail budget. ### Authentication No security scheme is declared. See the operation description. ### Request body ```json { "description": "The address that asks for a reset message.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthPasswordResetRequest" } } } } ``` Schemas: [AuthPasswordResetRequest](https://docs.tidynotebook.com/api-schemas.md#authpasswordresetrequest). ### Responses #### 200 The request was accepted. ```json { "description": "The request was accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthOutcome" } } } } ``` Schemas: [AuthOutcome](https://docs.tidynotebook.com/api-schemas.md#authoutcome). #### 400 The request did not match the endpoint. ```json { "description": "The request did not match the endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 401 The credential was refused. ```json { "description": "The credential was refused.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 403 The request did not come from the configured origin. ```json { "description": "The request did not come from the configured origin.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 404 The named record does not exist. ```json { "description": "The named record does not exist.", "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. ```json { "description": "The request body is larger than the configured limit.", "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 attempts. Try again later. ```json { "description": "Too many attempts. Try again later.", "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). ## resetPassword `POST /api/auth/reset-password` Choose a new password with a reset token. Sets a new password and revokes every session of the account. The token works once and expires one hour after it was created. ### Authentication No security scheme is declared. See the operation description. ### Request body ```json { "description": "The new password and the reset token.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthPasswordReset" } } } } ``` Schemas: [AuthPasswordReset](https://docs.tidynotebook.com/api-schemas.md#authpasswordreset). ### Responses #### 200 The password was replaced. ```json { "description": "The password was replaced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthOutcome" } } } } ``` Schemas: [AuthOutcome](https://docs.tidynotebook.com/api-schemas.md#authoutcome). #### 400 The request did not match the endpoint. ```json { "description": "The request did not match the endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 401 The credential was refused. ```json { "description": "The credential was refused.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 403 The request did not come from the configured origin. ```json { "description": "The request did not come from the configured origin.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 404 The named record does not exist. ```json { "description": "The named record does not exist.", "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. ```json { "description": "The request body is larger than the configured limit.", "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 attempts. Try again later. ```json { "description": "Too many attempts. Try again later.", "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). ## signInWithPassword `POST /api/auth/sign-in/email` Sign in with an address and a password. Checks a local password and sets the Secure HttpOnly session cookie. Public registration is disabled, so this endpoint never creates an account. ### Authentication No security scheme is declared. See the operation description. ### Request body ```json { "description": "Address and password of a local account.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthPasswordSignIn" } } } } ``` Schemas: [AuthPasswordSignIn](https://docs.tidynotebook.com/api-schemas.md#authpasswordsignin). ### Responses #### 200 The sign-in completed. ```json { "description": "The sign-in completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSession" } } } } ``` Schemas: [AuthSession](https://docs.tidynotebook.com/api-schemas.md#authsession). #### 400 The request did not match the endpoint. ```json { "description": "The request did not match the endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 401 The credential was refused. ```json { "description": "The credential was refused.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 403 The request did not come from the configured origin. ```json { "description": "The request did not come from the configured origin.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 404 The named record does not exist. ```json { "description": "The named record does not exist.", "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. ```json { "description": "The request body is larger than the configured limit.", "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 attempts. Try again later. ```json { "description": "Too many attempts. Try again later.", "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). ## signOut `POST /api/auth/sign-out` End the current session. Removes the session on the server and clears the session cookie. A cleared session cannot be used again. ### Authentication No security scheme is declared. See the operation description. ### Request body ```json { "description": "Sign-out carries no data.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSignOut" } } } } ``` Schemas: [AuthSignOut](https://docs.tidynotebook.com/api-schemas.md#authsignout). ### Responses #### 200 The session ended. ```json { "description": "The session ended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSignOutResult" } } } } ``` Schemas: [AuthSignOutResult](https://docs.tidynotebook.com/api-schemas.md#authsignoutresult). #### 400 The request did not match the endpoint. ```json { "description": "The request did not match the endpoint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 401 The credential was refused. ```json { "description": "The credential was refused.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 403 The request did not come from the configured origin. ```json { "description": "The request did not come from the configured origin.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 404 The named record does not exist. ```json { "description": "The named record does not exist.", "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. ```json { "description": "The request body is larger than the configured limit.", "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 attempts. Try again later. ```json { "description": "Too many attempts. Try again later.", "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). ## registerAccount `POST /api/registrations` Make an account from an invitation and sign it in. Makes an account for the address that the invitation binds, with the given password, and starts its session. A used, revoked, or expired invitation makes nothing, and the answer does not say which of the three applied. Two requests with one invitation make one account. When the installation names its terms and its privacy notice, the request names the versions that the person accepted, and a missing or an older version makes nothing (record 0120). ### Authentication No security scheme is declared. See the operation description. ### Request body ```json { "description": "The invitation token and the password of the new account.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationInput" } } } } ``` Schemas: [RegistrationInput](https://docs.tidynotebook.com/api-schemas.md#registrationinput). ### Responses #### 201 The account exists and its session started. ```json { "description": "The account exists and its session started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Registered" } } } } ``` Schemas: [Registered](https://docs.tidynotebook.com/api-schemas.md#registered). #### 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). #### 403 The invitation opens nothing. The code is invitation_invalid for a token that expired, that somebody used, that an administrator revoked, or that never existed. The answer does not say which. ```json { "description": "The invitation opens nothing. The code is invitation_invalid for a token that expired, that somebody used, that an administrator revoked, or that never existed. The answer does not say which.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` Schemas: [ProblemDetails](https://docs.tidynotebook.com/api-schemas.md#problemdetails). #### 409 The change cannot be accepted next to the state that the workspace holds. The code names the reason: path_conflict for a path that another live file occupies, and mutation_reused for a mutation identity that was already used for another operation. A save of a note adds epoch_mismatch, which means that the note holds another generation of its document, so the device reads the current document before it saves again. ```json { "description": "The change cannot be accepted next to the state that the workspace holds. The code names the reason: path_conflict for a path that another live file occupies, and mutation_reused for a mutation identity that was already used for another operation. A save of a note adds epoch_mismatch, which means that the note holds another generation of its document, so the device reads the current document before it saves 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). ## getSignUpChallenge `GET /api/registrations/challenge` Read a proof of work challenge for one sign-up. Answers a random value, a difficulty and an expiry, signed by this server (record 0115). The browser finds a solution whose digest starts with as many zero bits as the difficulty names, and sends it with the sign-up. One solution makes one account. No third party takes part. The installation must have the open registration policy. ### Authentication No security scheme is declared. See the operation description. ### Responses #### 200 One challenge for the proof of work of a sign-up. ```json { "description": "One challenge for the proof of work of a sign-up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpChallenge" } } } } ``` Schemas: [SignUpChallenge](https://docs.tidynotebook.com/api-schemas.md#signupchallenge). #### 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). #### 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). #### 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). ## readInvitation `POST /api/registrations/invitation` Read the address that a valid invitation binds. Answers the address of a valid invitation, so the person sees the address of their new account before they choose a password. The token travels in the body, so it reaches no address log. ### Authentication No security scheme is declared. See the operation description. ### Request body ```json { "description": "The token of the invitation to read.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationReadInput" } } } } ``` Schemas: [InvitationReadInput](https://docs.tidynotebook.com/api-schemas.md#invitationreadinput). ### Responses #### 200 The address that the invitation binds. ```json { "description": "The address that the invitation binds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationAddress" } } } } ``` Schemas: [InvitationAddress](https://docs.tidynotebook.com/api-schemas.md#invitationaddress). #### 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). #### 403 The invitation opens nothing. The code is invitation_invalid for a token that expired, that somebody used, that an administrator revoked, or that never existed. The answer does not say which. ```json { "description": "The invitation opens nothing. The code is invitation_invalid for a token that expired, that somebody used, that an administrator revoked, or that never existed. The answer does not say which.", "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). ## signUpAccount `POST /api/registrations/open` Ask for an account with an address and a password. Open registration (record 0114). A new address gets a pending account and a verification link by mail. An address that already signs in gets a mail that tells its owner about the attempt. A pending address is replaced, with its password. Every one of these answers the same status and body, so the answer states nothing about the address. The installation must have the open registration policy. ### Authentication No security scheme is declared. See the operation description. ### Request body ```json { "description": "The address and the password of the account that a person asks for.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpInput" } } } } ``` Schemas: [SignUpInput](https://docs.tidynotebook.com/api-schemas.md#signupinput). ### Responses #### 202 The sign-up was taken. A message goes to the address. ```json { "description": "The sign-up was taken. A message goes to the address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpAccepted" } } } } ``` Schemas: [SignUpAccepted](https://docs.tidynotebook.com/api-schemas.md#signupaccepted). #### 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). #### 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 change cannot be accepted next to the state that the workspace holds. The code names the reason: path_conflict for a path that another live file occupies, and mutation_reused for a mutation identity that was already used for another operation. A save of a note adds epoch_mismatch, which means that the note holds another generation of its document, so the device reads the current document before it saves again. ```json { "description": "The change cannot be accepted next to the state that the workspace holds. The code names the reason: path_conflict for a path that another live file occupies, and mutation_reused for a mutation identity that was already used for another operation. A save of a note adds epoch_mismatch, which means that the note holds another generation of its document, so the device reads the current document before it saves 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). ## verifyAddress `POST /api/registrations/verification` Prove the address of a pending account and make the account. Takes the token of a verification link. A valid token marks the address verified and makes the account, and the person then signs in. An expired, a replaced and an unknown token all take one refusal. The token travels in the body, so it reaches no address log. ### Authentication No security scheme is declared. See the operation description. ### Request body ```json { "description": "The token of a verification link.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressVerificationInput" } } } } ``` Schemas: [AddressVerificationInput](https://docs.tidynotebook.com/api-schemas.md#addressverificationinput). ### Responses #### 200 The address is proved and the account exists. ```json { "description": "The address is proved and the account exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressVerified" } } } } ``` Schemas: [AddressVerified](https://docs.tidynotebook.com/api-schemas.md#addressverified). #### 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). #### 403 The verification link opens nothing. The code is verification_invalid for a token that expired, that a later sign-up replaced, or that never existed. The answer does not say which. The code is registration_closed when the installation stopped open registration after the sign-up. ```json { "description": "The verification link opens nothing. The code is verification_invalid for a token that expired, that a later sign-up replaced, or that never existed. The answer does not say which. The code is registration_closed when the installation stopped open registration after the sign-up.", "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). ## getSetupStatus `GET /api/setup` Report whether the first account exists and who can make one. Reports if first-run setup is complete without exposing account data. ### Authentication No security scheme is declared. See the operation description. ### Responses #### 200 The setup state. ```json { "description": "The setup state.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "initialized", "openRegistration", "passwordReset", "legalDocuments" ], "properties": { "initialized": { "type": "boolean", "readOnly": true }, "openRegistration": { "type": "boolean", "readOnly": true, "description": "Whether a person can ask for an account without an invitation (record 0114)." }, "passwordReset": { "type": "boolean", "readOnly": true, "description": "Whether a person can reset a forgotten password by mail (record 0141). It is false when the installation has no mail transport." }, "legalDocuments": { "oneOf": [ { "$ref": "#/components/schemas/LegalDocuments" }, { "type": "null" } ], "description": "The terms and the privacy notice, or null when the installation names none (record 0120)." } } } } } } ``` Schemas: [LegalDocuments](https://docs.tidynotebook.com/api-schemas.md#legaldocuments). #### 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). #### 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). ## createOwner `POST /api/setup` Create the first account during first-run setup. Creates the first account of the installation as its administrator and signs it in. This operation is refused after the first account exists. Every later account comes in through an invitation. ### Authentication No security scheme is declared. See the operation description. ### Request body ```json { "description": "The email address and password of the first account.", "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email", "password" ], "properties": { "email": { "$ref": "#/components/schemas/EmailAddress" }, "password": { "$ref": "#/components/schemas/Password" } } } } } } ``` Schemas: [EmailAddress](https://docs.tidynotebook.com/api-schemas.md#emailaddress), [Password](https://docs.tidynotebook.com/api-schemas.md#password). ### Responses #### 201 The first account was created and signed in. ```json { "description": "The first account was created and signed in.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "initialized" ], "properties": { "initialized": { "type": "boolean", "readOnly": true } } } } } } ``` #### 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). #### 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). #### 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).