Cloud BOT RESTful API Reference (4.2)

Download OpenAPI specification:Download

This is Cloud BOT RESTful API Reference.
You need to set a public ID and issue your access tokens for using API.
Cloud BOT dashboard > Please set them from the For Developers page.
https://console.c-bot.pro/development

All the multi-byte characters contained in the request payload and the response will be treated as UTF-8 format.
The request will be rejected if the request payload page has a capacity of more than 4 MB.

Contract List

Refers to the contract list for which API function is enabled.
The Reference permission is required for your access token.

query Parameters

properties

string

Example: properties=plan,owner

An additional array of property name
List the following property names separated by ,(comma)
plan: Plan name
owner: Plan's owner
timezone: Time zone
location: Location
name: Contract name
organization: Organization name(Personal name)
postcode: Zip code
address: Address
phone: Phone number
department: Department
username: Contact person
(public_id, public_path property is required.)

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string Access token This is required for token based authentication.
secret-key	string Secret key This is required for token based authentication.
authorization	string Value: "Bearer {Token}" OAuth access token This is required for OAuth authentication. The value will be written in Bearer scheme.

Responses

Response samples

Content type

application/json

{"code": 200,
"contracts": [{"public_id": "example1",
"public_path": "/example1/",
"plan": "free",
"owner": "example1@example.com",
"timezone": "Asia/Tokyo",
"location": "Japan",
"name": null,
"organization": null,
"postcode": null,
"address": null,
"phone": null,
"department": null,
"username": null
},
{"public_id": "example2",
"public_path": "/example2/",
"plan": "Single Office",
"owner": "example2@example.com",
"timezone": "Asia/Tokyo",
"location": "Japan",
"name": "Head Office",
"organization": "Cloud BOT,Inc.",
"postcode": "000-0000",
"address": "1560 Broadway Suite 1001 New York, NY",
"phone": "000-0000-0000",
"department": "General Affairs Department",
"username": "John Smith"
}
]
}

BOT List

Refer to the API publishing BOT list
The Reference permission is required for your access token.

path Parameters

public_id

required

string

Public ID of API

query Parameters

properties

string

Example: properties=icon,created,last_modified,creator

An additional array of property name
List the following property names separated by ,(comma)
icon: Icon Image
created: Created Date
last_modified: Updated Date
creator: Author
(id, name, description property is required)

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string Access token This is required for token based authentication.
secret-key	string Secret key This is required for token based authentication.
authorization	string Value: "Bearer {Token}" OAuth access token This is required for OAuth authentication. The value will be written in Bearer scheme.

Responses

Response samples

Content type

application/json

{"code": 200,
"bots": [{"id": "get_items",
"name": "GETTING ITEMS BOT",
"description": "A BOT for getting items.",
"icon": "data:image/png;base64,0000000000",
"created": "2020-04-06T14:32:23Z",
"last_modified": "2020-04-07T15:10:02Z",
"creator": "example@example.com"
},
{"id": "add_item",
"name": "Adding Additional ITEMS BOT",
"description": "A BOT for adding items.",
"icon": "data:image/png;base64,0000000000",
"created": "2020-04-07T06:29:41Z",
"last_modified": "2020-04-07T09:41:44Z",
"creator": "example@example.com"
}
]
}

BOT Details

Refer to the BOT details.
The Reference permission is required for your access token.

path Parameters

public_id required	string Public ID of API
bot_id required	string BOT ID

query Parameters

properties

string

Example: properties=icon,created,last_modified,creator,input,output

An additional array of property name
List the following property names separated by ,(comma)
icon: Icon Image
created: Created Date
last_modified: Updated Date
creator: Author
input: Input Definition
outout: Output Definition
(id, name, description property is required)

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string Access token This is required for token based authentication.
secret-key	string Secret key This is required for token based authentication.
authorization	string Value: "Bearer {Token}" OAuth access token This is required for OAuth authentication. The value will be written in Bearer scheme.

Responses

Response samples

Content type

application/json

{"code": 200,
"id": "add_item",
"name": "Adding Additional ITEMS BOT",
"description": "A BOT for adding items.",
"icon": "data:image/png;base64,0000000000",
"created": "2020-04-07T06:29:41Z",
"last_modified": "2020-04-07T09:41:44Z",
"creator": "example@example.com",
"input": {"data": {"Login ID": {"type": "string"
},
"Password": {"type": "string"
},
"Items": {"type": "group",
"data": {"Item Name": {"type": "string"
},
"Price": {"type": "string"
},
"Image": {"type": "files"
},
"Tags": {"type": "string[]"
}
}
}
}
},
"output": {"data": {"Items": {"type": "group",
"data": {"Item ID": {"type": "string"
}
}
}
}
}
}

