Skip to content
Create a gist now

Instantly share code, notes, and snippets.

@caspyin /
Last active May 22, 2016

A curl tutorial using GitHub's API


An introduction to curl using GitHub's API

The Basics

Makes a basic GET request to the specifed URI


Includes HTTP-Header information in the output

curl --include

Pass user credential to basic auth to access protected resources like a users starred gists, or private info associated with their profile

curl --user "caspyin:PASSWD"
curl --user "caspyin:PASSWD"

Passing just the username without the colon (:) will cause you to be prompted for your account password. This avoids having your password in your command line history

curl --user "caspyin"


Use the --request (-X) flag along with --data (-d) to POST data

curl --user "caspyin" --request POST --data '{"description":"Created via API","public":"true","files":{"file1.txt":{"content":"Demo"}}'

curl --user "caspyin" -X POST --data '{"description":"Created via API","public":"true","files":{"file1.txt":{"content":"Demo"}}'

Of course --data implies POST so you don't have to also specify the --request flag

curl --user "caspyin" --data '{"description":"Created via API","public":"true","files":{"file1.txt":{"content":"Demo"}}'

Here is an example that uses the old GitHub API (v2). You can use multiple --data flags

curl --data "login=caspyin" --data "token=TOKEN"

The post data gets combined into one so you can also just combine them yourself into a single --data flag

curl --data "login=caspyin&token=TOKEN"

You can tell curl to read from a file (@) to POST data

curl --user "caspyin" --data @data.txt 

Or it can read from STDIN (@-)

curl --user "caspyin" --data @-
  "files": {
    "file1.txt": {
end with ctrl+d


Often when POSTing data you'll need to add headers for things like auth tokens or setting the content type. You can set a header using -H.

curl -H "Content-Type: application/json" -H "authToken: 349ab29a-xtab-423b-a5hc-5623bc39b8c8" --data '{}'

Dealing with HTTPS

If an API doens't have an SSL cert but is using HTTPS you can tell curl to ignore the security by using --insecure. Be warned this is a very "insecure" thing to do and is only listed here for "educational purposes".

curl --insecure

For my own reference mostly, here is where I first learned about using --insecure


The first thing to know is that your API Token (found in is not the same token used by OAuth. They are different tokens and you will need to generate an OAuth token to be authorized.

Follow the API's instructions at under the sections "Non-Web Application Flow" and "Create a new authorization" to become authorized.

Note: Use Basic Auth once to create an OAuth2 token

curl \
--user "caspyin" \
--data '{"scopes":["gist"],"note":"Demo"}'

This will prompt you for your GitHub password and return your OAuth token in the response. It will also create a new Authorized application in your account settings

Now that you have the OAuth token there are two ways to use the token to make requests that require authentication (replace "OAUTH-TOKEN" with your actual token)

curl -H "Authorization: token OAUTH-TOKEN"

List the authorizations you already have

curl --user "caspyin"



Thank you for this post. Is it possible to send the gist content as encoded-64? I've got a file with lots of characters that seem to cause json parse issues when I attempt to post the data. I can encode64 the string; just don't know how to tell github that it's encoded ... I just see the encoded string show up in my gist.

I appreciate any help & guidance you can offer!

caspyin commented Jan 31, 2013

@jeremyschulman Not sure. It looks like encoding the string should work ( Can you give me an example of what you're trying?


Nice. Thanks for the info.

atif93 commented May 27, 2013

I want my followers to stop receiving notifications. For that I read somewhere that the command is
DELETE /followers/:id
and I should be logged in and authenticated with basic auth or OAuth with the user:follow scope.
Can you please tell me how to do this.


Very nice, clean and clear.

Thanks for sharing !

caspyin commented Oct 1, 2013

Added info on using -H (headers) and the --insecure options




Can you create a new repository? tried the following. , saw one that did create a new repo
curl -u "$carlmart :$ch4yrj685432eecb289484848483736363636363" -d '{"CarlMart":"'$test1'"}


You have two easy ways to create a repo via terminal

This first one you just need to put in your username between the single quotes and then the name of the repo you want in-between the double quotes. This will then prompt you to type in your password. P.S. You wont see your password as your type. It's hidden for security.

curl -u 'YOUR-USER-NAME' -d '{"name": "PUT-YOUR-REPO-NAME-HERE"}'

Option two is the best (IMO) Just go to your account and create an authtoken and paste it where it says below. Then just give your repo a name. This will not ask your for a password.

curl -H "Authorization: token PUT-YOUR-AUTH-TOKEN-HERE" -d '{"name": "PUT-YOUR-REPO-NAME-HERE"}'


Thanks, great info, plain and simple!

i4h commented May 5, 2015

Thank you for the helpful and clear tutorial!
I have been trying to write a curl request to send an .md-file from my computer to the github markdown api, but i couldn't figure out how to send data (with unescaped quotes) from a file in a named jason variable. I am using httpie now, but that solution bugs me because it is not as available. Could you maybe add this use case?


Can i retrieve the number of open issues from a public repository using this?

becky7 commented Dec 5, 2015



Great, thanks for the information.

djap96 commented Feb 12, 2016

Pretty cool. rocks


In POST section, a close curly is missing in the first example.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.