Getting started overview

GoFile provides a service for uploading, storing, and sharing files, offering both a web interface and a public API. The API enables developers to integrate GoFile's functionalities into their own applications, facilitating programmatic file uploads and management. This guide outlines the steps to begin using GoFile, from account setup to executing a basic file upload request via its API. While many basic API operations, such as anonymous file uploads, do not strictly require an account or API keys, registering an account provides access to personalized features, file management, and higher limits associated with a user profile. For those opting for the GoFile Pro tier, additional benefits like increased file retention and ad-free usage become available, further enhancing the developer experience for sustained use cases.

Before proceeding, ensure you have a basic understanding of HTTP requests and command-line tools like curl for making API calls. GoFile's API is RESTful, communicating primarily through JSON responses. The API documentation provides details on available endpoints and expected parameters, serving as the primary reference for all specific API interactions.

Below is a quick reference table summarizing the initial steps:

Step What to Do Where
1. Sign Up (Optional) Create a free GoFile account to manage files and retrieve API keys. GoFile registration page
2. Obtain API Token Generate or find your API token in your account settings. GoFile user profile
3. Understand Endpoints Review the API documentation for upload servers and methods. GoFile API documentation
4. Make First Request Use curl or a similar HTTP client to upload a file. Your local development environment

Create an account and get keys

While GoFile allows anonymous file uploads, creating an account is recommended for managing your uploaded content, accessing personalized features, and obtaining an API token for authenticated requests. An API token enables you to link uploads to your profile, manage files, and potentially benefit from higher limits or retention policies associated with a GoFile Pro subscription.

Account Registration

  1. Navigate to the GoFile registration page.
  2. Provide a username, email address, and strong password.
  3. Complete any CAPTCHA verification required.
  4. Click the "Register" button to create your account.

Once registered, you may need to verify your email address. Follow the instructions in the verification email sent to you. After verification, log in to your new GoFile account.

Obtaining your API Token

Accessing your API token typically involves navigating to your profile or settings page within the GoFile website. The API token acts as a form of authentication, similar in function to an OAuth 2.0 access token, which grants your applications permission to perform actions on your behalf without requiring your username and password for each request. For more information on token-based authentication, refer to the OAuth 2.0 specification.

  1. Log in to your GoFile account.
  2. Go to your Account Profile page.
  3. Locate the section labeled "API Token" or similar. Your API token is a string of alphanumeric characters.
  4. Copy this token. Keep it secure and do not expose it in client-side code or public repositories.

For programmatic access, this token will be included in your API requests, typically in a header or as a query parameter, depending on the specific API endpoint and method. Consult the GoFile API documentation for precise instructions on how to pass your API token for each request type.

Your first request

The core functionality of GoFile for developers revolves around file uploads. Before uploading a file, you first need to determine the optimal upload server. GoFile provides an endpoint to retrieve a list of available servers, allowing you to choose one that is geographically closer or less loaded for better performance.

Getting an Upload Server

To get a list of available servers, make a GET request to the /getServer endpoint. This request does not require authentication.

curl -X GET "https://api.gofile.io/getServer"

The response will be a JSON object containing information about available servers. Look for the data.server field, which will provide the hostname of an available upload server. For example, if the response indicates "server": "store1", your upload URL might be https://store1.gofile.io/uploadFile.

{
  "status": "ok",
  "data": {
    "server": "store1"
  }
}

Uploading a File

Once you have an upload server (e.g., store1), you can make a POST request to upload a file. The upload endpoint is typically https://SERVER.gofile.io/uploadFile, where SERVER is the hostname obtained from the getServer call. This request generally requires the file to be sent as multipart/form-data. You can optionally include your API token (token) as a form field to associate the upload with your account.

Let's assume you have a file named example.txt that you want to upload. You can use curl as follows:

# Replace 'store1' with the server you obtained from /getServer
# Replace 'YOUR_API_TOKEN' with your actual API token (optional for anonymous upload)

curl -X POST \
     -F "[email protected]" \
     -F "token=YOUR_API_TOKEN" \
     "https://store1.gofile.io/uploadFile"

