API Concepts

A successful API request can return one page of files, create a user, or start work that continues in the background. An integration needs to recognize which result it received before taking the next step.

An application programming interface (API) is a defined way for software to request work from another system. Files.com's API exposes resources such as files, folders, users, permissions, and Syncs. You can use it through the CLI, an SDK, or a supported connector without constructing HTTP requests yourself.

Clients of the Same API

A client is the software making the request. The CLI, SDKs, and Files.com connectors use the same API; the integration method guide helps you choose a client for your environment.

An SDK, or software development kit, supplies a client library for your programming language. For example, its folder-listing method formats an API request, authenticates it, and turns the response into objects your application can use. Iteration can fetch more pages as your application reads the list. A file-transfer helper can make several requests, so one method or CLI command can produce several billable API calls.

Requests, Resources, and Responses

Files.com's REST API uses HTTP over an encrypted HTTPS connection. Representational State Transfer (REST) organizes an API around resources addressed by URLs and operations expressed through HTTP methods. An endpoint is the address for a particular API operation. The site address identifies the Files.com site; the resource address identifies the collection or object involved.

For a nightly report job, listing a pickup folder asks Files.com for information. Uploading a report changes file contents. Updating a user's settings changes a different resource and requires the corresponding administrative authority. These operations use the same service but have different inputs, permissions, and results.

HTTP methods describe the kind of request: GET retrieves information, POST creates a resource or starts an action, PUT or PATCH updates a resource, and DELETE removes one. The selected operation's reference defines the exact method and behavior. In particular, an HTTP update method does not tell you whether an omitted Files.com setting is preserved or cleared.

A request has an address and method, headers carrying information such as credentials and content format, and any inputs the operation requires. Inputs can identify a resource, narrow a list, or supply settings to change. Structured request bodies commonly use JSON, a text format containing named values, objects, and lists. Uploading and downloading file contents also involves transferring the file data; a metadata response describing a file is not the contents of that file.

Files.com returns an HTTP status, response headers, and any response content. A successful result might be a user record, a page of folder entries, or the status of an operation. An error contains a diagnostic explanation and a structured error type. The CLI, SDK, or connector presents these in its own form.

Authentication and Authorization

Authentication establishes which credential or session is making a request. Authorization determines whether that connection can perform the requested operation on the selected resource. A valid key can authenticate successfully while lacking permission to write to a folder or create a user.

For unattended integrations, Files.com recommends an API key. Choose its account and scope for the job's required access, following the integration credential guidance. For example, a report uploader needs write access to its destination; a valid key limited to reading that folder will still receive an authorization error when it tries to upload.

Session authentication supports applications in which a person signs in. Sessions expire under the site's session rules, and the application must handle sign-in again. That is a different lifecycle from an API key's expiration and revocation.

OAuth is an authorization process through which a person approves a client's access without giving that client their password. For example, the Remote MCP server's Sign In with Files.com flow gives the AI client a bearer token representing the authorized session. A bearer token is a credential the recipient can use by presenting it; the term describes how the token is used, while OAuth describes how access is authorized. Follow the authentication method supported by the particular Files.com client rather than assuming its OAuth flow also applies to every API integration.

API keys, session credentials, and bearer tokens all require protected storage. An environment variable is a named value supplied to a running process outside its source code. A secret manager stores credentials under access controls and supplies them to an authorized application or job. Environment injection keeps the key out of the script and command arguments, but the running process still receives the secret. Restrict the job's operating-system account and avoid logging its environment.

The CLI authentication guide explains environment-based credentials. The REST authentication reference documents the exact credential headers and request examples for direct HTTP clients.

Results and Errors

Use the operation's status and the Files.com error's message, class, or type to understand the outcome. Use structured error types or SDK error families for automatic decisions, and messages for the person diagnosing the problem. Different Files.com errors can share an HTTP code, and message wording can change.

An SDK presents an API error through its language's error or exception mechanism. A specific error belongs to a broader family, so application code can handle a particular condition or a category such as missing authorization. For example, Python's FolderAdminPermissionRequiredError belongs to the NotAuthorizedError family. The SDK references document the classes or types for each language. A failure originating locally, such as an unreadable source file or an invalid SDK argument, can occur before any API request is sent.

For example, a missing read permission and an invalid input need different repairs even if the surrounding workflow simply reports that its Files.com step failed. Capture the specific message and structured error information that the client makes available. Files.com deliberately uses a not-found response for some inaccessible resources so the response does not disclose their existence. Check access using the production connection: an administrator can see paths that a restricted integration cannot.

At the HTTP level, 2xx responses indicate request success, 4xx responses indicate a request or access condition, and 5xx responses indicate a server failure. These are broad transport categories, not a complete recovery decision. A rate-limit condition can be temporary even though it is in 4xx, while a successful request can start work that is still running in the background.

The REST error reference shows the response structure, field-level validation details, and supported error types. For CLI scripts, use the process exit code and stderr. Selecting JSON output does not turn every CLI failure into a JSON API error.

Use bounded retries and rate-limit handling to recover temporary failures, and Notifications or Event Channels when another system needs to react to activity or an operational outcome.

Pagination and Complete Lists

Pagination divides a list into bounded portions, reducing the size and processing cost of each request. A folder with 100,000 entries takes 100 pages at 1,000 entries per page. The first successful response supplies only the first portion of that inventory.

Files.com uses cursors to continue list requests. A cursor is a continuation value returned with a page of results. Pass it back to resume the same listing, keeping its page size and selection criteria consistent. This differs from calculating a page number or offset yourself. Treat the cursor as an opaque value supplied by Files.com, rather than constructing or modifying it.

Official SDK iterators handle subsequent pages as you consume the results. Check for an error during iteration as well as when starting the list: a later page can fail after earlier records have already been processed. If your application reads only part of an iterator, it has not retrieved the whole inventory.

The CLI normally follows list pages for you. For scripts that need a bounded portion and an explicit continuation, the JSON envelope procedure uses --json-envelope, --per-page, and the returned cursor. Limits on pages or records intentionally produce a partial inventory.

For a direct client, the REST pagination reference documents the cursor headers and page-size parameter. The default page size is 1,000 records; the pagination reference allows up to 10,000, and recommends 1,000 or fewer. Page size determines records per request, not the total size of the folder or site. API call usage also depends on how often you repeat the listing.

Reading a Files.com Reference Entry

Select the reference for the client you will actually run. A CLI command, SDK method, and REST operation can describe the same resource while using different syntax. The Files.com API Reference provides those client-specific views.

Start with the resource's meaning and the operation's purpose: listing folders and creating a folder are different actions. For a REST entry, read the method and endpoint together. Placeholders identify values to supply, such as the identifier of an existing object; they are not literal parts of your site's configuration.

Read authorization requirements before choosing a key. Then distinguish required inputs, optional settings, defaults, types, and supported values. Check the meaning of omitted inputs in that operation instead of assuming that leaving out a setting clears it. Response attributes describe what the call returns and may include generated identifiers needed by later operations.

Finally, read completion and error behavior. Determine whether the operation returns the final result or starts background work, how a list continues, and which error conditions your workflow can handle. Adapt example values to your site and credentials; use reference examples to learn the syntax, then choose the permissions and workflow for your integration.

Match examples to the client version you deploy. API compatibility and SDK versioning explain why a client-library upgrade and a change to the hosted API are different decisions.