Suggest Edits

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.

API Key

Once you login to your account, you can retrieve your API Key by performing the following steps.

  1. Go to your Account Settings.
  2. Click on Integrate.
  3. Click on Add API Key if it's not already enabled.
  4. 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

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.

Scope
Desc

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.

Supply Credentials

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.

Method
Format
Desc

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.

2 Factor Authentication

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.

Suggest Edits

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.

 
get/user/token/:token
$ curl https://go.fast.io/api/current/user/token/:token \
  -u username:password
A binary file was returned

You couldn't be authenticated

{
  "result" : "true",
  "expires_in" : 1209600,
  "auth_token" :  "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxMjM0NTY3ODkwMTIzNDU2Nzg5Iiwic2NvcGUiOiJnby5mYXN0LmlvIiwicGFzc3dvcmQiOiIwMTIzNDUiLCJleHBpcmVzIjoxNDkzNjY2Mzc0LCJ2ZXJzaW9uIjoiMS4wIn0.EjXlk6ULnXFDYUUrh-JFe2Wr3DhTtO3541hhbTo7IGpPKLUFpay8rfKGnP0I_kM9K5e9rq-Fshik2k-dPiS1vA",
  "2factor" : false
}
 

Result Codes

HTTP Result
Description

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 JSON

Variable
Type
Desc

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.

Suggest Edits

Create Key

This endpoint creates an API Key which can be used for all subsequent requests.

 
post/user/key/
$ curl https://go.fast.io/api/v1.0/user/key/ \
	-X POST \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
  -d "memo=Integration for XYZ Platform"
A binary file was returned

You couldn't be authenticated

{
  "result" : "true",
  "api_key" :  "n4ws4ghm9nohak807iamxw5ne5t6dhsq8nrb"
}

Body Params

memo
string

Add a note for referencing what this API Key is used for. Maximum length of 200 Characters.

 

Result Codes

HTTP Result
Description

200

The request was successful and a valid API Key has been returned.

400

An invalid request was made.

Result JSON

Variable
Type
Desc

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.

Memo

The Memo field must be between 2 and 128 characters and is optional. Invalid Memo's will cause the request to fail. Memo's cannot be updated.

Suggest Edits

List Keys

This endpoint lists existing API keys registered to the current account.

 
get/user/keys/key
$ curl https://go.fast.io/api/v1.0/user/keys/ \
 -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : "true",
  "results" : 2,
  "api_keys" : [
    {
      "api_key" : "yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72",
      "memo" : "My personal server",
      "created" : "2018-04-23 15:22:58 UTC"
    },
    {
      "api_key" : "n4ws4ghm9nq7ia72iamxw5ne5t6dhsq8nrbd",
      "memo" : "Integration with another service",
      "created" : "2018-04-23 15:22:58 UTC"
    }
  ]
}

Path Params

key
string
required

A 36 character API key you wish to fetch details of. Omit this for all API Keys.

 

Result Codes

HTTP Result
Description

200

The request was successful and a valid API Key has been returned.

Result JSON

Variable
Type
Desc

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.

Suggest Edits

Delete Key

This endpoint deletes an API Key permanently.

 
delete/user/key/key
$ curl https://go.fast.io/api/v1.0/user/key/n4ws4ghm9nq7ia72iamxw5ne5t6dhsq8nrbd \
	-X DELETE
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : "true"
}

Query Params

key
string

The 36 character API key you want to delete.

 

Result Codes

HTTP Result
Description

200

The request was successful and a valid API Key has been deleted.

404

The API Key was not found to delete.

Result JSON

Variable
Type
Desc

result

Boolean

true if the credentials were accepted and an api_key was deleted.

Suggest Edits

Add 2Factor

This endpoint enables 2-Factor authentication for your user account.

 
post/user/2factor/
$ curl https://go.fast.io/api/v1.x/user/2factor/ \
   -X POST \
   -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}
 

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.

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

result

boolean

true if 2Factor authentication was added.

Suggest Edits

Verify 2Factor

This endpoint enables 2-Factor authentication for your user account.

 
post/user/2factor/verify/token
$ curl https://go.fast.io/api/v1.x/user/2factor/verify/8320489 \
   -X POST \
   -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

token
string
required

The token provided from Authy in a phone call, SMS, or through an application.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

result

boolean

true if 2Factor authentication was verified and is now fully enabled.

Suggest Edits

Get 2Factor

This endpoint gets the current status of 2Factor for the current users account.

 
get/user/2factor/
$ curl https://go.fast.io/api/v1.x/user/2factor/ \
   -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "state": "disabled"
}
 

Result Codes

HTTP Results
Description

200

2Factor authentication request was accepted.

429

Too many requests were made in too short a period of time.

Result JSON

Variable
Type
Description

result

boolean

true if 2Factor authentication was added.

state

string

The current state of 2Factor Auth for the provided credentials. See table below.

State
Desc

disabled

2Factor authentication is disabled.

enabled

2Factor authentication is enabled and verified.

unverified

2Factor authentication has been configured but not verified.

Suggest Edits

Remove 2Factor

This endpoint provides removes 2-factor authentication from a users account.

 
delete/user/2factor/token
$ curl https://go.fast.io/api/v1.x/user/2factor \
    -X DELETE \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

token
string
required
 

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

HTTP Results
Description

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 JSON

Variable
Type
Description

result

boolean

true if 2-Factor authentication was successfully removed or was already removed from your account.

Suggest Edits

Send 2Factor Code

This endpoint sends an authorization token via SMS to the users phone_number.

 
get/user/2factor/code/
$ curl https://go.fast.io/api/v1.x/user/2factor/code \
   -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}
 

General

Tokens are 6 digit numbers.

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

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.

Suggest Edits

Send 2Factor Call

This endpoint sends an authorization token via a Phone Call to the users phone_number.

 
get/user/2factor/call/
$ curl https://go.fast.io/api/v1.x/user/2factor/call \
   -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}
 

General

Tokens are 6 digit numbers.

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

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.

Suggest Edits

Auth 2Factor

This endpoint authorizes a 2-Factor token and provides a JWT in return.

 
post/user/2factor/auth/token
$ curl https://go.fast.io/api/v1.x/user/2factor/auth/8320489 \
   -X POST \
   -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

token
string
required

The token provided from Authy in a phone call, SMS, or through an application.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Desc

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.

Suggest Edits

User Object

This object is contains the details of a single user account.

 
Field
Type
Description
Read Only

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

Suggest Edits

User Details

This endpoint gets the account details associated with the provided credentials.

 
get/user/details
$ curl https://go.fast.io/api/current/user/details \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true,
  "user" : {
    "id" : "8914921300623612769",
    "email_address" : "[email protected]",
    "country_code" : "US",
    "tos_agree" : true,
    "first_name" : "Henry",
    "last_name" : "Larson",
    "phone_country" : null,
    "phone_number" : null,
    "2factor" : false,
    "subscriber" : true,
    "valid_phone" : false,
    "valid_email" : true,
    "locked" : false,
    "suspended" : false,
    "updated": "2018-07-01 23:14:01 UTC",
    "created": "2017-06-16 23:14:42 UTC"
  }
}
 

2Factor Verification

If 2Factor Authorization is enabled on this account, you must supply the token parameter with your request or it will be rejected.

Result Codes

HTTP Results
Description

200

The request and resource are valid and the user details are returned in the body.

Result JSON

Variable
Type
Description

result

boolean

true if user details are returned.

user

user object

This object contains all the user details if the request result was true.

Suggest Edits

Update User Details

This endpoint updates the account details associated with the provided credentials.

 
post/user
$ curl https://go.fast.io/api/current/user \
  -X POST \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
  -d email_address="[email protected]" \ 
  -d first_name="Derek" \
  -d last_name="Labian"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Body Params

email_address
string

The email address of the account to be updated. The string must be a valid email address between 4 and 30 characters in length.

password
string

The password to set for the new account. The string must be between 6 and 30 characters in length.

first_name
string

The first name of the user. The string must be between 2 and 30 characters in length.

last_name
string

The last name of the user. The string must be between 2 and 30 characters in length.

phone_country
int32

The users phone country code. This must be a int value between 1 and 4 digits in length.

phone_number
int32

The users phone number excluding the country code. This must be an int value between 7 and 15 digits in length.

 

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.

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

result

boolean

true if the account details were accepted.

Suggest Edits

Send Validation Email

This endpoint sends a validation email to the currently configured email address.

 
get/user/email/validate
$ curl https://go.fast.io/api/v1.0/user/email/validation/ \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}
 

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

HTTP Results
Description

202

The validation email was sent to the address specified by the account holder.

Result JSON

Variable
Type
Description

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.

Suggest Edits

Validate Email

This endpoint validates an email with a code previously sent via email.

 
post/user/email/validate/email
$ curl https://go.fast.io/api/v1.0/user/email/validate/[email protected] \
  -X POST \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
  -d email_token="0y6zgw34izjqx61mo78ni9zck2ikef"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

email
string
required

The email address of the account you are verifying.

Query Params

email_token
string

This is the token provided in email to validate an 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

HTTP Results
Description

202

The email_token was accepted and the password has been updated.

Result JSON

Variable
Type
Description

result

boolean

true if the email_address is validated. false for all other responses.

Suggest Edits

Check Email

This endpoint checks to see if an email address is valid and its availability. This resource is restricted.

 
get/user/email/email_address
$ curl https://go.fast.io/api/v1.0/user/email/[email protected] \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

email_address
string
required

The email_address to check if its both valid and available. This string must be between 4 and 50 characters in length.

 

Restricted Resource

This resource is rate limited to 1 request per second, 3 requests per minute and 5 per hour.

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

result

boolean

true if the email_address is valid and available.

Suggest Edits

Check Phone

This endpoint checks to see if a phone number is valid to use with an account.

 
get/user/phone/:phone_country-:phone_check
$ curl https://api.fast.io/v1/user/phone/1-7015555555 \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

phone_check
string
required

The phone_country and phone_number to check if valid. This string must be between 8 and 16 characters in length.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

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.

Suggest Edits

Check Password Code

This endpoint checks a password the provided code for validity and returns the associated email.

 
get/user/password/email/code
$ curl https://go.fast.io/api/v1.x/user/password/email/tq7lyt3xyichbagqta6di4ata5st2x
A binary file was returned

You couldn't be authenticated

{
  "result" : true,
  "email" : "[email protected]"
}

Path Params

code
string
required

A 30 character code used to identify the account credentials to set the password of. Codes have a limited lifespan.

 

Restricted Resource

This is a rate-limited and restricted resource.

Result Codes

HTTP Results
Description

200

The code was valid and the associated email was returned.

Result JSON

Variable
Type
Description

result

boolean

true if the code was valid.

email

string

The email of the account associated with the code.

Suggest Edits

Set Password

