Quickstart

Like the Console UI and the Serverless Toolkit, create and manage your Services, Functions, and Assets with the Serverless API. This API lets you create custom Build and Deployment automations that suit your specific needs.

(warning)

Classic Functions and Assets unavailable through the API

This API can't access classic Functions and Assets. Nor can the classic Functions and Assets interface access API-generated Functions and Assets.

Deploying a single Function

Create a Service that contains your Environments. The value of the uniqueName parameter becomes part of your hostname for your Function.

For example: A Service with the unique name Hoot creates a hostname of https://hoot-3234.twil.io.
View the Create Service example
Create a Service
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID at twilio.com/console
5
// Provision API Keys at twilio.com/console/runtime/api-keys
6
// and set the environment variables. See http://twil.io/secure
7
// For local testing, you can use your Account SID and Auth token
8
const accountSid = process.env.TWILIO_ACCOUNT_SID;
9
const apiKey = process.env.TWILIO_API_KEY;
10
const apiSecret = process.env.TWILIO_API_SECRET;
11
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12

13
async function createService() {
14
const service = await client.serverless.v1.services.create({
15
friendlyName: "testing",
16
includeCredentials: true,
17
uniqueName: "demo",
18
});
19

20
console.log(service.sid);
21
}
22

23
createService();
Response
1
{
2
"sid": "ZS00000000000000000000000000000000",
3
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"friendly_name": "testing",
5
"unique_name": "demo",
6
"include_credentials": true,
7
"ui_editable": false,
8
"domain_base": "service-unique-1234",
9
"date_created": "2018-11-10T20:00:00Z",
10
"date_updated": "2018-11-10T20:00:00Z",
11
"url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000",
12
"links": {
13
"environments": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments",
14
"functions": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Functions",
15
"assets": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Assets",
16
"builds": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds"
17
}
18
}
The response contains a Service SID, in the format ZSXX..XX.

Create an Environment using the Service SID.

View the Create Environment example

Create an Environment

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createEnvironment() {
14  const environment = await client.serverless.v1
15    .services("ZS00000000000000000000000000000000")
16    .environments.create({
17      domainSuffix: "dev",
18      uniqueName: "dev-Environment",
19    });
20
21  console.log(environment.sid);
22}
23
24createEnvironment();

Response

1{
2  "sid": "ZE00000000000000000000000000000000",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ZS00000000000000000000000000000000",
5  "build_sid": null,
6  "unique_name": "dev-Environment",
7  "domain_suffix": "dev",
8  "domain_name": "foobar-1234-stage.twil.io",
9  "date_created": "2018-11-10T20:00:00Z",
10  "date_updated": "2018-11-10T20:00:00Z",
11  "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000",
12  "links": {
13    "variables": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Variables",
14    "deployments": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Deployments",
15    "logs": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Logs"
16  }
17}

The request returns an empty Environment as a hostname like demo-X4HX-dev.twil.io.

To view the hostname, fetch the Environment for your Environment using the ZEXX..XX SID.

View the Fetch Environment Hostname example

Fetch Environment Hostname

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function fetchEnvironment() {
14  const environment = await client.serverless.v1
15    .services("ZS00000000000000000000000000000000")
16    .environments("ZE00000000000000000000000000000000")
17    .fetch();
18
19  console.log(environment.domainName);
20}
21
22fetchEnvironment();

Response

1{
2  "sid": "ZE00000000000000000000000000000000",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ZS00000000000000000000000000000000",
5  "build_sid": "ZB00000000000000000000000000000000",
6  "unique_name": "testing-environment",
7  "domain_suffix": "testing",
8  "domain_name": "foobar-1234-testing.twil.io",
9  "date_created": "2018-11-10T20:00:00Z",
10  "date_updated": "2018-11-10T20:00:00Z",
11  "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000",
12  "links": {
13    "variables": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Variables",
14    "deployments": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Deployments",
15    "logs": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Environments/ZE00000000000000000000000000000000/Logs"
16  }
17}

Create a Function with a FriendlyName parameter.

The response includes a Function SID in the format ZHxxx.
Save this SID. To create the first version of this Function, you need this SID.

View the Create Function example

Write the code for your Function and save it as firstfunc.js.

View the example Function code

Create the first version of your Function using a POST request.

Function or Asset versions define the path, Visibility (public, protected, or private), and file content.
Replace ZSXX..XX with your Service SID and ZHXX..XX with your Function SID.
The response returns a Version SID (ZNXX..XX).

View the Upload Function example

To compile your Function and Asset versions into a single, deployable package, create a Build.

Twilio stores this Build on your behalf.
The response returns a status property.

View the Create Build without dependencies example

