openapi: 3.0.3 info: title: HedgeDoc description: HedgeDoc is an open source collaborative note editor. Several tasks of HedgeDoc can be automated through this API. version: 2.0.0 contact: name: HedgeDoc on GitHub url: https://github.com/codimd/server license: name: AGPLv3 url: https://github.com/codimd/server/blob/master/LICENSE externalDocs: description: The CodiMD Documentation. url: https://github.com/codimd/server/tree/master/docs servers: - url: "/api/v2" description: The base API Path. security: - bearerAuth: [] paths: /me: get: tags: - user summary: Get the user information of the currently logged-in user operationId: getMe responses: '200': description: The user information. content: application/json: schema: "$ref": "#/components/schemas/UserInfo" '401': "$ref": "#/components/responses/UnauthorizedError" /me/history: get: tags: - history - user summary: Returns a list of the last viewed notes operationId: getHistory description: The list is returned as a JSON object with an array containing for each entry it's id, title, tags, last visit time and pinned status. responses: '200': description: The list of recently viewed notes and pinned notes. content: application/json: schema: "$ref": "#/components/schemas/History" '401': "$ref": "#/components/responses/UnauthorizedError" /me/history/{note}: get: tags: - history - user summary: Returns History data for a note operationId: getHistoryObject description: JSON Object which contains id, title, tags, last visit time and pinned status responses: '200': description: The list of recently viewed notes and pinned notes. content: application/json: schema: "$ref": "#/components/schemas/HistoryObject" '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" parameters: - name: note in: path required: true description: The name of the note which is used to address it. content: text/plain: example: my-note put: tags: - history - user summary: Update the history object of the note (e.g change it's pin status) operationId: updateHistoryObject requestBody: description: The updated history object. content: application/json: schema: "$ref": "#/components/schemas/HistoryObject" responses: '200': description: The new history. content: application/json: schema: "$ref": "#/components/schemas/HistoryObject" '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" parameters: - name: note in: path required: true description: The note for which the revision should be shown. content: text/plain: example: my-note delete: tags: - history - user summary: Remove the note from the currently logged-in user's history operationId: deleteHistoryObject responses: '204': "$ref": "#/components/responses/SuccessfullyDeleted" '401': "$ref": "#/components/responses/UnauthorizedError" '404': "$ref": "#/components/responses/NotFoundError" parameters: - name: note in: path required: true description: The note for which the revision should be shown. content: text/plain: example: my-note /me/notes: get: tags: - user summary: Returns a list of the notes metadata the user owns operationId: getOwnNotes description: The list is returned as a JSON object with an array containing each notes metadata. responses: '200': description: The list of notes owned by the currently logged in user. content: application/json: schema: type: array description: The array that contains notes metadata. items: "$ref": "#/components/schemas/NoteMetadata" '401': "$ref": "#/components/responses/UnauthorizedError" /notes: post: tags: - note summary: Imports some markdown data into a new note operationId: createNoteFromMarkdown description: A random id will be assigned and the content will equal to the body of the received HTTP-request. security: - bearerAuth: [] - {} requestBody: required: false description: The content of the note to be imported as markdown. content: 'text/markdown': schema: type: string examples: markdownExample: "$ref": '#/components/examples/markdownExample' responses: '200': description: Get information about the newly created note. content: application/json: schema: "$ref": "#/components/schemas/Note" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" /notes/{note}: get: tags: - note summary: Returns the note operationId: getNote description: This includes all metadata and the content of the note. responses: '200': description: All data of the note. content: application/json: schema: "$ref": "#/components/schemas/Note" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" parameters: - name: note in: path required: true description: The name of the note which is used to address it. content: text/plain: example: my-note post: tags: - note summary: Imports some markdown data into a new note with a given alias operationId: createNoteWithAlias description: This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](https://github.com/codimd/server/tree/master/docs/configuration-env-vars.md#users-and-privileges) is enabled. requestBody: required: true description: The content of the note to be imported as markdown. content: 'text/markdown': schema: type: string examples: markdownExample: "$ref": '#/components/examples/markdownExample' responses: '200': description: Get information about the newly created note. content: application/json: schema: "$ref": "#/components/schemas/Note" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '409': description: This alias is already in use. parameters: - name: note in: path required: true description: The name of the note which is used to address it. content: text/plain: example: my-note delete: tags: - note summary: Remove the note operationId: deleteNote responses: '204': "$ref": "#/components/responses/SuccessfullyDeleted" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" parameters: - name: note in: path required: true description: The note for which the revision should be shown. content: text/plain: example: my-note put: tags: - note summary: Imports some markdown data into an existing note, creating a new revision operationId: createNewRevisionForNote description: This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](https://github.com/codimd/server/tree/master/docs/configuration-env-vars.md#users-and-privileges) is enabled. requestBody: required: true description: The content of the note to be imported as markdown. content: 'text/markdown': schema: type: string examples: markdownExample: "$ref": '#/components/examples/markdownExample' responses: '200': description: The new, changed note content: application/json: schema: "$ref": "#/components/schemas/Note" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" parameters: - name: note in: path required: true description: The note for which the info should be shown. content: text/plain: example: my-note /notes/{note}/metadata: put: tags: - note summary: Set the permissions of a note operationId: updateNoteMetadata requestBody: required: true content: application/json: schema: "$ref": "#/components/schemas/NoteMetadata" responses: '200': description: The updated permissions of the note. content: application/json: schema: "$ref": "#/components/schemas/NoteMetadata" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" parameters: - name: note in: path required: true description: The note for which the info should be shown. content: text/plain: example: my-note get: tags: - note summary: Get the permissions of a note operationId: getNoteMetadata responses: '200': description: The permissions of the note. content: application/json: schema: "$ref": "#/components/schemas/NoteMetadata" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" parameters: - name: note in: path required: true description: The note for which the info should be shown. content: text/plain: example: my-note /notes/{note}/revisions: get: tags: - note summary: Returns a list of the available note revisions operationId: getAllRevisionsOfNote description: The list is returned as a JSON object with an array of revision-id and length associations. The revision-id equals to the timestamp when the revision was saved. responses: '200': description: Revisions of the note. content: application/json: schema: "$ref": "#/components/schemas/NoteRevisionsMetadata" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" parameters: - name: note in: path required: true description: The note for which revisions should be shown. content: text/plain: example: my-note /notes/{note}/revisions/{revision-id}: get: tags: - note summary: Returns the revision of the note with some metadata operationId: getSpecificRevisionOfNote description: The revision is returned as a JSON object with the content of the note and the authorship. responses: '200': description: Revision of the note for the given timestamp. content: application/json: schema: "$ref": "#/components/schemas/NoteRevision" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" parameters: - name: note in: path required: true description: The note for which the revision should be shown. content: text/plain: example: my-note - name: revision-id in: path required: true description: The id (timestamp) of the revision to fetch. content: text/plain: example: 1570921051959 /notes/{note}/content: get: tags: - note - export summary: Returns the raw markdown content of a note operationId: getNoteContent responses: '200': description: The raw markdown content of the note. content: 'text/markdown': schema: type: string format: binary '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" '404': "$ref": "#/components/responses/NotFoundError" parameters: - name: note in: path required: true description: The note for which the markdown should be exported. content: text/plain: example: my-note /media/upload: post: tags: - media summary: Uploads an image to the backend storage description: Uploads an image to be processed by the backend. requestBody: required: true description: The binary image to upload. content: image/*: schema: type: string format: binary responses: '200': description: The image was uploaded successfully. '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" /monitoring: get: tags: - monitoring summary: Returns the current status of the backend operationId: getMonitoring description: The data is returned as a JSON object containing the number of notes stored on the server, (distinct) online users and more. responses: '200': description: The server info. content: application/json: schema: "$ref": "#/components/schemas/ServerStatus" '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" /monitoring/prometheus: get: tags: - monitoring summary: Returns the current status of the backend for Prometheus. operationId: getPrometheus description: The data is returned in Prometheus Exposition Format responses: '200': description: Prometheus compatible monitoring data. content: text/plain: {} '401': "$ref": "#/components/responses/UnauthorizedError" '403': "$ref": "#/components/responses/ForbiddenError" components: schemas: UserInfo: type: object properties: userName: type: string displayName: type: string photo: type: string format: uri email: type: string format: email UserPasswordChange: type: object properties: password: type: string ImageProxyRequest: type: object properties: src: type: string description: The url of the image that should be processed by the image proxy. ImageProxyResponse: type: object properties: src: type: string description: The url of the provied version of the image. Note: type: object properties: content: type: string description: The markdown content of the note metadata: $ref: "#/components/schemas/NoteMetadata" editedByAtPosition: type: array description: Data which gives insights about who worked where on the note. items: type: integer description: Unique user ids and additional data NoteMetadata: type: object properties: id: type: string format: UUIDv4 description: The id of the note. alias: type: string description: The alias of the note. title: type: string description: Title of the note description: type: string description: Description of the note. tags: type: array description: A list of tags attached to the note. items: type: string description: A tag updateTime: type: integer description: UNIX-timestamp of when the note was last changed. updateUser: $ref: "#/components/schemas/UserInfo" viewCount: type: integer minimum: 0 description: How often the published version of the note was viewed. createTime: type: string description: The timestamp when the note was created in ISO 8601 format. editedBy: type: array description: List of usernames who edited the note. items: type: string permissions: $ref: "#/components/schemas/NotePermissions" NotePermissions: type: object properties: owner: type: string description: Username of the owner of the note sharedTo: type: array description: Contains all usernames that can read the note and a boolean that denotes if they can also edit. items: type: object properties: username: type: string canEdit: type: boolean NoteRevisionsMetadata: type: object properties: revision: type: array description: Array that holds all revision-info objects. items: type: object properties: time: type: integer description: UNIX-timestamp of when the revision was saved. Is also the revision-id. length: type: integer description: Length of the document to the timepoint the revision was saved. NoteRevision: type: object properties: content: type: string description: The raw markdown content of the note revision. authorship: type: array description: Data which gives insights about who worked on the note. items: type: integer description: Unique user ids and additional data. patch: type: array description: Data which gives insight about what changed in comparison to former revisions. items: type: string GistLink: type: object properties: link: type: string format: uri description: A Gist link. DropboxLink: type: object properties: link: type: string format: uri description: A Dropbox link. EmailLogin: type: object properties: email: type: string format: email password: type: string format: password LdapLogin: type: object properties: username: type: string format: email password: type: string format: password OpenIdLogin: type: object properties: openId: type: string ServerStatus: type: object properties: serverVersion: type: object properties: major: type: integer minor: type: integer patch: type: integer preRelease: type: string commit: type: string description: Version of the server specified according to SemVer specification onlineNotes: type: integer description: How many notes are edited at the moment. onlineUsers: type: integer description: How many users are online at the moment. distinctOnlineUsers: type: integer description: How many distinct users (different machines) are online at the moment. notesCount: type: integer description: How many notes are stored on the server. registeredUsers: type: integer description: How many users are registered on the server. onlineRegisteredUsers: type: integer description: How many of the online users are registered on the server. distinctOnlineRegisteredUsers: type: integer description: How many of the distinct online users are registered on the server. isConnectionBusy: type: boolean connectionSocketQueueLength: type: integer isDisconnectBusy: type: boolean disconnectSocketQueueLength: type: integer HistoryObject: type: object properties: metadata: $ref: "#/components/schemas/NoteMetadata" pinned: type: boolean description: Whether the user has pinned this note. History: type: object properties: history: type: array description: The array that contains history objects. items: "$ref": "#/components/schemas/HistoryObject" examples: markdownExample: value: '# Some header\nSome normal text. **Some bold text**' summary: A sample markdown content securitySchemes: bearerAuth: type: http scheme: bearer responses: UnauthorizedError: description: Authorization information is missing or invalid. ForbiddenError: description: Access to the requested resource is not permitted. NotFoundError: description: The requested resource was not found. SuccessfullyDeleted: description: The requested resource was sucessfully deleted.