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 Meta token 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 ‘Applications’ endpoints towards the bottom of the API Explorer page.
The Meta API has the API type meta
which is the Kloudless API itself.
The meta
API has the following available object types representing the
objects described below:
-
kloudless_id
: An encoded ID representing an object accessible via the Kloudless API. -
developer
: A Developer who has signed up at the Kloudless Developer Portal. -
application
: An Application created by a Kloudless Developer. -
apikey
: An API Key belonging to an Application. -
trusted_domain
: A Trusted Domain configured for an Application. -
webhook
: A Webhook configured for an Application. -
service_key
: A custom OAuth Credential configured for an Application. -
redirect_uri
: A Redirect URL whitelisted for an Application’s OAuth flow. -
fe_upload_location
: An Upload Location whitelisted for an Application’s use of the File Explorer. -
usage_report
: A summary of usage over a period of time. -
license
: A Kloudless Enterprise license associated with the developer’s account. -
invoice
: Invoice, received from Kloudless. -
analytics_api_request
: Statistics describing an individual API request.
Authorization
A developer can use an Authorization header to authorize requests for the Kloudless API with an Meta token:
Authorization: Bearer {token: string}
Here is how you can make a request using cURL:
curl -L -H 'Authorization: Bearer [TOKEN]' \
https://api.kloudless.com/v1/[RESOURCE]
Here are some example requests:
curl -L -H 'Authorization: Bearer isgqXuDfLBOhcZzf7cO93T' \
https://api.kloudless.com/v1/meta/applications
Developers
Kloudless Developers have the attributes below:
-
id
Unique identifier for this developer. -
first_name
The developer’s first name. -
last_name
The developer’s last name. -
email
The developer’s email address. -
organization
The ID of the Kloudless Enterprise organization the developer belongs to. -
organization_name
The name of the organization with the ID in theorganization
field. -
company
The developer’s company. -
date_joined
ISO 8601 timestamp indicating when the developer signed up at the Kloudless developer portal. -
admin
Grants admin access and all permissions in the Kloudless Admin Portal without specifically assigning them to this developer. -
type
Will always bedeveloper
. -
api
Will always bemeta
List Developers
The response contains the following information:
-
total
Total number of objects. Always 1. -
count
Number of objects inobjects
list. Always 1. -
objects
List of developer objects. Will always contain one object for the currently authorized developer. -
type
Alwaysobject_list
. -
api
Alwaysmeta
.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "total": 1, "count": 1, "objects": [ { "id": 4, "first_name": "John", "last_name": "Brown", "email": "test@test.com", "organization": "Test", "organization_name": "test.com", "company": "Company Name", "api": "meta", "type": "developer", "date_joined": "2017-05-25T14:48:08Z", "admin": true } ], "type": "object_list", "api": "meta" }
Retrieve a Developer
Retrieve information about an individual developer with a known ID. Only information about the currently authorized developer can be retrieved.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": 4, "first_name": "John", "last_name": "Brown", "email": "test@test.com", "organization": "Test", "organization_name": "test.com", "api": "meta", "type": "developer", "date_joined": "2017-05-25T14:48:08Z", "admin": true }
Update a Developer
Update information about an individual developer with a known ID. Only information about the currently authorized developer can be updated.
Here are the properties that can be updated:
-
first_name
-
last_name
The new object will be returned if successful.
Example request:
curl -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-XPATCH -d '{"first_name": "J", "last_name": "B"}' \
'https://api.kloudless.com/v1/meta/developers/4'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "first_name": "J", "last_name": "B" }
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": 4, "first_name": "J", "last_name": "B", "email": "test@test.com", "organization": "Test", "organization_name": "test.com", "api": "meta", "type": "developer", "date_joined": "2017-05-25T14:48:08Z", "admin": true }
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
. -
internal_use
Internal Development: This indicates that accounts connected to this application are only used internally for development, testing, and similar purposes. This enables Kloudless to waive usage fees for these accounts. -
created
ISO 8601 timestamp indicating when the application object was created. -
modified
ISO 8601 timestamp indicating when the application object was modified. -
type
Will always beapplication
. -
api
Will always bemeta
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 -
type
Alwaysobject_list
-
api
Alwaysmeta
- Parameters
- active
boolean
(optional)Retrieves only active/inactive applications, if present.
Choices:
True
False
- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional)Page 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, "internal_use": false, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2014-03-18T03:57:16.770685Z", "modified": "2014-06-26T04:13:45.439534Z", "type": "application", "api": "meta", }, { "id": "osM_FF6fIWXmCLDfWVRX", "name": "Test App 2", "description": "A test application.", "logo_url": "", "active": true, "internal_use": false, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2014-03-26T05:51:45.725705Z", "modified": "2015-01-27T08:52:12.356049Z", "type": "application", "api": "meta", }, { "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, "internal_use": false, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2014-06-25T05:54:05.801428Z", "modified": "2015-05-01T06:01:39.905658Z", "type": "application", "api": "meta", } ], "type": "object_list", "api": "meta" }
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: Bearer S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-d '{"name": "Test App 1", "description": "A test application."}' \
'https://api.kloudless.com/v1/meta/applications/'
curl -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-d '{"name": "Test App 2", "source": "wSPk9y5D7p5o87k0ACGKxR"}' \
'https://api.kloudless.com/v1/meta/applications/'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
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, "internal_use": false, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2015-06-01T03:57:16.770685Z", "modified": "2015-06-01T03:57:16.770685Z", "type": "application", "api": "meta", }
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, "internal_use": false, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2015-06-01T03:57:16.770685Z", "modified": "2015-06-01T03:57:16.770685Z", "type": "application", "api": "meta", }
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: Bearer S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-XPATCH -d '{"description": "A better test application."}' \
'https://api.kloudless.com/v1/meta/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: Bearer [TOKEN]
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, "internal_use": false, "implicit_grant_enabled": false, "recent_enabled": false, "events_enabled": false, "created": "2015-06-01T03:57:16.770685Z", "modified": "2015-06-01T08:10:20.128361Z", "type": "application", "api": "meta", }
Delete an Application
Example request:
curl -L -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-XDELETE 'https://api.kloudless.com/v1/meta/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. -
type
Will always beapikey
. -
api
Will always bemeta
.
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 -
type
Alwaysobject_list
-
api
Alwaysmeta
- Parameters
- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional)Page 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", "type": "apikey", "api": "meta", } ], "type": "object_list", "api": "meta" }
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: Bearer S4i5EG5ViEAVmMaCilB5' \
'https://api.kloudless.com/v1/meta/applications/wSPk9y5D7p5o87k0ACGKxR/apikeys/'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/json- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "key": "80OdF5hXzkNqEs9DHRkiA1EXz1pbF4", "created": "2014-03-18T03:57:16.770685Z", "modified": "2014-03-18T03:57:16.770685Z", "type": "apikey", "api": "meta", }
Delete an API Key
This deletes an API Key.
Example request:
curl -L -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-XDELETE 'https://api.kloudless.com/v1/meta/applications/koiR71rFLPTdld9N-YUR/apikeys/80OdF5hXzkNqEs9DHRkiA1EXz1pbF4'
- Response
204
Trusted Domains
UI Tools such as the Authenticator and File Explorer JS libraries allow users to connect accounts. Bearer tokens for accounts connected can be returned to your application’s web page in the event callback if the domain of the web page is a Trusted Domain. This allows further API requests to be made from the web page using the bearer tokens.
Kloudless Trusted Domains have the attributes below:
-
id
The trusted domain id. This is unique across all applications. -
domain
The trusted domain itself. Wildcards are permitted for subdomain names. A domain of the form *.domain.com will trust all subdomains, such as x.domain.com and y.x.domain.com but not domain.com itself. -
created
ISO 8601 timestamp indicating when the Trusted Domain object was created. -
modified
ISO 8601 timestamp indicating when the Trusted Domain object was modified. -
type
Will always beapikey
. -
api
Will always bemeta
.
List Trusted Domains
The response contains the following information:
-
total
Total number of objects -
count
Number of objects on this page -
page
Page number -
objects
List of trusted domain objects -
type
Alwaysobject_list
-
api
Alwaysmeta
- Parameters
- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional)Page 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": "1", "domain": "*.my-domain.com", "created": "2017-07-25T05:37:50.663920Z", "modified": "2017-07-25T05:37:50.663944Z", "type": "trusted_domain", "api": "meta", } ], "type": "object_list", "api": "meta" }
Create a Trusted Domain
The required parameters are:
domain
Described above
Example requests:
curl -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-XPOST -d '{"domain": "*.my-domain.com"}' \
'https://api.kloudless.com/v1/meta/applications/wSPk9y5D7p5o87k0ACGKxR/trusted_domains/'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "domain": "*.my-domain.com" }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": "1", "domain": "*.my-domain.com", "created": "2017-07-25T05:37:50.663920Z", "modified": "2017-07-25T05:37:50.663944Z", "type": "trusted_domain", "api": "meta", }
Retrieve a Trusted Domain
Retrieve information about an individual trusted domain.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "1", "domain": "*.my-domain.com", "created": "2017-07-25T05:37:50.663920Z", "modified": "2017-07-25T05:37:50.663944Z", "type": "trusted_domain", "api": "meta", }
Delete a Trusted Domain
This deletes a Trusted Domain.
Example request:
curl -L -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-XDELETE 'https://api.kloudless.com/v1/meta/applications/koiR71rFLPTdld9N-YUR/trusted_domains/1'
- 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 Activity 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. -
type
Will always bewebhook
. -
api
Will always bemeta
. -
body_format
This indicates the content type of the webhook request’s body. Here are the supported values:json
(default): The Content-Type will beapplication/json
.form
: This is a legacy format for Webhooks created prior to Sept 2019. The content type will beapplication/x-www-form-urlencoded
.eventbridge
: This indicates an Amazon EventBridge endpoint.
-
extra
A read-only JSON object with additional data about the webhook.
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 -
type
Alwaysobject_list
-
api
Alwaysmeta
- Parameters
- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional)Page 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", "body_format": "json", "created": "2015-08-10T03:34:28.273777Z", "modified": "2015-08-10T03:34:28.273804Z", "extra": {}, "type": "webhook", "api": "meta", } ], "type": "object_list", "api": "meta" }
Create a WebHook
WebHooks can be created to let Kloudless notify your application of activity for file creation and deletion. See the Activity API docs for more information.
Here are the required parameters:
url
Described above.
Example requests:
curl -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-XPOST -d '{"url": "http://localhost:5000"}' \
'https://api.kloudless.com/v1/meta/applications/wSPk9y5D7p5o87k0ACGKxR/webhooks'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "url": "http://localhost:5000" }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": "100", "url": "http://localhost:5000", "body_format": "json", "created": "2015-08-10T03:34:28.273777Z", "modified": "2015-08-10T03:34:28.273804Z", "extra": {}, "type": "webhook", "api": "meta", }
Retrieve a WebHook
Retrieve information about an individual webhook.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "100", "url": "http://localhost:5000", "body_format": "json", "created": "2015-08-10T04:53:50.185879Z", "modified": "2015-08-10T04:53:50.185879Z", "extra": {}, "type": "webhook", "api": "meta", }
Delete a WebHook
This deletes a WebHook.
Example request:
curl -L -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-XDELETE 'https://api.kloudless.com/v1/meta/applications/koiR71rFLPTdld9N-YUR/webhooks/100'
- Response
204
Service Keys
Kloudless Service Keys are used when configuring OAuth credentials to authenticate users connecting a certain account. They have the attributes below:
-
id
Unique identifier for this Service Key. -
application
ID of the Kloudless Application that this key is configured for. -
service_name
Human-friendly name of the Service this key is for. e.g.Google Drive
. -
service
The key’s service identifier. e.g.gdrive
. -
key
Service Key ID. Usually the OAuth Client ID. -
secret
Serivice key’s secret. This attribite is write-only. Usually corresponds to the OAuth Client Secret. -
secondary_key
Secondary key for the service. Purpose varies by Service, but is usually a secondary OAuth Client ID if needed. -
secondary_secret
Secret for the secondary key. This attribute is write-only. Corresponds to an OAuth Client Secret if needed, although its purpose varies by Service. -
secondary_id
The Secondary ID. Purpose varies by Service. -
resource
Set an optional domain here to ensure that this Service Key is only used when authenticating accounts connecting to this domain. End-users must first see a preliminary authentication screen prompting them to enter their email address for this to take effect. -
deactivation
ISO 8601 timestamp indicating when the service key is deactivated. -
admin
Whether this is an admin service key. Defaults tofalse
. -
created
ISO 8601 timestamp indicating when the object was created. -
modified
ISO 8601 timestamp indicating when the object was modified. -
type
Will always beservice_key
. -
api
Will always bemeta
.
List Service 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 application objects -
type
Alwaysobject_list
-
api
Alwaysmeta
- Parameters
- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional)Page 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": 4, "application": "koiR71rFLPTdld9N-YUR", "service": "evernote", "key": "88", "created": "2017-10-05T07:49:08.140717Z", "modified": "2017-10-05T07:49:08.140736Z", "admin": false, "secondary_key": "", "secondary_id": "", "resource": "", "deactivation": "9999-12-31T23:59:59.999999Z", "service_name": "Evernote", "api": "meta", "type": "service_key" } ], "type": "object_list", "api": "meta" }
Create a Service Key
The required parameters are:
service
Described above.
In addition, the following optional parameters may be provided:
-
key
Described above. -
secret
Described above. -
resource
Described above. -
secondary_id
Described above. -
secondary_key
Described above. -
secondary_secret
Described above. -
admin
Described above.
Example request:
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' -d '{ \
"service": "gdrive", \
"key": "test-key" \
}' 'https://api.kloudless.com/v1/meta/applications/wSPk9y5D7p5o87k0ACGKxR/service_keys/'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "service": "gdrive", "key": "test-key" }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": 10, "application": "wSPk9y5D7p5o87k0ACGKxR", "service": "gdrive", "key": "test-key", "created": "2017-12-22T18:54:51.873276Z", "modified": "2017-12-22T18:54:51.873298Z", "admin": false, "secondary_key": "", "secondary_id": "", "resource": "", "deactivation": "9999-12-31T23:59:59.999999Z", "service_name": "Google Drive", "api": "meta", "type": "service_key" }
Retrieve a Service Key
Retrieve information about an individual Service Key.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": 10, "application": "wSPk9y5D7p5o87k0ACGKxR", "service": "gdrive", "key": "test-key", "created": "2017-12-22T18:54:51.873276Z", "modified": "2017-12-22T18:54:51.873298Z", "admin": false, "secondary_key": "", "secondary_id": "", "resource": "", "deactivation": "9999-12-31T23:59:59.999999Z", "service_name": "Google Drive", "api": "meta", "type": "service_key" }
Update a Service Key
Here are the properties that can be updated:
-
service
-
key
-
secret
-
resource
-
secondary_id
-
secondary_secret
-
secondary_key
-
admin
The new object will be returned on success.
Example request:
curl -X PATCH \
-H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-d '{"key": "new key"}' \
'https://api.kloudless.com/v1/meta/applications/wSPk9y5D7p5o87k0ACGKxR/service_keys/10/'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "key": "new key" }
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": 10, "application": "koiR71rFLPTdld9N-YUR", "service": "gdrive", "key": "new key", "created": "2017-12-22T18:54:51.873276Z", "modified": "2017-12-22T19:44:01.152707Z", "admin": false, "secondary_key": "", "secondary_id": "", "resource": "", "deactivation": "9999-12-31T23:59:59.999999Z", "service_name": "Google Drive", "api": "meta", "type": "service_key" }
Delete a Service Key
Example request:
curl -XDELETE \
-H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
'https://api.kloudless.com/v1/meta/applications/koiR71rFLPTdld9N-YUR/service_keys/10/'
- Response
204
Redirect URIs
Kloudless Redirect URIs have the attributes below:
-
id
Unique identifier for this Redirect URI. -
application
Kloudless Application ID. -
uri
Redirect URL. -
created
ISO 8601 timestamp indicating when the object was created. -
modified
ISO 8601 timestamp indicating when the object was modified. -
type
Will always beredirect_uri
. -
api
Will always bemeta
List Redirect URIs
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 -
type
Alwaysobject_list
-
api
Alwaysmeta
- Parameters
- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional)Page 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": 4, "application": "wSPk9y5D7p5o87k0ACGKxR", "uri": "root", "created": "2017-12-14T08:29:45.909414Z", "modified": "2017-12-14T08:29:45.909444Z", "api": "meta", "type": "redirect_uri" } ], "type": "object_list", "api": "meta" }
Create a Redirect URI
The required parameter is:
uri
Described above.
Example requests:
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-d '{"uri": "root"}' \
'https://api.kloudless.com/v1/meta/applications/wSPk9y5D7p5o87k0ACGKxR/redirect_uris/'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "uri": "root", }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": 6, "application": "wSPk9y5D7p5o87k0ACGKxR", "uri": "root", "created": "2017-12-22T07:58:03.429613Z", "modified": "2017-12-22T07:58:03.429642Z", "api": "meta", "type": "redirect_uri" }
Retrieve a Redirect URI
Retrieve information about an individual Redirect URI.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": 6, "application": "wSPk9y5D7p5o87k0ACGKxR", "uri": "root", "created": "2017-12-22T07:58:03.429613Z", "modified": "2017-12-22T07:58:03.429642Z", "api": "meta", "type": "redirect_uri" }
Delete a Redirect URI
Example request:
curl -L -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-XDELETE 'https://api.kloudless.com/v1/meta/applications/koiR71rFLPTdld9N-YUR/redirect_uris/3/'
- Response
204
File Explorer Upload Locations
Kloudless File Explorer Upload Locations (or FE Upload Locations) have the attributes below:
-
id
Unique identifier for the FE Upload Location. -
application
Kloudless Application ID. -
account
ID of the Kloudless Account accessed by the API request. -
folder_id
ID of the folder. -
folder_name
Name of the folder. -
allow_overwrites
Iftrue
, user-uploaded content with the same name will overwrite each other. Normally, files are renamed if they conflict and are being uploaded to the same folder. Do not set this totrue
unless a specific sub-folder is being specified, or deliberately want to overwrite content with the same name regardless of origin. This option defaults tofalse
. -
allow_specific_subfolder
Iftrue
, the File Explorer can be configured to upload files to either the root folder directly or any specified sub-folder. Otherwise, files will be uploaded to a randomly named sub-folder in the Upload Location to ensure uniqueness. The File Explorer’supload_location_folder
configuration option should contain the ID of the folder as usual, except it can be the configured Upload Location or any sub-folder rather than only the Upload Location. If enabling this behavior, ensure users only have access to IDs of folders their content should be uploaded to. Otherwise, malicious users could upload content to unexpected folders. This option defaults tofalse
. -
created
ISO 8601 timestamp indicating when the object was created. -
modified
ISO 8601 timestamp indicating when the object was modified. -
type
Will always befe_upload_location
. -
api
Will always bemeta
.
List File Explorer Upload Locations
/meta/applications/{application_id}/fe_upload_locations/{?page_size,page}
The response contains the following information:
-
total
Total number of objects -
count
Number of objects on this page -
page
Page number -
objects
List of FE Upload Location objects -
type
Alwaysobject_list
-
api
Alwaysmeta
- Parameters
- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional)Page 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": 2, "application": "T7W_5x_2O7k_P499EjPYL4rJ4VXS_K0JYBwpZKYGF3FEnjDB", "account": "12933", "folder_id": "folder_id_1", "folder_name": "folder_name 1", "allow_overwrites": false, "allow_specific_subfolder": false, "created": "2017-12-21T14:15:27.036803Z", "modified": "2017-12-21T14:15:27.036833Z", "api": "meta", "type": "fe_upload_location" } ], "type": "object_list", "api": "meta" }
Create a File Explorer Upload Location
The required parameters are:
In addition, the following optional parameters may be provided:
Example requests:
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' -d '{ \
"account": "12933", \
"allow_specific_subfolder": true, \
"allow_overwrites": true, \
"folder_id": "root", \
"folder_name": "Test Folder Name" \
}' 'https://api.kloudless.com/v1/meta/applications/wSPk9y5D7p5o87k0ACGKxR/fe_upload_locations/'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "account": "12933", "allow_specific_subfolder": true, "allow_overwrites": true, "folder_id": "root", "folder_name": "Test Folder Name" }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": 5, "application": "wSPk9y5D7p5o87k0ACGKxR", "account": "12933", "folder_id": "root", "folder_name": "Test Folder Name", "allow_overwrites": true, "allow_specific_subfolder": true, "created": "2017-12-21T14:59:43.996480Z", "modified": "2017-12-21T14:59:43.996506Z", "type": "fe_upload_location", "api": "meta" }
Retrieve a File Explorer Upload Location
/meta/applications/{application_id}/fe_upload_locations/{id}/
Retrieve information about an individual File Explorer Upload Location.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": 5, "application": "wSPk9y5D7p5o87k0ACGKxR", "account": "12933", "folder_id": "root", "folder_name": "Test Folder Name", "allow_overwrites": true, "allow_specific_subfolder": true, "created": "2017-12-21T14:59:43.996480Z", "modified": "2017-12-21T14:59:43.996506Z", "api": "meta", "type": "fe_upload_location" }
Update a File Explorer Upload Location
/meta/applications/{application_id}/fe_upload_locations/{id}/
Here are the properties that can be updated:
-
account
-
folder_id
-
folder_name
-
allow_specific_subfolder
-
allow_overwrites
The new object will be returned on success.
Example request:
curl -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-XPATCH -d '{"folder_name": "Test Folder Name 2"}' \
'https://api.kloudless.com/v1/meta/applications/wSPk9y5D7p5o87k0ACGKxR/fe_upload_locations/5/'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "folder_name": "Test Folder Name 2" }
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": 5, "application": "wSPk9y5D7p5o87k0ACGKxR", "account": "12933", "folder_id": "root", "folder_name": "Test Folder Name 2", "allow_overwrites": true, "allow_specific_subfolder": true, "created": "2017-12-21T14:59:43.996480Z", "modified": "2017-12-21T15:12:41.936672Z", "api": "meta", "type": "fe_upload_location" }
Delete a File Explorer Upload Location
/meta/applications/{application_id}/fe_upload_locations/{id}/
Example request:
curl -L -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-XDELETE 'https://api.kloudless.com/v1/meta/applications/koiR71rFLPTdld9N-YUR/fe_upload_locations/3/'
- Response
204
Usage Reports
Kloudless Usage Reports can be retrieved via this endpoint. Each object
describes the application’s API request statistics during a certain time
period beginning at from
(inclusive) and ending at until
(non-inclusive):
[from
, until
). An object has the attributes below:
-
application
Kloudless Application ID. -
from
ISO 8601 timestamp indicating the start of the time period this record contains information on. -
until
ISO 8601 timestamp indicating the end of time period this record contains information on. -
bandwidth
Bandwidth consumed by the application during the time period. -
active_accounts
Number of accounts accessed by the application during the time period. -
requests
Number of API Requests processed by the application during the time period. -
created
ISO 8601 timestamp indicating when the Usage Report record was created. -
type
Will always beusage_report
. -
api
Will always bemeta
.
List Usage Reports
/meta/applications/{application_id}/usage_reports/{?from,until,page_size,page}
The response contains the following information:
-
total
Total number of objects. -
count
Number of objects on this page. -
page
Page number. -
objects
List of Usage Report objects. -
type
Alwaysobject_list
-
api
Alwaysmeta
- Parameters
- from
string
(optional)ISO 8601 timestamp. Only Usage Reports representing periods ending at or after this time will be returned.
- until
string
(optional)ISO 8601 timestamp. Only Usage Reports representing periods beginning before this time will be returned.
- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional)Page 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": 4732, "application": "7J689s6Q6CQ2TVXfH5nfBJTEkWVUXbRQhUoDNiwEmi7WSsxq", "from": "2017-01-01T00:00:00Z", "until": "2017-01-02T00:00:00Z", "bandwidth": 1000000, "active_accounts": 69, "requests": 1043, "created": "2017-01-02T12:50:35.453230Z", "api": "meta", "type": "usage_report" } ], "type": "object_list", "api": "meta" }
Invoices
Kloudless Invoices can be retrieved via this endpoint. Each object describes an invoice received from Kloudless. An object has the attributes below:
-
created
ISO 8601 timestamp indicating when the invoice was created. -
amount
Total amount of the invoice in USD. -
description
The invoice’s description. -
status
The invoice’s status. Can be one ofpaid
orunpaid
. -
pdf_url
A URL to download a PDF representation of the invoice from. -
url
A URL to a web page with invoice details and an option to pay the invoice. -
type
Will always beinvoice
. -
api
Will always bemeta
.
List Invoices
The response contains the following information:
-
objects
List of Invoice objects. -
count
Number of objects on this page. -
page
Current page identifier. -
next_page
The value to provide in the request’spage
query parameter for the next page. This will benull
if there are no more pages. -
previous_page
The value to provide in the request’spage
query parameter for the previous page. This will benull
if there are no prior pages. -
type
Alwaysobject_list
-
api
Alwaysmeta
- Parameters
- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
must be between1
and100
.- page
string
(optional)Identifier of the page to return. By default, the first page is returned. The
previous_page
property of the response will benull
in this case. Thenext_page
property contains the identifier of the next page of invoices. Thenext_page
orprevious_page
data returned can be provided in a subsequent API request’spage
query parameter to request the next or previous page of invoices respectively.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "objects": [ { "created": "2018-11-13T07:22:14Z", "amount": 1000, "description": "Developer: Oct, 2018", "status": "paid", "pdf_url": "https://pay.stripe.com/invoice/invst_test_url/pdf", "url": "https://pay.stripe.com/invoice/invst_test_url", "api": "meta", "type": "invoice" } ], "count": 1, "page": null, "next_page": "cD1pbl8xRFZ3RHhBSjM3N2J5dHU0eU1KZEhvSFA=", "previous_page": null, "type": "object_list", "api": "meta" }
API Request Analytics
Statistics for individual Kloudless API Requests can be retrieved via these endpoints. Each object contains information describing an individual API request and has the attributes below:
-
application
Kloudless Application ID. -
account
ID of the Kloudless Account accessed by the API request. -
duration
Duration of the API Request in seconds. -
ip
IP address the API request originated from. -
method
HTTP method used in the API Request. -
path
Path component of the URL accessed. -
query
Query component of the URL accessed. -
request_id
Unique ID of the API Request. -
rx_bytes
Bytes in the HTTP request received by the Kloudless server. -
tx_bytes
Bytes in the HTTP response sent by the Kloudless server. -
start_time
ISO 8601 timestamp indicating when the API request started. -
created
ISO 8601 timestamp indicating when the API request was recorded. -
status
HTTP response status code. -
type
Will always beanalytics_api_request
. -
api
Will always bemeta
.
List API Request Analytics
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 Request Analytics objects. -
type
Alwaysobject_list
-
api
Alwaysmeta
- Parameters
- application
string
(optional)ID of a specific application to retrieve API requests for. The authorized developer must be the owner of application. If not specified, all applications of the authorized developer will be considered.
- from
string
(optional)ISO 8601 timestamp. Only information on API requests with a
created
timestamp at or after this time will be returned.- until
string
(optional)ISO 8601 timestamp. Only information on API requests with a
created
timestamp before this time will be returned.- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional)Page 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": [ { "created": "2017-11-16T12:06:45.203391787Z", "application": "WA5IgJ3b_REULZOWR9NJeOYBg5NQm_i1CnEK7fVBvf2EOyhW", "account": 12389, "duration": 72.448015213, "method": "GET", "path": "/v1/accounts/", "query": "", "ip": "203.0.113.81", "request_id": "bc872beb-a266-4d22-afc9-a7174a745097", "rx_bytes": 0, "start_time": "2017-11-16T12:04:51.580000Z", "tx_bytes": 436, "status": 200, "api": "meta", "type": "analytics_api_request" } ], "type": "object_list", "api": "meta" }
Licenses
Kloudless License objects represent individual licenses used to run Kloudless Enterprise Docker containers and virtual machines.
Kloudless Licenses have the attributes below:
-
id
The license identifier. This is unique across all applications. -
org_id
The organization identifier. This is unique across all applications. -
org_name
The organization name. This is the human-readable name of the Organization that owns this license. -
description
Description of the license’s purpose and any notes. -
release
Kloudless Enterprise release channel. e.g.prod
for production releases andtest
for QA releases. -
active
A boolean value indicating whether this license is active. -
expiry
ISO 8601 timestamp for when the license expires. -
scope
A string delimited by whitespaces indicating the scope of this license. -
apis_available
A list of Kloudless unified APIs available -
services_available
A list of third-party service IDs corresponding to connectors supported by this license. An empty list implies all services are supported. -
support_clustering
A boolean value indicating whether clustering is supported. -
created
ISO 8601 timestamp indicating when the license was created. -
modified
ISO 8601 timestamp indicating when the license was last updated. -
type
Will always belicense
. -
api
Will always bemeta
.
List Licenses
The response contains the following information:
-
total
Total number of objects -
count
Number of objects on this page -
page
Page number -
objects
List of license objects -
type
Alwaysobject_list
-
api
Alwaysmeta
- Parameters
- page_size
number
(optional) Default: 100Number of objects in each page. The
page_size
must be between1
and1000
.- page
number
(optional)Page 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": "1", "description": "", "release": "prod", "major_version": 1, "active": true, "expiry": "2018-10-04T00:00:00Z", "apis_available": [ "storage", "events" ], "services_available": [ "gdrive" ], "scope": "gdrive:normal.storage.default:kloudless gdrive:admin.storage.default:kloudless gdrive:normal.events.default:kloudless gdrive:admin.events.default:kloudless", "support_clustering": false, "created": "2017-10-04T03:03:46.779451Z", "modified": "2017-10-04T03:28:44.947599Z", "api": "meta", "type": "license" } ], "type": "object_list", "api": "meta" }
Create a License
Licenses can be added to your organization; however, not all of the fields can be specified and configured. Therefore, Kloudless allows ou to create a license by copying an existing one as a template. The provided parameters will override the original values.
Here are the required parameters:
-
id
License identifier to copy. -
description
License description
Example requests:
curl -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' -X POST \
-d '{"id": 1, "description": "New license for kloudless development."}' \
'https://api.kloudless.com/v1/meta/licenses'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "id": 1, "description": "New license for kloudless development." }
- Response
201
Toggle Headers
Content-Type: application/json
Body
{ "id": "5", "description": "New license for kloudless development.", "release": "prod", "active": true, "expiry": "2020-01-30T00:00:00Z", "apis_available": [ "storage", "events" ], "services_available": [ "gdrive", ], "support_clustering": false, "created": "2019-01-30T13:40:35.747196Z", "modified": "2019-01-30T13:40:35.747221Z", "api": "meta", "type": "license", "scope": "any:normal.basic", "admin_available": false, "events_available": true }
Retrieve a License
Retrieve information about an individual license.
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "1", "description": "", "release": "prod", "major_version": 1, "active": true, "expiry": "2018-10-04T00:00:00Z", "apis_available": [ "storage", "events" ], "services_available": [ "gdrive" ], "scope": "gdrive:normal.storage.default:kloudless gdrive:admin.storage.default:kloudless gdrive:normal.events.default:kloudless gdrive:admin.events.default:kloudless", "support_clustering": false, "created": "2017-10-14T03:03:46.779451Z", "modified": "2017-10-14T03:28:44.947599Z", "type": "license", "api": "meta", }
Download a License
This is a direct download of the encrypted license.
Example request:
curl -L -H 'Authorization: Bearer [TOKEN]' \
'https://api.kloudless.com/v1/meta/licenses/1/contents'
Update a License
Update information about an individual license with a known ID. Only licenses belonging to the currently authorized developer’s organization can be updated.
Here are the properties that can be updated:
description
The new object will be returned if successful.
Example request:
curl -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-H 'Content-Type: application/json' \
-XPATCH -d '{"description": "New license description."}' \
'https://api.kloudless.com/v1/meta/licenses/4'
- RequestToggle
Headers
Authorization: Bearer [TOKEN]
Content-Type: application/jsonBody
{ "description": "New license description." }
- Response
200
Toggle Headers
Content-Type: application/json
Body
{ "id": "4", "description": "New license description.", "release": "prod", "active": true, "expiry": "2020-01-30T00:00:00Z", "apis_available": [ "storage", "events" ], "services_available": [ "gdrive", ], "support_clustering": false, "created": "2019-01-30T13:40:35.747196Z", "modified": "2019-01-30T13:40:35.747221Z", "api": "meta", "type": "license", "scope": "any:normal.basic", "admin_available": false, "events_available": true }
Delete a License
This deletes a License.
Example request:
curl -L -H 'Authorization: Bearer S4i5EG5ViEAVmMaCilB5' \
-XDELETE 'https://api.kloudless.com/v1/meta/licenses/1'
- Response
204
Other Information
For more information such as Error Codes, SDKs and Support, please refer to the Core API docs.