Skip to content

Instantly share code, notes, and snippets.

Last active May 14, 2024 19:32
Show Gist options
  • Save btoone/2288960 to your computer and use it in GitHub Desktop.
Save btoone/2288960 to your computer and use it in GitHub Desktop.
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 rvm/rvm#1684


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"


Copy link

Very nice, clean and clear.

Thanks for sharing !

Copy link

btoone commented Oct 1, 2013

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

Copy link


Copy link

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

Copy link

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

Copy link

Thanks, great info, plain and simple!

Copy link

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?

Copy link

kenorb commented Aug 3, 2015

Copy link

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

Copy link

becky7 commented Dec 5, 2015


Copy link

Great, thanks for the information.

Copy link

Pretty cool. rocks

Copy link

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

Copy link

carc1n0gen commented May 26, 2016

Hello I know this is old, but I'm having issues sending the content of a file that has one or more new lines.

I get:

  "message": "Problems parsing JSON",
  "documentation_url": ""

But if the file content I send has a single line it works perfectly fine

Copy link

I want to update a specific file in my git master repo; How do I do that using curl ?

Copy link

Is it possible to upload image file through API?

Copy link

Not sure if this is the right place, but: have you ever figured out a way to trigger obtaining an OTP (e.g. via sms) by cURL against the github API?

curl -u <myusername>

reponds with

  "message": "Must specify two-factor authentication OTP code.",
  "documentation_url": ""

however, it doesn't trigger the creation of a OTP. Signing in through the website does send me an sms, so there doesn't seem to be a setup problem.

Copy link

larshp commented Feb 5, 2017

had the same issue as @konradkonrad describes above, following curl generates a SMS code when I try,

curl -i -u your_username -d '{"scopes": ["repo", "user"], "note": "getting-started"}'

Copy link

btoone commented Feb 23, 2017

It seems this has been useful over the years to various people. If you would like to contribute any changes to this gist, please fork and then ping me here in the comments to review.

Copy link

pwsouth commented May 5, 2017

Copy link

suntong commented Aug 14, 2017

@caspyin, thanks for the great post. How can you send base64 encoded content?

I tried,

curl -H 'Accept: application/vnd.github.VERSION.base64' --data @data.txt

But the content is still base64 encoded:

Here is my test data.txt:

  "description": "the description for this gist",
  "public": true,
  "files": {
    "file1.txt": {
      "content": "aG9zdEBtYWlsLmNvbTpwYXNzd29yZAo="


Copy link

suntong commented Aug 14, 2017

I figured it out -- base64 encoding is only supported for download, not upload.

So to post any arbitrary string or file, check out



jsonfiddle esc will escape any arbitrary string so as to embed it as content of json string. This seems useless at first, but it actually allows you to embed any arbitrary file into GitHub Gists JSON API, so as to post any arbitrary file onto GitHub Gist:

echo '{"description":"SmartyStreets API Demo","public":true,"files":{"SmartyStreets.json":{"content":'"`jsonfiddle fmt -i test/SmartyStreets.json | jsonfiddle esc -i`"'}}}' | curl --data @-

This will give you

By "arbitrary file" I do mean arbitrary file. Check this out:

This is why jsonfiddle esc is a command on its own, instead of being part of functionalities of jsonfiddle fmt or jsonfiddle sort.

Copy link

I'm trying to access my company's github repository(github enterprise). command i'm using is
curl --user "name:pwd" "https://github."company name".com/{owner}/repo" , but i'm getting "Not found error" .
When i login through the browser with the same credentials, it is going through.
i was reading through " OAuth and PAT(Personal Access tokens). Couldn't get to working. Can someone walk me through the steps if you have already done it?

Copy link

gmilos commented Sep 1, 2017

@aman0446 you need something like this:

curl -H "Authorization: token PAT-TOKEN"

Copy link

rpbaptist commented Dec 12, 2017

For OTP (2FA) you will have to send this header along:

curl -H "X-GitHub-OTP: 123456"

Copy link


curl --user "ttpro1995:MY_OWN_PASSWORD" --data '{"description":"Created via API","public":"false","files":{"file1.txt":{"content":"Demo"}}'
How can I replace password with something else (API key )?

Copy link

create a github repo webhook with curl:

curl -v --header "Authorization: token 123_generated_token" -X POST -d '{"active": true, "events": ["push"], "config": {"url": "https://service_url", "content_type": "json"}}'

Copy link

krpavan3 commented Mar 6, 2019

How to create a repository under a particular organization in Github enterprise account using curl command.

Curl command used:

curl -u 'user_name' -d '{"name":"Test-Repo","description":"This project is a test"}'

Error message displayed

"message": "Not Found",
"documentation_url": ""

Copy link

For User:

Replace ACCESS_TOKEN with Git OAuth Token and NEW_REPO_NAME with your New Repository Name

curl -H "Authorization: token ACCESS_TOKEN" -d '{"name": "NEW_REPO_NAME", "private": <true/false>, "description": "<may_add_a_little_info_about_the_repo>"}'

Or like...

curl -i -X POST \
-H "Authorization: token <ACCESS_TOKEN>" \
-d @- << EOF
  "name": "<NEW_REPO_NAME>",
  "private": <true/false>,
  "description": "<add_a_little_info_about_the_repo>"

»» At least the name key is Required to create the repo.

For Organization:

Replace ORGANISATION_NAME with the Organization Name that you have access to

curl -H "Authorization: token ACCESS_TOKEN" -d '{"name": "NEW_REPO_NAME"}'

★ This uses the latest Developer's API v3
»» Works well even if you have enabled Two-Factor Security

Copy link

elect86 commented May 9, 2021

Is it possible to create/update multiple files at once? Because right now we have a PUT per commit..

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment