API Reference v0.4 (Beta)

Pico Cloud REST API

Welcome to the Pico Cloud Technology Ltd API documentation. Our REST API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL https://rest.picotw.com

Overview

The Pico Cloud REST API provides programmatic access to Pico Cloud's messaging services. You can use this API to send SMS and MMS messages, manage campaigns and templates, and retrieve account information.

All API requests must be made over HTTPS. Requests made over plain HTTP will be refused. All request and response bodies are JSON-encoded.

Authentication

PICO API uses API keys and JWT token to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via the following HTTP headers. Only the API for retrieving JWT token does not require the Authorization field. You do not need to provide a password.

Required HTTP Headers

"X-API-Key": "1O1IQxPv53888888899999000538888888999999"
"Authorization": "Bearer eyJhbGciOiJIUzUxMiJ9..."

⚠️ Security Warning

The JWT token expires if the time interval between each request exceeds 30 minutes. If the token is incorrect or expired, you will receive a 401 error.

401 Unauthorized Example

{
 "msg": "請求訪問：/xxx/yyy，驗證失敗，無法訪問系统資源",
 "code": "401"
}

IP Whitelist: If you need to enable the IP whitelist feature, use the domain api.picotw.com instead of rest.picotw.com. Submit your IP address on the "HTTP IP Whitelist" page in the Pico platform and contact the sales team for backend approval.

Security Schemes

Type	Name	In
apiKey	`Authorization`	HEADER
apiKey	`X-API-Key`	HEADER

Errors

Pico Cloud uses conventional HTTP response codes to indicate success or failure. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error based on the information provided.

HTTP Code	Status	Description
`200`	OK	The request was successful.
`400`	BAD_REQUEST	The request was unacceptable, often due to a missing or invalid parameter.
`401`	UNAUTHORIZED	JWT token is missing, invalid, or expired. Retrieve a new token and retry.
`417`	EXPECTATION_FAILED	The server could not meet the expectation given in the request.

Error Response Body

All error responses return a JSON body with the following structure:

{
 "request_id": "9ca38439-732f-4c88-87c7-0b3eda19dfca",
 "errors": ["Error description message"]
}

GET /token/{username}

Retrieve JWT Token

Before performing operations, you must retrieve a JWT token. This token is required in the Authorization header for all subsequent requests.

Path Parameters

Parameter	Type	Description
username	string	Your unique API account username. Example: user333

Header Parameters

Parameter	Type	Description
X-API-Key	string	Your account API Key. Example: 3RbGvrZp...

Responses

HTTP Code	Description
`200`	OK — Returns UserTokenResponse
`400`	BAD_REQUEST — Returns MsgExceptionResponse

cURL

curl -X GET "https://rest.picotw.com/token/user333" \
 -H "X-API-Key: 3RbGvrZp53888888899999000"

Response 200 OK

{
 "request_id": "9ca38439-732f-4c88-87c7-0b3eda19dfca",
 "token": "eyJhbGciOiJIUzUxMiJ9..."
}

Rate Limit: 1 request per second per API key.

POST /campaign

Create Campaign

Create a campaign in your account. Campaigns are used to organise and group your message templates.

Body Parameters

Parameter	Type	Description
username*	string	API account name.
name*	string	The name of the campaign. Length: 1 – 50 characters. Example: My Campaign
remark	string	A description or note for the campaign. Length: 0 – 255 characters.

cURL

curl -X POST "https://rest.picotw.com/campaign" \
 -H "X-API-Key: 1O1IQxPv53888888899999000538888888" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..." \
 -H "Content-Type: application/json; charset=utf-8" \
 -d '{
 "username": "user333",
 "name": "Campaign",
 "remark": "Campaign"
 }'

Response 200 OK

{
 "request_id": "db675a0f-c0ca-46b1-bfc1-abf76663feee"
}

GET /campaigns

List Campaigns

Retrieve a list of all campaigns in your account.

cURL

curl -X GET "https://rest.picotw.com/campaigns" \
 -H "X-API-Key: 1O1IQxPv53888888899999000538888888" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..."

Response 200 OK

{
 "campaigns": [
 {
 "id": "campaign-123",
 "name": "My Campaign",
 "remark": "Campaign description",
 "created_at": "2024-01-15T10:30:00Z"
 }
 ],
 "request_id": "9ca38439-732f-4c88-87c7-0b3eda19dfca"
}

PUT /campaign/{campaignId}

Update Campaign

Update an existing campaign's information.

Path Parameters

Parameter	Type	Description
campaignId*	string	The unique identifier of the campaign.

Body Parameters

Parameter	Type	Description
name	string	New name for the campaign.
remark	string	New description for the campaign.

cURL

curl -X PUT "https://rest.picotw.com/campaign/campaign-123" \
 -H "X-API-Key: 1O1IQxPv53888888899999000538888888" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..." \
 -H "Content-Type: application/json" \
 -d '{"name": "Updated Campaign"}'

DELETE /campaign/{campaignId}

Delete Campaign

Delete a campaign from your account.

Path Parameters

Parameter	Type	Description
campaignId*	string	The unique identifier of the campaign.

cURL

curl -X DELETE "https://rest.picotw.com/campaign/campaign-123" \
 -H "X-API-Key: 1O1IQxPv53888888899999000538888888" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..."

POST /template/sms

Create SMS Template

Create a new SMS message template for approval.

Body Parameters

Parameter	Type	Description
username*	string	API account name.
campaignId*	string	Campaign ID to associate this template with.
name*	string	Template name.
content*	string	SMS message content. Use {{var}} for variables.

cURL

curl -X POST "https://rest.picotw.com/template/sms" \
 -H "X-API-Key: 1O1IQxPv53888888899999000538888888" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..." \
 -H "Content-Type: application/json" \
 -d '{
 "username": "user333",
 "campaignId": "campaign-123",
 "name": "Verification Code",
 "content": "Your code is {{code}}"
 }'

POST /template/mms

Create MMS Template

Create a new MMS message template with media content.

Body Parameters

Parameter	Type	Description
username*	string	API account name.
campaignId*	string	Campaign ID to associate this template with.
name*	string	Template name.
content*	string	MMS message text content.
mediaUrl	string	URL to the media file (image/video).

cURL

curl -X POST "https://rest.picotw.com/template/mms" \
 -H "X-API-Key: 1O1IQxPv53888888899999000538888888" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..." \
 -H "Content-Type: application/json" \
 -d '{
 "username": "user333",
 "campaignId": "campaign-123",
 "name": "Promo Image",
 "content": "Check out our new product!",
 "mediaUrl": "https://example.com/image.jpg"
 }'

GET /templates

List Templates

Retrieve a list of all message templates in your account.

Query Parameters

Parameter	Type	Description
campaignId	string	Filter templates by campaign ID.
status	string	Filter by approval status (pending, approved, rejected).

cURL

curl -X GET "https://rest.picotw.com/templates" \
 -H "X-API-Key: 1O1IQxPv53888888899999000538888888" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..."

DELETE /template/{templateId}

Delete Template

Delete a message template from your account.

Path Parameters

Parameter	Type	Description
templateId*	string	The unique identifier of the template.

cURL

curl -X DELETE "https://rest.picotw.com/template/template-123" \
 -H "X-API-Key: 1O1IQxPv53888888899999000538888888" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..."

POST /sms

Send an SMS

Send a single SMS message to a specific phone number. You can use either raw text or a pre-approved templateId.

Body Parameters

Parameter	Type	Description
username*	string	API account name.
from*	string	The sender ID or number. Example: 8612345678888
to*	string	The destination number in E.164 format. Example: 8612345678901
text	string	The message body. Required if templateId is not provided. Example: Your code is 1234
templateId	string	UUID of a pre-approved template. Required if text is not provided.
callback	string	Webhook URL to receive the Delivery Receipt (DLR).

cURL — Using text

curl -X POST "https://rest.picotw.com/sms" \
 -H "X-API-Key: 1O1IQxPv53888888899999000538888888" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..." \
 -H "Content-Type: application/json" \
 -d '{
 "username":"user333",
 "from":"8612345678888",
 "to":"8612345678901",
 "text":"Your verification code is 1234",
 "callback":"https://abcdefg.m.pipedream.net/"
 }'

Response 200 OK

{
 "request_id": "9ca38439-732f-4c88-87c7-0b3eda19dfca"
}

Rate Limit: 30 requests per second per API key. Contact sales for higher throughput.

POST /mms

Send an MMS

Send a multimedia message (SMS with media) to a specific phone number.

Body Parameters

Parameter	Type	Description
username*	string	API account name.
from*	string	The sender ID or number.
to*	string	The destination number in E.164 format.
text	string	The message text body.
mediaUrl*	string	URL to the media file (image, video, or audio).

cURL

curl -X POST "https://rest.picotw.com/mms" \
 -H "X-API-Key: 1O1IQxPv53888888899999000538888888" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..." \
 -H "Content-Type: application/json" \
 -d '{
 "username":"user333",
 "from":"8612345678888",
 "to":"8612345678901",
 "text":"Check out this image!",
 "mediaUrl":"https://example.com/image.jpg"
 }'

POST /voice

Send Voice TTS

Send a text-to-speech voice message to a phone number.

Body Parameters

Parameter	Type	Description
username*	string	API account name.
to*	string	The destination phone number.
text*	string	The text to convert to speech.
lang	string	Language code (e.g., en-US, zh-CN). Default: en-US

cURL

curl -X POST "https://rest.picotw.com/voice" \
 -H "X-API-Key: 1O1IQxPv53888888899999000538888888" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..." \
 -H "Content-Type: application/json" \
 -d '{
 "username":"user333",
 "to":"8612345678901",
 "text":"Your verification code is 1234",
 "lang":"en-US"
 }'

GET /balance/{username}

Get Account Balance

Retrieve the remaining credit balance in your account.

Path Parameters

Parameter	Type	Description
username	string	Your API account username. Example: user333

cURL

curl -X GET "https://rest.picotw.com/balance/user333" \
 -H "X-API-Key: 3RbGvrZp53888888899999000" \
 -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..."

Response 200 OK

{
 "balance": "1234.56",
 "request_id": "9ca38439-732f-4c88-87c7-0b3eda19dfca",
 "username": "user333"
}

Rate Limit: 1 request per second per API key.

Definitions

Data schemas referenced by the API responses above.

UserTokenResponse

request_id	The ID of this request operation. string
token	The JWT token for authentication. string

AddCampaignResponse

request_id

The ID of the created campaign. string

MsgExceptionResponse

request_id	The ID of this request operation. string
errors	The description of the errors. string[]

MsgInfo

request_id

The ID of this request operation. string

UserBalanceResponse

balance	The remaining balance in the account. string
request_id	The ID of this request operation. string
username	API account name. string