> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/temporalio/temporal/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontend Service API

> Public-facing Temporal Server API for client operations

The Frontend Service provides the public-facing gRPC API for Temporal clients, SDKs, and CLI tools. It handles authentication, authorization, rate limiting, and request routing to internal services.

## Overview

The Frontend Service is the primary entry point for:

* Workflow lifecycle operations (start, signal, query, terminate)
* Activity execution management
* Namespace management
* Task queue operations
* Workflow history queries
* Search and visibility operations
* Schedule management
* Batch operations

This service is defined by the Temporal API proto definitions in the `temporal.api.workflowservice.v1` package.

## Service Architecture

The Frontend Service:

* Accepts requests from Temporal SDKs and CLI
* Performs authentication and authorization checks
* Applies rate limiting policies
* Routes requests to History, Matching, and Worker services
* Handles datacenter redirection for global namespaces
* Provides both gRPC and HTTP/gRPC-Web endpoints

## Core Operations

### Workflow Execution

#### StartWorkflowExecution

Starts a new workflow execution.

<ParamField path="namespace" type="string" required>
  Namespace to start the workflow in
</ParamField>

<ParamField path="workflow_id" type="string" required>
  Unique identifier for the workflow (client-specified)
</ParamField>

<ParamField path="workflow_type" type="WorkflowType" required>
  Type of workflow to execute
</ParamField>

<ParamField path="task_queue" type="TaskQueue" required>
  Task queue for workflow tasks
</ParamField>

<ParamField path="input" type="Payloads">
  Input arguments for the workflow
</ParamField>

<ParamField path="workflow_execution_timeout" type="Duration">
  Maximum execution time for the workflow
</ParamField>

<ParamField path="workflow_run_timeout" type="Duration">
  Maximum run time for a single workflow run
</ParamField>

<ParamField path="workflow_task_timeout" type="Duration">
  Timeout for workflow task processing
</ParamField>

<ParamField path="workflow_id_reuse_policy" type="WorkflowIdReusePolicy">
  Policy for reusing workflow IDs
</ParamField>

<ParamField path="retry_policy" type="RetryPolicy">
  Retry policy for the workflow
</ParamField>

<ParamField path="cron_schedule" type="string">
  Cron schedule for recurring workflows
</ParamField>

<ParamField path="memo" type="Memo">
  Memo data attached to the workflow
</ParamField>

<ParamField path="search_attributes" type="SearchAttributes">
  Custom search attributes
</ParamField>

<ResponseField name="run_id" type="string">
  Unique identifier for the workflow run
</ResponseField>

#### GetWorkflowExecutionHistory

Retrieves the history of a workflow execution.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

<ParamField path="execution" type="WorkflowExecution" required>
  Workflow execution identifier (workflow\_id and run\_id)
</ParamField>

<ParamField path="maximum_page_size" type="int32">
  Maximum events per page
</ParamField>

<ParamField path="next_page_token" type="bytes">
  Pagination token
</ParamField>

<ParamField path="wait_new_event" type="bool">
  Long poll for new events
</ParamField>

<ParamField path="history_event_filter_type" type="HistoryEventFilterType">
  Filter for history events
</ParamField>

<ResponseField name="history" type="History">
  Workflow history events
</ResponseField>

<ResponseField name="next_page_token" type="bytes">
  Token for next page
</ResponseField>

<ResponseField name="archived" type="bool">
  Whether history is from archival storage
</ResponseField>

#### DescribeWorkflowExecution

Retrieves detailed information about a workflow execution.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

<ParamField path="execution" type="WorkflowExecution" required>
  Workflow execution identifier
</ParamField>

<ResponseField name="execution_config" type="WorkflowExecutionConfig">
  Workflow configuration
</ResponseField>

<ResponseField name="workflow_execution_info" type="WorkflowExecutionInfo">
  Execution state and metadata
</ResponseField>

