API

API Documentation

Integrate gofile.is storage and content delivery into your applications with the REST API.

The API is in beta — endpoints may evolve, check this page regularly.

Getting started

Authentication

Every API request is authenticated with an account token — yours is below, and on your profile page. Three equivalent ways to send it:

WhereHowApplies to
Authorization Authorization: Bearer YOUR_API_TOKEN Every request — recommended.
token ?token=YOUR_API_TOKEN GET requests only.
token "token": "YOUR_API_TOKEN" in the JSON body Non-GET requests only.
Your API token · Guest 5094769916
••••••••••••••••••••••••

This is a guest account: its token is the only way back in — save it somewhere safe, or add an email address from your profile.

The token authenticates as the account itself — anyone holding it has full access. Keep it server-side: never embed it in public client-side code or commit it to a repository.
Endpoints badged Premium require a Premium account. Everything else — uploading, creating folders, updating and deleting content — works with any account, including guests.

Requests & responses

All endpoints live under https://api.gofile.is (uploads excepted — see Uploading), speak JSON in and out, and are CORS-enabled, so browser-based integrations work too.

Every response is wrapped in the same envelope:

Success 
{
  "status": "ok",
  "data": { }
}
Error 
{
  "status": "error-notPremium",
  "data": { }
}
Always branch on the status field, not the HTTP code alone: "ok" means success, anything starting with error- is a failure.

Common error statuses

StatusHTTPMeaning
error-token 401 No token provided, or the token was rejected.
error-accountId 403 The requested account id does not match the token's account.
error-notPremium 401 The endpoint requires a Premium account.
error-rateLimit 429 Rate limit exceeded — back off and retry later.
error-limits 403 Account quota exceeded (storage, file size or content count).
error-notFound 404 Unknown content — also returned to non-owners for private or recycled content.
error-owner 401 The content belongs to another account.
error-passwordRequired 401 The content is password-protected: send its SHA-256 password.
error-rootFolder 400 The operation is not allowed on the root folder.
error-protectedFolder 403 The root folder cannot be deleted.
error-field 400 A parameter failed validation — the status names it (error-file, error-contentsId, error-folderId, error-attribute, error-attributeValue, error-tags, error-email, …).
error-guestAccount 400 Token reset refused for guest accounts.
error-mailUnavailable 503 Email delivery is not configured on this server.
error-storage 503 The storage backend could not complete the operation (upload, copy or import) — retry later.

Conventions

  • All timestamps are Unix seconds (e.g. 1754512800).
  • Content ids are UUIDs. Folders and files additionally carry a share code — 6 characters for folders, 8 for files. GET /contents/{contentId} and /contents/search accept either form; mutations require the UUID. A code grants no extra access: private content stays owner-only.
  • Listings paginate with page / pageSize; totals come back in a metadata object next to data.
  • Every account has a recycle bin: deletions are recoverable from the website's Recycle bin.

Rate limits

Rate limits are enforced per endpoint, both per IP address and per account. Exceeded limits answer 429 with error-rateLimit — back off and retry.

For security reasons, the exact values are not publicly disclosed. Normal API usage never comes close to them.

Repeatedly exceeding rate limits may result in automatic IP bans.

Need higher limits for a real use case? Contact us to discuss custom solutions.

Account structure

Every account owns a permanent root folder; all files and folders live somewhere under it:

Account Root folder Files & subfolders

The root folder cannot be deleted, moved or expired. Its UUID is the rootFolder field of the account details endpoint — start there to walk the tree.

Uploading

Uploads go to https://upload.gofile.is, which stores each file on a storage server.

POST https://upload.gofile.is/uploadfile

Upload a file. With no parameters at all, a guest account is created on the fly, a new public folder is generated at its root, and the file lands in it — the response carries everything needed to keep using both.