This endpoint sets a password for the account related to the provided code.

 
post/user/password/code
$ curl https://go.fast.io/api/v1.x/user/password/tq7lyt3xyichbagqta6di4ata5st2x \
  -X POST \
	-d password1="[email protected]" \
	-d password2="[email protected]"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

code
string
required

A 30 character code used to identify the account credentials to set the password of. Codes have a limited lifespan.

Body Params

password1
string
required

The password to set on the account provided by the code.

password2
string
required

The password to set on the account provided by the code. This must match password1.

 

Restricted Resource

This is a rate-limited and restricted resource.

Result Codes

HTTP Results
Description

202

The code was valid and accepted.

Result JSON

Variable
Type
Description

result

boolean

true if the password was accepted and updated.

Suggest Edits

Lost Password

This endpoint checks to see if an email address is valid and its availability. This resource is restricted.

 
get/user/email/reset/email_address
$ curl https://go.fast.io/api/v1.x/user/email/reset/[email protected] \
  -X POST \
	-d email_address="[email protected]"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Body Params

email_address
string
required

The email_address to reset the password of. This string must be between 4 and 50 characters in length.

 

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.

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

result

boolean

true if the email_address was found and a reset request was sent.

Suggest Edits

Close Account

This endpoint locks the account associated with the provided credentials.

 
post/user/close/
$ curl https://go.fast.io/api/v1.x/user/close \
  -X POST \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
  -d email_address="[email protected]"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Body Params

email_address
string

The email address of the account to be closed. The string must be a valid email address between 4 and 30 characters in length.

 

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.

https://fast.io/privacy-policy/

2Factor Verification

If 2Factor Authorization is enabled on this account, you must supply the token parameter with your request or it will be rejected.

Result Codes

HTTP Results
Description

202

The account close request was accepted for processing.

Result JSON

Variable
Type
Description

result

boolean

true if the account is closed.

Suggest Edits

Authorization Check

This endpoint checks can be polled to ensure your credentials are still valid.

 
get/user/auth/
$ curl https://go.fast.io/api/current/user/auth/
A binary file was returned

You couldn't be authenticated

{
  "result" : true,
  "id" : "8914921300623612769",
  "scope" : "fast.io/user"
}
 

Result Codes

HTTP Results
Description

202

The credentials provided are valid and accepted.

401

The credentials provided are not valid or expired.

429

Too many requests were made in too short a period of time.

Result JSON

Variable
Type
Description

result

boolean

true if the authorization credentials are valid and acceptable.

id

string

The user_Id of the provided credentials.

scope

string | null

The scope of the current credentials or null if there is no specific limitation on the provided credentials.

Authentication Types

This endpoint accepts all authorization methods compatible with this API. It can be used to test API keys but it is also rated limited.

Rate Limited API

This API endpoint is rate limited, overly aggressive requests will result in a 429 result.

Suggest Edits

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.

Supported Providers
API Name

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.

Suggest Edits

Storage Object

This object contains a analytics configuration.

 

Fixed Fields

The object used to describe Cloud Storage Providers linked to a user account.

Field
Type
Description
Read-Only

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.

State
Desc

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

Code
Desc

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.

Suggest Edits

List Storage

Get a list of all storage providers available to the currently authorized account.

 
get/storage/list/
$ curl https://go.fast.io/api/v1.x/storage/list/ \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 5,
    "storage": [
        {
            "id": "1",
            "name": "googledrive",
            "display": "Google Drive",
            "enabled": true,
            "origin_url": "https://drive.google.com/"
        },
        {
            "id": "2",
            "name": "dropbox",
            "display": "Dropbox",
            "enabled": true,
            "origin_url": "https://www.dropbox.com/"
        },
        {
            "id": "3",
            "name": "box",
            "display": "Box",
            "enabled": true,
            "origin_url": "https://www.box.com/"
        },
        {
            "id": "4",
            "name": "onedrive",
            "display": "Microsoft OneDrive",
            "enabled": true,
            "origin_url": "https://onedrive.live.com/"
        },
        {
            "id": "5",
            "name": "mediafire",
            "display": "MediaFire",
            "enabled": true,
            "origin_url": "https://www.mediafire.com/"
        }
    ]
}
 

Result Codes

HTTP Results
Description

200

Storage Providers were found and returned in the storage field.

404

No Storage Providers were found for the current account.

Result JSON

Variable
Type
Description

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/.

Suggest Edits

List My Storage

Get a list of storage providers linked to the current account.

 
get/storage/list/connected/
$ curl https://go.fast.io/api/v1.0/storage/list/linked/ \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated


{
    "result": true,
    "results": 3,
    "storage": [
        {
            "id": "1",
            "name": "googledrive",
            "display": "Google Drive",
            "enabled": true,
            "protected": false,
            "origin_url": "https://drive.google.com/"
        },
        {
            "id": "2",
            "name": "dropbox",
            "display": "Dropbox",
            "enabled": true,
            "protected": false,
            "origin_url": "https://www.dropbox.com/"
        },
        {
            "id": "4",
            "name": "onedrive",
            "display": "Microsoft OneDrive",
            "enabled": true,
            "protected": false,
            "origin_url": "https://onedrive.live.com/"
        }
    ]
}

Path Params

provider
string
required
 

Result Codes

HTTP Results
Description

200

Connected providers were found and returned in the storage field.

404

No connected providers were found.

Result JSON

Variable
Type
Description

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.

Suggest Edits

Storage Details

Get details of a Storage Provider linked to the current credentials.

 
get/storage/details/provider
$ curl https://go.fast.io/api/v1.0/storage/details/dropbox \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true,
  "storage" :
    {
      "id" : 3,
      "name" : "dropbox",
      "display" : "Dropbox",
      "provider_id" : "34609830",
      "email" : "[email protected]",
      "authenticated" : true,
      "expired" : false,
      "enabled" : true,
      "protected": false,
      "autoupdate": "available",
      "origin_url": "https://www.dropbox.com/",
      "error" : null,
      "updated" : "2018-04-23 15:22:58 UTC",
    }
}

Path Params

provider
string
required
:provider
string
required

The name of the Storage Provider you wish to fetch details of.

Query Params

user
boolean

Get the storage providers current user details in the response. Set to yes to retrieve.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

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.

Authentication

Re-authenticated Cloud Storage Providers that have lost credentials by adding the provider again to your account through the web interface. Do not remove the Server or the Provider first. Re-adding will update and fix the credentials.

Suggest Edits

Analytics Providers

A list of supported analytics providers you can integrate with Fast.

 
Provider
Identifier
Description
Enabled

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].

Suggest Edits

Analytics Object

This object contains a analytics configuration.

 

Fixed Fields

Field
Type
Description
Read-Only
Default

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.

Mode
Include
Exclude
Description

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:
Regular Expression
WIll Match

/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.

Suggest Edits

List Providers

This endpoint gets a list of the available analytics providers.

 
get/analytics/list/
$ curl https://go.fast.io/api/v1.0/analytics/providers/list \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 2,
    "providers": [
        {
            "id": "1",
            "name": "googleanalytics",
            "display": "Google Analytics",
            "provider_url": "https://analytics.google.com/analytics/web/",
            "enabled": true
        },
        {
            "id": "2",
            "name": "mixpanel",
            "display": "Mixpanel",
            "provider_url": "https://mixpanel.com/report",
            "enabled": true
        }
    ]
}
 

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.

Result Codes

HTTP Results
Description

200

The request and resource are valid and the provider list is returned in the body.

Result JSON

Variable
Type
Description

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.

Suggest Edits

Validate Filter

This endpoint validates a filter to be used with an analytics profile.

 
post/analytics/validate/filter/
$ curl https://go.fast.io/api/v1.0/analytics/validate/filter/ \
  -X POST \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
  -d "filter=/([A-Z]{3}|[0-9]{4})/i"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}
{
    "result": false,
    "error": {
        "code": 10059,
        "text": "An invalid filter was supplied."
}

Body Params

filter
string

The analytics filter to verify is acceptable.

 

Result Codes

HTTP Results
Description

202

The filter was valid and acceptable.

406

The filter was not valid and acceptable.

Result JSON

Variable
Type
Description

result

boolean

true if the filter was valid and acceptable.

Suggest Edits

Create Profile

This endpoint adds a provider to the current user account.

 
post/analytics/
$ curl https://go.fast.io/api/v1.0/analytics/ \
  -X POST \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
  -d name=MyGoogleProfile \
  -d type=GoogleAnalytics \
  -d token=UA-2349520-1 \
  -d "event_name=MySoftware Downloads"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Body Params

name
string

The name of this profile used for UI display, and updating, and assigning to Servers. Names between 3 and 30 characters are valid.

provider
string

The provider to use for this analytics profile.

token
string

The token provided by the analytics provider you wish to track file downloads under. Strings between 3 and 40 characters are valid.

event_name
string

The name of the event you wish file downloads to be reported as. Strings between 3 and 30 characters are valid.

referrer
boolean

Enable reporting of the HTTP referrer.

filter_mode
int32

The filter mode to set for analytics entries.

filter
string

The regex to use in combination with the filter_mode to include or exclude reporting data. Up to 200 characters.

 

Result Codes

HTTP Results
Description

202

The request and resource are valid and the analytics Provider was added to the user account.

Result JSON

Variable
Type
Description

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.

Suggest Edits

Profile Details

This endpoint gets the details for a provided Analytics profile for the provided credentials.

 
get/analytics/details/profile
$ curl https://go.fast.io/api/v1.0/analytics/details/MyGoogleProfile \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "profile": {
        "name": "MyGoogleProfile",
        "provider": "googleanalytics",
        "token": "UA-2309520-1",
        "event_name": "MySoftware Downloads",
        "referrer": false,
        "filter_mode": "0",
        "filter": null,
        "filter_mode_country": 0,
        "filter_country": null,
        "provider_url": "https://analytics.google.com/analytics/web/",
        "updated": "2018-04-23 15:22:58 UTC"
      }
}

Path Params

profile
string
required

The name of the analytics profile to get the details of.

 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the profile details are returned in the body.

Result JSON

Variable
Type
Description

result

boolean

true if Analytics Profile list is returned. true even if the results is set to 0.

profile

object

An Analytics Objects that was requested in the path.

Suggest Edits

List Profiles

