{
  "auth": "send a token as `Authorization: Bearer gp_…` or as the password of HTTP basic auth, tokens are made under /settings/tokens or with POST /api/me/tokens",
  "base": "https://gitpocket.io/api",
  "needs": {
    "admin": "a site administrator with a token scoped all",
    "gist": "a token scoped all or gist",
    "none": "anyone, private data appears when authenticated",
    "password": "a password or a session, never a token",
    "user": "any authenticated caller",
    "write": "a token scoped all, a password or a session"
  },
  "paging": "lists answer {items, total, next}, follow next or pass ?from= and ?limit= (at most 100)",
  "routes": [
    {
      "method": "GET",
      "path": "/",
      "needs": "none",
      "about": "this index: every route, the scope it needs and what it does"
    },
    {
      "method": "GET",
      "path": "/me",
      "needs": "user",
      "about": "the authenticated account, with email, admin flag and the scope of the credential"
    },
    {
      "method": "PATCH",
      "path": "/me",
      "needs": "write",
      "about": "change display, bio, location, workplace or websites"
    },
    {
      "method": "GET",
      "path": "/me/repos",
      "needs": "user",
      "about": "every repository you can push to: your own, your organizations' and those you collaborate on"
    },
    {
      "method": "GET",
      "path": "/me/orgs",
      "needs": "user",
      "about": "organizations you belong to"
    },
    {
      "method": "GET",
      "path": "/me/keys",
      "needs": "user",
      "about": "your SSH keys"
    },
    {
      "method": "POST",
      "path": "/me/keys",
      "needs": "write",
      "about": "add an SSH key from {title, key}"
    },
    {
      "method": "DELETE",
      "path": "/me/keys/:id",
      "needs": "write",
      "about": "remove an SSH key"
    },
    {
      "method": "GET",
      "path": "/me/tokens",
      "needs": "user",
      "about": "your tokens, never their secrets"
    },
    {
      "method": "POST",
      "path": "/me/tokens",
      "needs": "password",
      "about": "mint a token from {title, scope}, the secret appears once in the reply"
    },
    {
      "method": "DELETE",
      "path": "/me/tokens/:id",
      "needs": "write",
      "about": "revoke a token"
    },
    {
      "method": "GET",
      "path": "/me/notifications",
      "needs": "user",
      "about": "your inbox, ?unread=1 for unread only"
    },
    {
      "method": "PUT",
      "path": "/me/notifications/:id",
      "needs": "write",
      "about": "mark one notification read"
    },
    {
      "method": "DELETE",
      "path": "/me/notifications",
      "needs": "write",
      "about": "mark every notification read"
    },
    {
      "method": "GET",
      "path": "/me/blocks",
      "needs": "user",
      "about": "accounts you have blocked"
    },
    {
      "method": "PUT",
      "path": "/me/blocks/~:name",
      "needs": "write",
      "about": "block an account from your repositories"
    },
    {
      "method": "DELETE",
      "path": "/me/blocks/~:name",
      "needs": "write",
      "about": "unblock an account"
    },
    {
      "method": "POST",
      "path": "/orgs",
      "needs": "write",
      "about": "create an organization from {name} with you as its first member"
    },
    {
      "method": "GET",
      "path": "/search",
      "needs": "none",
      "about": "search with the site syntax, ?q= with lang:, user: and tag: qualifiers, ?kind=repos|people|gists"
    },
    {
      "method": "GET",
      "path": "/~:owner",
      "needs": "none",
      "about": "an account or organization"
    },
    {
      "method": "GET",
      "path": "/~:owner/repos",
      "needs": "none",
      "about": "repositories owned by the account that you can see"
    },
    {
      "method": "GET",
      "path": "/~:owner/stars",
      "needs": "none",
      "about": "repositories the account starred"
    },
    {
      "method": "GET",
      "path": "/~:owner/followers",
      "needs": "none",
      "about": "followers"
    },
    {
      "method": "GET",
      "path": "/~:owner/following",
      "needs": "none",
      "about": "accounts this one follows"
    },
    {
      "method": "PUT",
      "path": "/~:owner/follow",
      "needs": "write",
      "about": "follow the account"
    },
    {
      "method": "DELETE",
      "path": "/~:owner/follow",
      "needs": "write",
      "about": "stop following the account"
    },
    {
      "method": "GET",
      "path": "/~:owner/keys",
      "needs": "none",
      "about": "public SSH keys and PGP fingerprints, the same keys commit seals are checked against"
    },
    {
      "method": "GET",
      "path": "/~:owner/members",
      "needs": "none",
      "about": "members of an organization"
    },
    {
      "method": "PUT",
      "path": "/~:owner/members/~:name",
      "needs": "write",
      "about": "add a member, members only"
    },
    {
      "method": "DELETE",
      "path": "/~:owner/members/~:name",
      "needs": "write",
      "about": "remove a member, members only"
    },
    {
      "method": "GET",
      "path": "/admin/stats",
      "needs": "admin",
      "about": "account and repository counts"
    },
    {
      "method": "GET",
      "path": "/admin/accounts",
      "needs": "admin",
      "about": "every account with its flags"
    },
    {
      "method": "PUT",
      "path": "/admin/accounts/~:name/ban",
      "needs": "admin",
      "about": "ban an account"
    },
    {
      "method": "DELETE",
      "path": "/admin/accounts/~:name/ban",
      "needs": "admin",
      "about": "lift a ban"
    },
    {
      "method": "GET",
      "path": "/admin/reports",
      "needs": "admin",
      "about": "reports, ?state=open|resolved"
    },
    {
      "method": "POST",
      "path": "/admin/reports/:id",
      "needs": "admin",
      "about": "act on a report with {do: dismiss|resolve|ban|pages|delete, confirm}"
    },
    {
      "method": "POST",
      "path": "/admin/invites",
      "needs": "admin",
      "about": "mint a single use registration code"
    },
    {
      "method": "GET",
      "path": "/admin/gists",
      "needs": "admin",
      "about": "every gist, secret ones included, with size and open reports"
    },
    {
      "method": "GET",
      "path": "/repos",
      "needs": "none",
      "about": "public repositories, newest first, ?q= and ?tag= narrow the list"
    },
    {
      "method": "POST",
      "path": "/repos",
      "needs": "write",
      "about": "create a repository from {name, owner, description, visibility, tags}"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo",
      "needs": "none",
      "about": "a repository"
    },
    {
      "method": "PATCH",
      "path": "/~:owner/:repo",
      "needs": "write",
      "about": "change description, visibility, tags, pinned or archived, rename with name and transfer with owner"
    },
    {
      "method": "DELETE",
      "path": "/~:owner/:repo",
      "needs": "write",
      "about": "delete the repository, ?confirm= must repeat its name"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/forks",
      "needs": "none",
      "about": "forks you can see"
    },
    {
      "method": "POST",
      "path": "/~:owner/:repo/forks",
      "needs": "write",
      "about": "fork into your account"
    },
    {
      "method": "PUT",
      "path": "/~:owner/:repo/star",
      "needs": "write",
      "about": "star"
    },
    {
      "method": "DELETE",
      "path": "/~:owner/:repo/star",
      "needs": "write",
      "about": "unstar"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/collaborators",
      "needs": "user",
      "about": "collaborators, visible to anyone who can push"
    },
    {
      "method": "PUT",
      "path": "/~:owner/:repo/collaborators/~:name",
      "needs": "write",
      "about": "grant push access"
    },
    {
      "method": "DELETE",
      "path": "/~:owner/:repo/collaborators/~:name",
      "needs": "write",
      "about": "revoke push access"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/labels",
      "needs": "none",
      "about": "labels"
    },
    {
      "method": "POST",
      "path": "/~:owner/:repo/labels",
      "needs": "write",
      "about": "add a label from {name, colour}"
    },
    {
      "method": "DELETE",
      "path": "/~:owner/:repo/labels/:id",
      "needs": "write",
      "about": "delete a label"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/protections",
      "needs": "none",
      "about": "protected branches"
    },
    {
      "method": "PUT",
      "path": "/~:owner/:repo/protections/*branch",
      "needs": "write",
      "about": "protect a branch with {require_pull, approvals}"
    },
    {
      "method": "DELETE",
      "path": "/~:owner/:repo/protections/*branch",
      "needs": "write",
      "about": "lift a branch protection"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/refs",
      "needs": "none",
      "about": "branches and tags, ?kind=branch|tag"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/log/*ref",
      "needs": "none",
      "about": "history from a ref or the default branch, ?path= follows one file"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/commit/:sha",
      "needs": "none",
      "about": "a commit and the files it touched, ?patch=1 adds the hunks"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/compare/*spec",
      "needs": "none",
      "about": "commits and files between base...head, ?patch=1 adds the hunks"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/tree/*spec",
      "needs": "none",
      "about": "a directory listing or a file at ref/path, files carry their content up to 1 MiB"
    },
    {
      "method": "PUT",
      "path": "/~:owner/:repo/tree/*spec",
      "needs": "write",
      "about": "commit a file to branch/path from {content, encoding, message, parent}"
    },
    {
      "method": "DELETE",
      "path": "/~:owner/:repo/tree/*spec",
      "needs": "write",
      "about": "commit the removal of branch/path, ?message= and ?parent= are optional"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/raw/*spec",
      "needs": "none",
      "about": "the bytes of a file at ref/path"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/blame/*spec",
      "needs": "none",
      "about": "the last commit to touch each line of a file"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/readme",
      "needs": "none",
      "about": "the README of a ref, raw and rendered, ?ref= picks the ref"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/languages",
      "needs": "none",
      "about": "languages by bytes on the default branch"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/grep",
      "needs": "none",
      "about": "fixed string search through a ref, ?q= and ?ref="
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/archive/*spec",
      "needs": "none",
      "about": "a tar.gz or zip of a ref, as ref.tar.gz or ref.zip"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/issues",
      "needs": "none",
      "about": "issues, ?state=open|closed|all and ?label=name"
    },
    {
      "method": "POST",
      "path": "/~:owner/:repo/issues",
      "needs": "write",
      "about": "open an issue from {title, body}, collaborators may add labels and assignees"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/issues/:number",
      "needs": "none",
      "about": "an issue"
    },
    {
      "method": "PATCH",
      "path": "/~:owner/:repo/issues/:number",
      "needs": "write",
      "about": "change state, labels or assignees"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/issues/:number/comments",
      "needs": "none",
      "about": "comments, oldest first"
    },
    {
      "method": "POST",
      "path": "/~:owner/:repo/issues/:number/comments",
      "needs": "write",
      "about": "comment with {body}"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/pulls",
      "needs": "none",
      "about": "pull requests, ?state=open|closed|merged|all and ?label=name"
    },
    {
      "method": "POST",
      "path": "/~:owner/:repo/pulls",
      "needs": "write",
      "about": "open a pull request from {title, body, head, base, draft}, head is a branch or ~you/fork:branch"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/pulls/:number",
      "needs": "none",
      "about": "a pull request with its head, mergeability and verdicts"
    },
    {
      "method": "PATCH",
      "path": "/~:owner/:repo/pulls/:number",
      "needs": "write",
      "about": "change state, draft, labels or assignees"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/pulls/:number/commits",
      "needs": "none",
      "about": "commits the pull request adds"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/pulls/:number/files",
      "needs": "none",
      "about": "files the pull request changes, ?patch=1 adds the hunks"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/pulls/:number/revisions",
      "needs": "none",
      "about": "every head the pull request has had, oldest first"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/pulls/:number/comments",
      "needs": "none",
      "about": "conversation comments"
    },
    {
      "method": "POST",
      "path": "/~:owner/:repo/pulls/:number/comments",
      "needs": "write",
      "about": "comment with {body}"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/pulls/:number/reviews",
      "needs": "none",
      "about": "verdicts, each tied to the head it judged"
    },
    {
      "method": "POST",
      "path": "/~:owner/:repo/pulls/:number/reviews",
      "needs": "write",
      "about": "give a verdict with {verdict: approved|changes|comment, body}"
    },
    {
      "method": "GET",
      "path": "/~:owner/:repo/pulls/:number/notes",
      "needs": "none",
      "about": "line notes on the diff"
    },
    {
      "method": "POST",
      "path": "/~:owner/:repo/pulls/:number/notes",
      "needs": "write",
      "about": "note a line with {path, side: n|o, line, body}"
    },
    {
      "method": "PATCH",
      "path": "/~:owner/:repo/pulls/:number/notes/:id",
      "needs": "write",
      "about": "resolve or reopen a note with {resolved}"
    },
    {
      "method": "DELETE",
      "path": "/~:owner/:repo/pulls/:number/notes/:id",
      "needs": "write",
      "about": "delete a note"
    },
    {
      "method": "POST",
      "path": "/~:owner/:repo/pulls/:number/refresh",
      "needs": "write",
      "about": "fetch the source branch again"
    },
    {
      "method": "POST",
      "path": "/~:owner/:repo/pulls/:number/merge",
      "needs": "write",
      "about": "merge with {strategy: merge|squash|rebase|ff, title, body}"
    },
    {
      "method": "GET",
      "path": "/gists",
      "needs": "none",
      "about": "public gists, newest first"
    },
    {
      "method": "POST",
      "path": "/gists",
      "needs": "gist",
      "about": "create from {description, visibility, files: [{name, content}]}, or send the raw file with ?name=&description=&visibility= and get its address back as text"
    },
    {
      "method": "GET",
      "path": "/gists/:id",
      "needs": "none",
      "about": "a gist with every file's content, secret gists only need their id"
    },
    {
      "method": "PATCH",
      "path": "/gists/:id",
      "needs": "gist",
      "about": "change description or visibility, and files with [{name, content, rename, delete}], head guards against lost updates"
    },
    {
      "method": "DELETE",
      "path": "/gists/:id",
      "needs": "gist",
      "about": "delete the gist"
    },
    {
      "method": "PUT",
      "path": "/gists/:id/files/*name",
      "needs": "gist",
      "about": "write one file from the raw request body, creating it when missing"
    },
    {
      "method": "DELETE",
      "path": "/gists/:id/files/*name",
      "needs": "gist",
      "about": "remove one file"
    },
    {
      "method": "GET",
      "path": "/gists/:id/revisions",
      "needs": "none",
      "about": "revisions, newest first, ?patch=1 adds the hunks"
    },
    {
      "method": "PUT",
      "path": "/gists/:id/star",
      "needs": "gist",
      "about": "star"
    },
    {
      "method": "DELETE",
      "path": "/gists/:id/star",
      "needs": "gist",
      "about": "unstar"
    },
    {
      "method": "GET",
      "path": "/gists/:id/forks",
      "needs": "none",
      "about": "forks"
    },
    {
      "method": "POST",
      "path": "/gists/:id/forks",
      "needs": "gist",
      "about": "fork into your account"
    },
    {
      "method": "GET",
      "path": "/gists/:id/comments",
      "needs": "none",
      "about": "comments, oldest first"
    },
    {
      "method": "POST",
      "path": "/gists/:id/comments",
      "needs": "gist",
      "about": "comment with {body}"
    },
    {
      "method": "DELETE",
      "path": "/gists/:id/comments/:cid",
      "needs": "gist",
      "about": "delete a comment, yours or one on your gist"
    },
    {
      "method": "GET",
      "path": "/~:owner/gists",
      "needs": "none",
      "about": "an account's public gists, its secret ones too when it is you, ?starred=1 for the gists it starred"
    }
  ],
  "scopes": {
    "all": "everything the account may do",
    "gist": "reads, plus writes to your own gists",
    "read": "reads only"
  },
  "site": "gitpocket"
}