Get started
Make your first request
Walk through a complete request and response, from headers to status codes.
You need an API key. If you don't have one yet, follow the Quickstart and export it:
export API_KEY="paste-your-key-here"
Every request has the same four parts:
curl "https://api.example.com/v1/orders?limit=1" \
-X GET \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json"
| Part | What it does |
|---|---|
| URL | The endpoint, including the version prefix /v1 |
| Method | GET to read data, POST to create it |
Authorization header | Your credential, so the API knows who is calling |
| Query or body | Filters and data, depending on the endpoint |
Fetch your most recent order:
curl "https://api.example.com/v1/orders?limit=1" \
-H "Authorization: Bearer $API_KEY"
A successful call returns 200 OK:
{
"data": [
{
"id": "ord_1042",
"status": "shipped",
"total": 129.00
}
],
"has_more": false
}
Create a resource with a POST request and a JSON body:
curl "https://api.example.com/v1/orders" \
-X POST \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"total": 42.50, "currency": "USD"}'
A successful create returns 201 Created and the new resource, including its id.
| Status | Meaning | What to do |
|---|---|---|
200 OK | The request succeeded. | Read the JSON body. |
201 Created | A resource was created. | Save the id for later calls. |
401 Unauthorized | The key is missing, revoked, or mistyped. | Check the Authorization header. |
422 Unprocessable Entity | The body failed validation. | Read the error field, fix the request. |
429 Too Many Requests | You're over your rate limit. | Back off and retry. See Rate limits. |