This endpoint gets a list of all analytics profiles associated with the provided credentials.

 
get/analytics/list
$ curl https://go.fast.io/api/v1.0/analytics/list \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 2,
    "profiles": [
        {
            "name": "MyGoogleProfile",
            "provider": "googleanalytics",
            "token": "UA-2309520-1",
            "event_name": "MySoftware Downloads",
            "referrer": false,
            "filter_mode": "0",
            "filter": null,
            "filter_mode_country": "0",
            "filter_country": null,
            "provider_url": "https://analytics.google.com/analytics/web/",
            "updated": "2018-04-23 15:22:58 UTC"
        },
        {
            "name": "MyMixpanelProfile",
            "provider": "mixpanel",
            "token": "iDm36Dab601",
            "event_name": "MySoftware Downloads",
            "referrer": false,
            "filter_mode": "0",
            "filter": null,
            "filter_mode_country": "0",
            "filter_country": null,
            "provider_url": "https://mixpanel.com/report",
            "updated": "2018-04-24 15:22:58 UTC"
        }
    ]
}
 

Sort

By default, the Analytics profile list is sorted by name in an ascending (ASC) order. No alternative sorting is supported.

Result Codes

HTTP Results
Description

200

The request and resource are valid and the profile list is returned in the body.

Result JSON

Variable
Type
Description

result

boolean

true if Analytics Profile list is returned. true even if the results is set to 0.

results

integer

Indicates the number of Analytics Profiles returned in the analytics list.

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.

Suggest Edits

Update Profile

This endpoint updates the details of an analytics Provider configuration.

 
post/analytics/update/:profile
$ curl https://go.fast.io/api/v1.0/analytics/MyGoogleProfile \
  -X POST \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
  -d token=UA-2309520-1 \
  -d "event_name=MySoftware Downloads"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}
{
  "result" : false,
  "error" : {
    "error_code" : 3499,
    "error_text" : "The [event_name] was invalid."
  }
}
{
  "result" : false,
  "error" : {
    "error_code" : 3499,
    "error_text" : "The [provider] was not found."
  }
}
{
  "result" : false,
  "error" : {
    "error_code" : 8499,
    "error_text" : "The [provider] was not found but in use; its name cannot be updated."
  }
}

Path Params

name
string
required

The nameof the profile you wish to update.

Body Params

name
string
required

The name of this profile used for UI display, and updating, and assigning to Servers.

provider
string
required

The provider to use for this analytics profile.

token
string
required

The token provided by the analytics provider you wish to track file downloads under. Strings between 3 and 40 characters are valid.

event_name
string

The name of the event you wish file downloads to be reported as. Strings between 3 and 30 characters are valid.

referrer
boolean

Enable reporting of the HTTP referrer.

filter_mode
int32

The filter mode to set for log entries URLs.

filter
string

The regex to use in combination with the filter_mode to include or exclude reporting data by URL. Up to 200 characters.

filter_mode_country
int32

The filter mode to set for log entries client country codes.

filter_country
string

The regex to use in combination with the filter_mode to include or exclude reporting data by client country code. Up to 200 characters.

 

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.

Result Codes

HTTP Results
Description

202

The Analytics Profile configuration was accepted for an update.

Result JSON

Variable
Type
Description

result

boolean

true if the Analytics Profile configuration was updated.

Suggest Edits

Delete Profile

This endpoint gets the details of an analytics Provider configuration.

 
delete/analytics/profile
$ curl https://go.fast.io/api/v1.0/analytics/MyGoogleProfile \
  -X DELETE \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}
{
  "result" : false,
  "error" : {
    "error_code" : 3499,
    "error_text" : "The [provider] was not found or already deleted."
  }
}
{
  "result" : false,
  "error" : {
    "error_code" : 4999,
    "error_text" : "The [profile] was in use by a Server."
  }
}

Path Params

profile
string
required

The Analytics Profile name to delete the configuration of.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

result

boolean

true if the profile was deleted.

Suggest Edits

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.

CDN Name
API Name
Description
Tier

Akamai

akamai

Akamai Global Network utilizing thousands of global points of presence.

1

Tier

CDN Tiers are tied to the cost and performance of the provider. The tier is fixed to the provider.

Pricing

Pricing is not implemented in this version of the API.

Suggest Edits

List CDNs

Get a list of all CDN providers available to the currently authorized account.

 
get/cdn/list/
$ curl https://go.fast.io/api/v1.0/cdn/list/ \
  -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 1,
    "CDN": [
        {
            "id": "1",
            "name": "akamai",
            "display": "Akamai",
            "pricing": "1",
            "enabled": true
        }
    ]
}
 

Result Codes

HTTP Results
Description

200

CDN Providers were found and returned in the storage field.

404

No CDN Providers were found for the current account.

Result JSON

Variable
Type
Description

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.

Suggest Edits

CDN Details

This endpoint gets the details of a single CDN available to the provided credentials.

 
get/cdn/details/name
$ curl https://go.fast.io/api/v1.0/cdn/details/Akamai \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "CDN": {
        "id": "1",
        "name": "akamai",
        "display": "Akamai",
        "pricing": "1",
        "enabled": true
    }
}

Path Params

name
string
required

The name of the CDN to get details of.

 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the CDN details are in the CDN array.

Result JSON

Variable
Type
Description

result

boolean

true if CdN details are returned.

CDN

CDN Object

The CDN Object for the provided CDN name.

Suggest Edits

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.

Suggest Edits

Server Object

This object contains is used for server details.

 

Fixed Fields

These fields are required with every server object response or request.

Field
Type
Description
Read Only
Default

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:

Code
Desc

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.

Options Array

There are a few flags that can be set on a configured server.

Name
Description
Default

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

Priority
Filename

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.

Suggest Edits

Check Server Name

This endpoint checks to see if a Server name is valid and available.

 
get/server/check/server
$ curl https://go.fast.io/api/v1.x/server/check/MyDropboxServer.imfast.io \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}
{
  "result" : false
}

Path Params

server
string
required

The name and domain name combined to check if its both valid and available. This string must meet the requirements for a valid name and domain.

 

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.

Result Codes

HTTP Results
Description

202

The fqdn is valid and is acceptable.

406

The fqdn is not valid, reserved, in use, or otherwise not acceptable.

Result JSON

Variable
Type
Description

result

boolean

true if the fqdn is valid and available.

Suggest Edits

Create Server

This endpoint updates the details of a Server.

 
post/server/
$ curl https://go.fast.io/api/v1.x/server/ \
    -X POST \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
    -d name=MyDropboxServer \
    -d storage=box \
    -d enabled=true \
    -d analytics=MyGoogleProfile \
    -d cdn=akamai
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Body Params

name
string
required

The name of the Server. A string length of 3 to 50 characters is supported.

domain
string

The domain name to use for this server. Combined with the name this creates the fqdn to be used for the server.

storage
string
required

The name of the Cloud Storage Provider to use for this Server.

cdn
string
required

The name of the CDN to use for this Server. See Server overview for a list of CDN Providers and API Names.

analytics
string
required

The name of the Analytics Profile to report analytics to. You can set this to null if you do not wish external reporting.

enabled
string

Set to true if you want the Server to be publicly accessible.

fancyindexing
boolean

Set to true if you want Fancy Indexing enabled for directory access without an index.

indexfiles
boolean

Set to true if you want to look for index files when a directory is accessed.

autoupdate
boolean

Set to true if you want automatic updates done to your cloud storage to be applied to your CDN.

precache
boolean

Set to true if you want pre-caching of your cloud storage metadata to be enabled.

precachedata
boolean

Set to true if you want to pre-cache actual data from your cloud storage as well as metadata. Normal usage rates/fees apply.

search
string

Set to true if you want a indexable response to be returned for requests to this Server.

expires
int32

The amount of time, in seconds, you want content to be cached in a users browser before they revalidate to your Server. Set low for frequently updated content.

error_url
string

The URL users will be sent to when an error occurs processing a request to this Server.

 

Result Codes

HTTP Results
Description

200

The request was valid and the Server was created.

Result JSON

Variable
Type
Description

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.

Suggest Edits

List Servers

This endpoint gets a list and configuration of all Servers associated with the provided credentials.

 
get/server/list
$ curl https://go.fast.io/api/v1.x/server/list \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 2,
    "servers": [
        {
            "name": "MyServer",
            "domain": "imfast.io",
            "server": "myserver.imfast.io",
            "storage": "dropbox",
            "analytics": "mygoogleprofile",
            "cdn": "akamai",
            "enabled": true,
            "locked" : false,
            "fancyindexing": true,
            "indexfiles": true,
            "autoupdate" : true,
            "precace" : true,
            "precachedata" : false,
            "error": null,
            "deleted": null,
            "updated": "2018-04-24 15:22:58 UTC",
            "created": "2018-04-24 15:22:58 UTC"
        },
        {
            "name": "MyServer2",
            "domain": "imfast.io",
            "server": "myserver2.imfast.io",
            "storage": "dropbox",
            "analytics": "mygoogleprofile",
            "cdn": "akamai",
            "enabled": true,
            "locked" : false,
            "fancyindexing": false,
            "indexfiles": true,
            "autoupdate" : true,
            "precache" : true,
            "precachedata" : false,
            "error": null,
            "deleted": null,
            "updated": "2018-04-23 15:22:58 UTC",
            "created": "2018-04-23 15:22:58 UTC"
        }
    ]
}

Query Params

nodeleted
boolean

If nodeleted is set, only servers that are not deleted are returned.

 

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

HTTP Results
Description

200

The request and resource are valid and the server list is returned in the body.

Result JSON

Variable
Type
Description

result

boolean

true if Server list is returned. true even if the results is set to 0.

results

integer

Indicates the number of server objects returned in the servers list.

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.

Suggest Edits

Server Details

This endpoint gets the configuration of a single Server associated with the provided credentials.

 
get/server/details/server
$ curl https://go.fast.io/api/v1.x/server/details/MyDropboxServer.imfast.io \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "server": {
        "name": "mydropboxserver",
        "domain": "imfast.io",
        "server": "mydropboxserver.imfast.io",
        "storage": "dropbox",
        "analytics": "MyGoogleAnalytics",
        "cdn": "akamai",
        "enabled": true,
        "locked" : false,
        "fancyindexing": true,
        "indexfiles": true,
        "autoupdate" : true,
        "precache" : true,
        "precachedata" : false,
        "error": null,
        "deleted": null,
        "updated": "2018-04-23 15:22:58 UTC",
        "created": "2018-04-23 15:22:58 UTC"
    }
}

Path Params

server
string
required

The name and domain name combined with a period separating them. This string must meet the requirements for a valid name and domain.

 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the server details are returned in the body.

Result JSON

Variable
Type
Description

result

boolean

true if Server details are returned.

server

server object

The server object for the requested server.

Suggest Edits

Update Server

This endpoint updates the configuration of a Server.

 
post/server/update/server
$ curl https://go.fast.io/api/v1.x/server/update/MyDropboxServer.imfast.io \
    -X POST \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
    -d indexfiles=false \
    -d analytics=MyMixpanelProfile
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

server
string
required

The name and domain name combined with a period separating them. This string must meet the requirements for a valid name and domain.

Body Params

storage
string

The name of the Server. A string length of 3 to 50 characters is supported.

analytics
string

