Client API

Overview

This article is intended for CloudFlare users with a Business or Enterprise subscription. Hosting partners must use the Optimized Partner API. All Railgun API requests must either include a Client API token and email address as a request parameter. API keys can be found and managed on the My Account page. All API requests should be directed at ‘https://www.cloudflare.com/‘.

Multiple Railguns may be added to a CloudFlare account. Only one registered and activated Railgun may be used per domain. Railgun can be load-balanced and multiple Railgun daemons can be used per activated public IP and token. There is no need to register each Railgun daemon.

All API methods may be performed either as GET requests that include query string parameters or POST requests. The return status of the API request and any relevant errors messages are within the returned JSON response body. The result member indicates success or failure and the msg member contains further details if applicable.

Creation, Activation, and Deletion

Creating and activating a Railgun requires two API calls. First, a Railgun must be initialized using the init call. The activation API call is made by Railgun when the daemon is started and does not need to be made by a user.

POST /api/v2/railgun/init

Create a Railgun. If request is successful, a new Railgun is added to a user account and placed in initializing status (INI).

Form Parameters:
 
  • email – User account email
  • tkn – User API token
  • name – Name of Railgun
  • pubname – Name of Railgun shown to users

Example request:

POST /api/v2/railgun/init HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp
pubname=My%20Railgun
name=my-railgun

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_init",
         "railgun_id": "1",
         "railgun_name": "RG_a1b2c3d4e5f6g7h8i9j0k1",
         "railgun_status": "INI",
         "rtkn": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp"
     },
     "result": "success"
}
GET /api/v2/railgun/init

Create a Railgun. If request is successful, a new Railgun is added to a user account and placed in initializing status (INI).

Query Parameters:
 
  • email – User account email
  • tkn – User API token
  • name – Name of Railgun
  • pubname – Name of Railgun shown to users

Example request:

GET /api/v2/railgun/init?email=&tkn=&pubname=&name= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp
pubname=My%20Railgun
name=my-railgun

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_init",
         "railgun_id": "1",
         "railgun_name": "RG_a1b2c3d4e5f6g7h8i9j0k1",
         "railgun_status": "INI",
         "rtkn": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp"
     },
     "result": "success"
}

POST /api/v2/railgun/delete

Delete a Railgun. If request is successful, the Railgun with a token matching rtkn is removed from the account and set to deleted status (D).

Form Parameters:
 
  • email – User account email
  • tkn – User API token
  • rtkn – Railgun token

Example request:

POST /api/v2/railgun/delete HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_delete",
         "railgun_id": "1",
     },
     "result": "success"
}
GET /api/v2/railgun/delete

Delete a Railgun. If request is successful, the Railgun with a token matching rtkn is removed from the account and set to deleted status (D).

Query Parameters:
 
  • email – User account email
  • tkn – User API token
  • rtkn – Railgun token

Example request:

GET /api/v2/railgun/delete?email=&tkn=&rtkn= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_delete",
         "railgun_id": "1",
     },
     "result": "success"
}

Listing and Viewing Railgun Details

The following API calls can be used to determine details and the status or one or more Railguns assigned to an account. These calls are sometimes needed to determine the unique rtkn or id assigned to a Railgun.

POST /api/v2/railgun/user_get_all

Assign a Railgun to a domain

Form Parameters:
 
  • email – User account email
  • tkn – User API token

Example request:

POST /api/v2/railgun/user_get_all HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "msg": null,
    "response": {
        "act": "railgun_user_get_all",
        "railguns": {
            "count": 5,
            "objs": [
                {
                    "cdate": "2012-10-27 16:34:37.718746-07",
                    "edate": "2012-11-06 13:02:16.153332-08",
                    "props": {
                        "build": "2012-10-27-1257",
                        "number": "2.6.0",
                        "revision": "ff3f8f25f5238de327cf34059659de0738399176"
                    },
                    "railgun_activated_on": "2012-11-06 13:02:16.122355-08",
                    "railgun_api_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp",
                    "railgun_deleted_on": null,
                    "railgun_host_id": null,
                    "railgun_id": "1",
                    "railgun_ip": null,
                    "railgun_mode": "1",
                    "railgun_name": "RG_100f5777999990edb60d2db56627f9",
                    "railgun_port": "2408",
                    "railgun_pubname": "Railgun for example.com",
                    "railgun_rec_id": "100",
                    "railgun_rec_name": "rg-d65dfffff666a75fd3dea2a7cfeede90.port2408.net",
                    "railgun_status": "V",
                    "railgun_tag": "a18bbbbc555f4g6h2i8j222l711n",
                    "railgun_type": "user",
                    "railgun_user_id": "1000"
                },
                {
                    "cdate": "2012-11-02 00:03:33.17205-07",
                    "edate": "2012-11-02 00:03:33.17205-07",
                    "props": {
                        "build": null,
                        "number": null,
                        "revision": null
                    },
                    "railgun_activated_on": null,
                    "railgun_api_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp",
                    "railgun_deleted_on": null,
                    "railgun_host_id": null,
                    "railgun_id": "178",
                    "railgun_ip": null,
                    "railgun_mode": "0",
                    "railgun_name": "RG_000f7777999690edb60d2db56627f9",
                    "railgun_port": "2408",
                    "railgun_pubname": "Railgun for mydomain.com",
                    "railgun_rec_id": null,
                    "railgun_rec_name": null,
                    "railgun_status": "INI",
                    "railgun_tag": "d18bbbbc555f4g6h2i8j222l711n",
                    "railgun_type": "user",
                    "railgun_user_id": "1000"
                }
            ]
        }
    },
    "result": "success"
}
GET /api/v2/railgun/user_get_all

