Send a JSON POST

Overview

POST a JSON body to create a new resource. On success you typically get back 201 Created plus the resource that was created.

In code

curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","email":"ada@example.com"}'

const res = await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Ada', email: 'ada@example.com' })
});
const created = await res.json();

import requests

res = requests.post('https://api.example.com/users',
                    json={'name': 'Ada', 'email': 'ada@example.com'})
res.raise_for_status()
created = res.json()

Details

You must send `Content-Type: application/json` so the server parses the body as JSON. Without it, many frameworks assume form data and hand your handler an empty object.

In curl, `-d` implies POST and defaults the Content-Type to `application/x-www-form-urlencoded`, so override it with `-H` when sending JSON. In `requests`, the `json=` argument both serializes the dict and sets the header for you.

POST is not idempotent: sending it twice can create two resources. If you need safe retries and the server supports it, add an `Idempotency-Key` header. The `Location` header of a 201 response contains the URL of the newly created resource.

Related headers

Related status codes