# Filebase Platform APIs

## Filebase Platform APIs

The Filebase Platform API is a general purpose API that can be used to manage various Filebase resources. These resources include storage usage, bandwidth usage, IPNS names, and dedicated gateways.

**Request Body Schema:** `application/json`

### Authorization

`Authorization: Bearer <access-token>`

To generate the `access-token`, start by retrieving your [Filebase Access Key and Secret Access Key](https://docs.filebase.com/getting-started/getting-started-guides/getting-started-guide#access-keys) pair.

Then, navigate to [Base64Encode](https://www.base64encode.org/) and input the following information:&#x20;

`ACCESS-KEY:SECRET-KEY`

Then select 'Encode' and copy the result:

<figure><img src="https://3861818989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lyjw7dWpiQtUFDa1pO0%2Fuploads%2FLzxnROrBLwCkOvdmgOzx%2FScreen%20Shot%202023-01-25%20at%204.50.17%20PM.png?alt=media&#x26;token=c70ac905-2177-4147-99d6-4c6dac9f3c94" alt=""><figcaption></figcaption></figure>

## Total Storage and Recent Bandwidth (Past 24 Hours) Usage API

Used to generate reports on a user's current storage in bytes across all buckets. This API also returns information regarding the user's bandwidth usage over the last 24 hours.&#x20;

### Payload

**Request Body Schema:** `application/json`

## List current storage across all buckets and all bandwidth usage in the last 24 hours.

<mark style="color:blue;">`GET`</mark> `https://api.filebase.io/v1/usage`

This API can be used to generate a report that provides information on the user's current storage across all buckets, and all bandwidth usage within the last 24 hours.

{% tabs %}
{% tab title="200: OK Returns current storage across all buckets and all bandwidth usage in the last 24 hours. " %}

```json
{
    "storage": {
        "bytes": 4977622511155
    },
    "bandwidth": {
        "bytes": 0
    }
}
```

{% endtab %}
{% endtabs %}

## Total Storage for a Specific Bucket API

Used to generate reports on a user's current storage in a specific bucket.

### Payload

**Request Body Schema:** `application/json`

## List current storage usage in bytes for a specific bucket.

<mark style="color:blue;">`GET`</mark> `https://api.filebase.io/v1/usage/storage/<bucket-name>`

This API can be used to generate a report that provides information on the user's current storage across a specific bucket.&#x20;

#### Path Parameters

| Name                                          | Type   | Description             |
| --------------------------------------------- | ------ | ----------------------- |
| bucket-name<mark style="color:red;">\*</mark> | String | A Filebase bucket name. |

{% tabs %}
{% tab title="200: OK Reports current storage usage in bytes for a specific bucket " %}

```json
{
    "storage": {
        "bytes": 1251576869
    }
}
```

{% endtab %}
{% endtabs %}

## Bandwidth Usage For an IPFS Dedicated Gateway API

Used to generate a usage report of a dedicated IPFS gateway over the last 24 hours.&#x20;

### Payload

**Request Body Schema:** `application/json`

## List bandwidth usage for an IPFS dedicated gateway.

<mark style="color:blue;">`GET`</mark> `https://api.filebase.io/v1/usage/gateway/<gateway-name>`

This API reports bandwidth usage over the last 30 days by default for a specific IPFS dedicated gateway. The date range can be modified using query string parameters.

#### Path Parameters

| Name                                           | Type   | Description                             |
| ---------------------------------------------- | ------ | --------------------------------------- |
| gateway-name<mark style="color:red;">\*</mark> | String | A Filebase IPFS dedicated gateway name. |

#### Query String Parameters

| Name  | Type   | Description                       |
| ----- | ------ | --------------------------------- |
| start | String | Beginning timestamp of usage data |
| end   | String | End timestamp of usage data       |

#### Example URL

```
http://api.filebase.io/v1/usage/gateway/my-gateway?start=2023-06-10T12:24:34.043Z&end=2023-06-21T12:24:34.043Z5
```

{% tabs %}
{% tab title="200: OK Response reports bandwidth usage over the last 24 hours for a specific IPFS dedicated gateway" %}

```json
{
    "gateway": {
        "bytes": 620424
    }
}
```

{% endtab %}
{% endtabs %}

## Gateways

This set of APIs can be used to manage dedicated IPFS gateways.

## List gateways

<mark style="color:blue;">`GET`</mark> `https://api.filebase.io/v1/gateways`

Returns a list of all Dedicated IPFS Gateways

{% tabs %}
{% tab title="200: OK Lists all Dedicated IPFS gateways. " %}

```json
[
    {
        "name": "gateway123",
        "domain": null,
        "private": false,
        "created_at": "2023-02-14T11:24:39.298-05:00",
        "updated_at": "2023-02-14T11:24:39.298-05:00",
        "enabled": true
    },
    {
        "name": "gateway1234",
        "domain": null,
        "private": false,
        "created_at": "2023-02-14T11:25:11.893-05:00",
        "updated_at": "2023-02-14T11:25:11.893-05:00",
        "enabled": true
    },
    {
        "name": "gateway123223",
        "domain": null,
        "private": false,
        "created_at": "2023-02-14T11:54:31.926-05:00",
        "updated_at": "2023-02-14T11:54:31.926-05:00",
        "enabled": true
    }
]
```

{% endtab %}
{% endtabs %}

## Return details of a specific gateway

<mark style="color:blue;">`GET`</mark> `https://api.filebase.io/v1/gateways/<gateway-name>`

Response returns details for the specified gateway.

{% tabs %}
{% tab title="200: OK Returns details for the specified gateway." %}

```json
{
    "name": "test-josh555567778",
    "private": false,
    "enabled": true

}
```

{% endtab %}
{% endtabs %}

## Create a dedicated gateway

<mark style="color:green;">`POST`</mark> `https://api.filebase.io/v1/gateways`

Allows a user to create a dedicated gateway.

Example JSON Body Payload:

#### Request Body

| Name                                   | Type    | Description                                                                                                                                                                                                |
| -------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark> | String  | The name of the gateway. The name restrictions here match bucket names, 3..63 characters, must be globally unique. If a bucket name is already taken, a HTTP 409 Conflict will be returned with a message. |
| private                                | Boolean | False by default. This controls whether the gateway is public (can fetch any IPFS content) or private (can only fetch content that you've pinned).                                                         |
| enabled                                | Boolean | True by default. This controls whether a gateway is actually functional. A user can disable a gateway to prevent it from serving content.                                                                  |

{% tabs %}
{% tab title="200: OK Gateway created." %}

{% endtab %}
{% endtabs %}

## Update a gateway

<mark style="color:orange;">`PUT`</mark> `https://api.filebase.io/v1/gateways/<gateway-name>`

Allows a user to update the configuration of a gateway.

#### Request Body

| Name    | Type    | Description                                                                                                                                                                                                                                                                                                                                        |
| ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| private | Boolean | False by default. This controls whether the gateway is public (can fetch any IPFS content) or private (can only fetch content that you've pinned).                                                                                                                                                                                                 |
| enabled | Boolean | True by default. This controls whether a gateway is actually functional. A user can disable a gateway to prevent it from serving content. This will keep the gateway created, but transition it into a non-functional state. The only real use case here (so far) is to let a user pause a gateway temporarily without having to give up the name. |

{% tabs %}
{% tab title="200: OK Gateway updated. " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Delete a gateway

<mark style="color:red;">`DELETE`</mark> `https://api.filebase.io/v1/gateways/<gateway-name>`

No body payload required. Allows a use to delete a dedicated gateway. Upon deletion, the gateway will no longer be functional and it will stop serving content.

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

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Names

This set of APIs can be used to manage IPNS name records.

## List Names

<mark style="color:blue;">`GET`</mark> `https://api.filebase.io/v1/names`

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

````json
```json
[
    {
        "enabled": true,
        "label": "ocean",
        "network_key": "k51qzi5uqu5dljhjh797be563mf1dnodaued1v68zacnmfxarkfsitboa3gkrx",
        "cid": "QmZ3BYWSc1wHfMpXfXkLnctS7ABvNZYMECdbP6q68Ld18f",
        "sequence": 1,
        "published_at": "2023-12-19T15:00:08.384-05:00",
        "created_at": "2023-12-07T16:01:46.222-05:00",
        "updated_at": "2023-12-09T10:48:00.803-05:00"
    }
]
```
````

{% endtab %}
{% endtabs %}

## Return details of a specific name record

<mark style="color:blue;">`GET`</mark> `https://api.filebase.io/v1/names/<label>`

#### Path Parameters

| Name                                    | Type   | Description          |
| --------------------------------------- | ------ | -------------------- |
| label<mark style="color:red;">\*</mark> | String | Label of name record |

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

````json
```json
{
    "enabled": true,
    "label": "ocean",
    "network_key": "k51qzi5uqu5dljhjh797be563mf1dnodaued1v68zacnmfxarkfsitboa3gkrx",
    "cid": "QmZ3BYWSc1wHfMpXfXkLnctS7ABvNZYMECdbP6q68Ld18f",
    "sequence": 1,
    "published_at": "2023-12-19T15:00:08.384-05:00",
    "created_at": "2023-12-07T16:01:46.222-05:00",
    "updated_at": "2023-12-09T10:48:00.803-05:00"
}
```
````

{% endtab %}
{% endtabs %}

## Create a name

<mark style="color:green;">`POST`</mark> `https://api.filebase.io/v1/names`

#### Request Body

| Name                                    | Type   | Description                     |
| --------------------------------------- | ------ | ------------------------------- |
| label<mark style="color:red;">\*</mark> | String | Label used to identify the name |
| cid<mark style="color:red;">\*</mark>   | String | CID for the name record         |

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

````json
```json
{
    "enabled": true,
    "label": "mouse1",
    "network_key": "k51qzi5uqu5dijyeugm3dqe7odqj6s1h2pqp8toc1toy7j9bdyig6x8nzjd890",
    "cid": "bafybeieszr5kq4w7qdd4lujsje2uqwt76nlf3s4en6xc7q5hqpda5de3xy",
    "sequence": 1,
    "published_at": null,
    "created_at": "2023-12-19T16:44:44.052-05:00",
    "updated_at": "2023-12-19T16:44:44.052-05:00"
}
```
````

{% endtab %}
{% endtabs %}

## Update a name

<mark style="color:orange;">`PUT`</mark> `https://api.filebase.io/v1/names/<label>`

#### Request Body

| Name  | Type   | Description                     |
| ----- | ------ | ------------------------------- |
| label | String | Label used to identify the name |
| cid   | String | CID for the name record         |

{% tabs %}
{% tab title="204: No Content " %}

```json
```

{% endtab %}
{% endtabs %}

## Delete a name record

<mark style="color:red;">`DELETE`</mark> `https://api.filebase.io/v1/names/<label>`

{% tabs %}
{% tab title="204: No Content " %}

```json
```

{% endtab %}
{% endtabs %}