API published
This page is for the person who connects a program to the API.
The reader path of a published link. No operation of this tag names a security scheme, so no identity hook runs for one.
getPublishedPage
GET /published/{token}
Read the page of a published link.
Answers the published note as one HTML document that the server builds with the one sanitized renderer. The operation declares an empty security requirement, so no identity hook runs for it and no session reaches it. Every state of a link answers one document: it shows the note, or it says that the link is not available, or it asks for the password. A link that never existed, a revoked link, an expired link and a wrong password therefore read alike.
Authentication
No security scheme is declared. See the operation description.
Parameters
x-request-id
{
"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._-]+$"
}
}
token
{
"name": "token",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"description": "The token of the published link. It is the one part of the address that opens the link. Any single segment of an address is accepted here, because a value that no link holds opens nothing and must read like every other value that no link holds.",
"schema": {
"$ref": "#/components/schemas/PublishedSecret"
}
}
Schemas: PublishedSecret.
note
{
"name": "note",
"in": "query",
"required": false,
"style": "form",
"explode": true,
"description": "The note of a folder link that the page shows. Leave it out to read the list of every note that the link opens. A link over one note opens that note, so it needs no value here.",
"schema": {
"$ref": "#/components/schemas/PublishedNoteReference"
}
}
Schemas: PublishedNoteReference.
ticket
{
"name": "ticket",
"in": "query",
"required": false,
"style": "form",
"explode": true,
"description": "The reading ticket of a link that has a password. The reader carries it in the address, because a picture inside a server built page sets no header and the reader path sets no cookie. Leave it out for a link that opens without a password.",
"schema": {
"$ref": "#/components/schemas/PublishedSecret"
}
}
Schemas: PublishedSecret.
Responses
200
The published page, as one HTML document.
{
"description": "The published page, as one HTML document.",
"headers": {
"cache-control": {
"description": "States that the page belongs to this reader. No shared cache stores it.",
"schema": {
"type": "string",
"maxLength": 256
}
}
},
"content": {
"text/html": {
"schema": {
"$ref": "#/components/schemas/PublishedDocument"
}
}
}
}
Schemas: PublishedDocument.
400
The request did not match the contract.
{
"description": "The request did not match the contract.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: ProblemDetails.
500
The service failed to complete the request.
{
"description": "The service failed to complete the request.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: ProblemDetails.
openPublishedPage
POST /published/{token}
Give the password of a published link from its page.
Takes the password that the form of the published page carries and answers the page again. A served page holds no script, so the form sends a form encoded body and the answer is a document rather than a program. The right password answers the note, and every address on that page carries the reading ticket. A wrong password answers the same form and the same words as a link that was never opened. The operation declares an empty security requirement, so no identity hook runs for it. The attempt limit of this route guards the password check.
Authentication
No security scheme is declared. See the operation description.
Parameters
x-request-id
{
"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._-]+$"
}
}
token
{
"name": "token",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"description": "The token of the published link. It is the one part of the address that opens the link. Any single segment of an address is accepted here, because a value that no link holds opens nothing and must read like every other value that no link holds.",
"schema": {
"$ref": "#/components/schemas/PublishedSecret"
}
}
Schemas: PublishedSecret.
note
{
"name": "note",
"in": "query",
"required": false,
"style": "form",
"explode": true,
"description": "The note of a folder link that the page shows. Leave it out to read the list of every note that the link opens. A link over one note opens that note, so it needs no value here.",
"schema": {
"$ref": "#/components/schemas/PublishedNoteReference"
}
}
Schemas: PublishedNoteReference.
Request body
{
"description": "The password of the published link, as its page form sends it.",
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/PublishedPasswordFormInput"
}
}
}
}
Schemas: PublishedPasswordFormInput.
Responses
200
The published page, as one HTML document.
{
"description": "The published page, as one HTML document.",
"headers": {
"cache-control": {
"description": "States that the page belongs to this reader. No shared cache stores it.",
"schema": {
"type": "string",
"maxLength": 256
}
}
},
"content": {
"text/html": {
"schema": {
"$ref": "#/components/schemas/PublishedDocument"
}
}
}
}
Schemas: PublishedDocument.
400
The request did not match the contract.
{
"description": "The request did not match the contract.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: 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.
{
"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.
415
The request media type is not supported.
{
"description": "The request media type is not supported.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: 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.
{
"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, UsageLimit.
500
The service failed to complete the request.
{
"description": "The service failed to complete the request.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: ProblemDetails.
getPublishedAttachment
GET /published/{token}/attachments/{fileId}/{revisionId}
Read a picture of a published note.
Streams the bytes of one attachment revision that a published note names. The address names the link, the note and the revision, and the server proves all three facts on every call: the link opens the note, and the current content of that note names that revision. It trusts no part of the address. The operation declares an empty security requirement, so no identity hook runs for it. Every failure takes the one refusal of the reader path.
Authentication
No security scheme is declared. See the operation description.
Parameters
x-request-id
{
"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._-]+$"
}
}
token
{
"name": "token",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"description": "The token of the published link. It is the one part of the address that opens the link. Any single segment of an address is accepted here, because a value that no link holds opens nothing and must read like every other value that no link holds.",
"schema": {
"$ref": "#/components/schemas/PublishedSecret"
}
}
Schemas: PublishedSecret.
fileId
{
"name": "fileId",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"description": "Identifier of the file that the operation acts on.",
"schema": {
"$ref": "#/components/schemas/Uuid"
}
}
Schemas: Uuid.
revisionId
{
"name": "revisionId",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"description": "Identifier of the revision that the operation reads.",
"schema": {
"$ref": "#/components/schemas/Uuid"
}
}
Schemas: Uuid.
ticket
{
"name": "ticket",
"in": "query",
"required": false,
"style": "form",
"explode": true,
"description": "The reading ticket of a link that has a password. The reader carries it in the address, because a picture inside a server built page sets no header and the reader path sets no cookie. Leave it out for a link that opens without a password.",
"schema": {
"$ref": "#/components/schemas/PublishedSecret"
}
}
Schemas: PublishedSecret.
Responses
200
Binary bytes of the immutable attachment.
{
"description": "Binary bytes of the immutable attachment.",
"headers": {
"content-disposition": {
"description": "Names the file and states what the client does with the bytes. An image of an accepted type is shown, and every other type is saved.",
"schema": {
"type": "string",
"maxLength": 1024
}
}
},
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/jpeg": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/gif": {
"schema": {
"type": "string",
"format": "binary"
}
},
"image/webp": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
400
The request did not match the contract.
{
"description": "The request did not match the contract.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: ProblemDetails.
404
The link is not available. Every reader operation answers this one shape for a link that never existed, a revoked link, an expired link and a wrong password, so the four causes read alike.
{
"description": "The link is not available. Every reader operation answers this one shape for a link that never existed, a revoked link, an expired link and a wrong password, so the four causes read alike.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/PublishedRefusal"
}
}
}
}
Schemas: PublishedRefusal.
500
The service failed to complete the request.
{
"description": "The service failed to complete the request.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: ProblemDetails.
getReportPage
GET /published/{token}/report
Read the report form of a published link.
Answers one HTML document that the server builds, with no script. The form asks for a reason from a fixed list and an optional note. The form answers the same document for every token, so it states nothing about the link.
Authentication
No security scheme is declared. See the operation description.
Parameters
x-request-id
{
"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._-]+$"
}
}
token
{
"name": "token",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"description": "The token of the published link. It is the one part of the address that opens the link. Any single segment of an address is accepted here, because a value that no link holds opens nothing and must read like every other value that no link holds.",
"schema": {
"$ref": "#/components/schemas/PublishedSecret"
}
}
Schemas: PublishedSecret.
Responses
200
The published page, as one HTML document.
{
"description": "The published page, as one HTML document.",
"headers": {
"cache-control": {
"description": "States that the page belongs to this reader. No shared cache stores it.",
"schema": {
"type": "string",
"maxLength": 256
}
}
},
"content": {
"text/html": {
"schema": {
"$ref": "#/components/schemas/PublishedDocument"
}
}
}
}
Schemas: PublishedDocument.
400
The request did not match the contract.
{
"description": "The request did not match the contract.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: ProblemDetails.
500
The service failed to complete the request.
{
"description": "The service failed to complete the request.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: ProblemDetails.
reportPublishedLink
POST /published/{token}/report
Report a published link to the administrators.
Takes the reason and the note of the report form and answers one document that thanks the reader. The report is the second write of the reader path. One narrow function stores it for a link that opens now, and stores nothing for any other token. Both answer the same document. The operation declares an empty security requirement, so no identity hook runs for it. The attempt limit of this route counts each client address, and each /64 prefix of an IPv6 address.
Authentication
No security scheme is declared. See the operation description.
Parameters
x-request-id
{
"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._-]+$"
}
}
token
{
"name": "token",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"description": "The token of the published link. It is the one part of the address that opens the link. Any single segment of an address is accepted here, because a value that no link holds opens nothing and must read like every other value that no link holds.",
"schema": {
"$ref": "#/components/schemas/PublishedSecret"
}
}
Schemas: PublishedSecret.
Request body
{
"description": "The report of a published link, as its form sends it.",
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/PublishedReportFormInput"
}
}
}
}
Schemas: PublishedReportFormInput.
Responses
200
The published page, as one HTML document.
{
"description": "The published page, as one HTML document.",
"headers": {
"cache-control": {
"description": "States that the page belongs to this reader. No shared cache stores it.",
"schema": {
"type": "string",
"maxLength": 256
}
}
},
"content": {
"text/html": {
"schema": {
"$ref": "#/components/schemas/PublishedDocument"
}
}
}
}
Schemas: PublishedDocument.
400
The request did not match the contract.
{
"description": "The request did not match the contract.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: 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.
{
"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.
415
The request media type is not supported.
{
"description": "The request media type is not supported.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: 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.
{
"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, UsageLimit.
500
The service failed to complete the request.
{
"description": "The service failed to complete the request.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: ProblemDetails.
unlockPublishedLink
POST /published/{token}/unlock
Give the password of a published link.
Takes the password of one link and answers a reading ticket that is bound to that link. The reader carries the ticket in the address of every later call to the link, and the server sets no cookie. The operation declares an empty security requirement, so no identity hook runs for it. A wrong password and a link that never existed take one refusal, so a caller cannot walk the tokens. The attempt limit of this route guards the password check.
Authentication
No security scheme is declared. See the operation description.
Parameters
x-request-id
{
"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._-]+$"
}
}
token
{
"name": "token",
"in": "path",
"required": true,
"style": "simple",
"explode": false,
"description": "The token of the published link. It is the one part of the address that opens the link. Any single segment of an address is accepted here, because a value that no link holds opens nothing and must read like every other value that no link holds.",
"schema": {
"$ref": "#/components/schemas/PublishedSecret"
}
}
Schemas: PublishedSecret.
Request body
{
"description": "The password of the published link.",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnlockPublishedLinkInput"
}
}
}
}
Schemas: UnlockPublishedLinkInput.
Responses
200
The reading ticket of the link.
{
"description": "The reading ticket of the link.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReadingTicketGrant"
}
}
}
}
Schemas: ReadingTicketGrant.
400
The request did not match the contract.
{
"description": "The request did not match the contract.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: ProblemDetails.
404
The link is not available. Every reader operation answers this one shape for a link that never existed, a revoked link, an expired link and a wrong password, so the four causes read alike.
{
"description": "The link is not available. Every reader operation answers this one shape for a link that never existed, a revoked link, an expired link and a wrong password, so the four causes read alike.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/PublishedRefusal"
}
}
}
}
Schemas: PublishedRefusal.
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.
{
"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.
415
The request media type is not supported.
{
"description": "The request media type is not supported.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: 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.
{
"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, UsageLimit.
500
The service failed to complete the request.
{
"description": "The service failed to complete the request.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
Schemas: ProblemDetails.