Skip to main content

File Upload

Many applications need to upload the file to the backend. Hypi provides a simple API to do so!

Hypi’s core App has a type definition called File. A file can be uploaded using an endpoint. Once it is uploaded an object of File type gets created. The information about the file gets extracted and stored as a File object. The definition includes metadata about the file, the URL to download it, and more. You may place these file objects within your data model. For example, profile picture of a user with his personal information.

The file can be downloaded from the URL given in the object using an authorization token. Anonymous users cannot download the file. To allow access to other users, permission can be granted to download the file.

With this preliminary information, let’s get inside the File type definition.

type File {
name: String!
directory: String!
path: String!
isDirectory: Boolean!
status: FileStatus
url: URL
type: String
size: Long
extension: String
isStared: Boolean
isSharable: Boolean
content: String
children(...): [File!]
nameStringName of the file
directoryStringThe name of the directory
pathStringThe path of the file
isDirectoryBooleanIf the file has to be uploaded in a virtual file system like Google Drive/Dropbox, this field is set to true
statusFileStatusStatus of file upload
urlURLURL to download file
typeStringMedia type
sizeLongSize of the file in Bytes
extensionStringExtension of the file (.txt,.jpg, etc)
isStaredBooleanFor the virtual file system, the file can be set to Starred status
isSharableBooleanFile sharing status
contentStringFor the virtual file system upload, the content of the file would be set to a String value. Otherwise, the content would be null.
childrenFileFor the virtual file system, the directory can have sub-files

Upload endpoint‚Äč

To upload a file (any file can be uploaded, image, pdf, etc), use the following endpoint

POST /upload/**

Note the **, if you use a path like /upload/my/path, then the File object will have a directory value of /my/path. If you have many files to upload, you may put all of them in one directory.

Download endpoint‚Äč

GET /file/<path>.ext

To download a file uploaded to the platform, the above URL pattern should be used.

The <path> is by default the ID of the File object. The .ext is the original extension of the file e.g. .txt. You may copy the value from path field of File object.

curl upload example‚Äč

curl -v -H "Accept: application/json" -H "Authorization: $auth" -H "hypi-domain: <instance-domain>" -F 0=@/path/to/file.txt
  • The response of the upload is JSON
  • The Authorization header is required
  • The hypi-domain header is required (like other API requests)
  • You may copy the authorization token and hypi instance domain from GraphQL configuration of the instance.
  • @ is the root directory of the file to be uploaded.

In the following example of curl request, we are uploading logo.png file to Hypi domain.

curl -v -H "Accept: application/json" -H "Authorization: <auth-token>" -H "hypi-domain:" -F 0=@static/img/logo.png

The URL Path could be if you want to upload the file under mydir directory.

Here, we have uploaded an image file. So, an Image object also gets created that has details of the uploaded image. It contains the File object with file details.

type Image {
name: String!
file: File!
description: String
location: Geo

After executing curl command, let's retrieve the details of the file object.

find(type: File, arcql: "*") {
edges {
node {
... on File {
hypi {
url {
path #Path to download file

curl download example‚Äč

curl -v<id>.ext -H "Authorization: $auth"

Let's download the file that we uploaded earllier.

curl -v -H "Authorization: <auth-token>" --output filedownload.png  

--ouput filedownload.png would redirect the data from the file to an output file.


You need to create the URL to download a file. Copy the path from File object and append it to the hypi endpoint.

In the above example, we provide an authorisation token. This is because file resource is private to the account which created it by default. To give access to other users or allow anonymous download, an access grant must be created for the File resource.

To give the anonymous users access (no token required), create an AccessRight as follows.

mutation {
values: {
AccessRight: [
resourceType: "File"
operationType: "Query"
operation: "*"
permissionType: RBP
approved: true
members: { hypi: { id: "anonymous" } }
) {

Note: resource field has the of the file uploaded. To grant access to specific users, provide s of the user Accounts in the members field.

In this example, we explicitly give anonymous users access to the file uploaded.


You need to enable Anonymous requests in the API configurations for downloading files without authorization headers.

Due to the permission above, the curl request can now be made without any authorisation headers.

curl -v<id>.ext

Now you can download the file without the hassle of providing authorization token.

curl -v --output file.png