Storage Server Reference

Self-Hosting Storage

An S3 compatible object storage service that integrates with Postgres.

  • Uses Postgres as it's datastore for storing metadata
  • Authorization rules are written as Postgres Row Level Security policies
  • Integrates with S3 as the storage backend (with more in the pipeline!)
  • Extremely lightweight and performant

Client libraries

Create a bucket

post/bucket/

Body

  • name
    Required
    string
  • id
    Optional
    string
  • public
    Optional
    boolean
  • type
    Optional
    enum
  • file_size_limit
    Optional
    any of the following options
  • allowed_mime_types
    Optional
    Array<string>

Response codes

  • 200
  • 4XX

Response (200)

1
{
2
  "name": "avatars"
3
}

Gets all buckets

get/bucket/

Query parameters

  • limit
    Optional
    integer
  • offset
    Optional
    integer
  • sortColumn
    Optional
    enum
  • sortOrder
    Optional
    enum
  • search
    Optional
    string

Response codes

  • 200
  • 4XX

Response (200)

1
[
2
  {
3
    "id": "bucket2",
4
    "name": "bucket2",
5
    "public": false,
6
    "file_size_limit": 1000000,
7
    "allowed_mime_types": [
8
      "image/png",
9
      "image/jpeg"
10
    ],
11
    "owner": "4d56e902-f0a0-4662-8448-a4d9e643c142",
12
    "created_at": "2021-02-17T04:43:32.770206+00:00",
13
    "updated_at": "2021-02-17T04:43:32.770206+00:00"
14
  }
15
]

Empty a bucket

post/bucket/{bucketId}/empty

Path parameters

  • bucketId
    Required
    string

Response codes

  • 200
  • 4XX

Response (200)

1
{
2
  "message": "Empty bucket has been queued. Completion may take up to an hour."
3
}

Get details of a bucket

get/bucket/{bucketId}

Path parameters

  • bucketId
    Required
    string

Response codes

  • 200
  • 4XX

Response (200)

1
{
2
  "id": "lorem",
3
  "name": "lorem",
4
  "owner": "lorem",
5
  "owner_id": "lorem",
6
  "public": true,
7
  "type": "STANDARD",
8
  "created_at": "lorem",
9
  "updated_at": "lorem"
10
}

Update properties of a bucket

put/bucket/{bucketId}

Body

  • public
    Optional
    boolean
  • file_size_limit
    Optional
    any of the following options
  • allowed_mime_types
    Optional
    Array<string>

Response codes

  • 200
  • 4XX

Response (200)

1
{
2
  "message": "Successfully updated"
3
}

Delete a bucket

delete/bucket/{bucketId}

Path parameters

  • bucketId
    Required
    string

Response codes

  • 200
  • 4XX

Response (200)

1
{
2
  "message": "Successfully deleted"
3
}

Delete an object

delete/object/{bucketName}/{wildcard}

Path parameters

  • bucketName
    Required
    string
  • *
    Required
    string

Response codes

  • 200
  • 4XX

Response (200)

1
{
2
  "message": "Successfully deleted"
3
}

Get object

get/object/{bucketName}/{wildcard}

Serve objects

Path parameters

  • bucketName
    Required
    string
  • *
    Required
    string

Response codes

  • 4XX

Update the object at an existing key

put/object/{bucketName}/{wildcard}

Path parameters

  • bucketName
    Required
    string
  • *
    Required
    string

Response codes

  • 200
  • 4XX

Response (200)

1
{
2
  "Id": "lorem",
3
  "Key": "avatars/folder/cat.png"
4
}

Upload a new object

post/object/{bucketName}/{wildcard}

Path parameters

  • bucketName
    Required
    string
  • *
    Required
    string

Response codes

  • 200
  • 4XX

Response (200)

1
{
2
  "Id": "lorem",
3
  "Key": "avatars/folder/cat.png"
4
}

Delete multiple objects

delete/object/{bucketName}

Path parameters

  • bucketName
    Required
    string

Body

  • prefixes
    Required
    Array<string>

Response codes

  • 200
  • 4XX

Response (200)

1
[
2
  {
3
    "name": "folder/cat.png",
4
    "bucket_id": "avatars",
5
    "owner": "317eadce-631a-4429-a0bb-f19a7a517b4a",
6
    "id": "eaa8bdb5-2e00-4767-b5a9-d2502efe2196",
7
    "updated_at": "2021-04-06T16:30:35.394674+00:00",
8
    "created_at": "2021-04-06T16:30:35.394674+00:00",
9
    "last_accessed_at": "2021-04-06T16:30:35.394674+00:00",
10
    "metadata": {
11
      "size": 1234
12
    }
13
  }
14
]

Retrieve an object

get/object/authenticated/{bucketName}/{wildcard}

Path parameters

  • bucketName
    Required
    string
  • *
    Required
    string

Query parameters

  • download
    Optional
    string

Response codes

  • 4XX

Generate a presigned url to retrieve an object

