2020-05-24 15:00:16 -04:00
openapi : 3.0 .3
2019-10-14 18:58:40 -04:00
info :
title : CodiMD
description : CodiMD is an open source collaborative note editor. Several tasks of CodiMD can be automated through this API.
2020-05-24 15:00:16 -04:00
version : 2.0 .0
2019-10-14 18:58:40 -04:00
contact :
name : CodiMD on GitHub
url : https://github.com/codimd/server
license :
name : AGPLv3
url : https://github.com/codimd/server/blob/master/LICENSE
externalDocs :
2020-05-24 15:00:16 -04:00
description : CodiMD Documentation
url : https://github.com/codimd/server/tree/master/docs
servers :
- url : "/api/v2.0/"
description : "Base API Path"
2019-10-14 18:58:40 -04:00
paths :
2020-05-24 15:00:16 -04:00
/auth/email :
post :
tags :
- auth
summary : Trying to login via email
operationId : loginEmail
requestBody :
required : true
content :
application/json :
schema :
$ref : '#/components/schemas/EmailLogin'
responses :
200 :
description : login succesful
2020-05-27 05:30:32 -04:00
headers :
Set-Cookie :
schema :
type : string
/auth/ldap :
post :
tags :
- auth
summary : Trying to login via LDAP
operationId : loginLdap
requestBody :
required : true
content :
application/json :
schema :
$ref : '#/components/schemas/LdapLogin'
responses :
200 :
description : login succesful
headers :
Set-Cookie :
schema :
type : string
/auth/openid :
post :
tags :
- auth
summary : Trying to login via OpenID
operationId : loginOpenId
requestBody :
required : true
content :
application/json :
schema :
$ref : '#/components/schemas/OpenIdLogin'
responses :
200 :
description : login succesful
headers :
Set-Cookie :
schema :
type : string
2020-05-24 15:00:16 -04:00
/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 :
description : the user is not logged in
content : {}
/me/export :
get :
tags :
- user
summary : Exports a zip-archive with all notes of the current user.
responses :
200 :
description : The zip-archive with all notes
/status :
get :
tags :
- server
summary : Returns the current status of the CodiMD instance.
operationId : getStatus
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"
2020-05-27 07:20:37 -04:00
/notes :
2019-10-14 18:58:40 -04:00
post :
tags :
- note
summary : Imports some markdown data into a new note.
2020-05-24 15:00:16 -04:00
operationId : createNoteFromMarkdown
2019-10-14 18:58:40 -04:00
description : A random id will be assigned and the content will equal to the body of the received HTTP-request.
requestBody :
2020-05-27 05:30:32 -04:00
required : false
2019-10-14 18:58:40 -04:00
description : The content of the note to be imported as markdown
content :
'text/markdown' :
2020-05-24 15:00:16 -04:00
schema :
type : string
examples :
markdownExample :
"$ref": '#/components/examples/markdownExample'
2019-10-14 18:58:40 -04:00
responses :
2020-05-24 15:00:16 -04:00
200 :
description : Get information about the newly created note
content :
application/json :
schema :
2020-05-27 07:25:37 -04:00
"$ref": "#/components/schemas/Note"
2020-05-27 07:20:37 -04:00
/notes/{note}:
2020-05-27 05:30:32 -04:00
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"
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
description : The note for which the info should be shown
content :
text/plain :
example : my-note
2019-10-14 18:58:40 -04:00
post :
tags :
- note
summary : Imports some markdown data into a new note with a given alias.
2020-05-24 15:00:16 -04:00
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.'
2019-10-14 18:58:40 -04:00
requestBody :
required : true
description : The content of the note to be imported as markdown
content :
'text/markdown' :
2020-05-24 15:00:16 -04:00
schema :
type : string
examples :
markdownExample :
"$ref": '#/components/examples/markdownExample'
2019-10-14 18:58:40 -04:00
responses :
2020-05-24 15:00:16 -04:00
200 :
description : Get information about the newly created note
content :
application/json :
schema :
2020-05-27 07:25:37 -04:00
"$ref": "#/components/schemas/Note"
2020-05-24 15:00:16 -04:00
409 :
description : This alias is already in use
2020-05-25 06:04:29 -04:00
parameters :
- name : note
in : path
required : true
description : The note for which the info should be shown
content :
text/plain :
example : my-note
2020-05-27 07:20:37 -04:00
/notes/{note}/permissions:
put :
tags :
- note
summary : Set the permissions of a note
operationId : updateNotePermissions
requestBody :
required : true
content :
application/json :
schema :
"$ref": "#/components/schemas/NotePermissions"
responses :
200 :
description : The updated permissions of the note
content :
application/json :
schema :
"$ref": "#/components/schemas/NotePermissions"
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 : getNotePermissions
responses :
200 :
description : The permissions of the note
content :
application/json :
schema :
"$ref": "#/components/schemas/NotePermissions"
parameters :
- name : note
in : path
required : true
description : The note for which the info should be shown
content :
text/plain :
example : my-note
2020-05-27 08:02:34 -04:00
/notes/{note}/websocket:
get :
tags :
- note
summary : Returns the websocket of a note.
operationId : getNoteWebsocket
responses :
200 :
description : The websocket of the note
content : {}
parameters :
- name : note
in : path
required : true
description : The note for which the markdown should be exported
content :
text/plain :
example : my-note
2020-05-27 07:20:37 -04:00
/notes/{note}/export/markdown:
2020-05-25 06:04:29 -04:00
get :
tags :
- note
- export
2019-10-14 18:58:40 -04:00
summary : Returns the raw markdown content of a note.
2020-05-24 15:00:16 -04:00
operationId : getNoteContent
2020-05-25 06:04:29 -04:00
responses :
200 :
description : The raw markdown content of the note
content :
'text/markdown' :
schema :
type : string
2020-05-27 05:30:32 -04:00
format : binary
2020-05-25 06:04:29 -04:00
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
2020-05-27 05:30:32 -04:00
description : The note for which the markdown should be exported
2020-05-25 06:04:29 -04:00
content :
text/plain :
example : my-note
2020-05-27 07:20:37 -04:00
/notes/{note}/export/html:
2020-05-25 06:04:29 -04:00
get :
tags :
- note
- export
summary : Returns the content of a note as HTML.
operationId : getNoteContentAsHTML
responses :
200 :
2020-05-27 05:30:32 -04:00
description : The raw html content of the note
2020-05-25 06:04:29 -04:00
content :
2020-05-27 05:30:32 -04:00
'text/html' :
2020-05-25 06:04:29 -04:00
schema :
type : string
2020-05-27 05:30:32 -04:00
format : binary
2020-05-25 06:04:29 -04:00
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
2020-05-27 05:30:32 -04:00
description : The note for which the html should be exported
2020-05-25 06:04:29 -04:00
content :
text/plain :
example : my-note
2020-05-27 07:20:37 -04:00
/notes/{note}/export/gist:
2020-05-25 06:04:29 -04:00
get :
tags :
- note
- export
summary : Exports the content of a note to a gist.
operationId : exportNoteToGist
2019-10-14 18:58:40 -04:00
responses :
200 :
2020-05-27 05:30:32 -04:00
description : The link to Gist of the note
2019-10-14 18:58:40 -04:00
content :
2020-05-27 05:30:32 -04:00
application/json :
2020-05-24 15:00:16 -04:00
schema :
2020-05-27 05:30:32 -04:00
"$ref": '#/components/schemas/GistLink'
2019-10-14 18:58:40 -04:00
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
2020-05-27 05:30:32 -04:00
description : The note which should be exported to gist
2019-10-14 18:58:40 -04:00
content :
2020-05-24 15:00:16 -04:00
text/plain :
2019-10-14 18:58:40 -04:00
example : my-note
2020-05-27 07:20:37 -04:00
/notes/{note}/export/dropbox:
2020-05-25 06:04:29 -04:00
get :
tags :
- note
- export
summary : Exports the content of a note to dropbox.
operationId : exportNoteToDropbox
responses :
200 :
2020-05-27 05:30:32 -04:00
description : The dropbox link of the note
2020-05-25 06:04:29 -04:00
content :
2020-05-27 05:30:32 -04:00
application/json :
2020-05-25 06:04:29 -04:00
schema :
2020-05-27 05:30:32 -04:00
"$ref": '#/components/schemas/DropboxLink'
2020-05-25 06:04:29 -04:00
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
2020-05-27 05:30:32 -04:00
description : The note which should be exported to dropbox
2020-05-25 06:04:29 -04:00
content :
text/plain :
example : my-note
2020-05-27 07:20:37 -04:00
/notes/{note}/export/pdf:
2019-10-14 18:58:40 -04:00
get :
tags :
- note
2020-05-27 05:30:32 -04:00
- export
summary : Exports the content of a note as PDF.
operationId : exportNoteToPDF
2019-10-14 18:58:40 -04:00
responses :
200 :
2020-05-27 05:30:32 -04:00
description : The note as an PDF
2019-10-14 18:58:40 -04:00
content :
2020-05-27 05:30:32 -04:00
application/pdf :
2019-10-14 18:58:40 -04:00
schema :
2020-05-27 05:30:32 -04:00
type : string
format : binary
2019-10-14 18:58:40 -04:00
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
2020-05-27 05:30:32 -04:00
description : The note which should be exported to dropbox
2019-10-14 18:58:40 -04:00
content :
2020-05-24 15:00:16 -04:00
text/plain :
2019-10-14 18:58:40 -04:00
example : my-note
2020-05-27 07:20:37 -04:00
/notes/{note}/revision:
2019-10-17 17:26:48 -04:00
get :
tags :
- note
summary : Returns a list of the available note revisions.
2020-05-24 15:00:16 -04:00
operationId : getAllRevisionsOfNote
2019-10-17 17:26:48 -04:00
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 :
2020-05-24 15:00:16 -04:00
application/json :
2019-10-17 17:26:48 -04:00
schema :
2020-05-24 15:00:16 -04:00
"$ref": "#/components/schemas/NoteRevisionsMetadata"
2019-10-17 17:26:48 -04:00
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
description : The note for which revisions should be shown
content :
2020-05-24 15:00:16 -04:00
text/plain :
2019-10-17 17:26:48 -04:00
example : my-note
2020-05-27 07:20:37 -04:00
/notes/{note}/revision/{revision-id}:
2019-10-17 17:26:48 -04:00
get :
tags :
- note
summary : Returns the revision of the note with some metadata.
2020-05-24 15:00:16 -04:00
operationId : getSpecificRevisionOfNote
2019-10-17 17:26:48 -04:00
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 :
2020-05-24 15:00:16 -04:00
application/json :
2019-10-17 17:26:48 -04:00
schema :
2020-05-24 15:00:16 -04:00
"$ref": "#/components/schemas/NoteRevision"
2019-10-17 17:26:48 -04:00
404 :
description : Note does not exist
parameters :
- name : note
in : path
required : true
description : The note for which the revision should be shown
content :
2020-05-24 15:00:16 -04:00
text/plain :
2019-10-17 17:26:48 -04:00
example : my-note
- name : revision-id
in : path
required : true
description : The id (timestamp) of the revision to fetch
content :
2020-05-24 15:00:16 -04:00
text/plain :
2019-10-17 17:26:48 -04:00
example : 1570921051959
2020-05-27 08:34:25 -04:00
/history :
get :
tags :
- history
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"
post :
tags :
- history
2020-05-27 10:50:56 -04:00
summary : Sets the history if none is already set
2020-05-27 08:34:25 -04:00
operationId : updateHistory
requestBody :
description : The history to update
content :
application/json :
schema :
"$ref": "#/components/schemas/History"
responses :
200 :
description : The new history
content :
application/json :
schema :
"$ref": "#/components/schemas/History"
delete :
tags :
- history
summary : Clear the users history
operationId : deleteHistory
responses :
200 :
description : Deleted the history
content : {}
2020-05-27 10:50:56 -04:00
/history/{note}/:
put :
tags :
- history
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"
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
summary : remove the history object of the note
operationId : deleteHistoryObject
responses :
200 :
description : The new history
content : {}
parameters :
- name : note
in : path
required : true
description : The note for which the revision should be shown
content :
text/plain :
example : my-note
2020-05-27 08:58:49 -04:00
/config :
get :
tags :
- config
summary : The config of the backend
operationId : getConfig
responses :
200 :
description : The config
content :
application/json :
schema :
"$ref": "#/components/schemas/Config"
2020-05-24 15:00:16 -04:00
components :
schemas :
UserInfo :
type : object
properties :
id :
type : string
format : UUIDv4
name :
type : string
photo :
type : string
format : uri
2020-05-27 08:58:49 -04:00
Config :
type : object
properties :
allowAnonymous :
type : boolean
description : Wether anonymous notes are allowed
authProviders :
type : object
properties :
facebook :
type : boolean
description : Wether Facebook login is possible
github :
type : boolean
description : Wether GitHub login is possible
twitter :
type : boolean
description : Wether Twitter login is possible
gitlab :
type : boolean
description : Wether Gitlab login is possible
dropbox :
type : boolean
description : Wether Dropbox login is possible
google :
type : boolean
description : Wether Google login is possible
saml :
type : boolean
description : Wether SAML login is possible
oauth2 :
type : boolean
description : Wether OAuth2 login is possible
email :
type : boolean
description : Wether E-Mail login is possible
ldap :
type : boolean
description : Wether LDAP login is possible
openid :
type : boolean
description : Wether OpenID login is possible
customAuthNames :
type : object
properties :
ldap :
type : string
description : The custom name for the LDAP Login
example : "FooBar LDAP"
oauth2 :
type : string
description : The custom name for the OAuth2 Login
example : "Olaf2"
saml :
type : string
description : The custom name for the SAML Login
example : "aufSAMLn.de"
specialLinks :
type : object
properties :
privacy :
type : string
format : uri
description : Link to the privacy notice
termsOfUse :
type : string
format : uri
description : Link to the terms of use
imprint :
type : string
format : uri
description : Link to the imprint
2020-05-25 06:04:29 -04:00
Note :
type : object
properties :
id :
type : string
format : UUIDv4
description : The id of the note
alias :
type : string
description : The alias of the note
lastChange :
type : object
properties :
userId :
type : string
format : UUIDv4
description : The id of the user that last changed the note
user :
type : string
description : The name of the user that last changed the note
timestamp :
type : integer
description : UNIX-timestamp of when the note was last changed.
2020-05-27 05:30:32 -04:00
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.
2020-05-25 06:04:29 -04:00
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
2020-05-27 07:20:37 -04:00
NotePermissions :
type : object
properties :
permission :
type : string
enum : [ 'freely' , 'editable' , 'limited' , 'locked' , 'protected' , 'private' ]
2020-05-24 15:00:16 -04:00
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 :
2019-10-17 17:26:48 -04:00
content :
2020-05-24 15:00:16 -04:00
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
2020-05-27 05:30:32 -04:00
GistLink :
2020-05-24 15:00:16 -04:00
type : object
properties :
2020-05-27 05:30:32 -04:00
link :
2020-05-24 15:00:16 -04:00
type : string
2020-05-27 05:30:32 -04:00
format : uri
description : A Gist link
DropboxLink :
type : object
properties :
link :
2020-05-24 15:00:16 -04:00
type : string
2020-05-27 05:30:32 -04:00
format : uri
description : A Dropbox link
2020-05-24 15:00:16 -04:00
EmailLogin :
type : object
properties :
email :
type : string
format : email
password :
type : string
format : password
2020-05-27 05:30:32 -04:00
LdapLogin :
type : object
properties :
username :
type : string
format : email
password :
type : string
format : password
OpenIdLogin :
type : object
properties :
openId :
type : string
2020-05-24 15:00:16 -04:00
ServerStatus :
type : object
properties :
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
2020-05-27 08:34:25 -04:00
HistoryObject :
type : object
properties :
id :
type : string
description : The id or alias of the note
title :
type : string
description : The title of the note
lastVisited :
type : integer
description : The UNIX-timestamp in milliseconds when the note was last accessed by the user
tags :
type : array
description : The tags that were added by the user to the note
items :
type : string
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"
2020-05-24 15:00:16 -04:00
examples :
markdownExample :
value : '# Some header\nSome normal text. **Some bold text**'
summary : A sample markdown content