File Lifecycle

Endpoints:

The new file upload will not be ready at release; this notice will be removed and @pnutapi will post when it is available.

Some endpoints have been deprecated as of v1.4.0, although they still function:

  • Create a file or placeholder
  • Upload derivatives of a file
  • Complete a placeholder file
  • Delete a file

For an explanation of how to attach files to other objects, read How To File.

POST /files/provision

Token: user

Scope: files

Prime the upload server for files to be uploaded. You can provision and upload up to 20 files at a time.

The provisioning will expire within 20 minutes. Provisioning does not "use" storage space; space is not used until a file is uploaded. You can provision as much as you want, but uploads in the next step will start being rejected once your limit is reached.

The response will include the upload_url to POST the files to, including a provisioning_token to authorize the uploads.

Total size of all files cannot exceed 100MiB.

The client can poll the meta.status_url to check on the upload progress.

POST Body Data

Name Description
files Required List of file objects. See details listed in table "files Objects" below. Up to 20 files at a time.
type Required Reverse domain name-style identifier of the file type. E.g., com.example.site. Searchable.

files Objects

Name Description
key Required The key that you submit for each file will be used to upload your file in the next step. If no name is included, the file will use the key as its name also.
size Required File size in bytes. Cannot exceed 100MiB.
is_public Defaults to false.
name Display name for the file when downloaded. Up to 250 bytes.
raw Embedded raw values.
Example
curl "https://api.pnut.io/v1/files/provision" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{
  \"files\": [
    {
      \"is_public\": true,
      \"key\": \"whatever\",
      \"name\": \"Dog under tree\",
      \"size\": 2544675,
      \"raw\": {
        \"arbitrary.something\": [
          {
            \"this\": \"that\"
          }
        ]
      }
    },
    {
      \"key\": \"another-example.txt\",
      \"size\": 71702
    }
  ],
  \"type\": \"com.example.site\"
}" \
    -X POST \
    -H "X-Pretty-Json: 1"

Returns the provisioned file details

{
    "meta": {
        "code": 200,
        "status_url": "https://api.pnut.io/v1/sys/ops/1b15eb3c-3594-4a6c-b678-5146f2daf474"
    },
    "data": {
        "expires_at": "ISO 8601",
        "files": [
            {
                "is_public": true,
                "key": "whatever",
                "name": "Dog under tree",
                "raw": {
                  "arbitrary.something": [
                      {
                        "this": "that"
                      }
                  ]
                },
                "size": 2544675,
            },
            {
                "is_public": false,
                "key": "another-example.txt",
                "name": "another-example.txt",
                "size": 71702
            }
        ],
        "provisioned_size": 2616377,
        "type": "com.example.site",
        "upload_url": "https://upload.pnut.io/files?provisioning_token=aZwnrOVsY61ya6C1rqIK7kZmfm6yh5vD"
    }
}

POST {server}/files

Token: custom

Scope: none

Upload a provisioned file to the upload server.

Content-Type should be multipart/form-data.

POST Body Data

Name Description
{key} Field named after the key used in the previous step.

URL Parameters

Name Description
server The domain and URL will be provided when provisioning files, in the upload_url field.
Example
curl "https://upload.pnut.io/v1/files" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -d "{
  \"name\":\"butternut squash\"
}" \
    -X POST \
    -H "X-Pretty-Json: 1"

Returns the updated file

{
    "meta": {
        "code": 200
    },
    "data": {"...File Object..."}
}

PATCH /files/{file_id}

Token: user

Scope: files

Update a file's details.

If a file is ever made public, it could be accessed by others indefinitely using a previously-exposed file_token_read, or for a while after via the cache. To make a public file relatively secure again, delete it and upload it again as a new file.

POST Body Data

Name Description
name 256-character name or description (to be displayed and attached to the object)
is_public True or false
raw Embedded raw values. Not deleted unless explicitly set to empty values for each type.

URL Parameters

Name Description
file_id ID of the file to update
Example
curl "https://api.pnut.io/v1/files/73" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "{
  \"name\":\"butternut squash\"
}" \
    -X PUT \
    -H "X-Pretty-Json: 1"

Returns the updated file

{
    "meta": {
        "code": 200
    },
    "data": {"...File Object..."}
}

DELETE /files

Token: user

Scope: files

Delete a list of files. This will not disassociate a file from any other objects (posts, messages...).

Because deleting files can take some time, the API call will return the list of files confirmed for deletion, and an endpoint to check the status of the operation.

Look at the operation status endpoint for more info.

Query Parameters

Name Description
ids Comma-separated list of file IDs. Up to 200 at a time.
Example
curl "https://api.pnut.io/v1/files?ids=5,35,6426,18259,18242" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -X DELETE \
    -H "X-Pretty-Json: 1"

Returns a list of files to attempt to delete, and a status endpoint to check status.

{
    "meta": {
        "code": 202,
        "status_url": "https://api.pnut.io/v1/sys/ops/ecfd4a43-4d75-4bea-8881-7a1194bedfdc"
    },
    "data": [
        "5",
        "6426"
    ]
}