BOT Execution

Execute an any BOT.
The Execution permission is required for your access token.

path Parameters

public_id required	string Public ID of API
bot_id required	string BOT ID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string Access token This is required for token based authentication.
secret-key	string Secret key This is required for token based authentication.
authorization	string Value: "Bearer {Token}" OAuth access token This is required for OAuth authentication. The value will be written in Bearer scheme.

Request Body schema: application/json

timeout	integer [ 0 .. 25000 ] The number of milliseconds waiting for the completion of BOT execution.(unspecified sets 0) Start the execution after the request and return a response after the specified time even if the BOT execution is not finished.(Response code is 202)
callback_endpoint	string <uri> The execution result will be posted to the endpoint.(Unspecified sets no callback) The endpoint must start with https://. For more information about the implement requirements for endpoint, please refer to Implement Requirements for Cloud BOT RESTful API Callback Endpoint.
callback_tries	integer [ 0 .. 5 ] Number of Attempts for callback posting. When the callback_endpoint get status code other than 200 series or an incorrect access token was set at the response header, Attempts number of times you specified. No callback if you set 0 times.
	object (datalist_input) An object that represents an input value.(The BOT default value will be used if it is not specified.) Set an any number of data names and group names for which you want to specify input values.

Responses

Request samples

Payload

Content type

application/json

Example

example-1

{"timeout": 20000,
"input": {"Keyword": "Cloud BOT"
}
}

Response samples

Content type

application/json

{"code": 201,
"job_id": "00000000-0000-0000-0000-000000000000",
"bot_id": "get_items",
"bot_name": "GETTING ITEMS BOT",
"status": 0,
"start_time": "2019-12-02T05:30:13Z",
"elapsed_time": 6,
"output": {"Number": "2",
"Items": [{"Item name": "Cheese Cake",
"Price": "500",
"Image": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000000",
"meta": {"name": "0001.jpg",
"size": 603956,
"timestamp": 1513657350000
}
}
]
},
"Tags": ["Cake",
"Cheese"
]
},
{"Item name": "Gateau Chocolat",
"Price": "600",
"Image": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000001",
"meta": {"name": "0002.jpg",
"size": 694475,
"timestamp": 1651024763990
}
}
]
},
"Tags": ["Cake",
"Chocolate"
]
}
]
}
}

BOT Job List

Refer to BOT job list.
The Reference permission is required for your access token.

400 error response will be returned if the response size exceeds 4MB.

path Parameters

public_id required	string Public ID of API
bot_id required	string BOT ID

query Parameters

properties	string Example: properties=output An additional array of property name List the following property names separated by ,(comma) output: Output Object (job_id,bot_id,bot_name,status,start_time,elapsed_time property are required)
limit	integer >= 0 Example: limit=10 The maximum number of items
datetime_from	string <date-time> Example: datetime_from=2019-01-01T00:00:00Z Indicate jobs created after a specified time(ISO 8601)
datetime_to	string <date-time> Example: datetime_to=2019-01-01T00:00:00Z Indicate jobs created before a specified time(ISO 8601)
id_from	string Example: id_from=00000000-0000-0000-0000-000000000000 Indicate jobs whose ID are greater than specified ID
id_to	string Example: id_to=00000000-0000-0000-0000-000000000000 Indicate jobs whose ID are smaller than specified ID
statuses	integer Example: statuses=1 Indicates jobs with the specified status Status(0:Succeeded 1:Error 2:Executing) Can be specified multiple times by separating with ,(comma) (statuses=0,1)
sort_order	string Default: "desc" Enum: "asc" "desc" Example: sort_order=asc By sort

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string Access token This is required for token based authentication.
secret-key	string Secret key This is required for token based authentication.
authorization	string Value: "Bearer {Token}" OAuth access token This is required for OAuth authentication. The value will be written in Bearer scheme.

Responses

Response samples

Content type

application/json

