API Title

Markdown formatted description.

Subtitle

Also Markdown formatted. This also includes automatic “smartypants” formatting – hooray!

“A quote from another time and place”

Another paragraph. Code sample:

Authorization: bearer 5262d64b892e8d4341000001

And some code with no highlighting:

Foo bar baz

A list
Of items
Can be
Very useful

Here is a table:

ID	Name	Description
1	Foo	I am a foo.
8	Bar	I am a bar.
15	Baz	I am a baz.

Extensions

Some non-standard Markdown extensions are also supported, such as this informational container, which can also contain formatting. Features include:

Informational block fenced with ::: note and :::
Warning block fenced with ::: warning and :::
GitHub-style checkboxes using [x] and [ ]
Emoji support 😀 🚀 🍰 using :smile: (cheat sheet)

These extensions may change in the future as the CommonMark specification defines a standard extension syntax.

Included File

This is content that was included from another file! It’s easy, simply use include(filename) in an HTML comment ().

Included files can include other files as well, allowing you to structure your API documentation as you see fit. Since Markdown supports inline HTML, the files you include can be either Markdown or HTML.

Notes ¶

Group description (also with Markdown)

Important Info

Descriptions may also contain sub-headings and more Markdown.

Note List ¶

Note list description

Even
More
Markdown

Get Notes
GET`/notes`

Get a list of notes.

Example URI

GET https://api.example.com/notes

Response 200

HideShow

Headers

Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms

Body

[
  {
    "id": 1,
    "title": "Grocery list",
    "body": "Buy milk"
  }
]

Schema

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number",
        "description": "Unique identifier"
      },
      "title": {
        "type": "string",
        "description": "Single line description"
      },
      "body": {
        "type": "string",
        "description": "Full description of the note which supports Markdown."
      }
    },
    "required": [
      "id",
      "title"
    ]
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Create New Note
POST`/notes`

Create a new note using a title and an optional content body.

Example URI

POST https://api.example.com/notes

Request with body

HideShow

Headers

Content-Type: application/json

Body

{
  "title": "My new note",
  "body": "This is the body"
}

Response 201

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "Invalid title"
}

Request without body

HideShow

Headers

Content-Type: application/json

Body

{
  "title": "My new note"
}

Response 201

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "Invalid title"
}

Note ¶

Note description

Get Note
GET`/notes/{id}{?body}`

Get a single note.

Example URI

GET https://api.example.com/notes/id?body=false

URI Parameters

HideShow

id: string (required) Example: 68a5sdf67
The note ID
body: boolean (required) Example: false
Set to false to exclude note body content.

Response 200

HideShow

Headers

Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms

Body

{
  "id": 1,
  "title": "Grocery list",
  "body": "Buy milk"
}

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Unique identifier"
    },
    "title": {
      "type": "string",
      "description": "Single line description"
    },
    "body": {
      "type": "string",
      "description": "Full description of the note which supports Markdown."
    }
  },
  "required": [
    "id",
    "title"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Response 404

HideShow

Headers

Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms

Body

{
  "error": "Note not found"
}

Update a Note
PUT`/notes/{id}`

Update a single note by setting the title and/or body.

Caution

If the value for title or body is null or undefined, then the corresponding value is not modified on the server. However, if you send an empty string instead then it will permanently overwrite the original value.

Example URI

PUT https://api.example.com/notes/id

URI Parameters

HideShow

id: string (required) Example: 68a5sdf67
The note ID

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "title": "Grocery List (Safeway)"
}

Response 200

HideShow

Headers

Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms

Body

