Authentication

You can read public gists anonymously, but you must be signed into GitHub to create gists. To read or write gists on a user's behalf, you need the gist OAuth scope and a token.

Truncation

The Gist API provides up to one megabyte of content for each file in the gist. Each file returned for a gist through the API has a key called truncated. If truncated is true, the file is too large and only a portion of the contents were returned in content.

If you need the full contents of the file, you can make a GET request to the URL specified by raw_url. Be aware that for files larger than ten megabytes, you'll need to clone the gist via the URL provided by git_pull_url.

In addition to a specific file's contents being truncated, the entire files list may be truncated if the total number exceeds 300 files. If the top level truncated key is true, only the first 300 files have been returned in the files list. If you need to fetch all of the gist's files, you'll need to clone the gist via the URL provided by git_pull_url.

List a user's gists

List public gists for the specified user:

GET /users/:username/gists

List the authenticated user's gists or if called anonymously, this will
return all public gists:

GET /gists

Parameters

Name

Type

Description

since

string

A timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Only gists updated at or after this time are returned.

Response

[{"url":"https://api.github.com/gists/aa5a315d61ae9438b18d","forks_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/forks","commits_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/commits","id":"aa5a315d61ae9438b18d","node_id":"MDQ6R2lzdGFhNWEzMTVkNjFhZTk0MzhiMThk","git_pull_url":"https://gist.github.com/aa5a315d61ae9438b18d.git","git_push_url":"https://gist.github.com/aa5a315d61ae9438b18d.git","html_url":"https://gist.github.com/aa5a315d61ae9438b18d","files":{"hello_world.rb":{"filename":"hello_world.rb","type":"application/x-ruby","language":"Ruby","raw_url":"https://gist.githubusercontent.com/octocat/6cad326836d38bd3a7ae/raw/db9c55113504e46fa076e7df3a04ce592e2e86d8/hello_world.rb","size":167}},"public":true,"created_at":"2010-04-14T02:15:15Z","updated_at":"2011-06-20T11:34:15Z","description":"Hello World Examples","comments":0,"user":null,"comments_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/comments/","owner":{"login":"octocat","id":1,"node_id":"MDQ6VXNlcjE=","avatar_url":"https://github.com/images/error/octocat_happy.gif","gravatar_id":"","url":"https://api.github.com/users/octocat","html_url":"https://github.com/octocat","followers_url":"https://api.github.com/users/octocat/followers","following_url":"https://api.github.com/users/octocat/following{/other_user}","gists_url":"https://api.github.com/users/octocat/gists{/gist_id}","starred_url":"https://api.github.com/users/octocat/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/octocat/subscriptions","organizations_url":"https://api.github.com/users/octocat/orgs","repos_url":"https://api.github.com/users/octocat/repos","events_url":"https://api.github.com/users/octocat/events{/privacy}","received_events_url":"https://api.github.com/users/octocat/received_events","type":"User","site_admin":false},"truncated":false}]

List all public gists

List all public gists sorted by most recently updated to least recently updated.

Note: With pagination, you can fetch up to 3000 gists. For example, you can fetch 100 pages with 30 gists per page or 30 pages with 100 gists per page.

GET /gists/public

Parameters

Name

Type

Description

since

string

A timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Only gists updated at or after this time are returned.

Response

[{"url":"https://api.github.com/gists/aa5a315d61ae9438b18d","forks_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/forks","commits_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/commits","id":"aa5a315d61ae9438b18d","node_id":"MDQ6R2lzdGFhNWEzMTVkNjFhZTk0MzhiMThk","git_pull_url":"https://gist.github.com/aa5a315d61ae9438b18d.git","git_push_url":"https://gist.github.com/aa5a315d61ae9438b18d.git","html_url":"https://gist.github.com/aa5a315d61ae9438b18d","files":{"hello_world.rb":{"filename":"hello_world.rb","type":"application/x-ruby","language":"Ruby","raw_url":"https://gist.githubusercontent.com/octocat/6cad326836d38bd3a7ae/raw/db9c55113504e46fa076e7df3a04ce592e2e86d8/hello_world.rb","size":167}},"public":true,"created_at":"2010-04-14T02:15:15Z","updated_at":"2011-06-20T11:34:15Z","description":"Hello World Examples","comments":0,"user":null,"comments_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/comments/","owner":{"login":"octocat","id":1,"node_id":"MDQ6VXNlcjE=","avatar_url":"https://github.com/images/error/octocat_happy.gif","gravatar_id":"","url":"https://api.github.com/users/octocat","html_url":"https://github.com/octocat","followers_url":"https://api.github.com/users/octocat/followers","following_url":"https://api.github.com/users/octocat/following{/other_user}","gists_url":"https://api.github.com/users/octocat/gists{/gist_id}","starred_url":"https://api.github.com/users/octocat/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/octocat/subscriptions","organizations_url":"https://api.github.com/users/octocat/orgs","repos_url":"https://api.github.com/users/octocat/repos","events_url":"https://api.github.com/users/octocat/events{/privacy}","received_events_url":"https://api.github.com/users/octocat/received_events","type":"User","site_admin":false},"truncated":false}]

