# Using curl

While Swagger UI provides a visual interface into the API, it is often desirable to send API calls via the command line. For this, [curl](https://curl.se/) can be used.

## Required information

To send a curl request to the API, two things are required:

* An API key
* The curl command string

## Obtaining an API key

If an API key is not already available from previous API usage, the following steps should be followed.

1. Log into the planet console using a Link11 WAAP account (i.e., **without using SSO**). The account must have an [Access Level](https://waap.docs.link11.com/console-walkthrough/system/users-management#user-parameters) of *Editor* or higher. 
2. Navigate to [**Account**](https://waap.docs.link11.com/console-walkthrough/account) by selecting the user icon on the top right of the page
3. Navigate to **Account Details** -> **API Keys**. (If Account Details is not displayed in the Account menu, verify that the login was done directly into the planet using an L11WAAP account. If SSO is used, Account Details will not be available in the interface.)
4. Select "New" -> Enter a name for the key -> "Confirm"
5. Copy the value of that key for use within curl. (Note: this is the string that the system generated, not the name you supplied.)

## Using Swagger UI to construct the curl command string

Sending an API request via Swagger UI will also construct and display its curl command string:

1. Navigate to [the planet's instance of Swagger UI](https://waap.docs.link11.com/using-the-product/the-link11-waap-api/using-swagger-ui). 
2. Expand the desired namespace, and then the desired route within the namespace.
3. Select the "**Try it Now**" button
4. Edit the input fields (if any), providing all required inputs
5. Select the **"Execute"** button
6. After sending the request, Swagger UI will display the curl command string. Copy this.

To send this request using curl, edit the command string to include an additional header (`Authorization:Basic`) for the API key obtained earlier.

### Example

When Swagger UI is used to get a list of configurations via `GET /api/v4/conf/configs`, it will also display this curl command:

```bash
curl -X 'GET' \
  'https://www.mysite.com/api/v4/conf/configs' \
  -H 'accept: application/json'
```

To submit this command directly via curl, the following header must be added:

```bash
-H 'Authorization:Basic <api-key-obtained-earlier>'
```

...without the `<>`, and where `api-key-obtained-earlier` is the string obtained [above](#obtaining-an-api-key).

## Manually constructing the curl command string

API calls using curl are constructed according to these requirements:

* The API key is included, as explained above
* Input parameters defined as *query* are encoded into the URL
* Input parameters defined as *header* are included as headers
* Input parameters defined as **Request body** are included via curl's `-d` option

### Example: query and header parameters

A route to retrieve traffic data has this definition:

<figure><img src="https://2966474948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcxktceFryDnM5HLHONr8%2Fuploads%2FvZ9y8diqwXGp58ITgcZa%2FSwagger%20example%20of%20query%20and%20header%20parameters.png?alt=media&#x26;token=057af7fb-1c42-4dc7-aced-3ff2e974ef0d" alt=""><figcaption></figcaption></figure>

Note that `limit`, `offset`, `filters`, and `debug` are marked as *query* parameters, and therefore, will be encoded into the URL. However, `syntax` and `provider` are marked as *header* parameters.

The resulting curl command will look like this:

```bash
curl -X 'GET' \
  'https://mysite.com/api/v4.0/data/logs?limit=100&offset=0&filters=%7B%22AND%22%3A%5B%7B%22field%22%3A%20%22timestamp%22%2C%20%22value%22%3A%20%5B%222024-06-02T00%3A00%3A00%22%2C%20%222024-06-03T00%3A00%3A00%22%5D%2C%22op%22%3A%20%22between%22%7D%20%5D%7D&debug=false' \
  -H 'accept: application/json' \
  -H 'syntax: json' \
  -H 'provider: bigquery' \
  -H 'Authorization:Basic kFiudeEIOSd18dDineS2wn98sIO'
```

### Example: request body&#x20;

The POST */api/v4.0/data/timeline/parse* call includes this input:

<figure><img src="https://2966474948-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FcxktceFryDnM5HLHONr8%2Fuploads%2FjCduc2k6bpAwUy8K7Bn0%2FSwagger%20example%20of%20request%20body.png?alt=media&#x26;token=0c0c0fb5-ace6-41fd-abbe-8b47a4e5f02a" alt=""><figcaption></figcaption></figure>

Let's say that an admin wants to submit the string `timestamp between 2024-06-06 09:31:00 and 2024-06-06 09:36:00, status=301`. The curl command would look like this:

```bash
curl -X 'POST' \
  'https://mysite.com/api/v4.0/data/timeline/parse' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization:Basic kFiudeEIOSd18dDineS2wn98sIO' \
  -d '{
  "query": "timestamp between 2024-06-06 09:31:00 and 2024-06-06 09:36:00, status=301"
}'
```