{"code": 200,
"jobs": [{"job_id": "00000000-0000-0000-0000-000000000001",
"bot_id": "get_items",
"bot_name": "GETTING ITEMS BOTT",
"status": 2,
"start_time": "2019-12-02T06:10:56Z",
"cast_url": "https://console.c-bot.pro/cast_url_sample"
},
{"job_id": "00000000-0000-0000-0000-000000000000",
"bot_id": "get_items",
"bot_name": "GETTING ITEMS BOT",
"status": 0,
"start_time": "2019-12-02T06:04:21Z",
"elapsed_time": 6,
"output": {"Number": "2",
"Items": [{"Item name": "Cheese Cake",
"Price": "500",
"Image": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000000",
"meta": {"name": "0001.jpg",
"size": 603956,
"timestamp": 1513657350000
}
}
]
},
"Tags": ["Cake",
"Cheese"
]
},
{"Item name": "Gateau Chocolat",
"Price": "600",
"Image": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000001",
"meta": {"name": "0002.jpg",
"size": 694475,
"timestamp": 1651024763990
}
}
]
},
"Tags": ["Cake",
"Chocolate"
]
}
]
}
}
]
}

Job Reference

Refer to an any job result.
The Reference permission is required for your access token.

path Parameters

public_id required	string Public ID of API
job_id required	string JOB ID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string Access token This is required for token based authentication.
secret-key	string Secret key This is required for token based authentication.
authorization	string Value: "Bearer {Token}" OAuth access token This is required for OAuth authentication. The value will be written in Bearer scheme.

Responses

Response samples

Content type

application/json

Example

example-1

{"code": 200,
"job_id": "00000000-0000-0000-0000-000000000000",
"bot_id": "get_items",
"bot_name": "GETTING ITEMS BOT",
"status": 0,
"start_time": "2019-12-02T06:04:21Z",
"elapsed_time": 6,
"output": {"Number": "2",
"Items": [{"Item name": "Cheese Cake",
"Price": "500",
"Image": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000000",
"meta": {"name": "0001.jpg",
"size": 603956,
"timestamp": 1513657350000
}
}
]
},
"Tags": ["Cake",
"Cheese"
]
},
{"Item name": "Gateau Chocolat",
"Price": "600",
"Image": {"type": "files",
"files": [{"ref": "jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000001",
"meta": {"name": "0002.jpg",
"size": 694475,
"timestamp": 1651024763990
}
}
]
},
"Tags": ["Cake",
"Chocolate"
]
}
]
}
}

Job Suspension

Suspend an any executing JOB.
The Suspension permission is required for your access token.

path Parameters

public_id required	string Public ID of API
job_id required	string JOB ID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string Access token This is required for token based authentication.
secret-key	string Secret key This is required for token based authentication.
authorization	string Value: "Bearer {Token}" OAuth access token This is required for OAuth authentication. The value will be written in Bearer scheme.

Responses

Response samples

Content type

application/json

{"code": 200,
"job_id": "00000000-0000-0000-0000-000000000000",
"bot_id": "get_items",
"bot_name": "GETTING ITEMS BOT",
"status": 1,
"start_time": "2019-12-02T06:15:33Z",
"elapsed_time": 3
}

BOT Subscription List (REST Hooks)

Refer to BOT subscription list.
The Reference permission is required for your access token.

path Parameters

public_id required	string Public ID of API
bot_id required	string BOT ID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string Access token This is required for token based authentication.
secret-key	string Secret key This is required for token based authentication.
authorization	string Value: "Bearer {Token}" OAuth access token This is required for OAuth authentication. The value will be written in Bearer scheme.

Responses

Response samples

Content type

application/json

{"code": 200,
"subscriptions": [{"subscribe_id": 1000000,
"language": "ja",
"event": "onended",
"callback_type": "webhook",
"callback_endpoint": "https://example.com/callback_endpoint",
"disabled": false,
"unsubscribe_endpoint": "https://api.c-bot.pro/example1/bots/get_items/subscriptions/1000000"
},
{"subscribe_id": 1000001,
"language": "en",
"event": "onsucceeded",
"callback_type": "mailhook",
"callback_emails": {"member_emails": ["sample1@example.com",
"sample2@example.com"
],
"other_emails": ["sample3@example.com",
"sample4@example.com"
]
},
"disabled": false,
"unsubscribe_endpoint": "https://api.c-bot.pro/example1/bots/get_items/subscriptions/1000001"
}
]
}

BOT Subscription (REST Hooks)

The subscription has started.
When subscription started, Webhook and Mailhook will be available that linked with BOT operation.
The Reference permission is required for your access token.

path Parameters

public_id required	string Public ID of API
bot_id required	string BOT ID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string Access token This is required for token based authentication.
secret-key	string Secret key This is required for token based authentication.
authorization	string Value: "Bearer {Token}" OAuth access token This is required for OAuth authentication. The value will be written in Bearer scheme.

Request Body schema: application/json