<ResponseField name="pending_activities" type="PendingActivityInfo[]">
  Currently pending activities
</ResponseField>

<ResponseField name="pending_children" type="PendingChildExecutionInfo[]">
  Pending child workflow executions
</ResponseField>

### Workflow Control

#### SignalWorkflowExecution

Sends a signal to a running workflow.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

<ParamField path="workflow_execution" type="WorkflowExecution" required>
  Target workflow execution
</ParamField>

<ParamField path="signal_name" type="string" required>
  Name of the signal
</ParamField>

<ParamField path="input" type="Payloads">
  Signal input data
</ParamField>

<ParamField path="identity" type="string" required>
  Identity of the signal sender
</ParamField>

<ParamField path="request_id" type="string">
  Unique request ID for idempotency
</ParamField>

#### QueryWorkflow

Queries the state of a workflow execution.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

<ParamField path="execution" type="WorkflowExecution" required>
  Workflow execution to query
</ParamField>

<ParamField path="query" type="WorkflowQuery" required>
  Query definition with name and arguments
</ParamField>

<ParamField path="query_reject_condition" type="QueryRejectCondition">
  Conditions under which query should be rejected
</ParamField>

<ResponseField name="query_result" type="Payloads">
  Result of the query
</ResponseField>

<ResponseField name="query_rejected" type="QueryRejected">
  Query rejection details if rejected
</ResponseField>

#### UpdateWorkflowExecution

Sends an update to a workflow execution.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

<ParamField path="workflow_execution" type="WorkflowExecution" required>
  Target workflow execution
</ParamField>

<ParamField path="request" type="Request" required>
  Update request with name and arguments
</ParamField>

<ParamField path="wait_policy" type="WaitPolicy">
  Policy for waiting for update completion
</ParamField>

<ResponseField name="outcome" type="Outcome">
  Update outcome if completed
</ResponseField>

<ResponseField name="update_ref" type="UpdateRef">
  Reference for polling update status
</ResponseField>

#### TerminateWorkflowExecution

Terminates a workflow execution.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

<ParamField path="workflow_execution" type="WorkflowExecution" required>
  Workflow to terminate
</ParamField>

<ParamField path="reason" type="string" required>
  Reason for termination
</ParamField>

<ParamField path="details" type="Payloads">
  Additional termination details
</ParamField>

<ParamField path="identity" type="string" required>
  Identity of the terminator
</ParamField>

#### CancelWorkflowExecution

Requests cancellation of a workflow execution.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

<ParamField path="workflow_execution" type="WorkflowExecution" required>
  Workflow to cancel
</ParamField>

<ParamField path="identity" type="string" required>
  Identity of the requester
</ParamField>

<ParamField path="request_id" type="string">
  Unique request ID
</ParamField>

#### ResetWorkflowExecution

Resets a workflow execution to a previous state.

<ParamField path="namespace" type="string" required>
  Namespace of the workflow
</ParamField>

<ParamField path="workflow_execution" type="WorkflowExecution" required>
  Workflow to reset
</ParamField>

<ParamField path="reason" type="string" required>
  Reason for reset
</ParamField>

<ParamField path="workflow_task_finish_event_id" type="int64">
  Event ID to reset to
</ParamField>

<ParamField path="request_id" type="string">
  Unique request ID
</ParamField>

<ResponseField name="run_id" type="string">
  New run ID after reset
</ResponseField>

### Task Operations

#### PollWorkflowTaskQueue

Polls for a workflow task.

<ParamField path="namespace" type="string" required>
  Namespace to poll from
</ParamField>

<ParamField path="task_queue" type="TaskQueue" required>
  Task queue to poll
</ParamField>

<ParamField path="identity" type="string" required>
  Worker identity
</ParamField>

<ParamField path="binary_checksum" type="string">
  Worker binary checksum
</ParamField>

<ResponseField name="task_token" type="bytes">
  Opaque task token
</ResponseField>