Uploading without a token creates a guest account: the response then includes a guestToken. Reuse it (and the returned parentFolder) in subsequent requests to keep uploading into the same account and folder.
Guest accounts (no verified email) get 1 GB of storage and files up to 1 GB; accounts with a verified email (Free) get 10 GB and files up to 5 GB. Both are capped at 10,000 stored contents — uploads past these limits fail with error-limits. Paid plan limits scale with the plan.

Parameters Content-Type: multipart/form-data

Parameter Type   Description
file file required The file to upload.
folderId string optional UUID of the destination folder. Omit to create a new public folder at the account root.
token string optional Account token. May also be sent as an Authorization: Bearer header instead — without either, a guest account is created.
Example request & response
Request 
curl -X POST https://upload.gofile.is/uploadfile \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "[email protected]" \
  -F "folderId=9f8e7d6c-5b4a-3928-1716-151413121110"
Response — trimmed 
{
  "status": "ok",
  "data": {
    "id": "d4c5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
    "type": "file",
    "name": "report.pdf",
    "parentFolder": "9f8e7d6c-5b4a-3928-1716-151413121110",
    "parentFolderCode": "x7k2p9",
    "downloadPage": "https://gofile.is/d/x7k2p9",
    "code": "Qp9w8eR7",
    "size": 2481621,
    "md5": "0f8adc1149b1a2c3d4e5f60718293a4b",
    "mimetype": "application/pdf",
    "createTime": 1754512800,
    "modTime": 1754512800,
    "servers": ["store-1"]
  }
}

Files & folders

Every file and folder lives under the account's root folder. Mutations take UUIDs only; the read and search endpoints also resolve share codes.

POST https://api.gofile.is/contents/createFolder

Create a folder inside a parent folder. The new folder inherits access (public, password, expiry) from its parent; change it afterwards with the update endpoint.

Parameters Content-Type: application/json

Parameter Type   Description
parentFolderId string required UUID of the parent folder. Use the account's root folder UUID to create a top-level folder.
folderName string optional Name of the new folder. Auto-generated if omitted.
public boolean optional Whether the folder is publicly accessible. Omit to inherit the parent's setting — the new folder also inherits the parent's password and expiry.
Example request & response
Request 
curl -X POST https://api.gofile.is/contents/createFolder \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parentFolderId": "9f8e7d6c-5b4a-3928-1716-151413121110", "folderName": "Reports"}'
Response — trimmed 
{
  "status": "ok",
  "data": {
    "id": "3a4b5c6d-7e8f-4a0b-9c1d-2e3f4a5b6c7d",
    "type": "folder",
    "name": "Reports",
    "parentFolder": "9f8e7d6c-5b4a-3928-1716-151413121110",
    "code": "m4Rt8z",
    "public": true,
    "createTime": 1754512800,
    "modTime": 1754512800
  }
}
GET https://api.gofile.is/contents/{contentId} Premium

Read a folder — its metadata plus its children — or a single file's metadata. contentId accepts a content UUID or its share code (6 characters for folders, 8 for files). A file returns its own payload, without children.

Direct API access to listings is Premium-only: other tiers receive error-notPremium. Non-owners can only read public, unexpired folders.

Parameters Query parameters

Parameter Type   Description
contentId path string required Content UUID or share code.
password string optional SHA-256 hex of the folder password, for password-protected folders.
page integer optional Page of children to return (starts at 1).
pageSize integer optional Children per page — default 100, max 1000.
sortField string optional createTime (default), name, size, downloads or mimetype.
sortDirection integer optional 1 ascending, -1 descending (default).
contentFilter string optional Case-insensitive substring filter on child names and tags.
maxdepth integer optional How many levels of subfolders to include, 1–16 (default 1).

Response fields