List starred gists

List the authenticated user's starred gists:

GET /gists/starred

Parameters

Name

Type

Description

since

string

A timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Only gists updated at or after this time are returned.

Response

[{"url":"https://api.github.com/gists/aa5a315d61ae9438b18d","forks_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/forks","commits_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/commits","id":"aa5a315d61ae9438b18d","node_id":"MDQ6R2lzdGFhNWEzMTVkNjFhZTk0MzhiMThk","git_pull_url":"https://gist.github.com/aa5a315d61ae9438b18d.git","git_push_url":"https://gist.github.com/aa5a315d61ae9438b18d.git","html_url":"https://gist.github.com/aa5a315d61ae9438b18d","files":{"hello_world.rb":{"filename":"hello_world.rb","type":"application/x-ruby","language":"Ruby","raw_url":"https://gist.githubusercontent.com/octocat/6cad326836d38bd3a7ae/raw/db9c55113504e46fa076e7df3a04ce592e2e86d8/hello_world.rb","size":167}},"public":true,"created_at":"2010-04-14T02:15:15Z","updated_at":"2011-06-20T11:34:15Z","description":"Hello World Examples","comments":0,"user":null,"comments_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/comments/","owner":{"login":"octocat","id":1,"node_id":"MDQ6VXNlcjE=","avatar_url":"https://github.com/images/error/octocat_happy.gif","gravatar_id":"","url":"https://api.github.com/users/octocat","html_url":"https://github.com/octocat","followers_url":"https://api.github.com/users/octocat/followers","following_url":"https://api.github.com/users/octocat/following{/other_user}","gists_url":"https://api.github.com/users/octocat/gists{/gist_id}","starred_url":"https://api.github.com/users/octocat/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/octocat/subscriptions","organizations_url":"https://api.github.com/users/octocat/orgs","repos_url":"https://api.github.com/users/octocat/repos","events_url":"https://api.github.com/users/octocat/events{/privacy}","received_events_url":"https://api.github.com/users/octocat/received_events","type":"User","site_admin":false},"truncated":false}]

Edit a gist

Allows you to update or delete a gist file and rename gist files. Files from the previous version of the gist that aren't explicitly changed during an edit are unchanged.

PATCH /gists/:gist_id

Input

Name

Type

Description

description

string

A descriptive name for this gist.

files

object

The filenames and content that make up this gist.

The value for each of the filenames in files is an object with these keys:

Name

Type

Description

content

string

The updated content of the file.

filename

string

The new name for this file. To delete a file, set the value of the filename to null.

Example

{"description":"Hello World Examples","files":{"hello_world_ruby.txt":{"content":"Run `ruby hello_world.rb` or `python hello_world.py` to print Hello World","filename":"hello_world.md"},"hello_world_python.txt":null,"new_file.txt":{"content":"This is a new placeholder file."}}}

Response if gist is not starred

Fork a gist

Response

{"url":"https://api.github.com/gists/aa5a315d61ae9438b18d","forks_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/forks","commits_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/commits","id":"aa5a315d61ae9438b18d","node_id":"MDQ6R2lzdGFhNWEzMTVkNjFhZTk0MzhiMThk","git_pull_url":"https://gist.github.com/aa5a315d61ae9438b18d.git","git_push_url":"https://gist.github.com/aa5a315d61ae9438b18d.git","html_url":"https://gist.github.com/aa5a315d61ae9438b18d","files":{"hello_world.rb":{"filename":"hello_world.rb","type":"application/x-ruby","language":"Ruby","raw_url":"https://gist.githubusercontent.com/octocat/6cad326836d38bd3a7ae/raw/db9c55113504e46fa076e7df3a04ce592e2e86d8/hello_world.rb","size":167}},"public":true,"created_at":"2010-04-14T02:15:15Z","updated_at":"2011-06-20T11:34:15Z","description":"Hello World Examples","comments":0,"user":null,"comments_url":"https://api.github.com/gists/aa5a315d61ae9438b18d/comments/","owner":{"login":"octocat","id":1,"node_id":"MDQ6VXNlcjE=","avatar_url":"https://github.com/images/error/octocat_happy.gif","gravatar_id":"","url":"https://api.github.com/users/octocat","html_url":"https://github.com/octocat","followers_url":"https://api.github.com/users/octocat/followers","following_url":"https://api.github.com/users/octocat/following{/other_user}","gists_url":"https://api.github.com/users/octocat/gists{/gist_id}","starred_url":"https://api.github.com/users/octocat/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/octocat/subscriptions","organizations_url":"https://api.github.com/users/octocat/orgs","repos_url":"https://api.github.com/users/octocat/repos","events_url":"https://api.github.com/users/octocat/events{/privacy}","received_events_url":"https://api.github.com/users/octocat/received_events","type":"User","site_admin":false},"truncated":false}