جديد تعرّف على Privyfile، موقعنا الجديد: مشاركة ملفات خاصة مع تشفير تام بين الطرفين وروابط تُحذف تلقائيًا. تعرّف على Privyfile، موقعنا الجديد المشفّر.
زيارة privyfile.ioprivyfile.ioAPI 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:
| Where | How | Applies 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. |
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:
{
"status": "ok",
"data": { }
}
{
"status": "error-notPremium",
"data": { }
}
status field, not the HTTP code alone: "ok" means success, anything starting with error- is a failure.Common error statuses
| Status | HTTP | Meaning |
|---|---|---|
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/searchaccept 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 ametadataobject next todata. - 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.
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:
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.
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.
guestToken. Reuse it (and the returned parentFolder) in subsequent requests to keep uploading into the same account and folder.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
curl -X POST https://upload.gofile.is/uploadfile \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "[email protected]" \
-F "folderId=9f8e7d6c-5b4a-3928-1716-151413121110"
{
"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.
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
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"}'
{
"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
}
}
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.
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
| Field | Applies to | Description |
|---|---|---|
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} (it opens the file page; it downloads the file directly only with the token of the owner of the file or of a Premium account in the Authorization: Bearer header — public direct links are a Premium feature, see directLinks). |
public, childrenCount |
folder child | Subfolder details (plus its own children when maxdepth > 1). |
metadata |
top level | page, pageSize, totalCount, totalPages, hasNextPage. |
Example request & response
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
{
"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
}
}
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
| Attribute | Applies to | Value 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 | 4–100 characters; empty removes it. Available on every plan. 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
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"}'
{
"status": "ok",
"data": {
"id": "3a4b5c6d-7e8f-4a0b-9c1d-2e3f4a5b6c7d",
"type": "folder",
"name": "Quarterly reports",
"code": "m4Rt8z",
"createTime": 1754512800,
"modTime": 1754516400
}
}
Delete files and/or folders. Deleting a folder removes everything inside it, recursively.
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
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"}'
{ "status": "ok", "data": {} }
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
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"}'
{ "status": "ok", "data": {} }
Move files and/or folders into another folder of your account. All attributes and permissions are preserved — only the location changes.
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
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"}'
{ "status": "ok", "data": {} }
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.
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
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"}'
{
"status": "ok",
"data": {
"7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f": {
"status": "ok",
"data": { "id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b" }
}
}
}
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
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"
{
"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
}
}
}
Direct links
Direct links download content straight from storage, bypassing the download page — for files the raw file, for folders a ZIP archive generated on the fly. Links look like https://gofile.is/download/direct/{directLinkId}/{name}. A Premium feature.
Create a direct link for a file or folder. Access can be restricted with an expiry, an IP allowlist, domain rules, or HTTP basic auth — combined freely.
Parameters Content-Type: application/json
| Parameter | Type | Description | |
|---|---|---|---|
contentId
path
|
string | required | Content UUID (file or folder). |
expireTime
|
integer | optional | Unix timestamp after which the link stops working. Omit for a link that never expires. |
sourceIpsAllowed
|
array | optional | IPv4 addresses allowed to use the link. |
domainsAllowed
|
array | optional | Domains allowed to use the link, checked against the Referer header. |
domainsBlocked
|
array | optional | Domains refused, checked against the Referer header. |
auth
|
array | optional | "user:password" pairs — the link then requires HTTP basic auth. |
Example request & response
curl -X POST https://api.gofile.is/contents/d4c5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f/directlinks \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expireTime": 1767225600, "domainsAllowed": ["example.com"], "auth": ["alice:s3cret"]}'
{
"status": "ok",
"data": {
"id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"directLink": "https://gofile.is/download/direct/b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e/report.pdf",
"expireTime": 1767225600,
"sourceIpsAllowed": [],
"domainsAllowed": ["example.com"],
"domainsBlocked": [],
"auth": ["alice:s3cret"]
}
}
Update the restrictions of an existing direct link.
[] — or the never-expires sentinel 4102444800 for expireTime.Parameters Content-Type: application/json
| Parameter | Type | Description | |
|---|---|---|---|
contentId
path
|
string | required | Content UUID. |
directLinkId
path
|
string | required | Direct link id, as returned on creation. |
expireTime
|
integer | optional | New expiry Unix timestamp; 4102444800 means never. |
sourceIpsAllowed
|
array | optional | IPv4 allowlist; [] removes it. |
domainsAllowed
|
array | optional | Allowed domains; [] removes the rule. |
domainsBlocked
|
array | optional | Blocked domains; [] removes the rule. |
auth
|
array | optional | "user:password" pairs; [] removes basic auth. |
Example request & response
curl -X PUT https://api.gofile.is/contents/d4c5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f/directlinks/b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"expireTime": 4102444800, "auth": []}'
{
"status": "ok",
"data": {
"id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"directLink": "https://gofile.is/download/direct/b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e/report.pdf",
"expireTime": null,
"sourceIpsAllowed": [],
"domainsAllowed": ["example.com"],
"domainsBlocked": [],
"auth": []
}
}
Permanently remove a direct link. Only the link is deleted — the content itself and its other direct links are unaffected.
Parameters No body
| Parameter | Type | Description | |
|---|---|---|---|
contentId
path
|
string | required | Content UUID. |
directLinkId
path
|
string | required | Direct link id. |
Example request & response
curl -X DELETE https://api.gofile.is/contents/d4c5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f/directlinks/b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e \
-H "Authorization: Bearer YOUR_API_TOKEN"
{ "status": "ok", "data": {} }
Accounts
One account is enough for most integrations: create it once, store its token, and reuse it for every call.
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.
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
curl -X POST https://api.gofile.is/accounts \
-H "Content-Type: application/json" \
-d '{}'
{
"status": "ok",
"data": {
"id": "8b9c0d1e-2f3a-4b4c-ad5e-6f7a8b9c0d1e",
"rootFolder": "9f8e7d6c-5b4a-3928-1716-151413121110",
"tier": "guest",
"token": "YOUR_API_TOKEN"
}
}
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
curl https://api.gofile.is/accounts/getid \
-H "Authorization: Bearer YOUR_API_TOKEN"
{
"status": "ok",
"data": {
"id": "8b9c0d1e-2f3a-4b4c-ad5e-6f7a8b9c0d1e",
"email": null,
"tier": "guest"
}
}
email is null for guests; tier is "guest", "standard" or "premium".
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
curl https://api.gofile.is/accounts/8b9c0d1e-2f3a-4b4c-ad5e-6f7a8b9c0d1e \
-H "Authorization: Bearer YOUR_API_TOKEN"
{
"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
}
}
}
Invalidate the current token and generate a new one. A sign-in link carrying the new token is emailed to the account's address.
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
curl -X POST https://api.gofile.is/accounts/8b9c0d1e-2f3a-4b4c-ad5e-6f7a8b9c0d1e/resettoken \
-H "Authorization: Bearer YOUR_API_TOKEN"
{ "status": "ok", "data": {} }
Need help with integration?
Something unclear, missing, or not working as documented? Send us a message — we read everything.
Contact us