FieldApplies toDescription
id, type, name, code folder Identity of the folder; type is "folder".
parentFolder folder Parent UUID, null for the root folder.
public / password folder Visibility; password is true when the folder is protected.
isOwner / isRoot folder Whether the token's account owns the folder, and whether it is the root folder.
description, tags, expire folder Optional metadata; expire is a Unix timestamp or null.
createTime, modTime folder Unix timestamps.
childrenCount, children folder Number of children and an object of children keyed by UUID.
size, md5, mimetype, downloadCount file child File details.
servers, serverSelected, link file child Storage servers holding the file and its download link https://gofile.is/dl/{code} (API clients get the file directly; a web browser opening it is shown the file page, add ?dl=1 to force the download).
public, childrenCount folder child Subfolder details (plus its own children when maxdepth > 1).
metadata top level page, pageSize, totalCount, totalPages, hasNextPage.
Example request & response
Request 
curl -G https://api.gofile.is/contents/m4Rt8z \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d page=1 -d pageSize=100 -d sortField=name -d sortDirection=1
Response — trimmed 
{
  "status": "ok",
  "data": {
    "id": "3a4b5c6d-7e8f-4a0b-9c1d-2e3f4a5b6c7d",
    "type": "folder",
    "name": "Reports",
    "code": "m4Rt8z",
    "parentFolder": "9f8e7d6c-5b4a-3928-1716-151413121110",
    "public": true,
    "password": false,
    "isOwner": true,
    "isRoot": false,
    "description": "",
    "tags": "",
    "expire": null,
    "createTime": 1754512800,
    "modTime": 1754512800,
    "childrenCount": 2,
    "children": {
      "d4c5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f": {
        "id": "d4c5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
        "type": "file",
        "name": "report.pdf",
        "code": "Qp9w8eR7",
        "parentFolder": "3a4b5c6d-7e8f-4a0b-9c1d-2e3f4a5b6c7d",
        "size": 2481621,
        "md5": "0f8adc1149b1a2c3d4e5f60718293a4b",
        "mimetype": "application/pdf",
        "downloadCount": 12,
        "createTime": 1754512800,
        "modTime": 1754512800,
        "servers": ["store-1"],
        "serverSelected": "store-1",
        "link": "https://gofile.is/dl/Qp9w8eR7"
      },
      "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b": {
        "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
        "type": "folder",
        "name": "2025",
        "code": "k9Pq2w",
        "parentFolder": "3a4b5c6d-7e8f-4a0b-9c1d-2e3f4a5b6c7d",
        "public": true,
        "childrenCount": 4,
        "createTime": 1754512900,
        "modTime": 1754512900
      }
    }
  },
  "metadata": {
    "page": 1,
    "pageSize": 100,
    "totalCount": 2,
    "totalPages": 1,
    "hasNextPage": false
  }
}
PUT https://api.gofile.is/contents/{contentId}/update

Update one attribute of a file or folder per call.

Parameters Content-Type: application/json

Parameter Type   Description
contentId path string required Content UUID (share codes are not accepted by mutations).
attribute string required The attribute to modify — see the table below.
attributeValue mixed required The new value; the expected format depends on the attribute. For removable attributes, an empty value deletes them.

Attributes

AttributeApplies toValue format
name files & folders New content name (max 255 characters).
description files & folders Free text, max 2,000 characters. Empty removes it.
tags files & folders Comma-separated tags — letters, digits, - and _, 25 characters each. Empty removes all tags.
public folders true / false. Making a folder public returns its share code.
password folders Premium 4–100 characters; empty removes it. Premium on gofile.is. Clients conventionally send the SHA-256 hex of the plaintext, which is what readers then send as the password parameter. Passwords set on the website are compatible.
expiry folders Unix timestamp after which the folder is no longer accessible; empty removes it. Rejected on the root folder with error-rootFolder.
modTime files & folders Unix timestamp.
Example request & response
Request 
curl -X PUT https://api.gofile.is/contents/3a4b5c6d-7e8f-4a0b-9c1d-2e3f4a5b6c7d/update \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"attribute": "name", "attributeValue": "Quarterly reports"}'
Response — trimmed 
{
  "status": "ok",
  "data": {
    "id": "3a4b5c6d-7e8f-4a0b-9c1d-2e3f4a5b6c7d",
    "type": "folder",
    "name": "Quarterly reports",
    "code": "m4Rt8z",
    "createTime": 1754512800,
    "modTime": 1754516400
  }
}
DELETE https://api.gofile.is/contents

