Cloud BOT
Documentation Powered by ReDoc

Cloud BOT RESTful API Reference (4.4)

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

get /services/contracts
https://api.c-bot.pro/services/contracts

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

200

[OK] The contract list has been responded.

401

[Unauthorized] The access token or secret key is incorrect.

403

[Forbidden] This access token is not authorized to refer to BOT.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] Content-type is incorrect.

422

[Unprocessable Entity] A request is unable to be processed.

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "code": 200,
  • "contracts":
    [
    ]
}

BOT List

get /{public_id}/bots
https://api.c-bot.pro/{public_id}/bots

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

200

[OK] The Bot list has been responded.

401

[Unauthorized] The access token or secret key is incorrect.

403

[Forbidden] This access token is not authorized to refer to BOT.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] content-type is incorrect.

422

[Unprocessable Entity] Request is incorrect.

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "code": 200,
  • "bots":
    [
    ]
}

BOT Details

get /{public_id}/bots/{bot_id}
https://api.c-bot.pro/{public_id}/bots/{bot_id}

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

200

[OK] The BOT details has been responded.

401

[Unauthorized] The access token or secret key is incorrect.

403

[Forbidden] This access token is not authorized to refer to BOT.

404

[Not Found] BOT does not exist.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] content-type is incorrect.

422

[Unprocessable Entity] Request is incorrect.

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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":
    {
    },
  • "output":
    {
    }
}

BOT Execution

post /{public_id}/bots/{bot_id}/jobs
https://api.c-bot.pro/{public_id}/bots/{bot_id}/jobs

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.

input
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

201

[Created] BOT execution is completed.

202

[Accepted] The BOT is executing.

401

[Unauthorized] The access token or secret key is incorrect.

403

[Forbidden] This access token is not authorized to execute BOT.

404

[Not Found] BOT does not exist.

410

[Gone] BOT execution is suspended.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] Content-type is incorrect.

422

[Unprocessable Entity] Request is incorrect.

423

[Locked] The BOT execution is locked. The execution time or the storage capacity has been exceeded.

429

[Too Many Requests] The maximum concurrent access has been exceeded.

Request samples

Content type
application/json
Example
example-1
Copy
 Expand all Collapse all
{
  • "timeout": 20000,
  • "input":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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":
    {
    }
}

BOT Job List

get /{public_id}/bots/{bot_id}/jobs
https://api.c-bot.pro/{public_id}/bots/{bot_id}/jobs

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

200

[OK] The job list has been responded.

400

[Bad Request] The response size exceeds the maximum limit.

401

[Unauthorized] The access token or secret key is incorrect.

403

[Forbidden] This access token is not authorized to refer to BOT.

404

[Not Found] BOT does not exist.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] Content-type is incorrect.

422

[Unprocessable Entity] Request is incorrect.

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "code": 200,
  • "jobs":
    [
    ]
}

Job Reference

get /{public_id}/jobs/{job_id}
https://api.c-bot.pro/{public_id}/jobs/{job_id}

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

200

[OK] The Job has been responded.

401

[Unauthorized] The access token or secret key is incorrect.

403

[Forbidden] This access token is not authorized to refer to BOT.

404

[Not Found] Job does not exist.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] content-type is incorrect.

422

[Unprocessable Entity] Request is incorrect.

Response samples

Content type
application/json
Example
example-1
Copy
 Expand all Collapse all
{
  • "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":
    {
    }
}

Job Suspension

delete /{public_id}/jobs/{job_id}
https://api.c-bot.pro/{public_id}/jobs/{job_id}

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

200

[OK] The Job was suspended.

401

[Unauthorized] The access token or secret key is incorrect.

403

[Forbidden] This access token is not authorized to suspend the job.

404

[Not Found] Job does not exist.

410

[Gone] Job has been already done.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] content-type is incorrect.

422

[Unprocessable Entity] Request is incorrect.

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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)

get /{public_id}/bots/{bot_id}/subscriptions
https://api.c-bot.pro/{public_id}/bots/{bot_id}/subscriptions

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

