Start uploading a file

POST

/{resource}/files

curl --request POST \
  --url https://example.com/v1/example/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "contentType": "image/webp", "size": 1, "path": "example" }'

Gives a presigned upload to the file store. Upload the file by POSTing a multipart/form-data form to upload.url: every field in upload.fields, then the file as file, last. Then call /files/complete with the uploadId to add the file to the space. The upload expires after an hour.

The store only takes the file at the type given, and no bigger than size. Types, and how big they can be: image/webp 25MB, image/png 25MB, image/jpeg 25MB, image/gif 25MB, audio/mpeg 50MB, audio/mp4 50MB, audio/aac 50MB, audio/ogg 50MB, audio/wav 50MB, model/gltf-binary 500MB, model/gltf+json 500MB, application/octet-stream 500MB, application/json 50MB.

Authorizations

• token

Parameters

Path Parameters

resource

required

string

/^\d+$/

The project ID of the space

Request Body^required

Media typeapplication/json

object

contentType

required

string

Allowed values: image/webp image/png image/jpeg image/gif audio/mpeg audio/mp4 audio/aac audio/ogg audio/wav model/gltf-binary model/gltf+json application/octet-stream application/json

size

required

The file’s size in bytes.

integer

>= 1

path

The path to give the file, e.g. /entities/desk/banner.webp. Defaults to one under /uploads/. A file already at the path is replaced.

string

<= 512 characters

Responses

201

The upload

Media typeapplication/json

object

uploadId

Identifies the upload, for /files/complete.

string

path

string

upload

object

url

string

fields

object

key

additional properties

string

expiresAt

When the upload expires, in milliseconds since the Unix epoch.

integer

Example ^generated

{
  "uploadId": "example",
  "path": "example",
  "upload": {
    "url": "example",
    "fields": {
      "additionalProperty": "example"
    }
  },
  "expiresAt": 1
}

400

The body is invalid. issues describes what was wrong.

Media typeapplication/json

object

error

required

A description of the error

string

code

required

A stable identifier for the kind of error

string

issues

For invalidBody: what failed validation, and where

Array<object>

object

Example ^generated

{
  "error": "example",
  "code": "example",
  "issues": [
    {}
  ]
}

401

The token is missing or invalid.

Media typeapplication/json

object

error

required

A description of the error

string

code

required

A stable identifier for the kind of error

string

issues

For invalidBody: what failed validation, and where

Array<object>

object

Example ^generated

{
  "error": "example",
  "code": "example",
  "issues": [
    {}
  ]
}

403

The token has no access to this space.

Media typeapplication/json

object

error

required

A description of the error

string

code

required

A stable identifier for the kind of error

string

issues

For invalidBody: what failed validation, and where

Array<object>

object

Example ^generated

{
  "error": "example",
  "code": "example",
  "issues": [
    {}
  ]
}

413

The file is bigger than its type allows (tooLarge)

Media typeapplication/json

object

error

required

A description of the error

string

code

required

A stable identifier for the kind of error

string

issues

For invalidBody: what failed validation, and where

Array<object>

object

Example ^generated

{
  "error": "example",
  "code": "example",
  "issues": [
    {}
  ]
}

429

Too many requests. Retry after Retry-After seconds.

Media typeapplication/json

object

error

required

A description of the error

string

code

required

A stable identifier for the kind of error

string

issues

For invalidBody: what failed validation, and where

Array<object>

object

Example ^generated

{
  "error": "example",
  "code": "example",
  "issues": [
    {}
  ]
}

Headers

Retry-After

integer

Seconds to wait before retrying

502

Something upstream failed.

Media typeapplication/json

object

error

required

A description of the error

string

code

required

A stable identifier for the kind of error

string

issues

For invalidBody: what failed validation, and where

Array<object>

object

Example ^generated

{
  "error": "example",
  "code": "example",
  "issues": [
    {}
  ]
}

503

The space is moving between servers. Retry after Retry-After seconds.

Media typeapplication/json

object

error

required

A description of the error

string

code

required

A stable identifier for the kind of error

string

issues

For invalidBody: what failed validation, and where

Array<object>

object

Example ^generated

{
  "error": "example",
  "code": "example",
  "issues": [
    {}
  ]
}

Headers

Retry-After

integer

Seconds to wait before retrying

504

Something upstream timed out.

Media typeapplication/json

object

error

required

A description of the error

string

code

required

A stable identifier for the kind of error

string

issues

For invalidBody: what failed validation, and where

Array<object>

object

Example ^generated

{
  "error": "example",
  "code": "example",
  "issues": [
    {}
  ]
}