Delete files and/or folders. Deleting a folder removes everything inside it, recursively.

Deleted content goes to the account's recycle bin and can be restored from the website's Recycle bin.
Only your own content can be deleted (error-owner otherwise); the root folder is protected (error-protectedFolder).

Parameters Content-Type: application/json

Parameter Type   Description
contentsId string required Comma-separated list of content UUIDs to delete.
Example request & response
Request 
curl -X DELETE https://api.gofile.is/contents \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contentsId": "d4c5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f,5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"}'
Response — trimmed 
{ "status": "ok", "data": {} }
POST https://api.gofile.is/contents/copy Premium

Copy files and/or folders into a destination folder of your account. The copies are independent new content with their own UUIDs; the originals are untouched.

Parameters Content-Type: application/json

Parameter Type   Description
contentsId string required Comma-separated list of content UUIDs to copy.
folderId string required UUID of the destination folder.
password string optional SHA-256 hex of the password, if the source is password-protected.
Example request & response
Request 
curl -X POST https://api.gofile.is/contents/copy \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contentsId": "d4c5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "folderId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"}'
Response — trimmed 
{ "status": "ok", "data": {} }
PUT https://api.gofile.is/contents/move Premium

Move files and/or folders into another folder of your account. All attributes and permissions are preserved — only the location changes.

Moving a folder moves its whole tree with it. Both the moved content and the destination must belong to your account, and a folder cannot be moved into itself.

Parameters Content-Type: application/json

Parameter Type   Description
contentsId string required Comma-separated list of content UUIDs to move.
folderId string required UUID of the destination folder.
Example request & response
Request 
curl -X PUT https://api.gofile.is/contents/move \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contentsId": "d4c5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "folderId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"}'
Response — trimmed 
{ "status": "ok", "data": {} }
POST https://api.gofile.is/contents/import Premium

Save content shared with you (public folders and files of other accounts) into your own account: the items are copied into your root folder. The UUIDs come from the shared folder's listing.

The response is keyed by source UUID, and each item carries its own status — a single item can fail (e.g. error-notFound) while the others succeed.

Parameters Content-Type: application/json

Parameter Type   Description
contentsId string required Comma-separated list of content UUIDs to import.
password string optional SHA-256 hex of the password, if the shared content is password-protected.
Example request & response
Request 
curl -X POST https://api.gofile.is/contents/import \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contentsId": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f"}'
Response — trimmed 
{
  "status": "ok",
  "data": {
    "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f": {
      "status": "ok",
      "data": { "id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b" }
    }
  }
}
GET https://api.gofile.is/contents/search Premium

Search a folder recursively by name or tags. Matches are case-insensitive substrings (doc matches document.pdf). The response is an object keyed by content UUID.

Parameters Query parameters

Parameter Type   Description
contentId string required UUID or share code of the folder to search in.
searchedString string required Text to look for in names and tags.
password string optional SHA-256 hex of the folder password, if protected.
createTimeFrom integer optional Only return content created at or after this Unix timestamp.
createTimeTo integer optional Only return content created at or before this Unix timestamp.
Example request & response
Request 
curl -G https://api.gofile.is/contents/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d contentId=9f8e7d6c-5b4a-3928-1716-151413121110 \
  --data-urlencode "searchedString=report"
Response — trimmed 
{
  "status": "ok",
  "data": {
    "d4c5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f": {
      "id": "d4c5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
      "type": "file",
      "name": "report.pdf",
      "code": "Qp9w8eR7",
      "parentFolder": "3a4b5c6d-7e8f-4a0b-9c1d-2e3f4a5b6c7d",
      "size": 2481621,
      "createTime": 1754512800
    },
    "3a4b5c6d-7e8f-4a0b-9c1d-2e3f4a5b6c7d": {
      "id": "3a4b5c6d-7e8f-4a0b-9c1d-2e3f4a5b6c7d",
      "type": "folder",
      "name": "Reports",
      "code": "m4Rt8z",
      "parentFolder": "9f8e7d6c-5b4a-3928-1716-151413121110",
      "createTime": 1754512800
    }
  }
}

