tidy notebookDocs GitHub

API reference

View as Markdown

API publishing

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

Read-only links that an owner makes over one note or one folder.

createPublishedLink

POST /api/workspaces/{workspaceId}/publications

Publish a read-only link to one note or one folder.

Makes one read-only link over one note, or over one folder and every note below it. The answer holds the token of the new link. The server keeps only a digest of that token, so this is the one time that the value exists outside the address that the owner copies. A workspace holds a bounded number of links, and a request past that bound is refused.

Authentication

Use one of these options:

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

workspaceId

JSON

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

Schemas: Uuid.

Request body

JSON

{
  "description": "What to publish, and how a reader reaches it.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreatePublishedLinkInput"
      }
    }
  }
}

Schemas: CreatePublishedLinkInput.

Responses

201

The new link and its token. This answer shows the token once, and no later answer holds it.

JSON

{
  "description": "The new link and its token. This answer shows the token once, and no later answer holds it.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PublishedLinkCreated"
      }
    }
  }
}

Schemas: PublishedLinkCreated.

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.

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.

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.

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.

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.

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.

422

The request is well formed but its content cannot be accepted. The code names the reason: invalid_path, invalid_graph, invalid_content, or too_many_files. A save of a note adds document_malformed for bytes that are not an update, document_dependency_missing for work that names an insertion or a deletion the document lacks, and document_unsupported for work that writes anything other than the text of the note, and unrenderable_note for a note over a limit of the Markdown grammar, with the limit in noteRefusal. Each of them leaves the accepted state exactly as it was.

JSON

{
  "description": "The request is well formed but its content cannot be accepted. The code names the reason: invalid_path, invalid_graph, invalid_content, or too_many_files. A save of a note adds document_malformed for bytes that are not an update, document_dependency_missing for work that names an insertion or a deletion the document lacks, and document_unsupported for work that writes anything other than the text of the note, and unrenderable_note for a note over a limit of the Markdown grammar, with the limit in noteRefusal. Each of them leaves the accepted state exactly as it was.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: 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.

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.

listPublishedLinks

GET /api/workspaces/{workspaceId}/publications

List the published links of a workspace.

Reports every published link of the workspace, what it opens, when it expires, and whether it has a password. No entry holds a token and no entry holds a part of one, so a read of this list opens nothing. The answer reports no reader count, because the reader path counts nothing.

Authentication

Use one of these options:

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

workspaceId

JSON

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

Schemas: Uuid.

Responses

200

Every published link of the workspace, without a token.

JSON

{
  "description": "Every published link of the workspace, without a token.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/PublishedLinkList"
      }
    }
  }
}

Schemas: PublishedLinkList.

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.

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.

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.

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.

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.

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.

revokePublishedLink

DELETE /api/workspaces/{workspaceId}/publications/{publicationId}

Revoke one published link.

Stops one published link. The server reads the link record on every reader call, so the link opens nothing from the next call onward. A reader that holds the token then takes the one refusal of the reader path.

Authentication

Use one of these options:

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

workspaceId

JSON

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

Schemas: Uuid.

publicationId

JSON

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

Schemas: 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.

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.

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.

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.

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.

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.

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.