The name of the Cloud Storage Provider to use for this Server.

cdn
string

The name of the CDN to use for this Server.

enabled
boolean

Set to true if you want the Server to be publicly accessible.

fancyindexing
boolean

Set to true if you want Fancy Indexing enabled for directory access without an index.

indexfiles
boolean

Set to true if you want to look for index files when a directory is accessed.

autoupdate
boolean

Set to true if you want automatic updates done to your cloud storage to be applied to your CDN.

precache
boolean

Set to true if you want pre-caching of your cloud storage to your CDN to be enabled.

precachedata
boolean

Set to true if you want to pre-cache actual data from your cloud storage as well as metadata. Normal usage rates/fees apply.

search
boolean

Set to true if you want a indexable response to be returned for requests to this Server.

expires
int32

The amount of time, in seconds, you want content to be cached in a users browser before they revalidate to your Server. Set low for frequently updated content.

error_url
string

The URL users will be sent to when an error occurs processing a request to this Server.

 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the request was completed.

Result JSON

Variable
Type
Description

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.

Suggest Edits

Disable All Servers

This endpoint disables all Servers in the current users account.

 
post/server/disable_all/
$ curl -X POST https://go.fast.io/api/v1.x/server/disable_all/ \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}
 

2Factor Verification

If 2Factor Authorization is enabled on this account, you must supply the token parameter with your request or it will be rejected.

Result Codes

HTTP Results
Description

200

The request and resource were valid and at least some servers have been disabled.

Result JSON

Variable
Type
Description

result

boolean

true if at least one Server is in account is disabled.

Suggest Edits

Delete Server

This endpoint deletes a Server and all its contents.

 
delete/server/server
$ curl -X DELETE https://go.fast.io/api/v1.x/server/MyDropboxServer.imfast.io \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

server
string
required

The name and domain name combined with a period separating them. This string must meet the requirements for a valid name and domain.

 

2Factor Verification

If 2Factor Authorization is enabled on this account, you must supply the token parameter with your request or it will be rejected.

Result Codes

HTTP Results
Description

200

The request and resource were valid and have been deleted.

Result JSON

Variable
Type
Description

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.

Suggest Edits

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.

Field
Type
Description
Read Only

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.

Suggest Edits

File Object

This object contains single files details.

 

Fixed Fields

These fields are required with every file object response or request.

Field
Type
Description

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:

  • mime
  • category
  • modified
  • cached_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

State
Description

ready

Indicates the file is ready and in a normal state.

locked

Indicates the file has been locked by our systems. Contact customer service.

Categories
Category
Description

1

Unknown Binary

2

Text

3

Image

4

Document

5

Archive

6

Executable

8

Video

9

CSS

10

Audio

11

HTML

12

Javascript

Suggest Edits

Path Details

This endpoint gets a single File or Folder details at the specified path and associated with the provided credentials.

 
get/server/details/server?path
$ curl https://go.fast.io/api/v1.x/server/details/MyDropboxServer.imfast.io?/MyFolder/test.png \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true,
  "type": "file",
  "name" : "MyDropboxServer",
  "domain" : "imfast.io",
  "server" : "mydropboxserver.imfast.io",
  "storage" : "dropbox",
  "details": {
     "id": "id:qSZH8F7zKAAAAAAAAAAAHQ",
     "name": "test.png",
     "size": 211522,
     "path": "/MyFolder/test.png",
     "mime": "image/png",
     "category": 3,
     "url": "https://MyDropboxServer.imfast.io/MyFolder/test.png",
     "origin_url" : "",
     "modified": "2018-04-23 15:22:58 UTC",
     "cached" : "2018-04-23 15:29:32 UTC"
  }
}

Path Params

server
string
required

The name and domain name combined with a period separating them. This string must meet the requirements for a valid name and domain.

path
string
required

The path to the File or Folder to get details of. A string length of 1 to 1024 characters is supported.

Query Params

path
string

The path to the File or Folder to get the details of. A string length of 1 to 1024 characters is supported.

 

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

HTTP Results
Description

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 JSON

Variable
Type
Description

result

boolean

true if path was found.

name

string

The name of the Server associated with this response.

domain

string

The domain of the Server associated with this response.

server

string

The fqdn of the server, which is the name and the domain.

storage

string

The name of the Storage Object associated with this response.

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.

Suggest Edits

Folder List

This endpoint gets a list of all files and folders at the specified path and associated with the provided credentials.

 
get/server/list/server?path
$ curl https://go.fast.io/api/v1.x/server/list/MyDropboxServer.imfast.io?/images/ \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true,
  "results" : 1,
  "name" : "MyDropboxServer",
  "domain" : "imfast.io",
  "server" : "mydropboxserver.imfast.io",
  "storage" : "dropbox",
  "path" : "/images/",
  "list" : [
    {
      "type": "file",
      "id": "id:qSZH8137zKAAAAAAAABAAAIK",
      "name": "picture.png",
      "size": 211522,
      "path": "/images/picture.png",
      "mime": "image/png",
      "category": 3,
      "url": "https://mydropboxserver.imfast.io/images/picture.png",
      "origin_url": "",
      "modified": "2018-04-23 15:22:58 UTC",
      "cached" : "2018-04-23 15:29:32 UTC"
    } ]
}

Path Params

server
string
required

The name and domain name combined with a period separating them. This string must meet the requirements for a valid name and domain.

Query Params

path
string

The path to the Folder to get the list of files and folders from. A string length of 1 to 1024 characters is supported.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

result

boolean

true if path was found.

results

integer

Indicates the number of File Object and folder objects returned in the list.

name

string

The name of the Server associated with this response.

domain

string

The domain of the Server associated with this response.

server

string

The fqdn of the server, which is the name and the domain.

storage

string

The name of the Storage Object associated with this response.

path

string

The path of the folder which the list corresponds to.

list

array

A array of File Object and folder objects that exist at the specified path.

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 /.

Suggest Edits

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.

Field
Type
Description

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.

Optional Fields

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.

Suggest Edits

Account Stats

This endpoint gets the transfer statistics for the current account for a given period.

 
get/stats/?interval=:interval&start=start&end=end
$ curl https://go.fast.io/api/v1.x/stats/?start=2018-04-10+13%3A26%3A09+UTC \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 5,
    "interval": 192000,
    "transfers": [
        {
            "transfers": "12892",
            "bytes": "92246456",
            "start": "2018-04-10 13:26:09 UTC",
            "end": "2018-04-12 18:46:09 UTC"
        },
        {
            "transfers": "12822",
            "bytes": "91954060",
            "start": "2018-04-12 18:46:09 UTC",
            "end": "2018-04-15 00:06:09 UTC"
        },
        {
            "transfers": "12831",
            "bytes": "92089128",
            "start": "2018-04-15 00:06:09 UTC",
            "end": "2018-04-17 05:26:09 UTC"
        },
        {
            "transfers": "12900",
            "bytes": "92219487",
            "start": "2018-04-17 05:26:09 UTC",
            "end": "2018-04-19 10:46:09 UTC"
        },
        {
            "transfers": "6459",
            "bytes": "46339529",
            "start": "2018-04-19 10:46:09 UTC",
            "end": "2018-04-20 13:36:09 UTC"
        }
    ]
}
{
    "result": false,
    "error": {
        "code": 46197,
        "text": "Too many requests made. Enhance your calm."
    }
}

Query Params

start
string
required

The start datetime to use when retrieving transfer statistics.

end
string

The end datetime to use when retrieving transfer statistics.

 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the user stats are returned in the body.

Result JSON

Variable
Type
Description

result

boolean

true if user stats were returned.

results

unsigned int

The number of Transfers Object's returned in transfers.

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.

Intervals

Intervals may be from 1-hour 3600 seconds to 1-week 604800 seconds. Intervals MUST be in multiples of 3600.

Omitting will create an interval that is 30 parts of the start or end dates.

Requesting more than 60 results will cause an error.

Suggest Edits

Account Stats Recent

This endpoint gets the recent stats for the past 15 hours for your entire account.

 
get/stats/recent
$ curl https://go.fast.io/api/v1.x/stats/recent \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 30,
    "interval": 1800,
    "transfers": [
        {
            "transfers": 129,
            "bytes": 995662,
            "start": "2018-07-09 02:00:00 UTC",
            "end": "2018-07-09 02:30:00 UTC"
        },
        {
            "transfers": 2,
            "bytes": 15416,
            "start": "2018-07-09 02:30:00 UTC",
            "end": "2018-07-09 03:00:00 UTC"
        },
        {
            "transfers": 1,
            "bytes": 7702,
            "start": "2018-07-09 03:00:00 UTC",
            "end": "2018-07-09 03:30:00 UTC"
        },
        {
            "transfers": 13,
            "bytes": 100243,
            "start": "2018-07-09 03:30:00 UTC",
            "end": "2018-07-09 04:00:00 UTC"
        },
        {
            "transfers": 71,
            "bytes": 547929,
            "start": "2018-07-09 04:00:00 UTC",
            "end": "2018-07-09 04:30:00 UTC"
        },
        {
            "transfers": 145,
            "bytes": 1119094,
            "start": "2018-07-09 04:30:00 UTC",
            "end": "2018-07-09 05:00:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165783,
            "start": "2018-07-09 05:00:00 UTC",
            "end": "2018-07-09 05:30:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165664,
            "start": "2018-07-09 05:30:00 UTC",
            "end": "2018-07-09 06:00:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165611,
            "start": "2018-07-09 06:00:00 UTC",
            "end": "2018-07-09 06:30:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165589,
            "start": "2018-07-09 06:30:00 UTC",
            "end": "2018-07-09 07:00:00 UTC"
        },
        {
            "transfers": 115,
            "bytes": 887748,
            "start": "2018-07-09 07:00:00 UTC",
            "end": "2018-07-09 07:30:00 UTC"
        },
        {
            "transfers": 145,
            "bytes": 1119242,
            "start": "2018-07-09 07:30:00 UTC",
            "end": "2018-07-09 08:00:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165552,
            "start": "2018-07-09 08:00:00 UTC",
            "end": "2018-07-09 08:30:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165589,
            "start": "2018-07-09 08:30:00 UTC",
            "end": "2018-07-09 09:00:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165589,
            "start": "2018-07-09 09:00:00 UTC",
            "end": "2018-07-09 09:30:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165636,
            "start": "2018-07-09 09:30:00 UTC",
            "end": "2018-07-09 10:00:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165577,
            "start": "2018-07-09 10:00:00 UTC",
            "end": "2018-07-09 10:30:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165703,
            "start": "2018-07-09 10:30:00 UTC",
            "end": "2018-07-09 11:00:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165569,
            "start": "2018-07-09 11:00:00 UTC",
            "end": "2018-07-09 11:30:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165619,
            "start": "2018-07-09 11:30:00 UTC",
            "end": "2018-07-09 12:00:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165705,
            "start": "2018-07-09 12:00:00 UTC",
            "end": "2018-07-09 12:30:00 UTC"
        },
        {
            "transfers": 76,
            "bytes": 586640,
            "start": "2018-07-09 12:30:00 UTC",
            "end": "2018-07-09 13:00:00 UTC"
        },
        {
            "transfers": 92,
            "bytes": 710238,
            "start": "2018-07-09 13:00:00 UTC",
            "end": "2018-07-09 13:30:00 UTC"
        },
        {
            "transfers": 101,
            "bytes": 779667,
            "start": "2018-07-09 13:30:00 UTC",
            "end": "2018-07-09 14:00:00 UTC"
        },
        {
            "transfers": 103,
            "bytes": 795280,
            "start": "2018-07-09 14:00:00 UTC",
            "end": "2018-07-09 14:30:00 UTC"
        },
        {
            "transfers": 150,
            "bytes": 1157928,
            "start": "2018-07-09 14:30:00 UTC",
            "end": "2018-07-09 15:00:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165815,
            "start": "2018-07-09 15:00:00 UTC",
            "end": "2018-07-09 15:30:00 UTC"
        },
        {
            "transfers": 151,
            "bytes": 1165831,
            "start": "2018-07-09 15:30:00 UTC",
            "end": "2018-07-09 16:00:00 UTC"
        },
        {
            "transfers": 148,
            "bytes": 1142463,
            "start": "2018-07-09 16:00:00 UTC",
            "end": "2018-07-09 16:30:00 UTC"
        },
        {
            "transfers": 134,
            "bytes": 1034656,
            "start": "2018-07-09 16:30:00 UTC",
            "end": "2018-07-09 17:00:00 UTC"
        }
    ]
}
 

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.