Accounts

One account is enough for most integrations: create it once, store its token, and reuse it for every call.

POST https://api.gofile.is/accounts

Create an account — no token needed, this is the entry point. With an empty body a guest account is created and its token returned immediately. With an email, a standard account is created and a sign-in link (carrying the token) is sent to that address.

Create one account and reuse its token — do not mint an account per upload. (Uploading without a token also auto-creates a guest account; see Uploading.)

Parameters Content-Type: application/json

Parameter Type   Description
email string optional Email address for a standard account; the sign-in link is sent there (requires email delivery — error-mailUnavailable otherwise). Omit to create a guest account. With an email, the response data is empty.
Example request & response
Request 
curl -X POST https://api.gofile.is/accounts \
  -H "Content-Type: application/json" \
  -d '{}'
Response — trimmed 
{
  "status": "ok",
  "data": {
    "id": "8b9c0d1e-2f3a-4b4c-ad5e-6f7a8b9c0d1e",
    "rootFolder": "9f8e7d6c-5b4a-3928-1716-151413121110",
    "tier": "guest",
    "token": "YOUR_API_TOKEN"
  }
}
GET https://api.gofile.is/accounts/getid

Resolve the account behind the current token: its id, email and tier. Useful to check which account a token belongs to.

Parameters No body

Parameter Type   Description
token string optional Only if not sent as an Authorization: Bearer header.
Example request & response
Request 
curl https://api.gofile.is/accounts/getid \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Response — trimmed 
{
  "status": "ok",
  "data": {
    "id": "8b9c0d1e-2f3a-4b4c-ad5e-6f7a8b9c0d1e",
    "email": null,
    "tier": "guest"
  }
}

email is null for guests; tier is "guest", "standard" or "premium".

GET https://api.gofile.is/accounts/{accountId}

Full account details: tier, plan, root folder and usage statistics. The requested id must belong to the token's account (error-accountId otherwise).

Parameters Path parameter

Parameter Type   Description
accountId path string required Account id, as returned by /accounts/getid.
Example request & response
Request 
curl https://api.gofile.is/accounts/8b9c0d1e-2f3a-4b4c-ad5e-6f7a8b9c0d1e \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Response — trimmed 
{
  "status": "ok",
  "data": {
    "id": "8b9c0d1e-2f3a-4b4c-ad5e-6f7a8b9c0d1e",
    "email": "[email protected]",
    "tier": "premium",
    "premiumType": "Pro",
    "premiumExpireTime": 1786048800,
    "token": "YOUR_API_TOKEN",
    "rootFolder": "9f8e7d6c-5b4a-3928-1716-151413121110",
    "createTime": 1754512800,
    "statsCurrent": {
      "storage": 2481621,
      "fileCount": 1,
      "folderCount": 2
    }
  }
}
POST https://api.gofile.is/accounts/{accountId}/resettoken

Invalidate the current token and generate a new one. A sign-in link carrying the new token is emailed to the account's address.

The old token stops working immediately — every app and device using it must be updated. Refused for guest accounts (error-guestAccount), because their token is the only way in; requires email delivery (error-mailUnavailable otherwise).

Parameters Path parameter

Parameter Type   Description
accountId path string required Account id of the token's account.
Example request & response
Request 
curl -X POST https://api.gofile.is/accounts/8b9c0d1e-2f3a-4b4c-ad5e-6f7a8b9c0d1e/resettoken \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Response — trimmed 
{ "status": "ok", "data": {} }

Need help with integration?

Something unclear, missing, or not working as documented? Send us a message — we read everything.

Contact us