<ResponseField name="workflow_execution" type="WorkflowExecution">
  Workflow execution information
</ResponseField>

<ResponseField name="workflow_type" type="WorkflowType">
  Workflow type
</ResponseField>

<ResponseField name="history" type="History">
  History events for processing
</ResponseField>

#### RespondWorkflowTaskCompleted

Completes a workflow task with commands.

<ParamField path="task_token" type="bytes" required>
  Task token from poll response
</ParamField>

<ParamField path="commands" type="Command[]">
  Workflow commands to execute
</ParamField>

<ParamField path="identity" type="string" required>
  Worker identity
</ParamField>

<ParamField path="sticky_attributes" type="StickyExecutionAttributes">
  Sticky task queue attributes
</ParamField>

<ParamField path="return_new_workflow_task" type="bool">
  Whether to return a new task immediately
</ParamField>

<ParamField path="messages" type="Message[]">
  Protocol messages
</ParamField>

<ResponseField name="workflow_task" type="PollWorkflowTaskQueueResponse">
  New workflow task if requested
</ResponseField>

#### PollActivityTaskQueue

Polls for an activity task.

<ParamField path="namespace" type="string" required>
  Namespace to poll from
</ParamField>

<ParamField path="task_queue" type="TaskQueue" required>
  Task queue to poll
</ParamField>

<ParamField path="identity" type="string" required>
  Worker identity
</ParamField>

<ResponseField name="task_token" type="bytes">
  Task token
</ResponseField>

<ResponseField name="workflow_execution" type="WorkflowExecution">
  Parent workflow
</ResponseField>

<ResponseField name="activity_id" type="string">
  Activity identifier
</ResponseField>

<ResponseField name="activity_type" type="ActivityType">
  Activity type
</ResponseField>

<ResponseField name="input" type="Payloads">
  Activity input
</ResponseField>

#### RecordActivityTaskHeartbeat

Records a heartbeat for a long-running activity.

<ParamField path="task_token" type="bytes" required>
  Activity task token
</ParamField>

<ParamField path="details" type="Payloads">
  Progress details
</ParamField>

<ParamField path="identity" type="string" required>
  Worker identity
</ParamField>

<ResponseField name="cancel_requested" type="bool">
  Whether cancellation has been requested
</ResponseField>

#### RespondActivityTaskCompleted

Completes an activity task with a result.

<ParamField path="task_token" type="bytes" required>
  Activity task token
</ParamField>

<ParamField path="result" type="Payloads">
  Activity result
</ParamField>

<ParamField path="identity" type="string" required>
  Worker identity
</ParamField>

#### RespondActivityTaskFailed

Marks an activity task as failed.

<ParamField path="task_token" type="bytes" required>
  Activity task token
</ParamField>

<ParamField path="failure" type="Failure">
  Failure details
</ParamField>

<ParamField path="identity" type="string" required>
  Worker identity
</ParamField>

### Namespace Operations

#### RegisterNamespace

Registers a new namespace.

<ParamField path="namespace" type="string" required>
  Namespace name
</ParamField>

<ParamField path="description" type="string">
  Namespace description
</ParamField>

<ParamField path="owner_email" type="string">
  Owner email address
</ParamField>

<ParamField path="workflow_execution_retention_period" type="Duration" required>
  Retention period for closed workflows
</ParamField>

<ParamField path="clusters" type="ClusterReplicationConfig[]">
  Cluster replication configuration
</ParamField>

<ParamField path="data" type="map<string, string>">
  Custom namespace data
</ParamField>

#### DescribeNamespace

Retrieves namespace information.

<ParamField path="namespace" type="string" required>
  Namespace name
</ParamField>

<ResponseField name="namespace_info" type="NamespaceInfo">
  Namespace metadata
</ResponseField>

<ResponseField name="config" type="NamespaceConfig">
  Namespace configuration
</ResponseField>