Explanation of parameters:

  • -X POST: Specifies that this is a POST request.
  • -F "[email protected]": Tells curl to send the content of example.txt as a file upload. The @ prefix indicates a file path.
  • -F "token=YOUR_API_TOKEN": (Optional) Includes your API token. If omitted, the file will be uploaded anonymously, and you won't be able to manage it from your GoFile account.
  • "https://store1.gofile.io/uploadFile": The target URL for the upload, using the server obtained previously.

A successful response will typically return a JSON object containing details about the uploaded file, including its download link, file ID, and other metadata. This file ID is crucial for any subsequent operations on the uploaded file, such as sharing or deletion.

{
  "status": "ok",
  "data": {
    "guestToken": "...",
    "downloadPage": "https://gofile.io/d/...",
    "code": "...",
    "parentFolder": "...",
    "fileId": "...",
    "fileName": "example.txt"
  }
}

Common next steps

After successfully performing your first file upload, several common next steps can enhance your integration with GoFile:

  1. File Management: Explore endpoints for managing your uploaded files. This includes listing files associated with your account, creating and managing folders, and deleting files. These operations typically require your API token for authentication.

  2. Sharing Files: GoFile is primarily a file-sharing service. Understand how to retrieve direct download links or sharing page URLs for your uploaded files programmatically. The initial upload response provides a downloadPage URL, which can be shared directly.

  3. Error Handling: Implement robust error handling in your application. The GoFile API returns HTTP status codes and JSON error messages for different scenarios, such as invalid tokens, file size limits, or server issues. Refer to the GoFile API documentation for a list of possible error codes and their meanings.

  4. Webhooks (If Available): Check the GoFile documentation for webhook support. Webhooks allow GoFile to notify your application about events, such as a file upload completion or a download event. This can be more efficient than polling the API for status updates. For a general understanding of webhooks, consult the MDN Web Docs on Webhooks.

  5. Client Libraries/SDKs: While GoFile does not officially provide SDKs in multiple languages, you might find community-contributed libraries. If not, consider building a simple client wrapper in your preferred programming language to abstract the HTTP requests and JSON parsing, making your code cleaner and easier to maintain.

  6. Monitor Usage: If you are on a GoFile Pro plan, monitor your usage against any limits to avoid service interruptions. The GoFile dashboard or potentially API endpoints might provide usage statistics.

  7. Security Best Practices: Always store your API token securely, preferably using environment variables or a secrets management service, rather than hardcoding it into your application. Rotate your API tokens periodically.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

  • Check Network Connectivity: Ensure your machine has an active internet connection and can reach api.gofile.io. A simple ping api.gofile.io can help confirm basic connectivity.

  • Verify Server Endpoint: Double-check that the upload URL you're using (e.g., https://store1.gofile.io/uploadFile) matches the server obtained from the getServer endpoint exactly. The server name changes, and using an outdated or incorrect server will result in an error.

  • Inspect curl Syntax: Carefully review your curl command for typos, missing quotes, or incorrect flags. Common errors include forgetting the @ before the file path in -F "[email protected]" or misplacing backslashes for line continuation.

  • HTTP Status Codes: Pay attention to the HTTP status code returned in the API response. Common codes to look for include:

    • 200 OK: Success.
    • 400 Bad Request: Indicates a problem with your request, such as missing parameters or incorrect data format.
    • 401 Unauthorized: If you are using an API token and it's invalid or missing.
    • 404 Not Found: Often means the endpoint URL is incorrect.
    • 5xx Server Error: Indicates an issue on GoFile's side.

    You can force curl to show response headers for more detailed information with the -v flag: curl -v ....

  • Examine JSON Response: Even if the HTTP status is not 200 OK, GoFile's API often provides informative JSON error messages in the response body. Parse this JSON to understand the specific issue.

    {
  "status": "error",
  "message": "Error message details here."
}

  • File Path Issues: Ensure that the file specified in @example.txt exists in the directory from which you are running the curl command, or provide its full path.

  • API Token Validity: If you are sending an API token, confirm it's correct and hasn't expired or been revoked. Generate a new one from your GoFile profile if unsure.

  • Consult Documentation: The GoFile API documentation is the authoritative source for endpoint specifics, required parameters, and error responses. Cross-reference your request against the documented requirements.