Result Codes

HTTP Results
Description

200

The request and resource are valid and Transfers Object's are returned.

Variable
Type
Description

result

boolean

true if transfers are returned.

results

unsigned integer

The number of interval Transfers Object's returned in transfers.

interval

unsigned integer

The time in seconds each transfer object covers.

transfers

list of Transfers Object's

List of Transfers Object's for the recent period.

Rate Limit

Because of the cost of this resource, calls are rate limited.

Suggest Edits

Server Stats

This endpoint gets the transfer statistics for a server for a given period.

 
get/stats/server/server?interval=:interval&start=start&end=end
$ curl https://go.fast.io/api/v1.x/stats/server/MyDropboxServer.imfast.io?start=2018-04-10+13%3A26%3A09+UTC \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 5,
    "server": "mydropboxserver.imfast.io",
    "interval": 192000,
    "transfers": [
        {
            "transfers": 3204,
            "bytes": "23030832",
            "start": "2018-04-10 13:26:09 UTC",
            "end": "2018-04-12 18:46:09 UTC"
        },
        {
            "transfers": "3193",
            "bytes": "22965245",
            "start": "2018-04-12 18:46:09 UTC",
            "end": "2018-04-15 00:06:09 UTC"
        },
        {
            "transfers": "3200",
            "bytes": "23009946",
            "start": "2018-04-15 00:06:09 UTC",
            "end": "2018-04-17 05:26:09 UTC"
        },
        {
            "transfers": "3211",
            "bytes": "23072252",
            "start": "2018-04-17 05:26:09 UTC",
            "end": "2018-04-19 10:46:09 UTC"
        },
        {
            "transfers": "1609",
            "bytes": "11576125",
            "start": "2018-04-19 10:46:09 UTC",
            "end": "2018-04-20 13:36:09 UTC"
        }
    ]
}

Path Params

server
string
required

The name and domain name combined with a period separating them. This string must meet the requirements for a valid name and domain.

Query Params

start
string
required

The start datetime to use when retrieving transfer statistics.

end
string

The end datetime to use when retrieving transfer statistics.

 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the user stats are returned in the body.

Result JSON

Variable
Type
Description

result

boolean

true if user stats were returned.

results

unsigned int

The number of Transfers Object's returned in transfers.

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.

Intervals

Intervals may be from 1-hour 3600 seconds to 1-week 604800 seconds. Omitting will create an interval that is 30 parts of the start or end dates.

Requesting more than 60 results will cause an error.

Suggest Edits

Server Stats Recent

This endpoint gets the recent stats for the past 15 hours for a particular Server.

 
get/stats/server/recent/server
$ curl https://go.fast.io/api/v1.x/stats/server/recent/MyDropboxServer.imfast.io \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 30,
    "server": "mydropboxserver.imfast.io",
    "interval": 1800,
    "transfers": [
        {
            "transfers": 24,
            "bytes": 185126,
            "start": "2018-07-09 02:00:00 UTC",
            "end": "2018-07-09 02:30:00 UTC"
        },
        {
            "transfers": 0,
            "bytes": 0,
            "start": "2018-07-09 02:30:00 UTC",
            "end": "2018-07-09 03:00:00 UTC"
        },
        {
            "transfers": 0,
            "bytes": 0,
            "start": "2018-07-09 03:00:00 UTC",
            "end": "2018-07-09 03:30:00 UTC"
        },
        {
            "transfers": 0,
            "bytes": 0,
            "start": "2018-07-09 03:30:00 UTC",
            "end": "2018-07-09 04:00:00 UTC"
        },
        {
            "transfers": 16,
            "bytes": 123438,
            "start": "2018-07-09 04:00:00 UTC",
            "end": "2018-07-09 04:30:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231421,
            "start": "2018-07-09 04:30:00 UTC",
            "end": "2018-07-09 05:00:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231468,
            "start": "2018-07-09 05:00:00 UTC",
            "end": "2018-07-09 05:30:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231412,
            "start": "2018-07-09 05:30:00 UTC",
            "end": "2018-07-09 06:00:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231369,
            "start": "2018-07-09 06:00:00 UTC",
            "end": "2018-07-09 06:30:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231457,
            "start": "2018-07-09 06:30:00 UTC",
            "end": "2018-07-09 07:00:00 UTC"
        },
        {
            "transfers": 21,
            "bytes": 162087,
            "start": "2018-07-09 07:00:00 UTC",
            "end": "2018-07-09 07:30:00 UTC"
        },
        {
            "transfers": 29,
            "bytes": 223717,
            "start": "2018-07-09 07:30:00 UTC",
            "end": "2018-07-09 08:00:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231466,
            "start": "2018-07-09 08:00:00 UTC",
            "end": "2018-07-09 08:30:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231460,
            "start": "2018-07-09 08:30:00 UTC",
            "end": "2018-07-09 09:00:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231376,
            "start": "2018-07-09 09:00:00 UTC",
            "end": "2018-07-09 09:30:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231416,
            "start": "2018-07-09 09:30:00 UTC",
            "end": "2018-07-09 10:00:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231470,
            "start": "2018-07-09 10:00:00 UTC",
            "end": "2018-07-09 10:30:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231555,
            "start": "2018-07-09 10:30:00 UTC",
            "end": "2018-07-09 11:00:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231472,
            "start": "2018-07-09 11:00:00 UTC",
            "end": "2018-07-09 11:30:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231482,
            "start": "2018-07-09 11:30:00 UTC",
            "end": "2018-07-09 12:00:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231543,
            "start": "2018-07-09 12:00:00 UTC",
            "end": "2018-07-09 12:30:00 UTC"
        },
        {
            "transfers": 13,
            "bytes": 100268,
            "start": "2018-07-09 12:30:00 UTC",
            "end": "2018-07-09 13:00:00 UTC"
        },
        {
            "transfers": 17,
            "bytes": 131178,
            "start": "2018-07-09 13:00:00 UTC",
            "end": "2018-07-09 13:30:00 UTC"
        },
        {
            "transfers": 18,
            "bytes": 138904,
            "start": "2018-07-09 13:30:00 UTC",
            "end": "2018-07-09 14:00:00 UTC"
        },
        {
            "transfers": 20,
            "bytes": 154469,
            "start": "2018-07-09 14:00:00 UTC",
            "end": "2018-07-09 14:30:00 UTC"
        },
        {
            "transfers": 29,
            "bytes": 223794,
            "start": "2018-07-09 14:30:00 UTC",
            "end": "2018-07-09 15:00:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231578,
            "start": "2018-07-09 15:00:00 UTC",
            "end": "2018-07-09 15:30:00 UTC"
        },
        {
            "transfers": 30,
            "bytes": 231587,
            "start": "2018-07-09 15:30:00 UTC",
            "end": "2018-07-09 16:00:00 UTC"
        },
        {
            "transfers": 27,
            "bytes": 208418,
            "start": "2018-07-09 16:00:00 UTC",
            "end": "2018-07-09 16:30:00 UTC"
        },
        {
            "transfers": 27,
            "bytes": 208402,
            "start": "2018-07-09 16:30:00 UTC",
            "end": "2018-07-09 17:00:00 UTC"
        }
    ]
}

Path Params

server
string
required

The name and domain name combined with a period separating them. This string must meet the requirements for a valid name and domain.

 

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.

Result Codes

HTTP Results
Description

200

The request and resource are valid and Transfers Object's are returned.

Variable
Type
Description

result

boolean

true if transfers are returned.

results

unsigned integer

The number of interval Transfers Object's returned in transfers.

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.

transfers

list of Transfers Object's

List of Transfers Object's for the recent period.

Rate Limit

Because of the cost of this resource, calls are rate limited.

Suggest Edits

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.

Field
Type
Description

entry_id

string

A permanent unique id string to describe this entry. Strings is 15 characters in length.

name

string

The Server that served the request.

domain

string

The domain name associated with the server.

server

string

The fqdn which is the name and the domain of the server.

cdn

string

The CDN Provider that fulfilled the request.

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.

Suggest Edits

Logs Retrieve