<ResponseField name="replication_config" type="NamespaceReplicationConfig">
  Replication settings
</ResponseField>

#### UpdateNamespace

Updates namespace configuration.

<ParamField path="namespace" type="string" required>
  Namespace to update
</ParamField>

<ParamField path="update_info" type="UpdateNamespaceInfo">
  Updated namespace metadata
</ParamField>

<ParamField path="config" type="NamespaceConfig">
  Updated configuration
</ParamField>

<ParamField path="replication_config" type="NamespaceReplicationConfig">
  Updated replication settings
</ParamField>

#### ListNamespaces

Lists all namespaces.

<ParamField path="page_size" type="int32">
  Maximum namespaces per page
</ParamField>

<ParamField path="next_page_token" type="bytes">
  Pagination token
</ParamField>

<ResponseField name="namespaces" type="DescribeNamespaceResponse[]">
  List of namespaces
</ResponseField>

<ResponseField name="next_page_token" type="bytes">
  Token for next page
</ResponseField>

### Visibility and Search

#### ListWorkflowExecutions

Lists workflow executions with optional filtering.

<ParamField path="namespace" type="string" required>
  Namespace to search
</ParamField>

<ParamField path="page_size" type="int32">
  Maximum executions per page
</ParamField>

<ParamField path="next_page_token" type="bytes">
  Pagination token
</ParamField>

<ParamField path="query" type="string">
  SQL-like search query
</ParamField>

<ResponseField name="executions" type="WorkflowExecutionInfo[]">
  List of workflow executions
</ResponseField>

<ResponseField name="next_page_token" type="bytes">
  Token for next page
</ResponseField>

#### ScanWorkflowExecutions

Scans workflow executions (similar to List but with different consistency guarantees).

<ParamField path="namespace" type="string" required>
  Namespace to scan
</ParamField>

<ParamField path="page_size" type="int32">
  Maximum executions per page
</ParamField>

<ParamField path="next_page_token" type="bytes">
  Pagination token
</ParamField>

<ParamField path="query" type="string">
  Search query
</ParamField>

<ResponseField name="executions" type="WorkflowExecutionInfo[]">
  List of workflow executions
</ResponseField>

#### CountWorkflowExecutions

Counts workflow executions matching a query.

<ParamField path="namespace" type="string" required>
  Namespace to count in
</ParamField>

<ParamField path="query" type="string">
  Search query
</ParamField>

<ResponseField name="count" type="int64">
  Number of matching executions
</ResponseField>

### Task Queue Management

#### DescribeTaskQueue

Retrieves information about a task queue.

<ParamField path="namespace" type="string" required>
  Namespace of the task queue
</ParamField>

<ParamField path="task_queue" type="TaskQueue" required>
  Task queue to describe
</ParamField>

<ParamField path="task_queue_type" type="TaskQueueType">
  Type of task queue (workflow or activity)
</ParamField>

<ParamField path="include_task_queue_status" type="bool">
  Whether to include status information
</ParamField>

<ResponseField name="pollers" type="PollerInfo[]">
  Active pollers
</ResponseField>

<ResponseField name="task_queue_status" type="TaskQueueStatus">
  Task queue status
</ResponseField>

## Configuration

Frontend Service configuration is defined in the server config file:

```yaml theme={null}
services:
  frontend:
    rpc:
      grpcPort: 7233
      httpPort: 7243
      membershipPort: 6933
      bindOnIP: "0.0.0.0"
```

## Authentication & Authorization

The Frontend Service supports:

* JWT-based authentication
* Custom authorizers via plugin
* Claim mappers for extracting permissions
* Per-namespace access control

## Rate Limiting

Rate limiting is applied per:

* API method
* Namespace
* User identity

Configure via dynamic config keys.

## See Also

* [History Service API](/api/history-service)
* [Matching Service API](/api/matching-service)
* [Server Configuration](/reference/server-config)
* [Authentication Guide](/guides/authentication)