netbox-community-netbox/docs/api/examples.md

# API Examples

Supported HTTP methods:

* `GET`: Retrieve an object or list of objects
* `POST`: Create a new object
* `PUT`: Update an existing object, all mandatory fields must be specified
* `PATCH`: Updates an existing object, only specifying the field to be changed
* `DELETE`: Delete an existing object

To authenticate a request, attach your token in an `Authorization` header:

```
curl -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0"
```

## Retrieving a list of sites

Send a `GET` request to the object list endpoint. The response contains a paginated list of JSON objects.

```
$ curl -H "Accept: application/json; indent=4" http://localhost/api/dcim/sites/
{
    "count": 14,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 6,
            "name": "Corporate HQ",
            "slug": "corporate-hq",
            "region": null,
            "tenant": null,
            "facility": "",
            "asn": null,
            "physical_address": "742 Evergreen Terrace, Springfield, USA",
            "shipping_address": "",
            "contact_name": "",
            "contact_phone": "",
            "contact_email": "",
            "comments": "",
            "custom_fields": {},
            "count_prefixes": 108,
            "count_vlans": 46,
            "count_racks": 8,
            "count_devices": 254,
            "count_circuits": 6
        },
        ...
    ]
}
```

## Retrieving a single site by ID

Send a `GET` request to the object detail endpoint. The response contains a single JSON object.

```
$ curl -H "Accept: application/json; indent=4" http://localhost/api/dcim/sites/6/
{
    "id": 6,
    "name": "Corporate HQ",
    "slug": "corporate-hq",
    "region": null,
    "tenant": null,
    "facility": "",
    "asn": null,
    "physical_address": "742 Evergreen Terrace, Springfield, USA",
    "shipping_address": "",
    "contact_name": "",
    "contact_phone": "",
    "contact_email": "",
    "comments": "",
    "custom_fields": {},
    "count_prefixes": 108,
    "count_vlans": 46,
    "count_racks": 8,
    "count_devices": 254,
    "count_circuits": 6
}
```

## Creating a new site

Send a `POST` request to the site list endpoint with token authentication and JSON-formatted data. Only mandatory fields are required. This example includes one non required field, "region."

```
$ curl -X POST -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0" -H "Content-Type: application/json" -H "Accept: application/json; indent=4" http://localhost:8000/api/dcim/sites/ --data '{"name": "My New Site", "slug": "my-new-site", "region": 5}'
{
    "id": 16,
    "name": "My New Site",
    "slug": "my-new-site",
    "region": 5,
    "tenant": null,
    "facility": "",
    "asn": null,
    "physical_address": "",
    "shipping_address": "",
    "contact_name": "",
    "contact_phone": "",
    "contact_email": "",
    "comments": ""
}
```
Note that in this example we are creating a site bound to a region with the ID of 5. For write API actions (`POST`, `PUT`, and `PATCH`) the integer ID value is used for `ForeignKey` (related model) relationships, instead of the nested representation that is used in the `GET` (list) action.

## Modify an existing site

Make an authenticated `PUT` request to the site detail endpoint. As with a create (`POST`) request, all mandatory fields must be included.

```
$ curl -X PUT -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0" -H "Content-Type: application/json" -H "Accept: application/json; indent=4" http://localhost:8000/api/dcim/sites/16/ --data '{"name": "Renamed Site", "slug": "renamed-site"}'
```

## Modify an object by changing a field

Make an authenticated `PATCH` request to the device endpoint. With `PATCH`, unlike `POST` and `PUT`, we only specify the field that is being changed. In this example, we add a serial number to a device.
```
$ curl -X PATCH -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0" -H "Content-Type: application/json" -H "Accept: application/json; indent=4" http://localhost:8000/api/dcim/devices/2549/ --data '{"serial": "FTX1123A090"}'
```

## Delete an existing site

Send an authenticated `DELETE` request to the site detail endpoint.

```
$ curl -v -X DELETE -H "Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0" -H "Content-Type: application/json" -H "Accept: application/json; indent=4" http://localhost:8000/api/dcim/sites/16/
* Connected to localhost (127.0.0.1) port 8000 (#0)
> DELETE /api/dcim/sites/16/ HTTP/1.1
> User-Agent: curl/7.35.0
> Host: localhost:8000
> Authorization: Token d2f763479f703d80de0ec15254237bc651f9cdc0
> Content-Type: application/json
> Accept: application/json; indent=4
>
* HTTP 1.0, assume close after body
< HTTP/1.0 204 No Content
< Date: Mon, 20 Mar 2017 16:13:08 GMT
< Server: WSGIServer/0.1 Python/2.7.6
< Vary: Accept, Cookie
< X-Frame-Options: SAMEORIGIN
< Allow: GET, PUT, PATCH, DELETE, OPTIONS
<
* Closing connection 0
```

The response to a successful `DELETE` request will have code 204 (No Content); the body of the response will be empty.


## Bulk Object Creation

The REST API supports the creation of multiple objects of the same type using a single `POST` request. For example, to create multiple devices:

```
curl -X POST -H "Authorization: Token <TOKEN>" -H "Content-Type: application/json" -H "Accept: application/json; indent=4" http://localhost:8000/api/dcim/devices/ --data '[
{"name": "device1", "device_type": 24, "device_role": 17, "site": 6},
{"name": "device2", "device_type": 24, "device_role": 17, "site": 6},
{"name": "device3", "device_type": 24, "device_role": 17, "site": 6},
]'
```

Bulk creation is all-or-none: If any of the creations fails, the entire operation is rolled back. A successful response returns an HTTP code 201 and the body of the response will be a list/array of the objects created.