# 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="/files/s7ydPKnA8yLitjQ224Mt" 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 %}


---

# 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.filebase.com/api-documentation/filebase-platform-apis.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.