Authentication
You can utilize our API by authenticating with either an API Key, a JSON Web Tokens or an Access Token which will provide a JSON Web Tokens. The JSON Web Token and an API Key are both valid forms of authentication in all API requests except the auth resources themselves.
auth_token referenced in this documentation can be populated with either your valid API Key or a valid JSON Web Token.
Disabled by default
API Keys are disabled by default for security and must be explicitly created.
HTTPs Only
Fast.io only supports requests over the HTTPs protocol. Any requests made via HTTP will be rejected or fail.
Server Side Only
The API key should never be publicly exposed. Its recommended you only use it in Server-Side applications where you can control access.
Once you login to your account, you can retrieve your API Key by performing the following steps.
- Go to your Account Settings.
- Click on Integrate.
- Click on Add API Key if it's not already enabled.
- Copy the API Key.
Key Length
API Keys are fixed at 36 characters in length.
API Key Expiration
API Keys do not expire but can be deleted at any time.
You can delete an API Key at any time using the Delete button. Once you delete an API Key it is immediately invalidated.
JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret.
The user/token API provides a valid JSON Web Token which can be useful for an on-demand token generation.
Scopes
Your JWT includes scopes that indicate access. Before accessing a given API, ensure you have the proper scope. For this version of the API, there are only 3 scopes which makes it pretty easy. Additionally, in this version of the API, only 1 scope will be provided with your JWT and they are meant to be inclusive of previous scopes.
fast.io/auth
This scope indicates you have limited access to secondary authentication API's only, such as 2-Factor Authentication. You will need to complete further authentication before getting any additional scopes. Specifically, you can call Authorization Check to see if 2Factor is enabled or get the current credentials scope, and you can call Auth 2Factor to get an extended scope beyond auth.
fast.io/user
This scope indicates you have standard user access to the API including the auth API's.
fast.io/role
This scope is not used in this version of the API.
fast.io/admin
This scope is not used in this version of the API.
Password Change
A password change will immediately invalidate all JSON Web Tokens, after changing an account password previous tokens will be invalid. API Keys are not affected.
Credentials may be supplied through several formats for flexibility of development. In this documentation we will use an API Key for readability and include it as a header where applicable.
HTTP Header
Authorization: Bearer :auth_token
This form of authentication can be used for all API requests except for user/token itself.
HTTP Post
auth_token: :auth_token
You can include it as a parameter in any HTTP Post requests.
HTTP Get
?auth_token=:auth_token
You can include it in the URI in get requests. Note: This is not recommended, but it is supported for your flexibility.
Failure to supply credentials for any resource that is protected results in a 401 response.
Accounts may have 2-Factor authentication enabled. If you're using an API Key for authentication, 2-Factor authentication is not used. If you're using JSON Web Tokens via user/token then you may be subject to additional authentication through the 2-Factor API.
2-Factor authentication is implemented via Authy and supports its apps, SMS, and phone call. Only cellphones should be used. Before enabling 2Factor, associate a phone_number and phone_country with your User. When this feature is enabled, calling user/token will generate a limited JSON Web Token that can only be utilized with the user/2factor APIs.
Once authentication is completed through user/2factor a second JSON Web Token with full scope privileges is provided.
Access Token
This endpoint provides the user a JSON Web Token when valid plain text credentials are supplied via HTTP Authentication. Requesting a new token will not invalidate any previously issued tokens.
200
The request was successful and a valid token has been supplied.
401
The user or password (or both) were not valid.
420
Login blocked because of too many attempts. Try again in a few.
result
Boolean
true if the credentials were accepted and an auth_token is returned.
expires_in
Integer
The token is valid for this many seconds from the time its issued.
auth_token
String
This is a JSON Web Token you can use for API authorization.
2Factor
Boolean
Indicates if 2Factor is enabled or required to continue. If true you must continue authentication through the 2Factor API.
Create Key
This endpoint creates an API Key which can be used for all subsequent requests.
200
The request was successful and a valid API Key has been returned.
400
An invalid request was made.
result
Boolean
true if the credentials were accepted and an auth_token is returned.
api_key
String
This is the API Key which can be used to access the origin account.
List Keys
This endpoint lists existing API keys registered to the current account.
200
The request was successful and a valid API Key has been returned.
result
Boolean
true if the request was valid and a list of api_keys was returned.
results
int
The number of api_key returned in the api_keys array.
api_keys
array
An array of api_key for each of the API Keys created in this account.
Empty Result
If you have not created any API Keys the api_keys array will be empty and the results field will be 0.
API Key Limit
You are limited to 20 API Keys per account.
Delete Key
This endpoint deletes an API Key permanently.
Add 2Factor
This endpoint enables 2-Factor authentication for your user account.
Authy
Fast.io uses Authy to provide its 2Factor authentication. They provide a variety of apps and you can use voice calls and SMS messages as well.
Cellphones Only
Only use cell phones with 2Factor authentication.
Requirements
To add 2Factor authentication, you must already have a valid phone_number and phone_country code in your User Object. 2factor must be false in the User Object as well.
Verification
Once you add 2Factor, you will have to verify the addition with a token response before it will be activated. This ensures you are not locked out of your account. The state will be unverified in Get 2Factor until it is verified.
Limited Time to Verify
You have limited time to verify your 2-Factor authentication. If you do not verify within 1 hour of the addition of 2Factor, it will be removed.
202
2Factor authentication request was accepted.
406
2Factor was not added to the account.
429
Too many requests were made in too short a period of time.
result
boolean
true if 2Factor authentication was added.
Verify 2Factor
This endpoint enables 2-Factor authentication for your user account.
202
The token was validated and 2-Factor is now enabled on the account.
406
The token was not accepted.
429
Too many requests were made in too short a period of time.
result
boolean
true if 2Factor authentication was verified and is now fully enabled.
Get 2Factor
This endpoint gets the current status of 2Factor for the current users account.
200
2Factor authentication request was accepted.
429
Too many requests were made in too short a period of time.
result
boolean
true if 2Factor authentication was added.
state
string
The current state of 2Factor Auth for the provided credentials. See table below.
disabled
2Factor authentication is disabled.
enabled
2Factor authentication is enabled and verified.
unverified
2Factor authentication has been configured but not verified.
Remove 2Factor
This endpoint provides removes 2-factor authentication from a users account.
General
If 2Factor authentication is enabled, you must supply a token to disable it with your removal request. If 2Factor authentication is unverified no token must be supplied to remove it.
Result Codes
200
The request successfully removed 2-Factor authentication from your account or 2-Factor was not enabled.
429
Slow down, too many requests for authorization codes. Try again in a bit.
result
boolean
true if 2-Factor authentication was successfully removed or was already removed from your account.
Send 2Factor Code
This endpoint sends an authorization token via SMS to the users phone_number.
202
The authentication code was created and sent to the assigned device.
429
Slow down, too many requests for authorization codes. Try again in a bit.
result
Boolean
true if the authentication code created and sent.
Rate Limit
This API is heavily rate-limited and may result in 429 responses if called too frequently.
Send 2Factor Call
This endpoint sends an authorization token via a Phone Call to the users phone_number.
202
The authentication code was created and sent to the assigned device via a phone call.
429
Slow down, too many requests for authorization codes. Try again in a bit.
result
Boolean
true if the authentication code created and sent.
Rate Limit
This API is heavily rate-limited and may result in 429 responses if called too frequently.
Auth 2Factor
This endpoint authorizes a 2-Factor token and provides a JWT in return.
200
The token was validated and 2-Factor is now enabled on the account.
406
The token was not accepted.
429
Too many requests were made in too short a period of time.
result
Boolean
true if the credentials were accepted and an auth_token is returned.
expires_in
Integer
The token is valid for this many seconds from the time its issued.
auth_token
String
This is a JSON Web Token you can use for API authorization.
User Object
This object is contains the details of a single user account.
id
int
The user_Id of the account. This will always be a 20 digit number.
email_address
string
The email address for the user account. String length 4 and 30 characters.
No
country_code
string
The country code for the user account. Fixed string length of 2 characters.
Yes
tos_agree
string
The version of Terms of Service affirmatively accepted by user.
Yes
first_name
string
The first name of the user. String length between 2 and 30 characters.
No
last_name
string
The last name of the user. String length between 2 and 30 characters.
No
phone_country
int
The country code associated with the phone number.
No
phone_number
int
The phone number of the user excluding the country code and formatting.
No
2factor
boolean
True if two-factor authentication is enabled on this account.
Yes
subscriber
boolean
True if the user has a subscription.
Yes
valid_phone
boolean
True if the phone number has been validated by the user.
Yes
valid_email
boolean
True if the email has been validated by the user.
Yes
created
datetime
The date and time this record was created.
Yes
updated
datetime
The date and time this record was last updated.
Yes
locked
boolean
true if the users account is locked. This indicates it was disabled and certain resources will be unavailable.
Yes
suspended
boolean
true if the users account is suspended. This indicates no user resources will be available.
Yes
User Details
This endpoint gets the account details associated with the provided credentials.
2Factor Verification
If 2Factor Authorization is enabled on this account, you must supply the token parameter with your request or it will be rejected.
200
The request and resource are valid and the user details are returned in the body.
Update User Details
This endpoint updates the account details associated with the provided credentials.
Phone Numbers for Verification
It is recommended you only use cellular phones for your phone_number field, they are used for verification of account services and are not compatible with non-SMS enabled devices.
ISO 3166-1
Country Codes are two-character alpha-codes indicating the origin country of the user and should adhere to the ISO 3166-1 standard.
202
The updates to the user details were accepted.
400
The request was invalid and could not be serviced. This could result from missing fields or exceeding character limits.
409
The email_address or phone_number you supplied available.
result
boolean
true if the account details were accepted.
Send Validation Email
This endpoint sends a validation email to the currently configured email address.
Overview
This is the first part of a two-part process to validate an email address. Once this API call is completed, an email is generated to the currently registered email address for the authorized account. The email will include an email_token which can be used in the second step, Validate Email.
Email addresses need to be re-validated after signup or any change to a verified email address.
Accounts with un-verified emails may be restricted from a variety of functionality and may automatically limit the scope.
Result Codes
202
The validation email was sent to the address specified by the account holder.
result
boolean
true if the email_address a validation email is sent.
Invalidating Previous Tokens
Requests to this API will invalidate any previous codes.
Time to Live
Tokens are only valid for 3 hours from time of generation.
Validating a validated address
If your email is already validated, your request will fail with a not acceptable response.
Validate Email
This endpoint validates an email with a code previously sent via email.
Overview
Email validation is the second step of the email validation process. The first step is to get a validation email, as shown in Send Validation Email. That email will include the email_token needed for this API.
Result Codes
202
The email_token was accepted and the password has been updated.
result
boolean
true if the email_address is validated. false for all other responses.
Check Email
This endpoint checks to see if an email address is valid and its availability. This resource is restricted.
Restricted Resource
This resource is rate limited to 1 request per second, 3 requests per minute and 5 per hour.
202
The email address is valid and available.
400
The request was invalid and could not be serviced. This could result from missing fields or exceeding character limits.
403
Your authentication credentials do not provide access to this resource.
406
The email_address you supplied is not available or acceptable.
result
boolean
true if the email_address is valid and available.
Check Phone
This endpoint checks to see if a phone number is valid to use with an account.
202
The phone_number is valid and is acceptable.
406
The phone_number is not valid or acceptable.
429
Too many requests were made in too short a period of time.
result
boolean
true if the phone_country and phone_number is valid. false if the phone number is invalid.
Formatting
The format of the phone_check field is the phone_country followed by a - followed by the numeric-only phone_number.
Rate Limited Resource
This resource is rate limited and frequent requests will result in a 429 error.
Check Password Code
This endpoint checks a password the provided code for validity and returns the associated email.
Restricted Resource
This is a rate-limited and restricted resource.
200
The code was valid and the associated email was returned.
result
boolean
true if the code was valid.
email
string
The email of the account associated with the code.
Set Password
This endpoint sets a password for the account related to the provided code.
Lost Password
This endpoint checks to see if an email address is valid and its availability. This resource is restricted.
Restricted Resource
This resource is rate limited to 1 request per second, 2 requests per minute and 5 per hour, so on and so forth.
202
The email address is valid and a reset email was sent.
400
The request was invalid and could not be serviced. This could result from missing fields or exceeding character limits.
406
The email_address you supplied is not in use or acceptable.
result
boolean
true if the email_address was found and a reset request was sent.
Close Account
This endpoint locks the account associated with the provided credentials.
Account Closure
Once an account is closed, it cannot be re-opened as this is a permanent action.
Some account meta-data is retained for legality purposes. See our privacy policy for information on data-retention.
2Factor Verification
If 2Factor Authorization is enabled on this account, you must supply the token parameter with your request or it will be rejected.
202
The account close request was accepted for processing.
result
boolean
true if the account is closed.
Storage Overview
An overview of how the provider system works and supported providers.
Supported Providers
Fast currently supports 4 major Cloud Storage Providers listed in the table below. All providers share the same common functionality on Fast. You can use multiple providers at the same time but only one provider is allowed per Server.
Dropbox
dropbox
Google Drive
googledrive
Microsoft OneDrive
onedrive
Box
box
MediaFire
mediafire
Pairing Cloud Storage
You can pair all supported Cloud Storage Providers with a single account. Each server may only have one provider however you can have multiple servers for each Provider.
Pairing Not Available in the API
To Pair Cloud Storage Providers, you must visit the website and connect a provider through OAuth.
Server Origin
Your Cloud Storage Provider serves as the backend for your Fast CDN Server. In your Cloud Storage, Fast creates a folder for all your Server origins. When you create a new server, a folder of the same name is created in the chosen Cloud Storage provider. Content in the folder will be made available on the Server.
Changing Providers
You can change the Cloud Storage Provider for a Server after the initial configuration to any paired Cloud Storage Provider. Content will not be transferred between providers by Fast. You must put whatever contents you want into the new provider either before or after changing it over.
Cached contents of a Server will be immediately flushed once a provider is updated.
Permissions
Any special permissions or restrictions you place on files in your Server folder will be ignored and the content will be accessible. Only place contents you wish to be accessible in your Server folder on your Cloud Storage Provider.
Options
Fancy Indexing
You can turn on automatic indexing of your Server contents where Fast automatically generates a list of the contents for easy access. This is enabled by default. If you would like to obscure the contents of your Server, disable this option.
Index Files
If you would like to provide your own index files, you can put default index files in the root of folders. Supported index files names are listed under the Server Object.
Protected Storage
Protected storage providers will only be visible if they are available to you. The protected field in the Storage Object will only be true if the Storage Overview is restricted or protected. In practical terms, this is typically used for pre-release providers and beta users.
Google Apps Files
Google Apps files will be converted to application/pdf when possible and not accessible when a conversion is not possible.
Google Apps Files Auto Updates
Google Rate Limits the rate of automatic updates to Google Apps Files. As such, rapid updates will not be picked up automatically as there is a delay, set by Google, as to how quickly updates can be exported.
Storage Object
This object contains a analytics configuration.
id
int
The id is statically set for this provider, and is not unique to your user.
Yes
name
string
The API name of the Provider which you can use with Server and other API calls.
Yes
display
string
The display name for use in human-readable applications.
Yes
provider_id
mixed
This is the ID provided to us by your Cloud Storage Provider to identify your user.
Yes
email
string
The email address associated with the linked account. This is the address you registered on the Storage Provider with.
Yes
authenticated
boolean
true if the authentication for this Cloud Storage Provider is currently believed to be valid.
Yes
expired
boolean
true if the current credentials are expired.
Yes
enabled
boolean
true if the Storage Provider is enabled for use.
Yes
protected
boolean
true if the Storage Provider is a protected or otherwise restricted provider.
Yes
autoupdate
string
A string indicating the status of auto updates for all servers using this storage provider.
Yes
origin_url
string
A non-server specific url to the cloud storage provider. null if none is available.
Yes
error
error object
If an error is present an Error Object will be returned. Otherwise this field will be null.
Yes
updated
datetime
The date time this object was last updated.
Yes
Email Field
The email field is only available via the Storage Details API call and reflects the current email address, not the email address at the time of registration.
Authentication and Errors
The most common type of issue is a failure to Authenticate with the Cloud Storage Provider. If you remove credentials from Fast, or if our token is invalidated in some other way this field will be false. To resolve you must re-add the provider through the "Add Provider" option on http://go.fast.io/app/.
Do Not Remove to Resolve Errors
Removing a Cloud Storage Provider will flush the cache and disable Servers. If your Server has errors, try re-authenticating through the "Add Provider" option before anything else.
Authenticated and Expired Fields
Accounts may have both authenticated and expired set to true. As long as the credentials are believed to be renewable, authenticated will be true even if expired. Once the storage provider rejects authorization 'token', the authenticated field will become false.
Updated Field
The updated field reflects the last time the storage object was updated. It is automatically set when updates to this provider are made or credentials are renewed.
Auto Update
This field indicates the status of auto-updates for this storage provider. Automatic updates are controlled on a per server basis, but the underlying storage provider must support automatic updates. The following table indicates the possible states.
available
This status indicates that automatic updates are supported and working on this storage provider and ready to use.
unavailable
This status indicates that automatic updates are supported but not currently working on this storage provider. Contact customer service.
unsupported
This status indicates that automatic updates are not supported for this storage provider.
Errors
Only the last error is kept on a storage provider. Re-authenticating a storage provider will clear current errors.
Common Errors
32000
Permanent Cloud Storage Provider Authorization Error. Re-add storage.
32001
Permanent Cloud Storage Provider Authorization Error. Re-add storage.
32002
Temporary Cloud Storage Provider Authorization Error. Re-add storage.
List Storage
Get a list of all storage providers available to the currently authorized account.
200
Storage Providers were found and returned in the storage field.
404
No Storage Providers were found for the current account.
result
boolean
true if the request was satisfied appropriately.
results
integer
The number of results returned in the storage field.
storage
array
Contains a list of storage providers available to the current account. This field may be empty if the results field is 0.
Storage Object
The result is a partial Storage Object, reference it for details on the values.
Connected providers
To get details on which Storage Providers are connected to the current account, query the list of connected Storage Providers via List My Storage.
Connecting a Provider
Connecting a provider must be done through the application website at https://go.fast.io/providers/add/.
List My Storage
Get a list of storage providers linked to the current account.
200
Connected providers were found and returned in the storage field.
404
No connected providers were found.
result
boolean
true if the request was satisfied appropriately.
results
integer
The number of results returned in the storage field.
storage
array
Contains a list of storage providers connected to the current account. This field may be empty if the results field is 0.
Storage Object
The result is a partial Storage Object, reference it for details on the values.
Details
Call the Get Storage API to retrieve details on a given provider. Use the id or name as provided in the storage field.
Connecting a Provider
Connecting a provider must be done through the application website at https://go.fast.io/providers/add/.
Disabled Providers
Disabled Storage Providers cannot be connected to accounts. Storage Providers may show up in connected Storage Providers though if they were connected before the Storage Provider was disabled.
Storage Details
Get details of a Storage Provider linked to the current credentials.
200
The provider was found and the details returned in the storage field.
406
The provider is not linked to your account or you specified an invalid provider.
result
boolean
true if the provider is valid and the details are returned. false if the provider is not valid or not linked to the current credentials.
storage
object
storage object of the requested provider.
Unlink Storage
Disconnect a Storage Provider from your account.
2Factor Verification
If 2Factor Authorization is enabled on this account, you must supply the token parameter with your request or it will be rejected.
202
The request and resource were valid and the delete request has been accepted for processing.
406
The provider was not currently linked to your account and cannot be deleted.
result
boolean
true if the delete request was accepted.
This operation unlinks a Cloud Storage Provider from your account. You can re-link that provider at any time.
The Provider in the URI must be a valid provider listed under the Storage Overview and currently linked to your account.
Unlink Storage
If you have any resources currently utilizing the Provider you wish to unlink, they will disable and the Cache will be flushed opportunistically.
Analytics Providers
A list of supported analytics providers you can integrate with Fast.
Google Analytics
googleanalytics
A Free analytics suite by Google. More Information is available on Googles Website.
Yes
Mixpanel
mixpanel
Mixpanel is a business analytics service and company. More Information is available on Mixpanel's Website.
No
Webhook
webhook
If you want to process analytics yourself, you can get a HTTP callback. Contact us for more details.
No
General Information
General information including fields mappings related to Google Analytics is located in the Analytics section of documents.
Something Missing?
Looking for an analytics provider that isn't listed? Tell us about it! [email protected].
Analytics Object
This object contains a analytics configuration.
name
string
The name used to assign, access, and identify this Analytics Profile.
Yes after creation.
-
provider
string
An identifier indicating the type of Provider this configuration this is for. See Analytics Support for a listing.
No
-
token
string
The reporting token or tracking ID used when reporting data. String length between 3 and 40 characters.
No
-
event_name
string
The event name that file transfers are logged under in the analytics provider. String length between 3 and 30 characters.
No
Download
user_agent
boolean
true if you want to report the user's agent.
No
true
referrer
boolean
true if you want to report the referring URL (if one exists).
No
true
filter_mode
int
Determines the filtering mode for analytics which can be a preset mode or a custom include or exclude regex.
No
0
filter
regex
Regex which includes or excludes transfers from being reported to your Analytics Provider. The default regex matches everything.
No
null
filter_mode_country
int
Determines the filtering mode for analytics which can be a preset mode or a custom include or exclude regex.
No
0
filter_country
regex
Regex which includes or excludes transfers from being reported to your Analytics Provider. The default regex matches everything.
No
null
provider_url
string
The URL to the provider which may or may not point to a specific profile.
Yes
-
updated
datetime
The date time this object was last updated.
Yes
-
Fancy Indexing
Fancy Indexing requests are never reported to your Analytics Provider.
Token/Tracking ID Provacy
Tokens and Tracking ID's stored in this object are never presented to the public. You can provide private ID's.
Updated Field
The updated field reflects the last time the analytics configuration was updated. It is automatically set when updates to this provider are made.
Name
Names used in Analytics Profiles only need be unique in the account namespace.
Analytics Filters
Analytics Filters allow you to prevent request spamming to your Analytics Provider for content not relevant to your application. For example, if you are serving a static web page, you may only want to report the HTML request and NOT image, CSS, or Javascript requests. Alternatively, if you were serving a software package, you may want to exclude all HTML and Images.
There are pre-defined modes you can choose or set custom include or exclude REGEX string. The available modes are detailed below. 0 is the default mode.
Filtering can be done based on the URL or the Country Code.
Filter and Filter Country
filter_mode and filter are used for URL filtering. This parses the regex based on the full request URL, including protocol and FQDN.
filter_mode_country and filter_country are used for client origin filtering. This filter applies the filter_country to the ISO country code of the client connection.
0
Everything
Nothing
The default filter includes all requests and excludes no requests.
1
Include Regex
Nothing
Includes only content that matches the filter fields regex.
2
Nothing
Exclude Regex
Excludes only content that matches the filter fields regex.
Include and Exclude Filters
When the filter_mode is set to include or exclude, only content matching/missing the filter will be sent to the analytics provider.
For example, if your filter finds entries ending in .jpg and your filter is set to include, any requests ending in .jpg will be transmitted. All other requests will be excluded.
Consequently, if you use an exclude filter, only entries matching the filter will be excluded, all other entries will be included.
Filters
Filters can be an effective tool to eliminate noise either by only including the data you want or by excluding the noise itself. Regular expressions are powerful tools that can be written to exclude or include many types of files or URL's). The regex is applied to the full request URL including protocol.
Regular Expressions Format
For compatibility information on constructing your REGEX, please see the PCRE reference documentation at http://www.pcre.org/pcre.txt and the Perl reference at http://perldoc.perl.org/perlre.html.
Invalid REGEX may result in a 406 Not Acceptable response. Invalid REGEX may also result in unintended inclusions or exclusions of analytics events.
Regex Examples
The goal of this regex is to either match data in the request so regex should be written with matching in mind which can be applied to either include or exclude the content.
All regex must start and end with a forward slash. Case insensitive, i, is the only supported modifier at this time.
Regular expressions support Unicode.
Examples:
/foo/
Any requests with the string foo in them.
/^foo/
Any requests that start with the string foo.
/foo$/
Any requests that end with the string foo. For example, to match entries ending in HTML: `/\.html$/.
/[abc]/
Any request that includes the characters a, b, or c.
/([A-Z]{3}|[0-9]{4})/
Any request that matches either three A-Z letters or four 0-9 numbers. For example, to match entries ending in HTML or JPG: /(\.html)|(\.jpg)/i.
List Providers
This endpoint gets a list of the available analytics providers.
Provider List
The Provider list is of all available providers, not of configured providers. GET the individual providers to see if they are configured or not.
200
The request and resource are valid and the provider list is returned in the body.
result
boolean
true if Provider details are returned.
results
integer
Indicates the number of providers returned in the providers array.
providers
array of strings
This is an array of strings containing the list of available Providers.
Empty Result
If no providers are available, the results field is set to 0 and providers field is set to null.
Validate Filter
This endpoint validates a filter to be used with an analytics profile.
Create Profile
This endpoint adds a provider to the current user account.
202
The request and resource are valid and the analytics Provider was added to the user account.
result
boolean
true if Provider was added to the account.
id
string
The id of the newly created Analytics Profile which can be assigned to Servers, updated or deleted.
Profile Details
This endpoint gets the details for a provided Analytics profile for the provided credentials.
200
The request and resource are valid and the profile details are returned in the body.
result
boolean
true if Analytics Profile list is returned. true even if the results is set to 0.
List Profiles
This endpoint gets a list of all analytics profiles associated with the provided credentials.
Sort
By default, the Analytics profile list is sorted by name in an ascending (ASC) order. No alternative sorting is supported.
Result Codes
200
The request and resource are valid and the profile list is returned in the body.
result
boolean
true if Analytics Profile list is returned. true even if the results is set to 0.
profiles
array
An array of Analytics Objects that exist in the account. See below for detail on returned fields.
Empty Array
If no Analytics Profiles are found, results will be set to 0 and analytics will be set to null.
Maximum Results
This version of the API never allows for more than 100 results from this resource.
Update Profile
This endpoint updates the details of an analytics Provider configuration.
Token Required
The analytics configuration cannot be enabled if the token field has not been previously populated or is provided in the same request.
Rename Unsupported
This version of the API does not support profile renaming, do not include the name field in your POST body.
202
The Analytics Profile configuration was accepted for an update.
result
boolean
true if the Analytics Profile configuration was updated.
Delete Profile
This endpoint gets the details of an analytics Provider configuration.
200
The request and resource are valid and the analytics provider configuration has been deleted.
404
The provided Analytics Profile was not found or was already deleted.
409
The Analytics Profile was already in use. You must remove it from active Servers before deleting the profile.
result
boolean
true if the profile was deleted.
CDN Overview
An overview of Content Delivery Networks and how they work.
Introduction
Content Delivery Networks are networks of servers that deliver the content in the last mile. They are located globally and attempt to deliver the content to end users as quickly as possible. Fast has support for multiple CDN's which have different performance levels and price points. You can only use one CDN per Server but you can use different CDNs for different Servers.
Supported CDN
The list of available CDN's is below. The Default CDN Provider is auto.
Akamai
akamai
Akamai Global Network utilizing thousands of global points of presence.
1
List CDNs
Get a list of all CDN providers available to the currently authorized account.
200
CDN Providers were found and returned in the storage field.
404
No CDN Providers were found for the current account.
result
boolean
true if the request was satisfied appropriately.
results
integer
The number of results returned in the CDN field.
CDN
array
Contains a list of CDN providers available to the current account. This field may be empty if the results field is 0.
CDN Details
This endpoint gets the details of a single CDN available to the provided credentials.
Server Overview
An overview of Servers and how they work.
Introduction
Each Server configured uses a Cloud Storage backend, a CDN to distribute the data, and an Analytics Provider to collect and analyze analytics data.
The Cloud Storage Provider and the Analytics Providers are configured separately from configuring the Server. The Cloud Storage Provider is required when creating the server, but the Analytics Providers may be set at any time, or not at all.
Server Names
Server names are unique in a global namespace, cannot be changed once created, and cannot be reused if you delete a server. This is done to ensure that names are not reused and traffic for a previous user transferred to a new user. It also allows us to keep accurate analytics for you even after a Server is deleted.
Server names are also used as unique subdomains to access your content. Currently, only Latin Character domains are supported with the characters A through Z and the numbers 0 through 9. Additionally, dashes, and underscores, are also supported. All domains are case insensitive.
Server names cannot have more than 4 dashes or underscores (special characters). Special characters cannot be next to each other and your name cannot start or end with a special character.
Each server is assigned a domain name. This API supports domain names but not the ability to set or change them. As such, domains are typically optional.
Future Domain Support
Future versions of this API will fully support the ability to select and change domain names. In this version of the API, you can include or omit the domain name with each request except for Server Create or Update.
Renaming Servers
Servers cannot be renamed after creation in this version of the API.
Deleted Servers
Once a Server is deleted it cannot be restored. Additionally, the name of the server cannot be reused in this version of the API. Do not casually delete Servers.
Supported CDN
CDN stands for Content Distribution Network and is a global collection of Servers designed to deliver content as quickly as possible to end users. Fast utilizes CDN servers to ensure as Fast of delivery as possible.
The list of available CDN's for a users account is available through the List CDNs API.
International Domain Name Support
This version of the API does not support UTF-8 domain and server names. Do you need support for this? Let Us Know!
Maxium Number of Servers
You may only have a maximum of 128 Servers. Deleted Servers do not count against your active count.
Pre Caching and Automatic Updates
Automatic Updates read changes from your storage provider and automatically flush cached data from the CDN. Pre-caching moves data from your storage provider to the CDN cache ahead of any user requests. Pre-caching and automatic updates can be stacked so data is flushed as soon as its updated and re-cached automatically.
If automatic updates are enabled, you must manually flush data when an update is made to cached data.
If pre-caching is disabled, caching of data happens on demand of end-users which may slow the initial request.
Pre Caching Transfer Fees
Normal costs and fees apply to data transfer under pre-caching. These transfers will show up under your account usage as a normal transfer. If you're storing large amounts of data, charges will apply. We make best efforts to only pre-cache data that is changed, and a pre-cache request for data that was already pre-cached usually results in no or minimal additional usage charges.
Pre Caching Analytics
No transfers from pre-caching events will show up in your analytics reports. They will, however, show up in your usage/billing reports.
Server Object
This object contains is used for server details.
name
string
The name of the server. Strings between 3 and 50 characters are valid. Names are converted to lower case.
Yes
-
domain
string
The domain name associated with this server. Strings between 3 and 30 characters are valid. Names are converted to lower case.
Yes
imfast.io
server
string
The fqdn which is the name and the domain of the server.
Yes
-
storage
string
The Cloud Storage Provider name to serve as the backend for this Server.
No
-
analytics
string
The analytics profile to assign to this server.
No
-
cdn
string
name of the CDN Provider to use for this server.
No
-
enabled
boolean
true if the Server is enabled for production traffic.
No
false
error
error object
An error object containing the current Server error or null if no error exists.
Yes
null
error_url
string
A url to be used for requests to your server that result in an error.
No
null
locked
boolean
true if the server is locked and will not accept any further operations.
Yes
false
fancyindexing
boolean
true enables fancy indexing when a request is made for a directory without an indexfiles or if indexfiles are disabled.
No
false
indexfiles
boolean
true to look for a file to return when a directory request is made.
No
false
autoupdate
boolean
true if automatic updates are enabled for this server.
No
true
precache
boolean
true if pre-caching of your cloud storage to the CDN is enabled.
No
true
precachedata
boolean
true if pre-caching will transfer data as well as metadata.
No
true
search
boolean
true to allow search engines to index content and pages.
No
true
expires
int
The time, in seconds, for browsers to cache content.
No
43200
deleted
boolean
true if the Server has been previously deleted.
Yes
null
updated
datetime
The date and time the Server was last updated. This is always populated by the API.
Yes
-
created
datetime
The date and time the Server was created. This is always populated by the API.
Yes
-
Server Name Valid Characters
The only characters that are valid for a Server name are a-z, 0-9, _, and -. Names are not case-sensitive.
Names must start and end with a-z or 0-9
Locked Accounts
Server requests to locked, suspended, or disabled accounts will result in 423 Locked responses.
Domain
The domain field is static in this version of the API.
Cloud Storage Provider
A Folder matching the name of the Server will be created on the corresponding Cloud Storage Provider in the Fast Application folder. If one already exists, it will be used.
Precaching
The precaching options are provided to ensure your CDN responds as quickly as possible. If pre-caching is disabled, requests will be cached on demand which will cause the initial request to be slower, but all subsequent requests will be quick.
We offer two different options for pre-caching, metadata only, and metadata and data. The metadata pre-caching stores all data except the actual file, such as file names, folder lists, etc. If you enable precaching with data, all the metadata is cached and the physical data is cached to the edge. This ensures the first request to your CDN is as fast as every subsequent request. As such, normal usage and transfer rates apply, and these transfers will show up in your account usage.
The option precachedata is only applied if precache is enabled, so if you do not enable precache, no pre-caching actions will be taken regardless of the state of precachedata.
See the API for Pre Cache for more information on how pre-caching works.
AutoUpdating
Auto-updating automatically watches the underlying cloud storage provider for changes. When content is changed, all relevant content is flushed so your Server stays in sync with your underlying cloud storage.
This option can be stacked with pre-caching which results in Fast automatically recognizing changes, flushing out changed content, and re-caching it.
See the API for Flushing for more information on how flushing works.
Expires
The expires time is relayed to the end user's browser indicating how long, in seconds, they should cache this content for before revalidating it. Set this to a lower value to ensure end users revalidate content more often or a high value to cache for long periods of time. The valid range of expires times is 60 seconds to 30 days. Always submit expires time in seconds.
Frequent Updates
If you make frequent updates you should set this value to a lower value. Modern web-browsers will revalidate content before re-requesting it which will limit usage fees if the content has not changed.
Search
When search is true, requests to the Server will return the X-Robots-Tag header will be returned with all, and if it's disabled, the X-Robots-Tag header will be returned with noindex, nofollow.
Errors
If the Server currently has an error, the error field will be populated with an Error Object. If no error exists, the error field will be null.
Authentication Errors
The most common type of error is a storage authentication error which occurs when we lose access to your cloud storage provider. See Storage Object for more details.
Multiple Errors
In the event there are multiple errors present, only one error object will be returned and it will be the most serious error. If that error is resolved, the next error, by priority, is returned.
Common Errors
Below is a table of the most common errors you might encounter:
24000
Unable to contact Cloud Storage Provider. Check status page.
24003
Server/CDN has been locked. Contact Support.
Provider Error Codes
In the event, and the underlying platform has an issue, such as the cloud storage provider, or the analytics provider, those errors will be returned. Please reference those objects for error details.
FancyIndexing
Set if you want to allow the server to automatically create index files of content (if IndexFiles files are disabled or missing).
If IndexFiles are enabled and FancyIndexing is enabled, the index file will be rendered.
true
IndexFiles
Looks for index files at a given path which are returned when the folder is accessed directly without a filename.
true
AutoUpdate
Automatically reads changes made to your cloud storage and updates your CDN.
true
Precache
Automatically pre-caches metadata from you cloud storage to your CDN before any end user request.
false
PrecacheData
Pre-caches both metadata and actual data. Warning: Normal usage/transfer rates apply.
false
Search
Returns an HTTP header with requests from your server indicating Search Indexing is allowed or disallowed.
false
Fancy Indexing
Fancy Indexing only has one style by default currently and cannot be customized. Let us know if you want something else by emailing us at [email protected].
Index Files
1
index.html
2
index.htm
3
default.html
4
default.htm
Requests to Disabled Servers
Requests made to a disabled server will be redirected to a Fast.io 403 Forbidden Page.
Error URL
Error URL's are not supported in v1.0 of this API, you may set the value, but it will not be utilized. If a value is set, future versions may use this value without notice.
Check Server Name
This endpoint checks to see if a Server name is valid and available.
Fully Qualified Domain Names are Unique
Server server, usually represented in the server field, are unique in the global namespace. Server names cannot be reused, even if a Server is deleted, and names cannot be changed. A false result indicates the name is in use, previously used, or reserved.
202
The fqdn is valid and is acceptable.
406
The fqdn is not valid, reserved, in use, or otherwise not acceptable.
result
boolean
true if the fqdn is valid and available.
Create Server
This endpoint updates the details of a Server.
200
The request was valid and the Server was created.
result
boolean
true if the Server was created.
Flags
The options field uses flags for each option as listed on the Server Object page. Set each bit for each option you want. Set to 0 to disable all options.
Server Name
The Server name is always lower case, any input is converted to lower case.
Domain Not Supported
This version of the API does not support configuration of a custom domain name. You can submit it but it will be ignored. The domain field is forced to imfast.io.
List Servers
This endpoint gets a list and configuration of all Servers associated with the provided credentials.
Sort
By default, the Server list is sorted by name in an ascending (ASC) order. name is the only sortable field.
Flags
Provide the nodeleted flag in the query string to avoid returning servers that have a deleted value not equal to null.
Result Codes
200
The request and resource are valid and the server list is returned in the body.
result
boolean
true if Server list is returned. true even if the results is set to 0.
servers
array
An array of server objects that exist in the account. See below for detail on returned fields.
Deleted Servers in List
Once a Server is deleted, it will continue to appear in your list of Servers. The deleted field will no longer be null and no more operations are allowed.
Deleted Servers Count
Deleted Servers in this API still count against the maximum number of Servers an account may have. There is no way to permanently remove a Server configuration.
Empty Array
If no servers are found, results will be set to 0 and servers will be set to null.
Maximum Results
This version of the API never allows for more than 100 results from this resource.
Server Details
This endpoint gets the configuration of a single Server associated with the provided credentials.
Update Server
This endpoint updates the configuration of a Server.
200
The request and resource are valid and the request was completed.
result
boolean
true if Server is updated.
Flush Cache
When Server updates change the Storage Provider, the cache will be automatically flushed for the entire Server. If you have pre-caching with data enabled, all data will be flushed and reached. Normal usage fees will apply.
Enabled Toggle
If you disable an active server, the CDN cache will be flushed and all future requests to that Server will result in a 405 Disabled response.
Disable All Servers
This endpoint disables all Servers in the current users account.
2Factor Verification
If 2Factor Authorization is enabled on this account, you must supply the token parameter with your request or it will be rejected.
200
The request and resource were valid and at least some servers have been disabled.
result
boolean
true if at least one Server is in account is disabled.
Delete Server
This endpoint deletes a Server and all its contents.
2Factor Verification
If 2Factor Authorization is enabled on this account, you must supply the token parameter with your request or it will be rejected.
200
The request and resource were valid and have been deleted.
result
boolean
true if the Server is deleted.
Deletes are Final
Delete operations are permanent and immediate. They cannot be reversed. The file and folder contents of a deleted server are flushed immediately as well. Server Names cannot be reused.
We Never Delete Data
Data is never deleted from your Cloud Storage Provider, if you delete a server, the contents in your Provider will be unchanged. If you want to delete that content, you will need to delete it yourself.
Folder Object
This object contains a single folders details.
Fixed Fields
This object is used to describe Folders used in all API calls that interact with Folders.
name
string
The name of the Folder. Strings between 1 and 50 characters are valid.
Yes
path
string
The path to the Folder on the cloud Storage Provider.
Yes
id
string
The id of the folder as specified by the cloud Storage Provider.
Yes
url
string
A public URL that can be used to access this folder.
Yes
origin_url
string
A private URL that can be used to access the origin on the cloud of this folder object.
Yes
modified
datetime
The date and time the Folder was created or last updated depending on the provider.
Yes
cached
datetime
The date and time the Folder metadata being returned was cached at.
Yes
Folder URL
The folder URL will be provided even if indexing is not turned on, as such a user may get an error accessing this URL. Check server configuration before utilizing.
Root Request
When you request the root of your server /, the name will be a null value and the path will be /.
Path
The path is relative to the Fast application root which varies from Storage Provider.
Origin URL Permissions
The origin_url is only accessible by a permissioned user of the Cloud Storage Provider. This URL does not provide any new access or public access, just a quick reference link for modifying, adding, or removing content from it.
Cached Responses
If metadata is not cached or cache metadata is not available, the cached_at field may return null. You should treat null responses as unknown, not as uncached.
Its also notable that in a Folder List response, a folder may have a cache time that differs from the equivalent Path Details response.
File Object
This object contains single files details.
name
string
The name of the File. Strings between 1 and 150 characters are valid.
size
unsigned integer
The size of the File. This value defaults to 0.
state
string
The current state of the file. See table below for details.
mime
string
The mime type of the file determined by the API. This is a string from 5 to 30 characters in length.
category
int
The category based on mime that we believe this file to be.
url
string
A public URL that can be used to access and download this file.
origin_url
string
A private URL that can be used to access the origin on the cloud of this file object.
modified
datetime
The date and time the File was created or updated as determined by the Cloud Storage Provider.
cached
datetime
The date and time the File metadata being returned was cached at.
URL based on Server
The url is a combination of the Server name and the path. The url includes the relative path from the Server root. If the file or folder is moved, or the Server is deleted or disabled, the URL will cease to work.
Origin URL Permissions
The origin_url is only accessible by a permissioned user of the Cloud Storage Provider. This URL does not provide any new access or public access, just a quick reference link for modifying, adding, or removing content from it.
Null Fields
A number of fields are set to null depending on what is provided by the Cloud Storage Provider including:
mimecategorymodifiedcached_at
Mime Types & Category
Mime Types are based on the name of the file and not by the content. Content that is named incorrectly will show the incorrect mime type.
Cached Responses
If metadata is not cached or cache metadata is not available, the cached_at field may return null. You should treat null responses as unknown, not as uncached.
It's also notable that in a Folder List response may have File Object's with a cache time that differs from the equivalent Path Details response for that File Object.
States
ready
Indicates the file is ready and in a normal state.
locked
Indicates the file has been locked by our systems. Contact customer service.
1
Unknown Binary
2
Text
3
Image
4
Document
5
Archive
6
Executable
8
Video
9
CSS
10
Audio
11
HTML
12
Javascript
Path Details
This endpoint gets a single File or Folder details at the specified path and associated with the provided credentials.
General
A valid path must start with a / and be the absolute path on the Server.
If no path is supplied, but a name is, the request will be processed as a Server Details request instead.
Results only include folders at the exact path specified, you will need to walk the tree to get sub-folders.
Result Codes
200
The request and resource are valid and the Folder details is returned in the body.
406
Errors including Storage Object authorization errors. Check the error object for code 10097.
result
boolean
true if path was found.
server
string
The fqdn of the server, which is the name and the domain.
type
string
Either file or folder depending on which object is provided in details.
details
folder object or File Object object
A folder object if the path is a folder or a File Object object if the path is a file.
details and type fields will be omitted if the result is false.
Root Directory
To get details on the root Folder, set the path to /.
Files and Folders
Both a folder and file node are included but the result will be either a folder or a file object based on the path. The unused node will be null.
Folder List
This endpoint gets a list of all files and folders at the specified path and associated with the provided credentials.
200
The request and resource are valid and the Folder list is returned in the body.
404
The requested Server name was not found or the Folder path does not exist, is not accessible, or is not a folder.
406
Errors including Storage Object authorization errors. Check the error object for code 10097.
result
boolean
true if path was found.
server
string
The fqdn of the server, which is the name and the domain.
path
string
The path of the folder which the list corresponds to.
Results only include files and folders at the exact path specified, you will need to walk the tree to get sub-folders contents.
File Object and Folder Object objects include an additional field in the list result of type which can be either file or folder depending on the type of object set.
Sorting
The list is sorted by name in an ascending (ASC) order.
Empty Array
If no objects are found, results will be set to 0 and list will be empty.
Maximum Results
This version of the API is limited to 1000 results per request to this resource.
Root Directory
For a listing of objects in the root directory, the path should be set to /.
Usage Statistics
General information on usage statistics API's.
General
Usage statistics are a way to understand costs associated with the account. Analytics should be done through Analytics Object API's.
Logs are delayed anywhere from 5 hours to 24 hours. Analytics reported to 3rd party providers will be available before usage statistics are updated.
The stats API's will automatically calculate the interval in hourly increments based on the period provided. We always attempt to give you 30 results. This value may not always be divisible by hours, and as such, you may get slightly more or less than 30 results.
Requested periods will be rounded to the nearest hours.
Recent stats cover a period of 15 hours in 30-minute increments.
Valid Timeframes
You can request usage timeframes up to 1 year and go back as far as 3 years.
Transfers Object
The transfers object is returned by stats API's to indicate the volume (bytes) and instances (transfers) that occurred during the period (between the start and end times). These stats include any data accumulated due to Pre Cache settings.
Fixed Fields
This object is read-only.
bytes
unsigned integer
The number of bytes transferred or null if no transfers occurred.
transfers
unsigned integer
The number of transfers, including partial or multipart transfers.
Transfer Count
Any HTTP transfer on a file will result in an increment of this transfers field. If a user does a multi-part transfer where they simultaneously download chunks of a file for performance, each part will be counted. Each HTTP or HTTPs connection will count as a transfer.
Reporting to analytics can have transferred from the same user aggregated.
start
date
The start of the date range for bytes and transfers reporting.
end
date
The end of the date range for bytes and transfers reporting.
Account Stats
This endpoint gets the transfer statistics for the current account for a given period.
200
The request and resource are valid and the user stats are returned in the body.
result
boolean
true if user stats were returned.
interval
unsigned int
The interval in seconds that splits the start and end datetime's.
transfers
This transfer stats for the requested timeframe if the request result was true.
Account Stats Recent
This endpoint gets the recent stats for the past 15 hours for your entire account.
Non-Authorative Results
Results may change from in Recent stats as more data is aggregated. Do not use stats provided by this API as authoritative or for billing purposes.
200
The request and resource are valid and Transfers Object's are returned.
result
boolean
true if transfers are returned.
interval
unsigned integer
The time in seconds each transfer object covers.
Rate Limit
Because of the cost of this resource, calls are rate limited.
Server Stats
This endpoint gets the transfer statistics for a server for a given period.
200
The request and resource are valid and the user stats are returned in the body.
result
boolean
true if user stats were returned.
server
string
The Server name and domain in FQDN format the returned statistics are for.
interval
unsigned int
The interval in seconds that splits the start and end datetime's.
transfers
This transfer stats for the requested timeframe if the request result was true.
Server Stats Recent
This endpoint gets the recent stats for the past 15 hours for a particular Server.
Non-Authorative Results
Results may change from in Recent stats as more data is aggregated. Do not use stats provided by this API as authoritative or for billing purposes.
200
The request and resource are valid and Transfers Object's are returned.
result
boolean
true if transfers are returned.
server
string
The Server name and domain in FQDN format the returned statistics are for.
interval
unsigned integer
The time in seconds each transfer object covers.
Rate Limit
Because of the cost of this resource, calls are rate limited.
Log Record Object
This object contains a transfer log records.
Fixed Fields
A corresponding object is created and stored for each transfer from your account. All records are read-only and permanent. Older records may be archived offline but are never flushed.
entry_id
string
A permanent unique id string to describe this entry. Strings is 15 characters in length.
domain
string
The domain name associated with the server.
server
string
The fqdn which is the name and the domain of the server.
client_uuid
string | null
A string assigned to each downloader to uniquely identify them. String length is between 5 and 35 characters. null on empty.
client_referer
string | null
The HTTP referer provided by the client for the request.
Strings range from 3 to 384 characters. null on empty.
client_user_agent
string | null
The HTTP User Agent provided by the client for the request. Strings range from 1 to 64 characters. null on empty.
client_ip
string | null
The IP Address of the client. Strings range between 7 and 45 characters may be returned.
client_country
string | null
The ISO country code of client at the time of the request.
request_path
string
The URI that was requested. Strings range from 10 to 1024 characters.
request_method
string
The method of the transfer. The only supported method in this version of the API is GET.
request_secure
boolean
true if the request was done over an encrypted connection.
transfer_code
integer
The HTTP status code returned to the user.
transfer_result
boolean
true if the requested transfer was completed successfully.
transfer_size_total
integer
The size in bytes of the entire transfer which includes headers and the content returned.
transfer_size
integer
The size in bytes of the content requested and returned.
transfer_start
datetime
The time the transfer started.
transfer_seconds
integer | null
The elapsed time of the transfer. null if the time is not available. Time is in milliseconds.
request_url
string
The complete URL of the request.
UUID
The uuid is automatically assigned to each unique user so you can track transfers by multiple users.
Country Code
Country codes are in ISO-3166-1 format and are determined at the time of the transfer. IP blocks and country codes for IP's may switch over time, so the supplied country code may be more accurate than using a secondary database after time has elapsed.
Logs Retrieve
This endpoint gets the account logs for a time range for a particular Server.
The start and end times are in datetime format. date format is also accepted for ease of use. limit and offset fields are both supported for this resource for chunked transfers.
The end datetime must always be later than the start datetime. If the end date is not specified, the current datetime is used.
There must be at least five (5) minutes between the start and the end time.
Result Codes
200
The request and resource are valid and the log records are returned in the body.
Record Availability
Records are only available for no more than 90 days after the creation date. To access older records, contact customer service.
404 Response
The 404 response will only indicate theserver is not found. If no log records are found in the time period, a 200 will be returned, the records list will be null and the result will be false.
Response Formats
This API supports responses in multiple formats. The default format is a standard API JSON response.
json
A standard API response including the log data in JSON format.
csv
A comma-separated log format as a file attachment that includes the fields in the Log Record Object in a comma-separated log.
CSV Response
The CSV Response will include a content-disposition header incidcating an attachment, this file should be saved for offline processing.
No JSON is returned with CSV results, if no rows are found, an empty CSV will be returned.
Result JSON
Results for records are ordered in ascending time from the start date.
result
boolean
true if logs are returned.
Log Limits
Each response format has specific limits for the number of records it may return. If your logs exceed this amount, additional records will be truncated. We suggest using an appropriate datetime window based on the expected size of your data-set. Be cognizant of the Rate Limit restrictions on this API.
JSON
In a given response, the number of response records will not exceed 10,000 records.
CSV
In a given response, the number of response records will not exceed 1,000,000 records.
Rate Limit
Because of the cost of this resource, calls are rate limited.
Data Retention
For specific details regarding data retention, please see our privacy policy.
Cache Management
General Information about how caching, changes are collecting, how/when flushing occurs, and pre-caching works.
The caching API's and functionality are designed to ensure that data stored in your storage cloud are available at the CDN and up to date. There are a wide variety of possible configurations and interactions. As such, this overview focuses only on the core concepts.
Changes
Changes are received from the Cloud Storage providers which allow us to determine if the contents of your CDN has changed. We collect changes while activity is happening before processing them. We may collect changes for an extended period of time if you're making many changes at once. Alternatively, you can manually flush and precache changes if you don't want to wait for us to finish collecting changes automatically.
Once changes are collected, flushing and pre-caching occur as configured.
Flushing
Flushing allows you to delete or "flush" the cache at a given path. That path may be a file or a folder, and it affects all children. In other words, if you flush /, everything on the server will be flushed from the cache.
Flush History is only tracked for the actual object flushed, so if you flush /, the history for any children of / will not reflect when / was flushed. If you want to determine when data was last cached, look at the cached_at field of the File Object or Folder Object.
Flushes are immediately completed in the API at the time of the request, however, may take up to 30 seconds to be visible at the CDN.
If you have pre-caching enabled, flushing a path will generate a pre-caching operation for that path.
PreCaching
Precaching replicates data from your cloud storage to the CDN edge to ensure the first request is as quick as every subsequent request. There are two basic modes for pre-caching, with or without data. If you pre-cache with data, files will be cached to the CDN edge. If you pre-cache without data, only metadata will be cached to the CDN edge.
History
Precache history is kept for 24-hours from the last update of a given Server.
Fees
Standard usage fees apply to pre-caching data.
Limits
Preaching, in this version of the API, will only allow 500 folders and 2,000 files to be preached in a single job. If you have more data that needs to be pre-cached, perform sequential smaller jobs.
Concurrency
Only one pre-cache operation on a Server configuration may be performed at once. If a superseding operation is made, the superseded operation will be canceled and replaced. You can follow the chain of how jobs are replaced by following the preempt field of the Pre Cache Object.
Concurrent Escalation
In the event that there is a conflict between operations, the lowest common path will be used as the pre-cache root. This may cause the entire server to be pre-cached if two different folders in the root of a Server attempt to run concurrent pre-cache jobs.
Automatic Updates
Automatic Updates are triggered when your underlying cloud storage contents are changed. The effect of Automatic Updates is to generate a flush on the changed object set. The flush itself may generate a pre-cache operation.
Precache Size
Precache is limited to 2GiB of data in any given operation. Any data transfers are limited to the first 250MB of data. Please contact us if this poses a problem for you.
Best Efforts
When Pre-caching with data, we make our best effort to not pre-cache data that is already cached and valid. Typically this results in no usage charges when data is already pre-cached.
Changes Object
An object containing job information of pending / recent changes that have been received.
This object is used to indicate changes that are being received from a storage provider but have not yet been processed. There is a variable delay in processing based on the cadence of changes to avoid thrashing.
Completed/Stale Jobs TTL
Once jobs are stale or completed, they are kept for up to 1 day after which they are flushed out. Only one job per server configuration is kept. New jobs will over-write previous completed or stale jobs.
name
string
The name of the server configuration this job applies to.
domain
string
The domain this configuration is assigned to.
server
string
The fqdn which is the name and the domain of the server.
waited
int
The amount of time in seconds that we have been waiting for changes to come in.
remaining
int
The estimated time in seconds remaining before these changes are processed.
extensions
int
The number of times the remaining time has been extended.
changes
array of strings
An array of strings of content paths that have recently changed.
complete
bool
Indicates if the changes have finished being received and have been sent for processing.
stale
bool
Indicates if the change processing has gone stale and should be manually processed by the user.
started
datetime
The date and time when the changes started being processed.
last
datetime
The date and time when the last change was received.
updated
datetime
The date and time when the status were last updated which should be at about 1-2 second intervals until a job is completed.
Stale Jobs
Stale jobs may happen from time to time. The next change received will pick up the stale job however if you want the changes to process immediately, call the related Cache Management API's manually.
Remaining Time Changes
When rendering current status for pending changes, note that the remaining time is subject to extensions if the platform determines we should wait long for more changes to settle.
Waiting
FALSE
FALSE
We are waiting for additional changes to be received before processing.
Processed
TRUE
FALSE
We have received all changes and have processed them.
Stale
FALSE
TRUE
We received changes however we stopped waiting before processing them. You may want to process them manually or wait for additional changes.
Changes List
This endpoint provides a list of all known changes status.
Only one status job is returned per server configuration when available. If a new set of changes are received, they will over-write the previous changes.
Result Codes
200
The request and resource are valid and the status is returned in the changes node.
result
boolean
true if the request was valid.
results
int
The number of Server Names returned in changes.
changes
array
An array of Server names and Domains that have changes for the current credentials.
Changes Status
This endpoint provides the full status of all known Change statuses.
200
The request and resource are valid and the status is returned in the changes node.
result
boolean
true if the request was valid.
results
int
The number of changes objects returned in changes.
changes
array of Changes Object's
An array of Changes Object's associated with the account credentials.
Changes Status Server
This endpoint provides details on a Changes Status for a given Server.
200
true if the request was valid and processed.
404
No changes were found for the provided credentials.
result
boolean
true if the status was found and returned.
Rate Limited API
This API is rate limited and may result in a 429 response if you call it too frequently.
Changes Run Stale
This endpoint processes Changes received but not processed automatically, yet.
202
true if the request was valid, the server was found with stale changes, and the request was accepted.
404
No changes were found for the provided server.
423
The changes were found but the changes are not stale and cannot be manually processed.
Only On Stale
You cannot call this API on non-stale Changes jobs. Changes jobs may become active at any moment so you must handle 423 errors when implementing this API.
result
boolean
true if the status was stale and the job completed manually.
Rate Limited API
This API is rate limited and may result in a 429 response if you call it too frequently.
Flush Object
Lookup the last time a path was flushed on a Server.
server
string
The fqdn which is the name and the domain of the server.
path
string
The path that was flushed on the server.
flushed
datetime
The date and time the path on the server was last flushed.
Flush Cache
Flushes the cache for a Server or part of a Server
202
The request and resource are valid and the request was accepted but will be completed asynchronously.
429
Too many requests were made in too short a period of time.
result
boolean
true if the flush request was accepted and will be processed.
Flush Request
Flush requests are processed asynchronously. The actual flush time may vary from CDN to CDN but generally, flush requests are completed within 1 minute, and usually, much faster.
Cache Flush is Recursive
When you specify a path, all contents under the path, if any, are also flushed. To flush the entire server, specify the root path /.
Cloud Storage
When contents in the cloud storage change and the provider supports notifications, contents are automatically flushed as needed.
Rate Limited API
This API is rate limited and may result in a 429 response if you call it too frequently.
Flush Lookup
Lookup the last time a path was flushed on a Server.
200
The request was valid and the last time this path was flushed is returned.
result
boolean
true if the flush lookup time was provided.
Flush Lookup is Exact Path
The flush time of the path is specifically for the provided path, not for any parents or children.
Flush History
Get the Flush history of paths on a Server.
200
The request was valid and the last time this path was flushed is returned.
result
boolean
true if the flush lookup time was provided.
Pre Cache Object
An object containing job information of pre-cache instances currently active and recently completed.
key
string
A 5-char alphanumeric identifier for a unique job. Keys are case sensitive.
name
string
The name of the server configuration this job applies to.
domain
string
The domain this configuration is assigned to.
server
string
The fqdn which is the name and the domain of the server.
status
string
The current status of the job. See table below.
path
array of strings and depths
An array of strings and depths to be completed by this pre-cache job. Each job will be completed in order.
path_curr
string
The current path being processed which will differ from the path when the path is a folder with children. In effect this indicates the progress of the job. This value will be null when at the start and end of the job and only contain a value when a path is being actively processed.
data
boolean
true if the data is being preached, false if only the metadata is preached.
flush
boolean
true if a flush proceeded this pre-cache job.
event
boolean
true if an event will be sent to the user when this job is completed.
preempts
integer
The number of jobs this job has pre-empted during its run. It is also the sum of previous jobs. 0 indicates no jobs were pre-empted.
preempt
string
The key of the job that was previously pre-empted. You can query that key to create a chain of preempt events.
files
integer
The number of files processed. This will increment during the runtime of the job as files are processed.
folders
integer
The number of folders processed. This will increment during the runtime of the job as folders are processed.
bytes
integer
The number of bytes transferred to pre-cache data which will count towards your service usage. If data is false this field will be 0.
stale
bool
true when a pre-cache job has failed in a catastrophic way. Restart the pre-cache job manually.
started
datetime
The date and time when the job started being processed, or, if another job was pre-empted, the time the original job was started.
updated
datetime
The date and time when the job status was last updated. This usually occurs at about a ~1 second cadence.
ended
datetime
The date and time when the job was completed. This field is null if the job is not completed.
auth error
There has been an authorization error during the job run and it was canceled and failed. Retry the job.
limit reached
A job limit was reached, the job was too large and cannot be processed in full. Try smaller jobs.
network error
A network error was encountered and the job could not be completed. Retry the job.
preempted
This job was pre-empted by another job.
canceled
The job was canceled. No more updates will occur.
completed
The job has completed successfully, see the completed field for the date and time of completion. No more updates will occur.
running
The job is currently being progressed. Updates will occur until completion.
missing
The target path of the job was not found.
unknown
The state of the job is currently unknown.
myself
This depth only caches the direct object and no children of that object.
children
This depth caches the direct object and any immediate descendants of that object.
all_children
This depth caches the direct object and all descendants of the direct object.
Pre Cache
Populates the cache for a Server or a given path for a Server.
202
The request and resource are valid and the request was accepted but will be completed asynchronously.
429
Too many requests were made in too short a period of time.
result
boolean
true if the precache request was accepted and will be processed.
General
Precaching allows content to be stored at the CDN edge ahead of an end user requests, this ensures all requests, including the first one, are serviced as quickly as possible. If you do not pre-cache data, data will be cached on-demand.
Only one request per server may be processed at a given time, subsequent requests will be queued.
In this version of the API, only SSL URL's are precached. If you explicitly need pre-caching of non-SSL URL's, please contact us.
Precache Request
Precache requests are processed asynchronously.
Pre-Cache is Recursive
When you specify a path, all contents under the path, if any, are also pre-cached. To pre-cache the entire server, specify the root path /.
Cloud Storage
When contents in the cloud storage change and the provider supports notifications, contents are automatically flushed as needed.
Data Rates Apply
If you specify to pre-cache data, normal charges will be associated with all data pre-cached. In other words, if you have 1GB of data in your cloud storage provider, and you specify to pre-cache the entire path, you will be charged at least 1GB of data plus the size of the headers.
Rate Limited API
This API is rate limited and may result in a 420 response if you call it too frequently.
Depth
See the Pre Cache Object Depth chart for more details on this field.
Pre Cache Cancel
This endpoint cancels an in-progress pre-cache job.
Pre Cache List
This endpoint provides a list of all known pre-cache jobs.
200
The request and resource are valid and the status is returned in the jobs node.
result
boolean
true if the request was valid and processed.
results
int
The full name of all servers that have pre-cache job status.
jobs
array
An array of Server names and Domains that have pre-cache job status for the current credentials.
Pre Cache Details
This endpoint provides full status of all known pre-cache jobs.
200
The request and resource are valid and the details are returned to the job node.
404
No job matching the key and provided credentials as found.
result
boolean
true if the request was valid and returned.
Pre Cache Status
This endpoint provides full status of all known pre-cache jobs.
200
The request and resource are valid and the status is returned in the jobs node.
result
boolean
true if the request was valid and returned.
results
int
The number of job objects returned in jobs.
Pre Cache Status Server
This endpoint provides details on a precache job for a given Server.
200
The request and resource are valid and the request was accepted but will be completed asynchronously.
404
No jobs for the given server was found for the provided credentials.
result
boolean
true if the request was accepted and returned.
job
object | null
A jobs object related to the server.
Rate Limited API
This API is rate limited and may result in a 429 response if you call it too frequently.
Subscriptions
General information on working with subscriptions.
Subscription plans may be both metered, fixed cost, or both a fixed cost with an additional metered cost. See the specific plan to determine how costs are accrued under List Plans. Get the current users plan, regardless of subscription status, by calling Get Plan.
Metered Billing
Metered usage is calculated by taking your Account Stats for a given period, in bytes transferred, dividing by the unit size, and multiplying by the cost.
If any free_days or free_units are configured for a plan, they are applied before any costs are calculated.
Cancellation
Plan cancellations in this version of the API are permanent. You can move plans at any time however, cancellations are permanent. Once you cancel, you cannot re-enable your subscription.
Payment Types
A variety of payment types are supported through Stripe, our payment provider. When you create a subscription, you must create a payment_token first by using the Stripe API. We utilize Stripe.js to do this directly. When creating a new payment_token, please utilize the public key provided by the Get Public Key API. See Stripe for more information.
Payments may be updated at any time by creating a new payment_token and calling Update Subscription.
Plans
Call the List Plans endpoint for a current list of available plans.
General
To calculate the price, divide the bytes during the period by the per multiplier and multiply by the price. So if 3GiB of data is transferred during the period, your invoice would be for $0.15 cents.
See this article for more information on Gibibits.
Plans Object
name
string
The unique id of the plan to be used with Create Subscription and Update Subscription. This name / id will not change.
desc
string
The human-readable description of the plan indicating frequency, cost, and unit size.
price_base
float
The amount charged as a base account fee regardless of usage.
price_meter
float
The amount per unit of this plan charges.
unit
integer
The units bytes_transfered is reduced by in bytes.
billed
string
The interval at which billing occurs.
free
boolean
true if this plan is free to use.
free_units
integer
The number of units you receive at no charge before costs accrue.
free_days
integer
The number of days that usage is ignored before costs accrue.
discount
string
Any discounts that may apply to this plan or null if no discount plan applies.
available
boolean
true if this plan is available and enabled.
active
bool
true if your subscription is active, false if its been canceled.
account_balance
float
The outstanding balance on the account.
currency
string
The currency of the account_balance.
delinquent
bool
true if your account is past due and in danger of being disabled. false if your account is current.
plan
Plan Object
The current plan object associated with this account's subscription.
canceled_at
datetime
The date and time when the subscription was canceled, null if not canceled.
current_period_start
datetime
The date and time when the current billing period starts.
current_period_end
datetime
The date and time when the current billing period ends.
created
datetime
The date and time when the subscription was created.
Payment Object
The type field in the payment object will indicate the other fields in the object. The possible types are bank_account and card. A null value for the payment object indicates no payment is currently set.
Card Object
type
string
Always credit for a following credit object.
brand
string
The brand of the card being used which varies widely.
last4
string
The last 4 digits of the card number.
exp_month
int
The month in which the card expires.
exp_year
int
The year in which the card expires.
zip
string | null
The zip code associated with the card if provided/available/relevant or null if not provided/available/relevant.
type
string
Always bank_account for the following bank account object.
bank
string
The name of the bank associated with the account and routing.
account
string
The name of the account holder at the bank.
last4
string
The last 4 digits of the bank account number.
routing
string
The routing number for the bank.
Get Plan
This endpoint gets the current credentials plan regardless of subscription status.
200
The request and resource are valid and the plan is returned.
429
Too many requests were made in too short a period of time.
List Plans
This endpoint gets a list of available plans for the current account credentials.
200
The request and resource are valid and the plans are returned.
429
Too many requests were made in too short a period of time.
Get Public Key
This endpoint gets public keys related to subscriptions for the current credentials.
200
The request and resource are valid public keys are returned.
429
Too many requests were made in too short a period of time.
mode
string
The current mode of the platform, you can ignore this.
payment_token_key
string
The token to use when creating a payment using Stripe API's to create a payment token.
Payment Tokens
A variety of payment types are supported through Stripe, our payment provider. When you create a subscription, you must create a payment_token first by using the Stripe API. We utilize Stripe.js to do this directly. Use the payment_token_key provided by this API when creating your payment_token. See Stripe for more information.
Create Subscription
This endpoint adds a subscription, payment type, and plan to the current account.
201
The request and resource are valid and the subscription was created.
409
A subscription already exists for the credentials provided.
423
The subscription was previously canceled and no more operations can be made. Please contact support.
429
Too many requests were made in too short a period of time.
result
boolean
true if the request was successful and a subscription was created.
Stripe Elemental
When creating a new payment_token, please utilize the public key provided by the Get Public Key API. See Stripe for more information.
Billing Details
This endpoint gets details on the current users paid subscription.
Only for Paid Subscriptions
Any user with a subscription plan that has free value of true calling this API will receive a 404 as there are no billing details.
200
The request and resource are valid and the subscription details are returned.
404
The current user is not a subscriber or the subscription was not found. If you feel this is in error, please contact support.
429
Too many requests were made in too short a period of time.
result
boolean
true if the request was successful and a subscription details are returned in the subscription object.
subscription
Subscription Object
A subscription object with the current credentials subscription details.
Update Subscription
This endpoint updates an existing subscriptions payment type or plan to the current account.
202
The request was accepted and the subscription was updated.
406
The request was not accepted because the input or the current state of your subscription does not support updates or the update you are attempting to make.
429
Too many requests were made in too short a period of time.
result
boolean
true if the request was successful and a subscription was updated.
General
Refer to Create Subscription for more details on plans and payment_tokens.
Cancel Subscription
This endpoint cancels a subscription to the current account.
200
The request was accepted but no change was necessary or made.
202
The request was accepted and the subscription was canceled.
404
The request was rejected because no subscription was found to cancel.
429
Too many requests were made in too short a period of time.
result
boolean
true if the subscription was canceled or already cancelled.
Cancellations are Permenant
In this version of the API, subscription cancellations are permanent. You cannot re-subscribe once you cancel.
Invoices
General information on working with invoices.
General
Invoices are available from the List Invoices API which returns a list of invoice objects as shown below. Invoices may change after being issued due to additional reporting, refunds, credits, discounts, or balance carry over.
Invoice Object
id
string
The invoice id associated with an invoice in the list. This will never change.
state
string
The current state of the invoice.
total
float
The total amount of the invoice.
currency
string
The currency of the account_balance.
starting_balance
float
The amount of previous invoices that were unpaid and have been carried over to this invoice.
subtotal
float
The amount of the invoice before tax is applied
tax
float
The amount of tax that will be added to the subtotal.
amount_paid
float
The amount already paid on this invoice towards the total.
amount_due
float
The amount still outstanding on the invoice, the total minus the amount_paid.
usage
Usage Object
The usage object associated with this invoice.
invoice_web
string
The HTTP URL to view this invoice.
invoice_pdf
string
The HTTP URL to retrieve a PDF copy of the invoice.
period_start
datetime
The date and time when the period covered by this invoice started.
period_end
datetime
The date and time when the period covered by this invoice ends. (which may be in the future)
next_payment_attempt
datetime | null
The date and time when payment will be attempted next. null if there have been no billing failures.
created
datetime
The date and time when this invoice was created.
unpaid
The invoice has not yet been paid.
paid
The invoice has been paid.
disputed
The invoice has been disputed by the customer.
refunded
The invoice total has been refunded.
Usage Object May Be Null
If an invoice object has no usage associated with it, the usage object will be set to null.
amount
float
The amount of cost associated with the units and plan.
units
integer
The units consumed in the unit of the plan.
List Invoices
This endpoint gets a list of the invoices associated with the current account.
200
The request and resource are valid and the subscription invoices are returned.
404
The current user is not a subscriber or the subscription was not found. If you feel this is in error, please contact support.
429
Too many requests were made in too short a period of time.
result
boolean
true if the request was successful and a subscription details are returned in the subscription object.
results
int
The number of invoices in the invoices list.
Get Usage
This endpoint gets the current usage information based on the user's plan.
200
The request and resource are valid and the plan usage is returned.
429
Too many requests were made in too short a period of time.
days_total
int
The number of days in the period.
days_elapsed
int
The rounded number of days that have elapsed since the start of the period.
days_remaining
int
The rounded number of days that remain in the period.
used
int
The number of bytes used in days_elapsed.
total
int | null
The number of total bytes available to this account during days_total. If there is no limit, this is returned as null.
avail
int | null
The number of bytes left to use in days_remaining or if there is no total, this field is null.
avail_percent
float | null
The percentage of available transfer remaining.
Not for Paid Subscriptions
This API returns data based on a calendar month. Other billing API's for paid plans operate on a monthly cadence that's dependant on when you subscribed. Thus this may conflict with your invoice.
Event Object
This object contains an event that occurred in a user account or on a server.
The event object is used for account wide events and per-server events. notices are used to draw attention to an important event and track when it was seen/acknowledged.
id
string
A permanent unique id string to describe this event. Strings are 10 case-sensitive characters.
server
string | null
The Server Name and Domain that the event applies to. If the event is not specific to a server, this value is null.
category
string
The type of event this is, error, warning, notice, etc. See table below.
subject
string
A brief description of the event. String may be up to 50-characters.
desc
string
A description of the event. String may be up to 1000 characters.
code
int
An ID associated with this specific category of event.
created
datetime
The time the transfer started.
alarm
boolean
true if this event should cause an alert or alarm status to the end user.
acknowledged
datetime | null
The datetime when the event is recognized by the user.
resolved
datetime | null
This field indicates when an event has been resolved.
error
An error occurred that is causing some impact and should be addressed.
warning
An event occurred that may not be intended or could be causing some impact, and should be investigated.
notice
An event that is worth noting but requires no action, this could include things such as a Server Object being enabled.
Acknowledging an Alarm
The acknowledged field only applies if the alarm field is set to true. If alarm is set to true and the acknowledged field is null, then the alarm has not yet been acknowledged. If it contains a datetime then the alarm has previously been acknowledged.
Alarms can be acknowledged through the Acknowledge API.
Resolved
The resolved field applies to events in the error category. This field is null unless it is an event that has been resolved. Once an error has been resolved, this field contains the datetime of the resolution.
This field serves to prevent the same error from occurring multiple times before being resolved.
Whenever an event is resolved it will also be acknowledged.
Events
This endpoint returns events for the account or a specific server.
200
The request and resource are valid and the request was processed.
result
boolean
true if the events request was accepted and returned.
results
integer
The number of results returned in the events array.
Return Amount
This API will only return the 50 newest events and only events that occurred in the last 90 days unless limit is set. limit reduces the number from 50 allowing you to get only the latest 10, 20, etc.
Null Fields
Fields may be null depending on the state of the event, including resolved, acknowledged, server, and body.
If the server is null, it's an account wide event. If the body is null, it just means do not attempt to show the body.
Filters
Alarm
To only get events that have an alarm messages specify alarm in the query string.
Un-Resolved
To only get events that have not been resolved, specify unresolved in the query string.
Un-Acknowledged
To only get events that have not been acknowledged, specify unack in the query string.
No Server and Any Server
To only get events that have no specific server assigned, specify noserver in the query string. Alternatively, to only get entries where a server is assigned, specify anyserver in the query string. These filters cannot be used together.
These filters are also incompatible with specifying a server on the URI and will be ignored if you specify a server.
Results Sorting
Events are sorted in order of unacknowledged first, then by created date in descending order.
See Events Object
See the Event Object for more details on the results.
Events for Server
This endpoint returns events for a specific server.
200
The request and resource are valid and the request was processed.
result
boolean
true if the events request was accepted and returned.
results
integer
The number of results returned in the events array.
Return Amount
This API will only return the 50 newest events and only events that occurred in the last 90 days unless limit is set. limit reduces the number from 50 allowing you to get only the latest 10, 20, etc.
Null Fields
Fields may be null depending on the state of the event, including resolved, acknowledged, server, and body.
If the server is null, it's an account wide event. If the body is null, it just means do not attempt to show the body.
Filters
Alarm
To only get events that have an alarm messages specify alarm in the query string.
Un-Resolved
To only get events that have not been resolved, specify unresolved in the query string.
Un-Acknowledged
To only get events that have not been acknowledged, specify unack in the query string.
Results Sorting
Events are sorted in order of unacknowledged first, then by created date in descending order.
See Events Object
See the Event Object for more details on the results.
Acknowledge
This endpoint acknowledges a notice has been received by an end user.
200
The request and resource are valid and the request was processed.
result
boolean
true if the events request was accepted and events acknowledged.
Acknowledge Server
This endpoint acknowledges a notice has been received by an end user for a given Server.
200
The request and resource are valid and the request was processed.
result
boolean
true if the events request was accepted and events for the specified server were acknowledged.
Poll
This endpoint returns the activity for various categories and allows you to wait for an update.
General
This API allows you to tell if certain types of objects have last been updated allowing you to locally cache data without the need to poll API's for updates. When activity occurs, you may recall the API to get the latest data.
You can request specific fields with the fields query parameter but no more than thirty (30). If you need more than 10, you should watch all the fields or make more than one request.
Best Effort
This API is a "best effort" API activity date may be updated when an update has not actually occurred. The worst case scenario is re-caching data that is unchanged.
Polling
This API allows you to long poll for up to fifty-five (55) seconds for any or specific activity fields by specifying the wait parameter. As soon an activity is updated, the API will return. All fields specified are returned even if only one is updated unless the updated flag is set. If the wait time is reached and no update has occurred, all fields are returned with the latest known datetime for each field.
If you specify a wait of zero (0) the API returns the latest activity for the specified fields immediately.
Last Activity and Last Key
You can also specify the lastactivity query parameter in a datetime format. If activity in the specified fields has occurred since the lastactivity the API immediately returns; otherwise, the API waits for an update for the specified wait time.
Additionally, you may provide the lastkey field with your last known key response. Even if the update time is unchanged, askew in the lastkey will trigger an updated response. This ensures that if changes happen subsecond or you are polling with updated set, you will not miss updates.
lastkey is directly tied to fields or lack thereof. If you change the fields, the key will change even if the activity timestamp has not. Key should only be used for a differential of the same fields.
If the provided lastkey is different from the calculated lastkey for the same dataset, the return will be immediate.
Last Key Always Returned
The lastkey field should be returned in all scenarios where result is true even if results are 0. There are some corner cases where a value of null may be returned. A null response from lastkey should be treated a value of "no key available".
200
The request and resource are valid and the response was returned.
result
boolean
true if the activity request was valid and returned.
results
int
The number of status elements returned.
key
int | null
A unique key of the status at a given time based on your request. You can use this with the lastkey field to avoid rapid updates or race conditions.
activity
array
An object.
analytics
The datetime of the last addition or modification of any analytics profile.
apikey
The datetime of the last API key addition or removal.
billing
The datetime of the billing related change including invoice, usage, or subscription status.
cdns
The datetime of the last CDN configuration change.
changes
The datetime when pending changes were last updated indicating a precache or flush may be forthcoming.
events
The datetime of the last event addition, acknowledgment, or resolution.
flush
The datetime of the flush action on any server.
precache
The datetime of the last precache job on any server.
servers
The datetime of the last addition or modification of a server profile.
user
The datetime of the last user profile modification which includes 2-Factor, email, phone, or subscription status.
Extended Activity
Extended activity is specific to conigurations for specific profiles and providers. The format is the field name followed by a = and the configuration name.
analytic:config
The datetime of the last configuration change of a specific analytics profile.
cdn:config
The datetime of the last change of a specific CDN configuration.
server:changes
The datetime of the last received pending changes update. Use the Cache Management API's to get additional status.
server:config
The datetime of the last change of a specific server configuration.
server:content
The datetime of the last automatic update was received for a specific server. If automatic updates are not supported or enabled, this field will not be set. This field will be updated even if automatic updates are not enabled.
server:event
The datetime of the last event added, resolved, or acknowledged on a specific server.
server:flush
The datetime of the last flush action occurred on a specific server. This activity includes Flush Cache actions that are manually or automatically initiated.
server:precache
The datetime of the last precache action occurred on a specific server. This activity includes Pre Cache actions that are manually or automatically initiated.
Rate Limited
This API is heavily rate-limited and may result in 429 responses if called too frequently.
System Status
This endpoint returns the platforms current status and version.
This API is really for programmatic access for users who are building on the API. All other users should utilize our status page.
Result Codes
200
The request and resource are valid and the response was returned.
result
boolean
true if the status request was valid and returned.
platform
object
An object containing the status of each platform component.
version
string
The platform version number currently running.
app
The web app used to manage your configurations.
api
The API that powers the web apps and may be accessed directly.
cdn
The status of the platforms CDN and our ability to serve content from the CDN.
analytics
The status of the platforms ability to report analytics data to analytics providers.
OK
The component status is nominal.
Degraded
The component status is partially degraded or certain segments are experiencing issues.
Failure
The component is in a failure state.
More Information
Check https://status.fast.io for more information on overall status.