This endpoint gets the account logs for a time range for a particular Server.

 
get/log/server?start=start&end=end&format=format
$ curl https://go.fast.io/api/v1.x/log/MyDropboxServer.imfast.io?start=2018-04-20&end=2018-04-21 \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 2,
    "records": [
        {
            "entry_id": "234078288",
            "name": "mydropboxserver",
            "domain": "imfast.io",
            "server": "mydropboxserver.imfast.io",
            "cdn": "akamai",
            "client_uuid": "23.212.108.46.304741539955611311",
            "client_referer": null,
            "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.124 Safari/537.36",
            "client_ip": "109.123.101.103",
            "client_country": "GB",
            "client_region": "EN",
            "client_city": "LONDON",
            "client_long": "-0.12",
            "client_lat": "51.5",
            "client_asn": 13213,
            "content_type": "image/png",
            "content_lastmod": "2018-10-19 13:27:21",
            "transfer_code": "200",
            "request_path": "/fast.io.png",
            "request_method": "GET",
            "request_secure": "Yes",
            "request_proto": "1.1",
            "transfer_result": "Success",
            "transfer_size": 7100,
            "transfer_size_total": 7407,
            "transfer_start": "2018-10-19 13:26:49 GMT",
            "transfer_seconds": 1859,
            "request_url": "https://mydropboxserver.imfast.io/fast.io.png"
        },
        {
            "entry_id": "234154560",
            "name": "mydropboxserver",
            "domain": "imfast.io",
            "server": "mydropboxserver.imfast.io",
            "cdn": "akamai",
            "client_uuid": "2.20.132.76.185501539955669416",
            "client_referer": null,
            "client_user_agent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.2117.157 Safari/537.36",
            "client_ip": "188.138.40.20",
            "client_country": "FR",
            "client_region": "GES",
            "client_city": "STRASBOURG",
            "client_long": "7.79",
            "client_lat": "48.6",
            "client_asn": 8972,
            "content_type": "image/png",
            "content_lastmod": "2018-10-19 13:28:19",
            "transfer_code": "200",
            "request_path": "/fast.io.png",
            "request_method": "GET",
            "request_secure": "Yes",
            "request_proto": "1.1",
            "transfer_result": "Success",
            "transfer_size": 7100,
            "transfer_size_total": 7405,
            "transfer_start": "2018-10-19 13:27:49 GMT",
            "transfer_seconds": 351,
            "request_url": "https://mydropboxserver.imfast.io/fast.io.png"
        }
    ]
}
{
    "result": false,
    "error": {
        "code": 46197,
        "text": "Too many requests made. Enhance your calm."
    }
}

Path Params

server
string
required

The name and domain name combined to check if its both valid and available. This string must meet the requirements for a valid name and domain.

Query Params

start
date
required

The start datetime to use when retrieving log records.

end
date

The end datetime to use when retrieving log records.

format
string

The response format you would like from this API.

 

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

HTTP Results
Description

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.

Variable
Type
Description

result

boolean

true if logs are returned.

records

list of log record object

List of log record objects for transfers matching the timeframe.

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.

Suggest Edits

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.

Suggest Edits

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.

Fixed Fields

This object is read-only.

Field
Type
Description

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.

States of Changes Object

There are three basic states to monitor for.

State
Completed
Stale
Desc

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.

Suggest Edits

Changes List

This endpoint provides a list of all known changes status.

 
get/server/changes/list/
$ curl https://go.fast.io/api/v1.x/server/changes/list/ \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 2,
    "jobs": [
        "mydropboxserver.imfast.io",
        "mygoogledrive.imfast.io"
    ]
}
 

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

HTTP Results
Description

200

The request and resource are valid and the status is returned in the changes node.

Result JSON

Variable
Type
Description

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.

Suggest Edits

Changes Status

This endpoint provides the full status of all known Change statuses.

 
get/server/changes/status/
$ curl https://go.fast.io/api/v1.x/server/changes/status/ \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 1,
    "changes": [
        {
            "name": "mydropboxserver",
            "domain": "imfast.io",
            "server": "mydropboxserver.imfast.io",
            "waited": 12,
            "remaining": 0,
            "extensions": 5,
            "changes": [
                "/"
            ],
            "complete": true,
            "stale": false,
            "started": "2018-11-24 01:14:38 UTC",
            "last": "2018-11-24 01:14:45 UTC",
            "updated": "2018-11-24 01:14:50 UTC"
        }
    ]
}
 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the status is returned in the changes node.

Result JSON

Variable
Type
Description

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.

Suggest Edits

Changes Status Server

This endpoint provides details on a Changes Status for a given Server.

 
get/server/changes/status/server
$ curl https://go.fast.io/api/v1.x/server/changes/status/MyDropboxServer.imfast.io
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "change": {
        "name": "mydropboxserver",
        "domain": "imfast.io",
        "server": "mydropboxserver.imfast.io",
        "waited": 12,
        "remaining": 0,
        "extensions": 5,
        "changes": [
            "/"
        ],
        "complete": true,
        "stale": false,
        "started": "2018-11-24 01:14:38 UTC",
        "last": "2018-11-24 01:14:45 UTC",
        "updated": "2018-11-24 01:14:50 UTC"
    }
}

Path Params

server
string
required

The name and domain name combined with a period separating them. This string must meet the requirements for a valid name and domain.

 

Result Codes

HTTP Results
Description

200

true if the request was valid and processed.

404

No changes were found for the provided credentials.

Result JSON

Variable
Type
Description

result

boolean

true if the status was found and returned.

change

object | null

A Change 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.

Suggest Edits

Changes Run Stale

This endpoint processes Changes received but not processed automatically, yet.

 
post/server/changes/runstale/server
$ curl https://go.fast.io/api/v1.x/server/changes/runstale/MyDropboxServer.imfast.io
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true
}

Path Params

server
string
required

The name and domain name combined to check if its both valid and available. This string must meet the requirements for a valid name and domain.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

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.

Suggest Edits

Flush Object

Lookup the last time a path was flushed on a Server.

 

Flush Object

The flush object is used in Lookups and History results.

Variable
Type
Description

name

string

The name of the Server Config name associated with this flush.

domain

string

The domain this Server is assigned to.

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.

Suggest Edits

Flush Cache

Flushes the cache for a Server or part of a Server

 
post/server/flush/server?path
$ curl https://go.fast.io/api/v1.x/server/flush/MyDropboxServer.imfast.io?/folder/ \
			-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

server
string
required

The name and domain name combined with a period separating them. This string must meet the requirements for a valid name and domain.

Query Params

path
string

The path to the File or Folder to flush. A string length of 1 to 1024 characters is supported.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

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.

Suggest Edits

Flush Lookup

Lookup the last time a path was flushed on a Server.

 
get/server/flush/lookup/:fqdn?path
$ curl https://go.fast.io/api/v1.x/server/flush/lookup/MyDropboxServer.imfast.io?/folder/ \
			-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "flush": {
        "name": "MyDropboxServer",
      	"domain": "imfast.io",
        "server": "mydropboxserver.imfast.io",
        "path": "/folder",
        "flushed": "2018-03-29 22:00:40 UTC"
    }
}

Path Params

server
string
required

The name and domain name combined to check if its both valid and available. This string must meet the requirements for a valid name and domain.

Query Params

path
string

The path to the File or Folder to get the last flush date of. A string length of 1 to 1024 characters is supported.

 

Result Codes

HTTP Results
Description

200

The request was valid and the last time this path was flushed is returned.

Result JSON

Variable
Type
Description

result

boolean

true if the flush lookup time was provided.

flush

object

A Flush Object with the requested path result.

Flush Lookup is Exact Path

The flush time of the path is specifically for the provided path, not for any parents or children.

Suggest Edits

Flush History

Get the Flush history of paths on a Server.

 
get/server/flush/history/server
$ curl https://go.fast.io/api/v1.x/server/flush/history/MyDropboxServer.imfast.io \
			-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 2,
    "flushes": [
        {
            "name": "MyDropboxServer",
            "domain": "imfast.io",
            "server": "mydropboxserver.imfast.io",
            "path": "/Folder1",
            "flushed": "2018-06-11 22:20:39 UTC"
        },
        {
            "name": "MyDropboxServer",
            "domain": "imfast.io",
            "server": "mydropboxserver.imfast.io",
            "path": "/folder2/FOLDER3",
            "flushed": "2018-06-11 22:20:24 UTC"
        }
    ]
}

Path Params

server
string
required

The name and domain name combined to check if its both valid and available. This string must meet the requirements for a valid name and domain.

 

Result Codes

HTTP Results
Description

200

The request was valid and the last time this path was flushed is returned.

Result JSON

Variable
Type
Description

result

boolean

true if the flush lookup time was provided.

results

int

The number of Flush Object's returned.

flushes

object

An array of Flush Object showing the history of the servers CDN flushing.

Ordering of Results

This API shows the last 50 flush events to the specified server. This includes flushes initiated by the API or through automatic processes.

Suggest Edits

Pre Cache Object

An object containing job information of pre-cache instances currently active and recently completed.

 

Fixed Fields

This object is read-only.

Field
Type
Description

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.

Status

Status
Description

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.

Depth

The value of each node in the path field indicates the depth for that path to be pre-cached.

Depth
Description

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.

Suggest Edits

Pre Cache

Populates the cache for a Server or a given path for a Server.

 
post/server/precache/server?path
$ curl https://go.fast.io/api/v1.x/server/precache/MyDropboxServer.imfast.io?/folder/ \
    -X POST \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
    -d event=true \
    -d data=false
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

server
string
required

The name and domain name combined to check if its both valid and available. This string must meet the requirements for a valid name and domain.

Query Params

path
string

The path to the File or Folder to precache. A string length of 1 to 1024 characters is supported.

Body Params

event
boolean

Create an event when pre-caching is complete or fails.

data
boolean

Cache the data as well as the metadata.

flush
boolean

Flush the path before pre-caching it.

depth
string

The depth from the specified path to pre-cache data. See table below.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

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.

Suggest Edits

Pre Cache Cancel

This endpoint cancels an in-progress pre-cache job.

 
post/server/precache/cancel/server
$ curl https://go.fast.io/api/v1.x/server/precache/cancel/MyDropboxServer.imfast.io \
    -X POST \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

server
string
required

The name and domain name combined to check if its both valid and available. This string must meet the requirements for a valid name and domain.

 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the job was canceled.

404

No job was found to cancel.

405

The job was not in a valid state to cancel.

Result JSON

Variable
Type
Description

result

boolean

true if an active job was found an canceled.

Suggest Edits

Pre Cache List

This endpoint provides a list of all known pre-cache jobs.

 
get/server/precache/list/
$ curl https://go.fast.io/api/v1.x/server/precache/list/ \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 2,
    "jobs": [
        "mydropboxserver.imfast.io",
        "mygoogledrive.imfast.io"
    ]
}
 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the status is returned in the jobs node.

Result JSON

Variable
Type
Description

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.

Suggest Edits

Pre Cache Details

This endpoint provides full status of all known pre-cache jobs.

 
get/server/precache/details/key
$ curl https://go.fast.io/api/v1.x/server/precache/details/9gsd9 \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "job": {
        "key": "9gsd9",
        "name": "mydropboxserver",
        "domain": "imfast.io",
        "server": "mydropboxserver.imfast.io",
        "status": "completed",
    	  "path": {
  	      "/": "myself"
	      },
        "path_curr": null,
        "data": false,
        "flush": false,
        "event": true,
        "preempts": 0,
        "prempted": null,
        "folders": 3,
        "files": 1,
        "bytes": 0,
        "stale" : false,
        "started": "2018-06-25 18:49:52 UTC",
        "updated": "2018-06-25 18:49:53 UTC",
        "ended": "2018-06-25 18:49:53 UTC"
    }
}

