Introduction to the Meta API
The Meta API provides programmatic access to your Kloudless developer account and information associated with it, such as applications.
You will need your Kloudless Developer Key to make requests to this API. This key is different from your individual application API Keys, and can be obtained on your Account Settings page.
You can test requests via the API Explorer page.
Authorization
A developer can use an Authorization header to authorize requests for the Kloudless API with a Developer Key:
Authorization: DeveloperKey {developer_key: string}
Here is how you can make a request using cURL:
curl -L -H 'Authorization: DeveloperKey [KEY]' \
https://api.kloudless.com/v0/[RESOURCE]
Here are some example requests:
curl -L -H 'Authorization: DeveloperKey isgqXuDfLBOhcZzf7cO93T' \
https://api.kloudless.com/v0/applications
Applications
Kloudless Applications have the attributes below:
-
id
Unique identifier for this application. Also known as the App ID. -
name
The application’s name. Will be displayed to a user connecting an account to the application. -
description
A description of the application. -
logo_url
A URL at which an image containing the logo for the application is available. The URL will be used to display the logo to the user when using Kloudless UI components. -
active
Whether the application is active or not. Deleted applications will not show up via the API and do not count as ‘inactive’. -
implicit_grant_enabled
IfTrue
, allows OAuth 2.0 Implicit Grant flow for this application. Defaults toFalse
. -
recent_enabled
IfTrue
, collects data on recent activity in accounts, such as information on recently modified files. Defaults toFalse
. -
events_enabled
IfTrue
, collects event data for accounts. Defaults toFalse
. -
created
ISO 8601 timestamp indicating when the application object was created. -
modified
ISO 8601 timestamp indicating when the application object was modified.
List Applications
The response contains the following information:
-
total
Total number of objects -
count
Number of objects on this page -
page
Page number -
objects
List of application objects
- Parameters
- active
boolean
(optional)Retrieves only active/inactive applications, if present.
Choices:
True
False
- page_size
number
(optional) Default: 10Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional) Default: 1Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects.page
must be greater than0
.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "total": 3, "count": 3, "page": 1, "objects": [ { "id": "wSPk9y5D7p5o87k0ACGKxR", "name": "Test App 1", "description": "A test application.", "logo_url": "", "active": true, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2014-03-18T03:57:16.770685Z", "modified": "2014-06-26T04:13:45.439534Z" }, { "id": "osM_FF6fIWXmCLDfWVRX", "name": "Test App 2", "description": "A test application.", "logo_url": "", "active": true, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2014-03-26T05:51:45.725705Z", "modified": "2015-01-27T08:52:12.356049Z" }, { "id": "koiR71rFLPTdld9N-YUR", "name": "Demo App", "description": "A demo app.", "logo_url": "https://s3-us-west-2.amazonaws.com/static-assets.kloudless.com/webapp/sources/gdrive.png", "active": true, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2014-06-25T05:54:05.801428Z", "modified": "2015-05-01T06:01:39.905658Z" } ] }
Create an application
Application creation is usually performed via the Developer Portal. However, it can be automated using this endpoint.
Here are the required parameters:
name
Described above.
In addition, the following optional parameters may be provided:
-
description
Described above. -
logo_url
Described above. -
implicit_grant_enabled
Described above. -
recent_enabled
Described above. -
events_grant_enabled
Described above. -
source
The ID of another application owned by the developer to use as a template to create the new application. If provided, values for all other optional fields will be populated from this existing application. In addition, any OAuth Keys owned by the application will be copied over to be used by the new application as well.
Example requests:
curl -H 'Authorization: DeveloperKey S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-d '{"name": "Test App 1", "description": "A test application."}' \
'https://api.kloudless.com/v0/applications/'
curl -H 'Authorization: DeveloperKey S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-d '{"name": "Test App 2", "source": "wSPk9y5D7p5o87k0ACGKxR"}' \
'https://api.kloudless.com/v0/applications/'
- RequestToggle
Headers
Authorization: DeveloperKey [KEY]
Content-Type: application/jsonBody
{ "name": "Test App 1", "description": "A test application." }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": "osM_FF6fIWXmCLDfWVRX", "name": "Test App 2", "description": "A test application.", "logo_url": "", "active": true, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2015-06-01T03:57:16.770685Z", "modified": "2015-06-01T03:57:16.770685Z" }
Retrieve an Application
Retrieve information about an individual application.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "wSPk9y5D7p5o87k0ACGKxR", "name": "Test App 2", "description": "A test application.", "logo_url": "", "active": true, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2015-06-01T03:57:16.770685Z", "modified": "2015-06-01T03:57:16.770685Z" }
Update an Application
Here are the properties that can be updated:
-
name
-
description
-
logo_url
-
active
-
implicit_grant_enabled
-
recent_enabled
-
events_enabled
The new object will be returned on success.
The source
parameter can not be used in an update.
Example request:
curl -H 'Authorization: DeveloperKey S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-XPATCH -d '{"description": "A better test application."}' \
'https://api.kloudless.com/v0/applications/wSPk9y5D7p5o87k0ACGKxR'
Setting an application to inactive will:
-
not permit any API requests to its accounts;
-
cease event data collection for all its accounts;
-
but keep its accounts active and refresh tokens as necessary to maintain their connectivity.
- RequestToggle
Headers
Authorization: DeveloperKey [KEY]
Content-Type: application/jsonBody
{ "description": "A better test application." }
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "wSPk9y5D7p5o87k0ACGKxR", "name": "Test App 1", "description": "A better test application.", "logo_url": "", "active": true, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2015-06-01T03:57:16.770685Z", "modified": "2015-06-01T08:10:20.128361Z" }
Delete an Application
Example request:
curl -L -H 'Authorization: DeveloperKey S4i5EG5ViEAVmMaCilB5' \
-XDELETE https://api.kloudless.com/applications/koiR71rFLPTdld9N-YUR
- Response
204
API Keys
Kloudless API Keys have the attributes below:
-
key
The API Key. This is unique across all applications. -
created
ISO 8601 timestamp indicating when the API Key object was created. -
modified
ISO 8601 timestamp indicating when the API Key object was modified.
List API Keys
The response contains the following information:
-
total
Total number of objects -
count
Number of objects on this page -
page
Page number -
objects
List of API Key objects
- Parameters
- page_size
number
(optional) Default: 10Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional) Default: 1Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects.page
must be greater than0
.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "total": 1, "count": 1, "page": 1, "objects": [ { "key": "80OdF5hXzkNqEs9DHRkiA1EXz1pbF4", "created": "2014-03-18T03:57:16.770685Z", "modified": "2014-03-18T03:57:16.770685Z" } ] }
Create an API Key
API Keys can be created to allow access to other Kloudless APIs.
The body of the request is empty.
Example requests:
curl -XPOST -H 'Authorization: DeveloperKey S4i5EG5ViEAVmMaCilB5' \
'https://api.kloudless.com/v0/applications/wSPk9y5D7p5o87k0ACGKxR/apikeys/'
Delete an API Key
This deletes an API Key.
Example request:
curl -L -H 'Authorization: DeveloperKey S4i5EG5ViEAVmMaCilB5' \
-XDELETE 'https://api.kloudless.com/applications/koiR71rFLPTdld9N-YUR/apikeys/80OdF5hXzkNqEs9DHRkiA1EXz1pbF4'
- Response
204
WebHooks
Kloudless WebHooks have the attributes below:
-
id
The WebHook ID. This is unique across all applications. -
url
The WebHook URL. See the storage API docs for more information. -
created
ISO 8601 timestamp indicating when the WebHook object was created. -
modified
ISO 8601 timestamp indicating when the WebHook object was modified.
List WebHooks
The response contains the following information:
-
total
Total number of objects -
count
Number of objects on this page -
page
Page number -
objects
List of webhook objects
- Parameters
- page_size
number
(optional) Default: 10Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional) Default: 1Page to return.
page_size
number of objects will be returned on each page. By default, the first page is returned. Thepage
parameter can be used to request further objects.page
must be greater than0
.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "total": 1, "count": 1, "page": 1, "objects": [ { "id": "100", "url": "http://localhost:5000", "created": "2015-08-10T03:34:28.273777Z", "modified": "2015-08-10T03:34:28.273804Z" } ] }
Create a WebHook
WebHooks can be created to let Kloudless notify your application of events for file creation and deletion. See the storage API docs for more information.
Here are the required parameters:
url
Described above.
Example requests:
curl -H 'Authorization: DeveloperKey S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-XPOST -d '{"url": "http://localhost:5000"}' \
'https://api.kloudless.com/v0/applications/wSPk9y5D7p5o87k0ACGKxR/webhooks'
- RequestToggle
Headers
Authorization: DeveloperKey [KEY]
Content-Type: application/jsonBody
{ "url": "http://localhost:5000" }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": "100", "url": "http://localhost:5000", "created": "2015-08-10T03:34:28.273777Z", "modified": "2015-08-10T03:34:28.273804Z" }
Retrieve a WebHook
Retrieve information about an individual webhook.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "100", "url": "http://localhost:5000", "created": "2015-08-10T04:53:50.185879Z", "modified": "2015-08-10T04:53:50.185879Z" }
Delete a WebHook
This deletes a WebHook.
Example request:
curl -L -H 'Authorization: DeveloperKey S4i5EG5ViEAVmMaCilB5' \
-XDELETE 'https://api.kloudless.com/applications/koiR71rFLPTdld9N-YUR/webhooks/100'
- Response
204
Other Information
For more information such as Error Codes, SDKs and Support, please refer to these API docs.