event required	string Enum: "onended" "onsucceeded" "onfailed" "oncannotexecute" Subscription Event onended: on the end onsucceeded: on the end (only if succeeded) onfailed: on the end (only if failed) oncannotexecute: when cannot execute
callback_type	string Default: "webhook" Enum: "webhook" "mailhook" Callback type webhook: When an event occurs, the BOT execution result will be posted to callback_endpoint. mailhook: When an event occurs, the BOT execution result will be notified to callback_emails.
callback_endpoint	string <uri> Specify when callback_type is 'webhook'. The endpoint must always start at https: //. Please refer to 'Cloud BOT RESTful API Callback Endpoint Implementation Requirements' for more information about endpoint implementation requirements.
	object Specify when callback_type is 'mailhook'. Only a verified email address can be specified.

Responses

Request samples

Payload

Content type

application/json

Example

example-1

{"event": "onended",
"callback_type": "webhook",
"callback_endpoint": "https://example.com/callback_endpoint"
}

Response samples

Content type

application/json

{"code": 200,
"subscribe_id": 1000000,
"unsubscribe_endpoint": "https://api.c-bot.pro/example1/bots/get_items/subscriptions/1000000"
}

BOT Unsubscription (REST Hooks)

Unsubscribe BOT
The Reference permission is required for your access token.

path Parameters

public_id required	string Public ID of API
bot_id required	string BOT ID
subscribe_id required	string Subscription ID

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string Access token This is required for token based authentication.
secret-key	string Secret key This is required for token based authentication.
authorization	string Value: "Bearer {Token}" OAuth access token This is required for OAuth authentication. The value will be written in Bearer scheme.

Responses

Response samples

Content type

application/json

{"code": 200
}

Download Files

Download files.
The WS token is required.

path Parameters

key

required

string

Example: jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000000

Ref value of the file to download.
This value must be included in the keys of WS token.

query Parameters

ws_token

required

string

Example: ws_token=00000000-0000-0000-0000-000000000000

WS token
Multiple downloads are possible within the expiration and tries specified when the WS token was issued.

Responses

Response samples

200
404

Content type

application/octet-stream

File Data

Upload files

Upload files.
The WS token is required.

Uploaded files will be stored in the temporary area of the contract and will be added to the storage usage.
The files will be automatically deleted after 6 hours and will be deducted from your storage usage.

query Parameters

ws_token

required

string

Example: ws_token=00000000-0000-0000-0000-000000000000

WS token
Can not upload more than once with one WS token.

header Parameters

content-type required	string Value: "text/plain"
x-cbot-encoding	string Default: plain Enum: "plain" "base64" Encoding type of file data
x-cbot-filename required	string <= 64 characters Name of the file (including the extension)
x-cbot-timestamp	string Last modification time of the file.(Unix timestamp with milliseconds.) Current time will be recorded if omitted.

Request Body schema: text/plain

File data string
The text will be base64 encoded string if the x-cbot-encoding request header is base64.

string

Responses

Request samples

Payload

Content type

text/plain

SGVsbG8sIHdvcmxkLg==

Response samples

Content type

application/json

{"code": 200,
"ref": "temp/00000000-0000-0000-0000-000000000000"
}

Issue WS token

Issue WS token.
This token is required for using a file upload/download API.
The Reference permission is required for your access token.

path Parameters

public_id

required

string

Public ID of API

header Parameters

content-type required	string Value: "application/json"
content-language required	string Enum: "ja" "en"
access-token	string Access token This is required for token based authentication.
secret-key	string Secret key This is required for token based authentication.
authorization	string Value: "Bearer {Token}" OAuth access token This is required for OAuth authentication. The value will be written in Bearer scheme.

Request Body schema: application/json

scopes required	Array of strings Items Enum: "upload" "download" Specify the operation name allowed by this token in an array. Download files: download Upload files: upload
keys required	Array of strings When downloding a file, specify a ref value of the file to be downloaded as an array. When uploading a file, specify the following array. ["temp/"]
expire	integer [ 0 .. 86400 ] Default: 60 Specify the token expiration time (seconds). This specification is valid only when "download" is specified for scopes. When you specify "upload" in scopes, it is always 60 seconds.
tries	integer [ 0 .. 1000 ] Default: 1 Specify the number of times each resource specified in keys can be accessed. This specification is valid only when "download" is specified for scopes. No limit if 0 is specified. Always 1 if scopes is "upload".

Responses

Request samples

Payload

Content type

application/json

Example

example-1

{"scopes": ["download"
],
"keys": ["jobs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000000",
"temp/00000000-0000-0000-0000-000000000000"
],
"expire": 120,
"tries": 3
}

Response samples

Content type

application/json

{"code": 200,
"ws_token": "00000000-0000-0000-0000-000000000000"
}