Path Params

key
string
required

The 5 character alphanumeric job key to get the details of. Case sensitive.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

result

boolean

true if the request was valid and returned.

job

A Job Object associated with the key.

Suggest Edits

Pre Cache Status

This endpoint provides full status of all known pre-cache jobs.

 
get/server/precache/status/
$ curl https://go.fast.io/api/v1.x/server/precache/status/ \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 2,
    "jobs": [
        {
            "key": "Z8cbj",
            "name": "MyDropboxServer",
            "domain": "imfast.io",
            "server": "mydropboxserver.imfast.io",
            "status": "completed",
            "path": {
              "/": "myself"
            },
            "path_curr": "/",
            "data": true,
            "flush": false,
            "event": true,
            "preempts": 0,
            "folders": 1,
            "files": 1,
            "bytes": 7100,
            "stale" : false,
            "started": "2018-06-24 20:15:56 UTC",
            "updated": "2018-06-24 20:15:57 UTC",
            "ended": "2018-06-24 20:15:57 UTC"
        },
        {
            "key": "HmVRx",
            "name": "MyGoogleDrive",
            "domain": "imfast.io",
            "status": "completed",
            "path": {
              "/": "myself"
            },
            "path_curr": "/",
            "data": true,
            "flush": false,
            "event": true,
            "preempts": 0,
            "folders": 1,
            "files": 1,
            "bytes": 7100,
            "stale" : false,
            "started": "2018-06-24 19:54:38 UTC",
            "updated": "2018-06-24 19:54:38 UTC",
            "ended": null
        }
    ]
}
 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the status is returned in the jobs node.

Result JSON

Variable
Type
Description

result

boolean

true if the request was valid and returned.

results

int

The number of job objects returned in jobs.

jobs

array of Job Object's

An array of Job Object's associated with the account credentials.

Suggest Edits

Pre Cache Status Server

This endpoint provides details on a precache job for a given Server.

 
get/server/precache/status/server
$ curl https://go.fast.io/api/v1.x/server/precache/status/MyDropboxServer.imfast.io
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "job": {
        "key": "Z8cbk",
        "name": "MyDropboxServer",
        "domain": "imfast.io",
        "server": "mydropboxserver.imfast.io",
        "status": "completed",
    	  "path": {
  	      "/": "all_children"
	      },
        "path_curr": "/",
        "data": true,
        "flush": false,
        "event": true,
        "preempts": 0,
        "folders": 1,
        "files": 10,
        "bytes": 7100,
        "stale" : false,
        "started": "2018-06-24 20:15:56 UTC",
        "updated": "2018-06-24 20:15:57 UTC",
        "ended": "2018-06-24 20:15:57 UTC"
    }
}

Path Params

server
string
required

The name and domain name combined with a period separating them. This string must meet the requirements for a valid name and domain.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

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.

Suggest Edits

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
Type
Desc

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.

Subscription Object

Name
Type
Desc

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

Field
Type
Desc

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.

Bank Account Object

Field
Type
Desc

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.

Suggest Edits

Get Plan

This endpoint gets the current credentials plan regardless of subscription status.

 
get/billing/plan/details
$ curl https://go.fast.io/api/v1.x/billing/plan/details \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "plan": {
        "name": "6cPerGBMonthly",
        "desc": "Metered biling at 6 cents per GB transfered + 50GB free, $7 base fee, billed monthly",
        "price_base": 7,
        "price_meter": 0.06,
        "unit": 1073741824,
        "billed": "monthly",
        "free": false,
        "free_units": 50,
        "free_days": 0,
        "discount": null,
        "available": true
    }
}
 

Result Codes

HTTP Results
Description

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.

Result JSON

Variable
Type
Description

result

boolean

true if the request was successful and an array of Plan objects are returned.

plan

Plan object

The Plan object related to the plan.

Suggest Edits

List Plans

This endpoint gets a list of available plans for the current account credentials.

 
get/billing/plan/list
$ curl https://go.fast.io/api/v1.x/billing/plan/list \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 2,
    "default": "FreeTier",
    "plans": [
        {
            "name": "FreeTier",
            "desc": "Free Tier of usage has no fees associated with it but specific usage limits on a calander month basis.",
            "price_base": 0,
            "price_meter": 0,
            "unit": 1073741824,
            "billed": "monthly",
            "free": true,
            "free_units": 50,
            "free_days": 0,
            "discount": null,
            "available": true
        },
        {
            "name": "6cPerGBMonthly",
            "desc": "Metered biling at 6 cents per GB transfered + 50GB free, $7 base fee, billed monthly",
            "price_base": 7,
            "price_meter": 0.06,
            "unit": 1073741824,
            "billed": "monthly",
            "free": false,
            "free_units": 50,
            "free_days": 0,
            "discount": null,
            "available": true
        }
    ]
}
 

Result Codes

HTTP Results
Description

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.

Result JSON

Variable
Type
Description

result

boolean

true if the request was successful and an array of Plan objects are returned.

results

integer

The number of Plan objects returned in the plans node.

plans

Array of Plan objects

An array of Plan objects available to the current credentials.

Suggest Edits

Get Public Key

This endpoint gets public keys related to subscriptions for the current credentials.

 
get/billing/keys
$ curl https://go.fast.io/api/v1.x/billing/keys \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "mode": "live",
    "payment_token_key": "pk_live_HDHRlEg23JZa2HuIeKnXycro"
}
 

Result Codes

HTTP Results
Description

200

The request and resource are valid public keys are returned.

429

Too many requests were made in too short a period of time.

Result JSON

Variable
Type
Description

result

boolean

true if the request was successful and an array of Plan objects are returned.

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.

Suggest Edits

Create Subscription

This endpoint adds a subscription, payment type, and plan to the current account.

 
post/billing
$ curl https://go.fast.io/api/v1.x/billing \
    -X POST \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
    -d plan=5cPerGBMonthly \
    -d payment_token=tok_1CkJGnDfm13tdY3MAr5DHmd5
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Query Params

plan
string
required

The subscription plan to use with this account.

payment_token
string
required

The stripe token generated by Stripe Elemental collection.

 

Result Codes

HTTP Results
Description

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 JSON cancellation

Variable
Type
Description

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.

Suggest Edits

Billing Details

This endpoint gets details on the current users paid subscription.

 
get/billing/details
$ curl https://go.fast.io/api/v1.x/billing/details \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "subscription": {
        "active": true,
        "account_balance": 0.0,
        "currency": "usd",
        "delinquent": false,
        "plan": {
            "name": "5cPerGBMonthly",
            "desc": "Metered Monthly Biling at 5 cents per GB",
            "price": 0.05,
            "unit": 1073741824,
            "billed": "monthly",
            "free_units": 20,
            "free_days": 0,
            "discount": null,
            "available": true
        },
        "canceled_at": null,
        "payment": {
            "type": "credit",
            "brand": "Visa",
            "last4": "4242",
            "exp_month": 3,
            "exp_year": 2020,
            "zip": "94105"
        },
        "current_period_start": "2018-07-07 20:50:56 UTC",
        "current_period_end": "2018-08-07 20:50:56 UTC",
        "created": "2018-07-07 20:50:55 UTC"
    }
}
 

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.

Result Codes

HTTP Results
Description

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 JSON cancellation

Variable
Type
Description

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.

Suggest Edits

Update Subscription

This endpoint updates an existing subscriptions payment type or plan to the current account.

 
post/billing
$ curl https://go.fast.io/api/v1.x/billing \
    -X POST \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72" \
    -d plan=5cPerGBWeekly \
    -d payment_token=tok_1CkJGnDfm13tdY3MAr5DHmd5
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Query Params

plan
string

The subscription plan to use with this account.

payment_token
string

The stripe token generated by Stripe Elemental collection.

 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

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.

Suggest Edits

Cancel Subscription

This endpoint cancels a subscription to the current account.

 
delete/billing
$ curl https://go.fast.io/api/v1.x/billing \
    -X DELETE \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}
 

Result Codes

HTTP Results
Description

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 JSON

Variable
Type
Description

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.

Suggest Edits

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

Name
Type
Desc

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.

States

State
Desc

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

Usage Object May Be Null

If an invoice object has no usage associated with it, the usage object will be set to null.

Name
Type
Desc

amount

float

The amount of cost associated with the units and plan.

units

integer

The units consumed in the unit of the plan.

plan

The plan object associated with this usage.

Suggest Edits

List Invoices

This endpoint gets a list of the invoices associated with the current account.

 
get/billing/invoices/list
$ curl https://go.fast.io/api/v1.x/billing/invoices/list \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 1,
    "invoices": [
        {
            "id": "in_1C2NMqDfm13tdY3mNzUEtopj",
            "total": 0.0,
            "currency": "usd",
            "starting_balance": 0.0,
            "subtotal": 0.0,
            "tax": 0.0,
            "amount_paid": 0.0,
            "amount_due": 0.0,
            "usage": {
                "amount": 0.0,
                "units": 0,
                "plan": {
                    "name": "5cPerGBMonthly",
                    "desc": "Metered Monthly Biling at 5 cents per GB",
                    "price": 0.05,
                    "unit": 1073741824,
                    "billed": "monthly",
                    "free_units": 20,
                    "free_days": 0,
                    "discount": null,
                    "available": true
                }
            },
            "invoice_web": "https://pay.stripe.com/invoice/invst_p9q95rXgX0bIC0soXAInJoe4xS",
            "invoice_pdf": "https://pay.stripe.com/invoice/invst_p9q95rXgX0bIC0soXAInJoe4xS/pdf",
            "period_start": "2018-07-07 20:50:56 UTC",
            "period_end": "2018-07-07 20:50:56 UTC",
            "next_payment_attempt": null,
            "created": "2018-07-07 20:50:56 UTC"
        }
    ]
}
 

Result Codes

HTTP Results
Description

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 JSON cancellation

Variable
Type
Description

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.

invoice

Array of Invoice Objects

An array of Invoice Objects associated with the current account.

Suggest Edits

Get Usage

This endpoint gets the current usage information based on the user's plan.

 
get/billing/usage/
$ curl https://go.fast.io/api/v1.x/billing/usage/ \
		-H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "plan": {
        "name": "6cPerGBMonthly",
        "desc": "Metered biling at 6 cents per GB transfered + 50GB free, $7 base fee, billed monthly",
        "price_base": 7,
        "base_id": "MeteredBaseFee",
        "price_meter": 0.06,
        "meter_id": "6cPerGBMonthly",
        "unit": 1073741824,
        "billed": "monthly",
        "free": false,
        "free_units": 50,
        "free_days": 0,
        "discount": null,
        "available": true
    },
    "transfers": {
        "transfers": "154386",
        "bytes": "1476139830",
        "start": "2018-09-01 00:00:00 UTC",
        "end": "2018-09-30 23:59:59 UTC"
    },
    "usage": {
        "period": "monthly",
        "days_total": 30,
        "days_elapsed": 25,
        "days_remaining": 5,
        "used": "1476139830",
        "total": null,
        "avail": null,
        "avail_precent": null
    }
}
 