Create a Build

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createBuild() {
14  const build = await client.serverless.v1
15    .services("ZS00000000000000000000000000000000")
16    .builds.create({
17      functionVersions: ["ZNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
18    });
19
20  console.log(build.sid);
21}
22
23createBuild();

Response

1{
2  "sid": "ZB00000000000000000000000000000000",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ZS00000000000000000000000000000000",
5  "asset_versions": [
6    {
7      "sid": "ZN00000000000000000000000000000000",
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "service_sid": "ZS00000000000000000000000000000000",
10      "asset_sid": "ZH00000000000000000000000000000000",
11      "date_created": "2018-11-10T20:00:00Z",
12      "path": "/asset-path",
13      "visibility": "PUBLIC"
14    }
15  ],
16  "function_versions": [
17    "ZNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
18  ],
19  "dependencies": [
20    {
21      "name": "twilio",
22      "version": "3.29.2"
23    },
24    {
25      "name": "@twilio/runtime-handler",
26      "version": "1.0.1"
27    }
28  ],
29  "runtime": "node24",
30  "status": "building",
31  "date_created": "2018-11-10T20:00:00Z",
32  "date_updated": "2018-11-10T20:00:00Z",
33  "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000",
34  "links": {
35    "build_status": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000/Status"
36  }
37}

View the Create Build with dependencies example

When you create a Build, specify dependencies that your code requires. Provide the Dependencies parameter as a JSON-stringified array of package name and version pairs.

Create a Build with dependencies

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createBuild() {
14  const build = await client.serverless.v1
15    .services("ZS00000000000000000000000000000000")
16    .builds.create({
17      dependencies: JSON.stringify([{ name: "randomcolor", version: "0.5.4" }]),
18      functionVersions: ["ZNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
19    });
20
21  console.log(build.sid);
22}
23
24createBuild();

Response

1{
2  "sid": "ZB00000000000000000000000000000000",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ZS00000000000000000000000000000000",
5  "asset_versions": [
6    {
7      "sid": "ZN00000000000000000000000000000000",
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "service_sid": "ZS00000000000000000000000000000000",
10      "asset_sid": "ZH00000000000000000000000000000000",
11      "date_created": "2018-11-10T20:00:00Z",
12      "path": "/asset-path",
13      "visibility": "PUBLIC"
14    }
15  ],
16  "function_versions": [
17    "ZNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
18  ],
19  "dependencies": "[{\"name\": \"randomcolor\", \"version\": \"0.5.4\"}]",
20  "runtime": "node24",
21  "status": "building",
22  "date_created": "2018-11-10T20:00:00Z",
23  "date_updated": "2018-11-10T20:00:00Z",
24  "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000",
25  "links": {
26    "build_status": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000/Status"
27  }
28}

To check the status of the Build, repeat sending the following GET request until "status": "completed".

View the Fetch Build example

Fetch a Build to check its status

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function fetchBuild() {
14  const build = await client.serverless.v1
15    .services("ZS00000000000000000000000000000000")
16    .builds("ZB00000000000000000000000000000000")
17    .fetch();
18
19  console.log(build.status);
20}
21
22fetchBuild();

Response

1{
2  "sid": "ZB00000000000000000000000000000000",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ZS00000000000000000000000000000000",
5  "asset_versions": [
6    {
7      "sid": "ZN00000000000000000000000000000000",
8      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9      "service_sid": "ZS00000000000000000000000000000000",
10      "asset_sid": "ZH00000000000000000000000000000000",
11      "date_created": "2018-11-10T20:00:00Z",
12      "path": "/asset-path",
13      "visibility": "PUBLIC"
14    }
15  ],
16  "function_versions": [
17    {
18      "sid": "ZN00000000000000000000000000000001",
19      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
20      "service_sid": "ZS00000000000000000000000000000000",
21      "function_sid": "ZH00000000000000000000000000000001",
22      "date_created": "2018-11-10T20:00:00Z",
23      "path": "/function-path",
24      "visibility": "PUBLIC"
25    }
26  ],
27  "dependencies": [
28    {
29      "name": "twilio",
30      "version": "3.29.2"
31    },
32    {
33      "name": "@twilio/runtime-handler",
34      "version": "1.0.1"
35    }
36  ],
37  "runtime": "node24",
38  "status": "building",
39  "date_created": "2018-11-10T20:00:00Z",
40  "date_updated": "2018-11-10T20:00:00Z",
41  "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000",
42  "links": {
43    "build_status": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000/Status"
44  }
45}

Associate the Build with the Environment you created. Twilio calls this association a Deployment.

View the Create Deployment example

After the Deployment completes, your Function begins serving at your Environment's hostname.

To access your function, go to a URL that resembles https://demo-X4HX-dev.twil.io/thanos. Replace demo-X4HX-dev.twil.io with your Environment's hostname.

Handle Asset uploads

Upload Assets by following the same pattern you used for Functions:

Create an Asset.
Create the Asset Version with a POST request to serverless-uploads.twilio.com.

When you create the Build, include the AssetVersion SIDs, any FunctionVersions, and dependencies.

View the example

Create a Build with a Function and an Asset

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createBuild() {
14  const build = await client.serverless.v1
15    .services("ZS00000000000000000000000000000000")
16    .builds.create({
17      assetVersions: ["ZNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
18      functionVersions: ["ZNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
19    });
20
21  console.log(build.sid);
22}
23
24createBuild();

Response

1{
2  "sid": "ZB00000000000000000000000000000000",
3  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4  "service_sid": "ZS00000000000000000000000000000000",
5  "asset_versions": [
6    "ZNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
7  ],
8  "function_versions": [
9    "ZNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
10  ],
11  "dependencies": [
12    {
13      "name": "twilio",
14      "version": "3.29.2"
15    },
16    {
17      "name": "@twilio/runtime-handler",
18      "version": "1.0.1"
19    }
20  ],
21  "runtime": "node24",
22  "status": "building",
23  "date_created": "2018-11-10T20:00:00Z",
24  "date_updated": "2018-11-10T20:00:00Z",
25  "url": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000",
26  "links": {
27    "build_status": "https://serverless.twilio.com/v1/Services/ZS00000000000000000000000000000000/Builds/ZB00000000000000000000000000000000/Status"
28  }
29}

Next steps

To learn more about Twilio Functions, see the API reference for all Serverless resources. Consider Variables. These let you define conditional values for a given Environment.