{
  "id": 1,
  "title": "Grocery list",
  "body": "Buy milk"
}

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Unique identifier"
    },
    "title": {
      "type": "string",
      "description": "Single line description"
    },
    "body": {
      "type": "string",
      "description": "Full description of the note which supports Markdown."
    }
  },
  "required": [
    "id",
    "title"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Response 404

HideShow

Headers

Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms

Body

{
  "error": "Note not found"
}

Request delete body

HideShow

Headers

Content-Type: application/json

Body

{
  "body": ""
}

Response 200

HideShow

Headers

Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms

Body

{
  "id": 1,
  "title": "Grocery list",
  "body": "Buy milk"
}

Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Unique identifier"
    },
    "title": {
      "type": "string",
      "description": "Single line description"
    },
    "body": {
      "type": "string",
      "description": "Full description of the note which supports Markdown."
    }
  },
  "required": [
    "id",
    "title"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Response 404

HideShow

Headers

Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms

Body

{
  "error": "Note not found"
}

Delete a Note
DELETE`/notes/{id}`

Delete a single note

Example URI

DELETE https://api.example.com/notes/id

URI Parameters

HideShow

id: string (required) Example: 68a5sdf67
The note ID

Response 204

Response 404

HideShow

Headers

Content-Type: application/json
X-Request-ID: f72fc914
X-Response-Time: 4ms

Body

{
  "error": "Note not found"
}

Users ¶

Group description

User List ¶

A list of users

Get users
GET`/users{?name,joinedBefore,joinedAfter,sort,limit}`

Get a list of users. Example:

https://api.mywebsite.com/users?sort=joined&limit=5

Example URI

GET https://api.example.com/users?name=alice&joinedBefore=2011-01-01&joinedAfter=2011-01-01&sort=joined&limit=25

URI Parameters

HideShow

name

string (optional) Example: alice

Search for a user by name

joinedBefore

string (optional) Example: 2011-01-01

Search by join date

joinedAfter

string (optional) Example: 2011-01-01

Search by join date

sort

string (optional) Default: name Example: joined

Which field to sort by

Choices: name joined -joined age -age location -location plan -plan

limit

integer (optional) Default: 10 Example: 25

The maximum number of users to return, up to 50

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "name": "alice",
    "image": "http://example.com/alice.jpg",
    "joined": "2013-11-01"
  },
  {
    "name": "bob",
    "image": "http://example.com/bob.jpg",
    "joined": "2013-11-02"
  }
]

Schema

{
  "type": "array",
  "maxItems": 50,
  "items": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "image": {
        "type": "string"
      },
      "joined": {
        "type": "string",
        "pattern": "\\d{4}-\\d{2}-\\d{2}"
      }
    }
  }
}

Tags and Tagging Long Title ¶

Get or set tags on notes

Resource ¶

GET`/tags`

Get a list of bars

Example URI

GET https://api.example.com/tags

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  "tag1",
  "tag2",
  "tag3"
]

Get one tag ¶

Get a single tag

GET`/tags/{id}`

Example URI

GET https://api.example.com/tags/id

URI Parameters

HideShow

id: string (required)
Unique tag identifier

Response 200

Subtitle ¶

Extensions ¶

Included File ¶

Notes ¶

Important Info ¶

Note List ¶

Get NotesGET/notes

Example URI

Headers

Body

Schema

Create New NotePOST/notes

Example URI

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Note ¶

Get NoteGET/notes/{id}{?body}

Example URI

Headers

Body

Schema

Headers

Body

Update a NotePUT/notes/{id}

Caution ¶

Example URI

Headers

Body

Headers

Body

Schema

Headers

Body

Headers

Body

Headers

Body

Schema

Headers

Body

Delete a NoteDELETE/notes/{id}

Example URI

Headers

Body

Users ¶

User List ¶

Get usersGET/users{?name,joinedBefore,joinedAfter,sort,limit}

Example URI

Headers

Body

Schema

Tags and Tagging Long Title ¶

Resource ¶

GET/tags

Example URI

Headers

Body

Get one tag ¶

GET/tags/{id}

Example URI

Subtitle

Extensions

Included File

Important Info

Get Notes
GET`/notes`

Create New Note
POST`/notes`

Get Note
GET`/notes/{id}{?body}`

Update a Note
PUT`/notes/{id}`

Caution

Delete a Note
DELETE`/notes/{id}`

Get users
GET`/users{?name,joinedBefore,joinedAfter,sort,limit}`

GET`/tags`

GET`/tags/{id}`