Skip to main content

Server Frontend API Reference

While it's usually easiest to interact with Temporal Server via a Client SDK or the Temporal CLI, you can also use its gRPC API.

gRPC API​

Our Client and Worker SDKs use the gRPC API. The API reference is located here:

api-docs.temporal.io

Use with code​

Usually you interact with the API via high-level methods like client.workflow.start(). However, Client SDKs also expose the underlying gRPC services. For instance, the TypeScript SDK has:

If you're not using an SDK Client (rare), you can generate gRPC client stubs by:

Use manually​

To query the API manually via command line or a GUI, first:

git clone https://github.com/temporalio/api.git
cd api

With command line​

Install evans.

cd /path/to/api
evans --proto temporal/api/workflowservice/v1/service.proto --port 7233

To connect to Temporal Cloud, set the host, cert, cert key, and TLS flag:

evans --proto temporal/api/workflowservice/v1/service.proto --host devrel.a2dd6.tmprl.cloud --port 7233 --tls --cert /Users/me/certs/temporal.pem --certkey /Users/me/certs/temporal.key

Once inside the evans prompt, you can run commands like help, show service to list available methods, and call ListWorkflowExecutions.

With a GUI​

  • Install BloomRPC.
  • Open the app
  • Select "Import Paths" button on the top-left and enter the path to the cloned repo: /path/to/api
  • Select the "Import protos" + button and select this file:
/path/to/api/temporal/api/workflowservice/v1/service.proto
  • A list of methods should appear in the sidebar. Select one.
  • Edit the JSON in the left pane.
  • Hit Cmd/Ctrl-Enter or click the play button to get a response from the server on the right.

ListWorkflowExecutions

ListWorkflowExecutions

One downside compared to command line is it doesn't show enum names, just numbers like "task_queue_type": 1.

DescribeTaskQueue

DescribeTaskQueue

HTTP API​

The Web UI uses temporalio/ui-server, an HTTP proxy for the gRPC API.

caution

As soon as this HTTP API proposal is implemented, it will be the recommended HTTP API, at which point the ui-server API may be discontinued. Further, ui-server was designed for use in the UI, and may make breaking changes.

To view the API docs, run temporal server start-dev and open:

localhost:8233/openapi/

To make a request, run:

$ curl localhost:8233/api/v1/namespaces/default/workflows

{
  "executions": [
    {
      "execution": {
        "workflowId": "workflow-_homozdkzYWLRpX6Rfou5",
        "runId": "c981cb26-baa4-4af8-ac5f-866451d3f83c"
      },
      "type": {
        "name": "example"
      },
      "startTime": ...
    },
    ...
  ],
  "nextPageToken": null
}
```

*/}