> For the complete documentation index, see [llms.txt](https://iqtlabs.gitbook.io/packet-cafe/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://iqtlabs.gitbook.io/packet-cafe/design/api.md).

# API

The `lb` (load balancer) will process requests for both the `ui` (frontend) and the `web` (API) containers. It is exposed on port 80 by default. Requests that prepend `/api` to the URL will route requests to the `web` container and all other URLs will be routed to the `ui` container. Additionally, there is an `admin` container that is exposed on its own port (5001) and is not load-balanced.

Here are the available API endpoints:

## `admin` (port 5001)

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0:5001/v1`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0:5001/v1/id/files`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0:5001/v1/id/results`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0:5001/v1/ids`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0:5001/v1/info`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0:5001/v1/logs/:id`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## `web` (port 80)

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0/api/v1`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0/api/v1/delete/:sess_id`

Deletes files and id directories associated with a session. The last session ID and request ID will be reset if they referred to this session.

#### Path Parameters

| Name     | Type   | Description |
| -------- | ------ | ----------- |
| sess\_id | string | Session ID  |

{% tabs %}
{% tab title="200 " %}

```
{ "status": "Success" }
```

{% endtab %}
{% endtabs %}

## /api/v1/id/:sess\_id/:req\_id/:tool/:pcap/:counter/:filename

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0/api/v1/id/:sess_id/:req_id/:tool/:pcap/:counter/:filename`

Serves up the results from a file produced by a tool given a specific PCAP uploaded for rendering.

#### Path Parameters

| Name     | Type   | Description                                                   |
| -------- | ------ | ------------------------------------------------------------- |
| filename | string | Filename to serve up that is returning results from the tool. |
| counter  | number | Which result file number to get, if only one use 1            |
| pcap     | string | The name of the PCAP file                                     |
| tool     | string | The tool to get results from                                  |
| req\_id  | string | The ID of the file request                                    |
| sess\_id | string | The ID of the session                                         |

{% tabs %}
{% tab title="200 Returns the contents of the results file, could be text or images or whatever." %}

```
```

{% endtab %}
{% endtabs %}

## /api/v1/ids/:sess\_id

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0/api/v1/ids/:sess_id`

Returns a list of all IDs and info about them for this session ID.

#### Path Parameters

| Name     | Type   | Description |
| -------- | ------ | ----------- |
| sess\_id | string | Session ID  |

{% tabs %}
{% tab title="200 Returns a list of all IDs and info about them for a given session ID." %}

```
[{"id": "ab7af73526814d58bf35f1399a5594b2", "filename": "trace_ab7af73526814d58bf35f1399a5594b2_2020-04-09_23_38_56.pcap", "tools": ["networkml", "mercury", "pcap-stats", "snort", "p0f", "pcapplot"], "original_filename": "smallFlows.pcap"}]
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0/api/v1/info`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0/api/v1/raw/:tool/:counter/:sess_id/:req_id`

Returns the raw JSON results from a tool.

#### Path Parameters

| Name     | Type   | Description                                            |
| -------- | ------ | ------------------------------------------------------ |
| req\_id  | string | The ID of the file request.                            |
| sess\_id | string | Session ID                                             |
| counter  | number | A tool might have more than 1 result, otherwise use 0. |
| tool     | string | Name of the tool to get results for.                   |

{% tabs %}
{% tab title="200 This is an example output of the tool p0f." %}

```
[
    {},
    {},
    {},
    {},
    {
        "10.0.2.15": {
            "full_os": "Windows NT kernel",
            "short_os": "Windows",
            "link": "Ethernet or modem",
            "raw_mtu": "1500",
            "mac": "08:00:27:cc:3f:1b"
        }
    }
]
```

{% endtab %}
{% endtabs %}

## /api/v1/results/:tool/:counter/:sess\_id/:req\_id

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0/api/v1/results/:tool/:counter/:sess_id/:req_id`

Returns the results from a tool for rendering.

#### Path Parameters

| Name     | Type   | Description                                             |
| -------- | ------ | ------------------------------------------------------- |
| req\_id  | string | The ID of the file request.                             |
| sess\_id | string | Session ID                                              |
| counter  | number | A tool might have more than 1 results, otherwise use 0. |
| tool     | string | Name of the tool to get results for.                    |

{% tabs %}
{% tab title="200 This will render actual html and/or imagery." %}

```
```

{% endtab %}
{% endtabs %}

## /api/v1/status/:sess\_id/:req\_id

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0/api/v1/status/:sess_id/:req_id`

Return the status of all tools for a request ID.

#### Path Parameters

| Name     | Type   | Description                 |
| -------- | ------ | --------------------------- |
| req\_id  | string | The ID of the file request. |
| sess\_id | string | Session ID                  |

{% tabs %}
{% tab title="200 Returns the status of all tools for a request ID." %}

```
{
    "cleaned": true,
    "mercury": {
        "state": "Complete",
        "timestamp": "2020-04-24T19:07:51.507362+00:00"
    },
    "pcap-stats": {
        "state": "Complete",
        "timestamp": "2020-04-24T19:07:43.972380+00:00"
    },
    "pcapplot": {
        "state": "Complete",
        "timestamp": "2020-04-24T19:10:54.366903+00:00"
    },
    "networkml": {
        "state": "Complete",
        "timestamp": "2020-04-24T19:09:17.470786+00:00"
    },
    "p0f": {
        "state": "Complete",
        "timestamp": "2020-04-24T19:09:26.266748+00:00"
    },
    "pcap-dot1q": {
        "state": "Complete",
        "timestamp": "2020-04-24T19:07:43.362974+00:00"
    },
    "snort": {
        "state": "Complete",
        "timestamp": "2020-04-24T19:07:54.466032+00:00"
    },
    "ncapture": {
        "state": "Complete",
        "timestamp": "2020-04-24T19:07:38.438424+00:00"
    },
    "pcap-splitter": {
        "state": "Complete",
        "timestamp": "2020-04-24T19:08:47.088579+00:00"
    }
}
```

{% endtab %}
{% endtabs %}

## /api/v1/stop/:sess\_id/:req\_id

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0/api/v1/stop/:sess_id/:req_id`

Stops jobs of a request ID.

#### Path Parameters

| Name     | Type   | Description                 |
| -------- | ------ | --------------------------- |
| req\_id  | string | The ID of the file request. |
| sess\_id | string | Session ID                  |

{% tabs %}
{% tab title="200 " %}

```
TO BE IMPLEMENTED
```

{% endtab %}
{% endtabs %}

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0/api/v1/tools`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

<mark style="color:green;">`POST`</mark> `http://0.0.0.0/api/v1/upload`

Upload a PCAP file.

#### Request Body

| Name      | Type   | Description        |
| --------- | ------ | ------------------ |
| file      | object | The file to upload |
| sessionId | string | Session ID         |

{% tabs %}
{% tab title="200 Upload a PCAP file." %}

```
{'filename': filename, 'uuid': uid, 'status': 'Success'}
```

{% endtab %}
{% endtabs %}

## `ui` (port 80)

<mark style="color:blue;">`GET`</mark> `http://0.0.0.0/`

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
|      | string |             |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

<mark style="color:green;">`POST`</mark> `http://0.0.0.0/express-upload`

Processing uploading a file and passes it on the API.

#### Path Parameters

| Name | Type   | Description     |
| ---- | ------ | --------------- |
| file | object | File to upload. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}