Like almost every API, the ReadMe API requires you to provide an API key in your requests to get responses. A ReadMe documentation project comes with an API key that anyone who uses the API to control the docs needs to use.
Quick start with ReadMe API uses basic authentication, if you've done this before:
Your API Key can be found at dash.readme.io/project/
yourProject/api-key. Or navigate as follows in your docs project dash:
- Click Configuration
- Click API Key
If you are using the Authorization header, the API Key will need to be encoded.
If you are using the
-useroption, your project API key is your username and the password field is left blank.
If you're unfamiliar with API authorization and the information in the preceding section isn't enough to get you started, then follow these steps to get your API key and make a first test request to your project using cURL.
You can make your test cURL call either through the ReadMe API Explorer, which is easiest, or through your command line if you have cURL installed.
- Navigate to https://docs.readme.com/developers/reference/changelog.
- Login to ReadMe. By logging in, you're enabling ReadMe to populate working example API requests for you.
- If you have multiple doc projects, then select the one that you want to send the API request to. If you switch between doc projects, you'll notice that the authorization string changes. This string is the API key of your project, which you can also view on the dash at
You can give your API users working examples too!
ReadMe gives you working API examples that you can try out right from the API reference. You can provide the same experience for your users, so that they automatically see their own individual API key that they can use with your company's API, after they log into your ReadMe-powered API reference. For more information see
You can get even fancier by assigning your API key to a documentation variable dash.readme.io/project/
yourProject/variables. For example, in this documentation, the variable `
\<<keys:user\>>shows up as your ReadMe API Key (KEYS:USER), if you are logged in. For more information see User Data in Readme.
Your cURL request will look something like the following:
curl --request GET \ --url 'https://dash.readme.io/api/v1/changelogs?perPage=10&page=1' \ --header 'authorization: Basic <<yourEncodedApiKey>>'
- In the changelogs endpoint, either leave the default query params, or modify them.
- Click the Try It button. If you get a 200 response, you know that the request succeeded. You can expand the JSON response to see the details of the results.
- Optional: Try changing the number of pages or the pagination. How many results would you expect if you type in the following? Try changing the language in which you make the call, for example, Python.
- Optional: Note you can see the history of API calls that you've made. Try clicking through the logs and see the changes you made in step 6.
You can give your API users their activity history too!
For more information on how to show customers a history of their API calls, see https://docs.readme.com/metrics/docs/showing-api-logs-to-users
What if you're not logged into ReadMe's docs, so you can't see your personal API key in the docs? If you have cURL installed on your local machine, you can still adapt the sample API calls you'll find in the docs and run them in your command line. Take the following steps to run your first test call:
- Copy the sample cURL request from the API Explorer at https://docs.readme.com/developers/reference/changelog. It will look something like this:
curl --request GET \ --url 'https://dash.readme.io/api/v1/changelogs?perPage=10&page=1' \
- Notice that there's no authentication info in the preceding code? Modify the code to add it in:
curl --request GET \ --url 'https://dash.readme.io/api/v1/changelogs?perPage=10&page=1' \ -u <yourApiKey>:
Behind the scenes, cURL encodes your API key and add it to the request's Authorization header for you.
For , paste in the doc project API key that you copy from your dash at dash.readme.io/project/
- Press Enter and observe the JSON body response in the command line.
- Complete any other optional steps from the preceding section.