- TOC {:toc}
You can read public gists and create them for anonymous users without a token; however, to read or write gists on a user's behalf the gist OAuth scope is required.
The Gist API provides up to one megabyte of content for each file in the gist. Every call to retrieve 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.
List a user's gists:
GET /users/:username/gists
List the authenticated user's gists or if called anonymously, this will return all public gists:
GET /gists
List all public gists:
GET /gists/public
List the authenticated user's starred gists:
GET /gists/starred
| 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. |
<%= headers 200, :pagination => default_pagination_rels %> <%= json(:gist) { |h| [h] } %>
GET /gists/:id
<%= headers 200 %> <%= json :full_gist %>
GET /gists/:id/:sha
<%= headers 200 %> <%= json :full_gist_version %>
POST /gists
| Name | Type | Description |
|---|---|---|
files |
object |
Required. Files that make up this gist. |
description |
string |
A description of the gist. |
public |
boolean |
Indicates whether the gist is public. Default: false |
The keys in the files object are the string filename, and the value is another object with a key of content, and a value of the file contents. For example:
<%= json
:description => "the description for this gist",
:public => true,
:files => {
"file1.txt" => {"content" => "String file contents"}
}
%>
Note: Don't name your files "gistfile" with a numerical suffix. This is the format of the automatic naming scheme that Gist uses internally.
<%= headers 201, :Location => get_resource(:full_gist)['url'] %> <%= json :full_gist %>
PATCH /gists/:id
The keys in the files object are the string filename. The value is another object with a key of content (indicating the new contents), or filename (indicating the new filename). For example:
<%= json
:description => "the description for this gist",
:files => {
"file1.txt" => {"content" => "updated file contents"},
"old_name.txt" => {"filename" => "new_name.txt", "content" => "modified contents"},
"new_file.txt" => {"content" => "a new file"},
"delete_this_file.txt" => nil,
} %>
Note: All files from the previous version of the gist are carried over by default if not included in the object. Deletes can be performed by including the filename with a null object.
<%= headers 200 %> <%= json :full_gist %>
GET /gists/:id/commits
<%= headers 200, :pagination => { :next => 'https://api.github.com/resource?page=2' } %> <%= json(:gist_history) %>
PUT /gists/:id/star
<%= fetch_content(:put_content_length) %>
<%= headers 204 %>
DELETE /gists/:id/star
<%= headers 204 %>
GET /gists/:id/star
<%= headers 204 %>
<%= headers 404 %>
POST /gists/:id/forks
Note: This was previously /gists/:id/fork
<%= headers 201, :Location => get_resource(:gist)['url'] %> <%= json(:gist) %>
GET /gists/:id/forks
<%= headers 200, :pagination => default_pagination_rels %> <%= json(:gist_forks) %>
DELETE /gists/:id
<%= headers 204 %>
The following media types are supported when fetching gist contents. You can read more about the use of media types in the API here.
application/vnd.github.VERSION.raw
application/vnd.github.VERSION.base64