post/object/sign/{bucketName}/{wildcard}

Path parameters

  • bucketName
    Required
    string
  • *
    Required
    string

Body

  • expiresIn
    Required
    integer
  • transform
    Optional
    object

Response codes

  • 200
  • 4XX

Response (200)

1
{
2
  "signedURL": "/object/sign/avatars/folder/cat.png?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1cmwiOiJhdmF0YXJzL2ZvbGRlci9jYXQucG5nIiwiaWF0IjoxNjE3NzI2MjczLCJleHAiOjE2MTc3MjcyNzN9.s7Gt8ME80iREVxPhH01ZNv8oUn4XtaWsmiQ5csiUHn4"
3
}

Retrieve an object via a presigned URL

get/object/sign/{bucketName}/{wildcard}

Path parameters

  • bucketName
    Required
    string
  • *
    Required
    string

Query parameters

  • download
    Optional
    string
  • token
    Required
    string

Response codes

  • 4XX

Generate presigned urls to retrieve objects

post/object/sign/{bucketName}

Path parameters

  • bucketName
    Required
    string

Body

  • expiresIn
    Required
    integer
  • paths
    Required
    Array<string>

Response codes

  • 200
  • 4XX

Response (200)

1
[
2
  {
3
    "error": "Either the object does not exist or you do not have access to it",
4
    "path": "folder/cat.png",
5
    "signedURL": "/object/sign/avatars/folder/cat.png?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1cmwiOiJhdmF0YXJzL2ZvbGRlci9jYXQucG5nIiwiaWF0IjoxNjE3NzI2MjczLCJleHAiOjE2MTc3MjcyNzN9.s7Gt8ME80iREVxPhH01ZNv8oUn4XtaWsmiQ5csiUHn4"
6
  }
7
]

Moves an object

post/object/move

Body

  • bucketId
    Required
    string
  • sourceKey
    Required
    string
  • destinationBucket
    Optional
    string
  • destinationKey
    Required
    string

Response codes

  • 200
  • 4XX

Response (200)

1
{
2
  "message": "Successfully moved"
3
}

Search for objects under a prefix

post/object/list/{bucketName}

Path parameters

  • bucketName
    Required
    string

Body

  • prefix
    Required
    string
  • limit
    Optional
    integer
  • offset
    Optional
    integer
  • sortBy
    Optional
    object
  • search
    Optional
    string

Response codes

  • 200
  • 4XX

Response (200)

1
[
2
  {
3
    "name": "folder/cat.png",
4
    "bucket_id": "avatars",
5
    "owner": "317eadce-631a-4429-a0bb-f19a7a517b4a",
6
    "id": "eaa8bdb5-2e00-4767-b5a9-d2502efe2196",
7
    "updated_at": "2021-04-06T16:30:35.394674+00:00",
8
    "created_at": "2021-04-06T16:30:35.394674+00:00",
9
    "last_accessed_at": "2021-04-06T16:30:35.394674+00:00",
10
    "metadata": {
11
      "size": 1234
12
    }
13
  }
14
]

Retrieve object info

get/object/info/{bucketName}/{wildcard}

Object Info

Path parameters

  • bucketName
    Required
    string
  • *
    Required
    string

Response codes

  • 4XX

Copies an object

post/object/copy

Body

  • bucketId
    Required
    string
  • sourceKey
    Required
    string
  • destinationBucket
    Optional
    string
  • destinationKey
    Required
    string
  • metadata
    Optional
    object
  • copyMetadata
    Optional
    boolean

Response codes

  • 200
  • 4XX

Response (200)

1
{
2
  "Id": "lorem",
3
  "Key": "folder/destination.png",
4
  "name": "lorem",
5
  "bucket_id": "lorem",
6
  "owner": "lorem",
7
  "owner_id": "lorem",
8
  "version": "lorem",
9
  "id": "lorem",
10
  "updated_at": "lorem",
11
  "created_at": "lorem",
12
  "last_accessed_at": "lorem",
13
  "metadata": {},
14
  "user_metadata": {},
15
  "buckets": {
16
    "id": "bucket2",
17
    "name": "bucket2",
18
    "public": false,
19
    "file_size_limit": 1000000,
20
    "allowed_mime_types": [
21
      "image/png",
22
      "image/jpeg"
23
    ],
24
    "owner": "4d56e902-f0a0-4662-8448-a4d9e643c142",
25
    "created_at": "2021-02-17T04:43:32.770206+00:00",
26
    "updated_at": "2021-02-17T04:43:32.770206+00:00"
27
  }
28
}

Retrieve an object from a public bucket

get/object/public/{bucketName}/{wildcard}

Path parameters

  • bucketName
    Required
    string
  • *
    Required
    string

Query parameters

  • download
    Optional
    string

Response codes

  • 4XX

Get object info

get/object/info/public/{bucketName}/{wildcard}

returns object info

Path parameters

  • bucketName
    Required
    string
  • *
    Required
    string

Response codes

  • 4XX