Assign a Railgun to a domain

Query Parameters:
 
  • email – User account email
  • tkn – User API token

Example request:

GET /api/v2/railgun/user_get_all?email=&tkn= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "msg": null,
    "response": {
        "act": "railgun_user_get_all",
        "railguns": {
            "count": 5,
            "objs": [
                {
                    "cdate": "2012-10-27 16:34:37.718746-07",
                    "edate": "2012-11-06 13:02:16.153332-08",
                    "props": {
                        "build": "2012-10-27-1257",
                        "number": "2.6.0",
                        "revision": "ff3f8f25f5238de327cf34059659de0738399176"
                    },
                    "railgun_activated_on": "2012-11-06 13:02:16.122355-08",
                    "railgun_api_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp",
                    "railgun_deleted_on": null,
                    "railgun_host_id": null,
                    "railgun_id": "1",
                    "railgun_ip": null,
                    "railgun_mode": "1",
                    "railgun_name": "RG_100f5777999990edb60d2db56627f9",
                    "railgun_port": "2408",
                    "railgun_pubname": "Railgun for example.com",
                    "railgun_rec_id": "100",
                    "railgun_rec_name": "rg-d65dfffff666a75fd3dea2a7cfeede90.port2408.net",
                    "railgun_status": "V",
                    "railgun_tag": "a18bbbbc555f4g6h2i8j222l711n",
                    "railgun_type": "user",
                    "railgun_user_id": "1000"
                },
                {
                    "cdate": "2012-11-02 00:03:33.17205-07",
                    "edate": "2012-11-02 00:03:33.17205-07",
                    "props": {
                        "build": null,
                        "number": null,
                        "revision": null
                    },
                    "railgun_activated_on": null,
                    "railgun_api_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp",
                    "railgun_deleted_on": null,
                    "railgun_host_id": null,
                    "railgun_id": "178",
                    "railgun_ip": null,
                    "railgun_mode": "0",
                    "railgun_name": "RG_000f7777999690edb60d2db56627f9",
                    "railgun_port": "2408",
                    "railgun_pubname": "Railgun for mydomain.com",
                    "railgun_rec_id": null,
                    "railgun_rec_name": null,
                    "railgun_status": "INI",
                    "railgun_tag": "d18bbbbc555f4g6h2i8j222l711n",
                    "railgun_type": "user",
                    "railgun_user_id": "1000"
                }
            ]
        }
    },
    "result": "success"
}

POST /api/v2/railgun/zone_conn_get_active

List all active Railgun connections for a domain.

Form Parameters:
 
  • email – User account email
  • tkn – User API token

Example request:

POST /api/v2/railgun/zone_conn_get_active HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "msg": null,
    "response": {
        "act": "railgun_zone_conn_get_active",
        "railgun_conn": {
            "obj": {
                    "railgun_conn_id": "2",
                    "railgun_id": "123",
                    "railgun_conn_status": "V",
                    "railgun_conn_mode": "1",
                    "railgun_enabled": "t",
                }
        }
    },
    "result": "success"
}
GET /api/v2/railgun/zone_conn_get_active

List all active Railgun connections for a domain.

Form Parameters:
 
  • email – User account email
  • tkn – User API token

Example request:

GET /api/v2/railgun/zone_conn_get_active?email=&tkn=&z= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "msg": null,
    "response": {
        "act": "railgun_zone_conn_get_active",
        "railgun_conn": {
            "obj": {
                    "railgun_conn_id": "2",
                    "railgun_id": "123",
                    "railgun_conn_status": "V",
                    "railgun_conn_mode": "1",
                    "railgun_enabled": "t",
                }
        }
    },
    "result": "success"
}

