API Title

API Endpoint

https://api.example.com

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 https://api.example.com/notes

Responses200

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#"
}

Get Notes
GET`/notes`

Get a list of notes.

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

Requestswith bodywithout body

Headers

Content-Type: application/json

Body

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

Responses201400

This response has no content.

Headers

Content-Type: application/json

Body

{
  "error": "Invalid title"
}

Headers

Content-Type: application/json

Body

{
  "title": "My new note"
}

Responses201400

This response has no content.

Headers

Content-Type: application/json

Body

{
  "error": "Invalid title"
}

Create New Note
POST`/notes`

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

Note ¶

Note description

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

Responses200404

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#"
}

Headers

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

Body

{
  "error": "Note not found"
}

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

Get a single note.

URI Parameters

HideShow

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

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

Requestsexample 1delete body

Headers

Content-Type: application/json

Body

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

Responses200404

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#"
}

Headers

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

Body

{
  "error": "Note not found"
}

Headers

Content-Type: application/json

Body

{
  "body": ""
}

Responses200404

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#"
}

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.

URI Parameters

HideShow

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

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

Responses204404

This response has no content.

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

URI Parameters

HideShow

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

Users ¶

Group description

User List ¶

A list of users

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

Responses200

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}"
      }
    }
  }
}

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

Get a list of users. Example:

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

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

Tags and Tagging Long Title ¶

Get or set tags on notes

Resource ¶

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

Responses200

Headers

Content-Type: application/json

Body

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

GET`/tags`

Get a list of bars

Get one tag ¶

Get a single tag

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

Responses200

This response has no content.

GET`/tags/{id}`

URI Parameters

HideShow

id: string (required)
Unique tag identifier

Generated by aglio on 11 Nov 2015

API Endpoint

Subtitle ¶

Extensions ¶

Included File ¶

Notes ¶

Important Info ¶

Note List ¶

Headers

Body

Schema

Get NotesGET/notes

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Create New NotePOST/notes

Note ¶

Headers

Body

Schema

Headers

Body

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

Headers

Body

Headers

Body

Schema

Headers

Body

Headers

Body

Headers

Body

Schema

Headers

Body

Update a NotePUT/notes/{id}

Caution ¶

Headers

Body

Delete a NoteDELETE/notes/{id}

Users ¶

User List ¶

Headers

Body

Schema

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

Tags and Tagging Long Title ¶

Resource ¶

Headers

Body

GET/tags

Get one tag ¶

GET/tags/{id}

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}`