# Getting started ## API Overview The Filemail API is accessible through an HTTP interface. Base URL of the API: `https://api-public.filemail.com` All endpoints accept JSON-encoded (`Content-Type: application/json`) request bodies, and return JSON-encoded responses. > One exception regarding content type is the `/savefile.ashx` endpoint used for file uploads. You can find more details about it here: [Upload files](/api/sending-files/upload-files.md) ## API Keys Accessing the Filemail API requires an API key. Log in to your Filemail account and head to the [API Key section](https://app.filemail.com/settings#apikeys). You can create, delete and rotate your API key there. If you don't have an account yet, you can create it here: . Note that only Personal, Pro, Business and Enterprise accounts have access to our API. {% hint style="warning" %} The API key is linked directly to your Filemail user. Anyone in possession of your API key is able to authenticate with Filemail (same as if they had your login and password) and perform operation. on behalf of your Filemail user account. For this reason you should secure your account key. Do not expose it to public, don't embed it in any client-side JavaScript code and don't store it in code repositories. {% endhint %} ## Authentication with the API Key Every request to Filemail API must include an `x-api-key` header containing a valid API key: ``` x-api-key: mJE5v1zHs.... ``` Any request without an API key will be rejected with a `401` HTTP status. As mentioned in the previous section, an API key automatically authenticates requests as the Filemail user who owns the API key. ## Custom authentication It is possible to act on behalf of other users as well. Please refer to [Custom authentication](/custom-authentication.md) article and learn how to obtain a `logintoken` and a `refreshtoken`. These two combined will allow making requests on behalf of other users. This functionality can be used for building standalone apps which integrate with Filemail file sharing infrastructure. Once obtained, the `logintoken` must be appendedas a request header, together with an API key. The request will be authenticated with `logintoken` which is taking precedence before `x-api-key` . ``` x-api-key: mJE5v1zHs.... logintoken: r9BPAFW..... ``` ## Versioning All requests to the Filemail API must include an `x-api-version` header. This header determines which version-specific logic will be executed by the Filemail server. This approach makes it very clear to API consumers what version of the API endpoint they are using. This in turn provides consistent behavior and eliminates any unexpected changes in API processing logic, validation, and response formats. * **Default Requirement**: If an endpoint does not specify versioning details in its documentation, it only supports version `2.0`. This value must be used in the `x-api-version` header. * **Multiple Versions**: If an endpoint supports multiple versions, the documentation will list them. You must specify either `2.0` or one of the listed custom versions in the header accordingly. Example request header for an endpoint which has no versioning specification: ``` x-api-key: mJE5v1zHs.... x-api-version: 2.0 ``` ## Rate limits Filemail API employs a protective rate limit to ensure stability and prevent abuse. Specifically, the API is limited to **20 requests every 10 seconds**. Exceeding the rate limit will result in request rejection with HTTP status `429` . ## Daily quotas In addition to the protective rate limit every Filemail subscription plan is assigned with a daily quota of API requests. The quota is refilled constantly using a leaky-bucket algorithm. This means that once you exhaust your daily quota, it starts refilling soon after. E.g. when the quota is 2400 requests per day, then you'll get 100 requests available 1 hour after quota has been exhausted. Exceeding your daily quota will result in request rejection with HTTP status `429` . More information on specific quotas per subscription plan will be announced soon. Stay tuned. :radio: --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.filemail.com/filemail-api-2.0/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.