Connections, Enabling and Disabling

After a Railgun has been activated, it can be assigned to a particular domain with the conn_set API call. conn_setmode_enabled and conn_setmode_disabled can be used to toggle Railgun on or off for the domain. conn_set also accepts a mode parameter to assign and enable Railgun in a single API call. zone_conn_get_active can be used to view active Railgun connections.

POST /api/v2/railgun/conn_set

Establish a connection between a domain and a Railgun

Form Parameters:
 
  • email – User account email
  • tkn – User API token
  • z – Domain name
  • rtkn – Railgun token
  • mode – Railgun operation mode, 1 for active 0 for inactive

Example request:

POST /api/v2/railgun/conn_set HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
mode=0
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_set",
         "railgun_id": "1"
     },
     "result": "success"
}
GET /api/v2/railgun/conn_set

Establish a connection between a domain and a Railgun

Query Parameters:
 
  • email – User account email
  • tkn – User API token
  • z – Domain name
  • rtkn – Railgun token
  • mode – Railgun operation mode, 1 for active 0 for inactive

Example request:

GET /api/v2/railgun/conn_set?email=&tkn=&rtkn=&z=&mode= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
mode=0
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_set",
         "railgun_id": "1"
     },
     "result": "success"
}

POST /api/v2/railgun/conn_setmode_enabled

Enable a Railgun. If request is successful, the specified Railgun will be enabled and traffic for the specified domain will be proxied through Railgun.

Form Parameters:
 
  • email – User account email
  • tkn – User API token
  • z – Domain name
  • rtkn – Railgun token

Example request:

POST /api/v2/railgun/conn_setmode_enabled HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_setmode_enabled",
         "railgun_id": "1"
     },
     "result": "success"
}
GET /api/v2/railgun/conn_setmode_enabled

Enable a Railgun. If request is successful, the specified Railgun will be enabled and traffic for the specified domain will be proxied through Railgun.

Query Parameters:
 
  • email – User account email
  • tkn – User API token
  • z – Domain name
  • rtkn – Railgun token

Example request:

GET /api/v2/railgun/conn_setmode_enabled?email=&tkn=&rtkn=&z= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5pp
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_setmode_enabled",
         "railgun_id": "1"
     },
     "result": "success"
}

POST /api/v2/railgun/conn_setmode_disabled

Disable a Railgun. If request is successful, the specified Railgun will be disabled and traffic for the specified domain will no longer use Railgun.

Form Parameters:
 
  • email – User account email
  • tkn – User API token
  • z – Domain name
  • rtkn – Railgun token

Example request:

POST /api/v2/railgun/conn_setmode_disabled HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_setmode_disabled",
         "railgun_id": "1"
     },
     "result": "success"
}
GET /api/v2/railgun/conn_setmode_disabled

Disable a Railgun. If request is successful, the specified Railgun will be disabled and traffic for the specified domain will no longer use Railgun.

Query Parameters:
 
  • email – User account email
  • tkn – User API token
  • z – Domain name
  • rtkn – Railgun token

Example request:

GET /api/v2/railgun/conn_setmode_disabled?email=&tkn=&rtkn=&z= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_setmode_disabled",
         "railgun_id": "1"
     },
     "result": "success"
}

POST /api/v2/railgun/conn_delete

Remove a connection between a domain and a Railgun. This API call will allow a connected Railgun to be assigned to a different domain. Removing the connection of an enabled Railgun and domain will disable Railgun for the domain until a new connection is made with conn_set.

Form Parameters:
 
  • email – User account email
  • tkn – User API token
  • z – Domain name
  • rtkn – Railgun token

Example request:

POST /api/v2/railgun/conn_delete HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example form parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_delete",
         "railgun_id": "1"
     },
     "result": "success"
}
GET /api/v2/railgun/conn_delete

Remove a connection between a domain and a Railgun. This API call will allow a connected Railgun to be assigned to a different domain. Removing the connection of an enabled Railgun and domain will disable Railgun for the domain until a new connection is made with conn_set.

Query Parameters:
 
  • email – User account email
  • tkn – User API token
  • z – Domain name
  • rtkn – Railgun token

Example request:

GET /api/v2/railgun/conn_delete?email=&tkn=&rtkn=&z= HTTP/1.1
Host: www.cloudflare.com
Accept: */*
Content-Type: application/x-www-form-urlencoded

Example query string parameters:

email=user%40cloudflare.com
tkn=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p
rtkn=7h8i9j0k1l2m3n4o5p6q7r8id9h0j1l
z=example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "msg": null,
     "response": {
         "act": "railgun_conn_delete",
         "railgun_id": "1"
     },
     "result": "success"
}