Create a file upload request (initiate direct upload)

curl --request POST \
  --url https://api.scholarlysoftware.com/api/v1/folders/{folder_id}/file_upload_requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '
{
  "data": {
    "type": "file",
    "attributes": {
      "name": "document.pdf",
      "size": 12345,
      "checksum": "XUFAKrxLKna5cZ2REBfFkg==",
      "content_type": "application/pdf"
    }
  }
}
'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "file",
    "attributes": {
      "name": "annual_report.pdf",
      "content_type": "application/pdf",
      "byte_size": 1024000,
      "checksum_md5": "<string>",
      "url": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "locked": true,
      "state": "<string>"
    },
    "relationships": {
      "folder": {
        "links": {
          "related": "<string>"
        },
        "meta": {}
      },
      "created_by": {
        "links": {
          "related": "<string>"
        },
        "meta": {}
      }
    }
  },
  "meta": {
    "direct_upload": {
      "url": "<string>",
      "headers": {}
    }
  }
}

File Upload Requests

Create a file upload request (initiate direct upload)

Step 1 of 3-step file upload: Initiate a direct upload.

This endpoint creates a placeholder file record and returns credentials for uploading the file directly to the storage service.

Upload Flow

Step 1 (this endpoint): POST to create file and get upload credentials
Step 2: Upload the file directly to the direct_upload.url using the direct_upload.headers
Step 3: PATCH the file to confirm upload complete (optional, for updating name)

Request Body

name: The filename (required)
size: File size in bytes (required)
content_type: MIME type of the file (optional, defaults to application/octet-stream)
checksum: Base64-encoded MD5 hash of the file content (required)

Response

The response includes a meta.direct_upload object containing:

url: The URL to upload the file to
headers: Headers to include in the upload request
blob_signed_id: Signed ID of the blob (for reference)

POST

api

folders

{folder_id}

file_upload_requests

Create a file upload request (initiate direct upload)

curl --request POST \
  --url https://api.scholarlysoftware.com/api/v1/folders/{folder_id}/file_upload_requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '
{
  "data": {
    "type": "file",
    "attributes": {
      "name": "document.pdf",
      "size": 12345,
      "checksum": "XUFAKrxLKna5cZ2REBfFkg==",
      "content_type": "application/pdf"
    }
  }
}
'

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "file",
    "attributes": {
      "name": "annual_report.pdf",
      "content_type": "application/pdf",
      "byte_size": 1024000,
      "checksum_md5": "<string>",
      "url": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "locked": true,
      "state": "<string>"
    },
    "relationships": {
      "folder": {
        "links": {
          "related": "<string>"
        },
        "meta": {}
      },
      "created_by": {
        "links": {
          "related": "<string>"
        },
        "meta": {}
      }
    }
  },
  "meta": {
    "direct_upload": {
      "url": "<string>",
      "headers": {}
    }
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Authorization

string

required

Bearer token

Path Parameters

folder_id

string

required

Folder UUID

Body

application/vnd.api+json

data

object

required

Show child attributes

data.type

enum<string>

required

Available options:

file

data.attributes

object

required

Show child attributes

data.attributes.name

string

required

Example:

"document.pdf"

data.attributes.size

integer

required

Example:

12345

data.attributes.checksum

string

required

Base64-encoded MD5 hash

Example:

"XUFAKrxLKna5cZ2REBfFkg=="

data.attributes.content_type

string

Example:

"application/pdf"

Response

file created with upload credentials

data

object

required

Show child attributes

data.id

string<uuid>

required

data.type

string

required

Allowed value: "file"

Example:

"file"

data.attributes

object

required

Show child attributes

data.attributes.name

string | null

required

Example:

"annual_report.pdf"

data.attributes.content_type

string | null

Example:

"application/pdf"

data.attributes.byte_size

integer | null

Example:

1024000

data.attributes.checksum_md5

string | null

data.attributes.url

string | null

data.attributes.created_at

string<datetime> | null

data.attributes.updated_at

string<datetime> | null

data.attributes.locked

boolean | null

data.attributes.state

string | null

data.relationships

object

Show child attributes

data.relationships.folder

object

required

Option 1
Option 2

Show child attributes

data.relationships.folder.links

object

required

Show child attributes

data.relationships.folder.meta

object

data.relationships.created_by

object

Option 1
Option 2

Show child attributes

data.relationships.created_by.links

object

required

Show child attributes

data.relationships.created_by.meta

object

API reference

Authorizations

Headers

Path Parameters

Body

Response