# with cURL

## Overview

We will here show how cURL can be used to interact with our REST API. As an example, Basic Auth will be used to authenticate a GET request that fetches a list of available projects. All available endpoints are listed in our [REST API Reference](https://developer.disruptive-technologies.com/api).

## Prerequisites

* **Enable Basic Auth**\
  You need to have [created a Service Account](/service-accounts/creating-a-service-account.md) with Basic Auth enabled. Any role will suffice.

## cURL

cURL is a command-line tool that can be used to easily make arbitrary HTTP requests. This includes our entire API which can be accessed via a single cURL command. Detailed information about the parameters used can be found under cURLs manpage, `man curl`.

### Installation

The tool comes preinstalled on most Linux and Mac systems. You can verify the install by opening your favorite shell and typing `which curl` , and are otherwise readily available in most package managers.

* **Debian-based distributions:** `apt install curl`
* **Arch-based distributions:** `pacman -S curl`
* **Mac:** `brew install curl`
* **Windows:** The cURL client binary can be found [here](https://curl.haxx.se/download.html#Win64).

## GET Request

The following command will fetch a list of all available projects for a Service Account.

```bash
curl -X GET "https://api.disruptive-technologies.com/v2/projects" \
    -u "<YOUR_SERVICE_ACCOUNT_KEY_ID>":"<YOUR_SERVICE_ACCOUNT_SECRET>"
```

* **-X \<command>**\
  Specifies the HTTP request method and to which URL it is sent.\
  The method, usually GET or POST, should be changed to accommodate the target URL.
* **-u \<user:password>**\
  Specifies the user for authentication.\
  We use a Service Account, and the key-id and secret can be found when creating the account, as explained in the [Basics of Service Accounts](/service-accounts/introduction-to-service-accounts.md).&#x20;

If the valid key-id and secret of a Service Account with sufficient privileges were used, cURL should return a list of the available projects for that account to stdout.

```javascript
{"projects":[{"name":"projects/btadoe94jplfdvvdr6q0","displayName":"wCaV7Y",
"organization":"organizations/b9spme0i0da0037ge49g","organizationDisplayName":
"Disruptive Technologies Research","sensorCount":10,"cloudConnectorCount":1,
"inventory":false}],"nextPageToken":""}
```

## POST Request

The following command adds the label `my-new-label` with value `some-value` to the specified device.

```bash
curl -X POST "https://api.d21s.com/v2/projects/<YOUR_PROJECT_ID>/devices/<YOUR_DEVICE_ID>/labels" \
    -u "<YOUR_SERVICE_ACCOUNT_KEY_ID>":"<YOUR_SERVICE_ACCOUNT_SECRET>" \
    -d '{"key": "my-new-label", "value": "some-value"}'
```

* **-X \<command>**\
  Specifies the HTTP request method and to which URL it is sent.\
  The method, usually GET or POST, should be changed to accommodate the target URL.
* **-u \<user:password>**\
  Specifies the user for authentication.\
  We use a Service Account, and the key-id and secret can be found when creating the account, as explained in the [Basics of Service Accounts](/service-accounts/introduction-to-service-accounts.md).&#x20;
* **-d \<data>**\
  Sends the specified data in a POST request to the HTTP server.

If the valid key-id and secret of a Service Account with sufficient privileges were used, cURL should return a list of the available projects for that account to stdout.

```javascript
{
  "name": "projects/<YOUR_PROJECT_ID>/devices/<YOUR_DEVICE_ID>/labels/my-new-label",
  "key": "my-new-label",
  "value": "some-value"
}
```

## Optional Formatting

cURL alone makes no attempt at formatting its output. By piping the cURL output through a command-line JSON processor like [jq](https://stedolan.github.io/jq/),  the result is much more readable.&#x20;

```bash
curl <insert-command-here> | jq
```

The same response as previously now looks like the following.

```bash
{
  "projects": [
    {
      "name": "projects/btadoe94jplfdvvdr6q0",
      "displayName": "wCaV7Y",
      "organization": "organizations/b9spme0i0da0037ge49g",
      "organizationDisplayName": "Disruptive Technologies Research",
      "sensorCount": 10,
      "cloudConnectorCount": 1,
      "inventory": false
    }
  ],
  "nextPageToken": ""
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.developer.disruptive-technologies.com/explore-our-rest-api/with-curl.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.