Result Codes

HTTP Results
Description

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.

Result JSON

Variable
Type
Description

result

boolean

true if the request was successful and an array of Plan objects are returned.

plan

Plan object

The Plan object related to the plan.

transfers

Transfers object

The Transfers object for the current plan period.

usage

object

The usage object as defined below.

Usage Object

The usage object indicates your plan limits and remaining availability.

Field
Type
Description

period

string

The billed period from the Get Plan object that usage is calculated based on.

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.

Suggest Edits

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.

Field
Type
Description

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.

Category

Name
Description

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.

Suggest Edits

Events

This endpoint returns events for the account or a specific server.

 
get/events/?limit=limit&alarm
$ curl https://go.fast.io/api/v1.x/events/ \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 4,
    "events": [
        {
            "id": "MzQ5MDkyM4",
            "server": null,
            "category": "notice",
            "code" : 10002,
            "subject": "Password Changed",
            "desc": "Your Password was changed.",
            "created": "2018-02-19 21:03:50 UTC",
            "alarm": false,
            "acknowledged": null,
            "resolved": null
        },
        {
            "id": "MzQ5MekyM1",
            "server": "mydropboxserver.imfast.io",
            "category": "error",
            "code" : 10000,
            "subject": "Permission Denied",
            "desc": "We were unable to access the cloud storage provider for this Server due to an authentication error.",
            "created": "2018-03-21 21:03:50 UTC",
            "alarm": true,
            "acknowledged": null,
            "resolved": null
        },
        {
            "id": "MzQ5MDkyM2",
            "server": "mydropboxserver.imfast.io",
            "category": "error",
            "code" : 10001,
            "subject": "Missing Folder",
            "desc": "The 'root' folder for this server, 'MyBoxServer' was not found on the cloud storage provider.  Please login to Box and resolve this issue.",
            "created": "2018-02-19 22:03:50 UTC",
            "alarm": true,
            "acknowledged": "2018-02-19 23:03:50 UTC",
            "resolved": "2018-02-19 24:03:50 UTC"
        },
        {
            "id": "MzQ5MDkyM3",
            "server": "mydropboxserver.imfast.io",
            "category": "error",
            "code" : 10001,
          "subject": "Missing Folder",
            "desc": "The 'root' folder for this server, 'MyOneDriveServer' was not found on the cloud storage provider.  Please login to OneDrive and resolve this issue.",
            "created": "2018-02-20 21:03:50 UTC",
            "alarm": true,
            "acknowledged": "2018-02-20 22:03:50 UTC",
            "resolved": null
        }
    ]
}

Query Params

limit
string

Limit the number of items you would like to receive in the response. This cannot exceed the maximum return value specified for the call.

alarm
boolean

If alarm is set, this API will only return events that match the other criteria and have an alarm set.

unresolved
boolean

If unresolved is set, this API will only return events that match the other criteria and have an not been resolved.

unack
boolean

If unack is set, this API will only return events that match the other criteria and have an not been acknowledged.

noserver
boolean

If noserver is set, only events that have no server assigned are returned.

anyserver
boolean

If anyserver is set, only events that have a server assigned are returned.

 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the request was processed.

Result JSON

Variable
Type
Description

result

boolean

true if the events request was accepted and returned.

results

integer

The number of results returned in the events array.

events

array

An array of Event Object's.

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.

Suggest Edits

Events for Server

This endpoint returns events for a specific server.

 
get/events/server?limit=limit&alarm
$ curl https://go.fast.io/api/v1.x/events/MyDropboxServer.imfast.io \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 4,
    "events": [
        {
            "id": "MzQ5MDkyM4",
            "server": "mydropboxserver.imfast.io",
            "category": "notice",
            "code" : 10002,
            "subject": "Password Changed",
            "desc": "Your Password was changed.",
            "created": "2018-02-19 21:03:50 UTC",
            "alarm": false,
            "acknowledged": null,
            "resolved": null
        },
        {
            "id": "MzQ5MekyM1",
            "server": "mydropboxserver.imfast.io",
            "category": "error",
            "code" : 10000,
            "subject": "Permission Denied",
            "desc": "We were unable to access the cloud storage provider for this Server due to an authentication error.",
            "created": "2018-03-21 21:03:50 UTC",
            "alarm": true,
            "acknowledged": null,
            "resolved": null
        },
        {
            "id": "MzQ5MDkyM2",
            "server": "mydropboxserver.imfast.io",
            "category": "error",
            "code" : 10001,
            "subject": "Missing Folder",
            "desc": "The 'root' folder for this server, 'MyBoxServer' was not found on the cloud storage provider.  Please login to Box and resolve this issue.",
            "created": "2018-02-19 22:03:50 UTC",
            "alarm": true,
            "acknowledged": "2018-02-19 23:03:50 UTC",
            "resolved": "2018-02-19 24:03:50 UTC"
        },
        {
            "id": "MzQ5MDkyM3",
            "server": "mydropboxserver.imfast.io",
            "category": "error",
            "code" : 10001,
            "subject": "Missing Folder",
            "desc": "The 'root' folder for this server, 'MyOneDriveServer' was not found on the cloud storage provider.  Please login to OneDrive and resolve this issue.",
            "created": "2018-02-20 21:03:50 UTC",
            "alarm": true,
            "acknowledged": "2018-02-20 22:03:50 UTC",
            "resolved": null
        }
    ]
}

Path Params

server
string
required

The name and domain name combined to check if its both valid and available. This string must meet the requirements for a valid name and domain.

Query Params

limit
string

Limit the number of items you would like to receive in the response. This cannot exceed the maximum return value specified for the call.

alarm
boolean

If alarm is set, this API will only return events that match the other criteria and have an alarm set.

unresolved
boolean

If unresolved is set, this API will only return events that match the other criteria and have an not been resolved.

unack
boolean

If unack is set, this API will only return events that match the other criteria and have an not been acknowledged.

 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the request was processed.

Result JSON

Variable
Type
Description

result

boolean

true if the events request was accepted and returned.

results

integer

The number of results returned in the events array.

events

array

An array of Event Object's.

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.

Suggest Edits

Acknowledge

This endpoint acknowledges a notice has been received by an end user.

 
post/events/ack/event_id
$ curl https://go.fast.io/api/v1.x/events/ack/MzQ5MDkyM4 \
    -X POST \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

event_id
string
required

The ID of the event you wish to acknowledge. String of 10 characters, case sensative.

 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the request was processed.

Result JSON

Variable
Type
Description

result

boolean

true if the events request was accepted and events acknowledged.

Result

A true result means the event was acknowledged now or has already been previously acknowledged or If no acknowledgment is needed.

If an event is invalid, an error object will be returned.

Acknowledging All Events

If you call this API without an event ID, all events will be acknowledged.

Suggest Edits

Acknowledge Server

This endpoint acknowledges a notice has been received by an end user for a given Server.

 
post/events/ack/server/server
$ curl https://go.fast.io/api/v1.x/events/ack/server/MyDropboxServer.imfast.io \
    -X POST \
    -H "Authorization: yffaenajzny66mrdiuk6s6dvk6ef2gq7ia72"
A binary file was returned

You couldn't be authenticated

{
  "result" : true
}

Path Params

server
string
required

The name and domain name combined with a period separating them. This string must meet the requirements for a valid name and domain.

 

Result Codes

HTTP Results
Description

200

The request and resource are valid and the request was processed.

Result JSON

Variable
Type
Description

result

boolean

true if the events request was accepted and events for the specified server were acknowledged.

Result

A true result means all events tied to a server were acknowledged now or has already been previously acknowledged or If no acknowledgment is needed.

If an event is invalid, an error object will be returned.

Suggest Edits

Poll

This endpoint returns the activity for various categories and allows you to wait for an update.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://go.fast.io/api/v1.x/activity/poll/
curl --request GET \
  --url https://go.fast.io/api/v1.x/activity/poll/
var request = require("request");

var options = { method: 'GET',
  url: 'https://go.fast.io/api/v1.x/activity/poll/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://go.fast.io/api/v1.x/activity/poll/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://go.fast.io/api/v1.x/activity/poll/");

xhr.send(data);
import requests

url = "https://go.fast.io/api/v1.x/activity/poll/"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "results": 10,
    "key": 3162419978,
    "activity": {
        "analytics": "2018-10-30 20:14:14 UTC",
        "apikey": "2018-10-30 20:14:14 UTC",
        "billing": "2018-10-30 20:14:14 UTC",
        "cdns": "2018-10-30 20:14:14 UTC",
        "changes": "2018-10-30 20:14:14 UTC",
        "events": "2018-11-03 21:46:01 UTC",
        "flush": "2018-11-03 22:37:25 UTC",
        "precache": "2018-11-03 22:37:25 UTC",
        "servers": "2018-10-30 20:14:14 UTC",
        "storage": "2018-11-03 17:54:19 UTC",
        "user": "2018-10-30 20:14:14 UTC"
    }
}

Query Params

fields
string

A comma separated list of fields you wish to get the activity of. A maximum of 30 fields can be specifically requested.

wait
string

The length of time in seconds to wait for an update. If set to 0, the API will return immediately.

lastactivity
string

This specifies the last known activity for any of the specified fields. The format is datetime in UTC.

lastkey
int32

This specifies the last known activity key which can be used in combination with the lastactivity field to avoid race conditions.

updated
boolean

If set, only fields updated are returned regardless of fields request. Variable inclusion is treated as TRUE.

 

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".

Result Codes

HTTP Results
Description

200

The request and resource are valid and the response was returned.

Result JSON

Variable
Type
Description

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.

Default Activity Fields

Field
Desc

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.

Field
Desc

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.

Suggest Edits

System Status

This endpoint returns the platforms current status and version.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://go.fast.io/api/v1.x/system/
curl --request GET \
  --url https://go.fast.io/api/v1.x/system/
var request = require("request");

var options = { method: 'GET', url: 'https://go.fast.io/api/v1.x/system/' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://go.fast.io/api/v1.x/system/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://go.fast.io/api/v1.x/system/");

xhr.send(data);
import requests

url = "https://go.fast.io/api/v1.x/system/"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "result": true,
    "platform": {
        "app": "OK",
        "api": "OK",
        "cdn": "OK",
        "analytics": "OK"
    },
    "version": "0.5-b486280e1b"
}
 

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

HTTP Results
Description

200

The request and resource are valid and the response was returned.

Result JSON

Variable
Type
Description

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.

Platform Status

Field
Desc

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.

Status Responses

Value
Desc

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.