# S3-Compatible API

The Filebase S3-compatible API can be used by thousands of standardized S3-compatible frameworks, tools, clients, and SDKs to manage data pinned to IPFS by Filebase.

[Filebase has certified](https://docs.filebase.com/code-development-+-sdks) several of these tools for use with the platform. Filebase certification consists of putting software tools through testing procedures to validate conformity with the Filebase S3-compatible API.

## **API Endpoint**

The Filebase S3-compatible API endpoint URL is:

`https://s3.filebase.com`

## **Region**

The Filebase S3-compatible API requires a region value of **us-east-1**. This value is used by the AWS CLI and AWS SDK to calculate the request signature during the authentication process.

## **Access Keys**

To use the Filebase S3-compatible API, you will need to have your Filebase Access and Secret key pair to submit API requests.

To view the access key for your Filebase account, start by clicking on the ‘Access Keys’ option from the menu to open the access keys dashboard.

Here you can view the access keys for your account. Each access key has two parts, the key and the secret associated with the key. The access key dashboard will also provide information such as the time and date the access key was created and its current status.

<figure><img src="https://3861818989-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lyjw7dWpiQtUFDa1pO0%2Fuploads%2F2QSO4JOmRhqKFFK6ml7P%2Fimage.png?alt=media&#x26;token=02874d20-ce2a-47f6-881c-c48d81cca171" alt=""><figcaption></figcaption></figure>

To use access keys, you will need to have both the key and the secret associated with that key.

## **Authentication**

The Filebase S3-compatible API only supports AWS **v4 signatures** (AWS4-HMAC-SHA256) for authentication and does not support AWS v2 signatures at this time. To learn more about S3 authentication, see this [article](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).

## **HTTPS Protocol**

Filebase maintains a strict HTTPS-only standard. This means objects and API calls are served only via HTTPS. The port for this connection is the HTTPS standard **port 443**.

It is not possible to disable this at this time. Requests sent via the HTTP protocol will be redirected to HTTPS.

## Rate Limit

The Filebase S3 API has an effective rate limit of 100 RPS (requests per second).&#x20;

## **Supported API Methods**

The list below documents Filebase's currently supported S3 API methods.

<details>

<summary>AbortMultipartUpload</summary>

Cancels a multipart upload. Once aborted, the upload is canceled and no additional parts can be uploaded using the original upload ID. Any of the parts that were uploaded prior to the cancellation will be deleted.

</details>

<details>

<summary>CompleteMultipartUpload</summary>

Completes a previously initiated multipart upload by assembling previously uploaded parts.

</details>

<details>

<summary>CopyObject</summary>

Used to create a duplicate copy of an existing object.

</details>

<details>

<summary>CreateBucket</summary>

Creates a new Filebase bucket. By default, this bucket is created on the IPFS network.&#x20;

</details>

<details>

<summary>CreateMultipartUpload</summary>

Initiates a multipart upload which returns a unique upload ID value. This ID value is used to identify all parts of the multipart upload.

</details>

<details>

<summary>DeleteBucket</summary>

Removes the specified bucket from Filebase. The bucket must be empty before it can be removed.&#x20;

</details>

<details>

<summary>DeleteBucketCors</summary>

Removes the current CORS policy set on the specified Filebase bucket.&#x20;

</details>

<details>

<summary>DeleteObject</summary>

Removes an object from being stored on Filebase.&#x20;

</details>

<details>

<summary>GetBucketAcl</summary>

Returns the specified bucket’s currently configured access control list.&#x20;

</details>

<details>

<summary>GetBucketCors</summary>

Returns the specified bucket’s current CORS policy.

</details>

<details>

<summary>GetBucketLifecycle</summary>

Returns the specified bucket’s current lifecycle configuration.

</details>

<details>

<summary>GetBucketLifecycleConfiguration</summary>

Returns the specified bucket’s current lifecycle configuration.&#x20;

</details>

<details>

<summary>GetBucketLocation</summary>

Returns the region of the specified bucket.

</details>

<details>

<summary>GetBucketLogging</summary>

Returns the current logging status of the specified bucket.

</details>

<details>

<summary>GetBucketVersioning</summary>

Returns the current versioning state of the specified bucket.&#x20;

</details>

<details>

<summary>GetObject</summary>

Retrieves the specified object(s) from Filebase.&#x20;

</details>

<details>

<summary>GetObjectAcl</summary>

Retrieves the current access control list configuration for the specified object.

</details>

<details>

<summary>HeadBucket</summary>

Used to determine if the specified bucket exists.

</details>

<details>

<summary>HeadObject</summary>

Used to determine if the specified object exists.

</details>

<details>

<summary>ListBuckets</summary>

Lists all current buckets on your Filebase account.

</details>

<details>

<summary>ListObjects</summary>

Lists all current objects within the specified bucket. Maximum return of 1,000 objects.

</details>

<details>

<summary>ListObjectsV2</summary>

Lists all current objects within the specified bucket. Maximum return of 1,000 objects. The newest version of ListObjects, and recommended for new workflows.&#x20;

</details>

<details>

<summary>PutBucketAcl</summary>

Used to configure the access control list permissions on the specified bucket.

</details>

<details>

<summary>PutBucketCors</summary>

Used to configure the CORS policy on the specified bucket.&#x20;

</details>

<details>

<summary>PutObject</summary>

Used to upload an object to the specified bucket.

</details>

<details>

<summary>PutObjectAcl</summary>

Used to configure the access control list permissions on the specified object.

</details>

<details>

<summary>UploadPart</summary>

Used to upload a part from a multipart upload using the upload’s unique ID value.

</details>

When a response payload is present, all responses are returned using UTF-8 encoded XML.

## **Pre-signed URLs**

The Filebase S3-compatible API supports pre-signed URLs for downloading and uploading objects. Pre-signed URLs can be generated in a number of ways including the AWS CLI and the AWS SDKs.&#x20;

For more information on Pre-signed URLS, see our guide [here](https://docs.filebase.com/api-documentation/s3-compatible-api/pre-signed-urls).

## **Access Control Lists (ACLs)**

The Filebase S3-compatible API features limited support for Access Control Lists (ACLs). Object-level ACLs are currently not supported.

The `GetObjectAcl` and `GetBucketAcl` methods will work as expected, but the `GetObjectAcl` response will return the ACL of the bucket that the object is contained in.

This design eliminates the possibility of a user accidentally making an object public within a private bucket. If a mix of private and public objects is required for your workflow, you can simply create two different buckets.&#x20;

For information on how to create a Filebase bucket, see [here](https://docs.filebase.com/api-documentation/broken-reference).