Actions API

The Actions API provides endpoints to help build, manage, and test your Action.

Client Library (Node.js)

While you can use the Actions API RESTful service by making direct HTTP requests to the server, we provide a client library that makes it easier to access the endpoints from Node.js. The Actions API client library allows you to manage and test your Action using a variety of endpoints.

For example, the code below makes a call to the writePreview endpoint to update a user's project preview based on the provided model:

   import {ActionsSdkClient} from '@assistant/actions';
   import { promisify } from 'util';
   import * as stream from 'stream';

   const PROJECT_ID = '<PROJECT_ID>';
   const VERSION = 123;

   const projectPath = `projects/${PROJECT_ID}`;
   const versionPath = `projects/${PROJECT_ID}/versions/${VERSION}`;

    async function publishPreview(projectPath, versionPath) {
      const request = {
        parent: projectPath,
        previewSettings: {sandbox: {value: true}},
        submittedVersion: {version: versionPath}

      const client = new ActionsSdkClient();
      const stream = client.writePreview(()=>{});
      const finished = promisify(stream.finished);
      await finished(stream);

For installation instructions and reference material for the Actions API Node.js client library, see the library and Actions API REST reference documentation.


The following requirements apply to requests made to the Actions API.

Request payload size

Requests made to the Actions API must be 10 MB or less. This includes client streaming endpoints, where each request in the stream must be 10 MB or less.

If your payload exceeds 10 MB, you should receive a 400 error from the Actions SDK server.

Best practices

The following best practices are strongly recommended when you use the Actions API.

Set the x-goog-user-project request header

When building a tool or application for your users, you may want a user's project to be billed and used for quota limits, rather than your client project. To specify a project for billing and quota purposes, set the x-goog-user-project request header.

Valid Values The Project ID for an existing Google Cloud project
Example x-goog-user-project: my-project
Details The project specified in the header is used for quota limits and billed for charges associated with the request.

Set the user-agent request header

Set an appropriate user agent using the user-agent request header. This helps the API determine if requests originate from partners.

Known limitations

This section describes known limitations of the Actions API.

Timeout for client streaming endpoints

This limitation only applies to HTTP requests you make to client streaming endpoints. Requests made using the client library are not affected by this limitation.

If you are using HTTP requests to call WritePreview, CreateVersion, or WriteDraft, we recommend that you implement a timeout to handle requests that are not successful.

If you receive a response header that specifies a status code other than 200, your code should terminate the stream after a certain period of time. This issue only affects client streaming endpoints. For example, the gactions tool, which uses the Actions API, has a 5-second timeout.