200

[OK] The subscription list has been responded.

401

[Unauthorized] The access token or secret key is incorrect.

403

[Forbidden] This access token is not authorized to refer to BOT.

404

[Not Found] BOT does not exist.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] content-type is incorrect.

422

[Unprocessable Entity] Request is incorrect.

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

BOT Subscription (REST Hooks)

post /{public_id}/bots/{bot_id}/subscriptions
https://api.c-bot.pro/{public_id}/bots/{bot_id}/subscriptions

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.

callback_emails
object

Specify when callback_type is 'mailhook'.
Only a verified email address can be specified.

Responses

200

[OK] The subscription has started.

401

[Unauthorized] The access token or secret key is incorrect.

403

[Forbidden] This access token is not authorized to refer to BOT.

404

[Not Found] BOT does not exist.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] content-type is incorrect.

422

[Unprocessable Entity] Request is incorrect.

429

[Too Many Subscriptions] The maximum number of subscriptions has been exceeded.

Request samples

Content type
application/json
Example
example-1
Copy
 Expand all Collapse all
{}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

BOT Unsubscription (REST Hooks)

delete /{public_id}/bots/{bot_id}/subscriptions/{subscribe_id}
https://api.c-bot.pro/{public_id}/bots/{bot_id}/subscriptions/{subscribe_id}

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

200

[OK] Unsubscribed.

401

[Unauthorized] The access token or secret key is incorrect.

403

[Forbidden] This access token is not authorized to refer to BOT.

404

[Not Found] BOT or subscription ID does not exist.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] content-type is incorrect.

422

[Unprocessable Entity] Request is incorrect.

423

[Locked] The subscription has been locked.

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "code": 200
}

Download Files

get /services/files/{key}
https://api.c-bot.pro/services/files/{key}

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

200

[OK] The file has been responded.

404

[Not Found] File does not exist.

Response samples

Content type
application/octet-stream
Copy
File Data

Upload files

post /services/files/temp/
https://api.c-bot.pro/services/files/temp/

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
Multiple uploads are possible within the expiration and tries specified when the WS token was issued.

header Parameters
content-type
required
string
Enum: "text/plain" "multipart/form-data; boundary=Boundary"
x-cbot-encoding
string
Default: plain
Enum: "plain" "base64"

Encoding type of file data
Applies when content-type is "text/plain".

x-cbot-filename
string <= 64 characters

Name of the file (including the extension)
This is required if content-type is "text/plain".

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
string

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

Responses

200

[OK] The file has been uploaded.

401

[Unauthorized] The WS token is incorrect.

403

[Forbidden] This WS token is not authorized to upload.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] Content-type is incorrect.

422

[Unprocessable Entity] Request is incorrect.

423

[Locked] The storage capacity has been exceeded.

Request samples

Content type
text/plain
Copy
SGVsbG8sIHdvcmxkLg==

Response samples

Content type
application/json
Example
example-1 (text/plain)
Copy
 Expand all Collapse all
{
  • "code": 200,
  • "ref": "temp/00000000-0000-0000-0000-000000000000"
}

Issue WS token

post /{public_id}/ws_tokens
https://api.c-bot.pro/{public_id}/ws_tokens

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

tries
integer [ 0 .. 1000 ]
Default: 1

Specify the number of times each resource specified in keys can be accessed.
If 0 is specified, there is no limit.

Responses

200

[OK] WS token issued

401

[Unauthorized] The access token or secret key is incorrect.

403

[Forbidden] This access token is not authorized to refer to BOT.

413

[Payload Too Large] Payload is too large.

415

[Unsupported Media Type] Content-type is incorrect.

422

[Unprocessable Entity] Request is incorrect.

Request samples

Content type
application/json
Example
example-1
Copy
 Expand all Collapse all
{
  • "scopes":
    [
    ],
  • "keys":
    [
    ],
  • "expire": 60,
  • "tries": 1
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "code": 200,
  • "ws_token": "00000000-0000-0000-0000-000000000000"
}