Dapr API reference on Dapr Docs

Actors API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides native, cross-platform, and cross-language virtual actor capabilities. Besides the language specific SDKs, a developer can invoke an actor using the API endpoints below.

User service code calling Dapr

Invoke actor method

Invoke an actor method through Dapr.

HTTP Request

POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/method/<method>

HTTP Response Codes

Code	Description
200	Request successful
500	Request failed
XXX	Status code from upstream call

URL Parameters

Parameter	Description
`daprPort`	The Dapr port.
`actorType`	The actor type.
`actorId`	The actor ID.
`method`	The name of the method to invoke.

Note, all URL parameters are case-sensitive.

Bindings API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides bi-directional binding capabilities for applications and a consistent approach to interacting with different cloud/on-premise services or systems. Developers can invoke output bindings using the Dapr API, and have the Dapr runtime trigger an application with input bindings.

Examples for bindings include Kafka, Rabbit MQ, Azure Event Hubs, AWS SQS, GCP Storage to name a few.

Bindings Structure

A Dapr Binding yaml file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
 namespace: <NAMESPACE>
spec:
 type: bindings.<TYPE>
 version: v1
 metadata:
 - name: <NAME>
 value: <VALUE>

The metadata.name is the name of the binding.

Configuration API reference

Mon, 01 Jan 0001 00:00:00 +0000

Get Configuration

This endpoint lets you get configuration from a store.

HTTP Request

GET http://localhost:<daprPort>/v1.0/configuration/<storename>

URL Parameters

Parameter	Description
`daprPort`	The Dapr port
`storename`	The `metadata.name` field component file. Refer to the component spec

Query Parameters

If no query parameters are provided, all configuration items are returned. To specify the keys of the configuration items to get, use one or more key query parameters. For example:

GET http://localhost:<daprPort>/v1.0/configuration/mystore?key=config1&key=config2

To retrieve all configuration items:

Conversation API reference

Mon, 01 Jan 0001 00:00:00 +0000

Alpha

The conversation API is currently in alpha.

Dapr provides an API to interact with Large Language Models (LLMs) and enables critical performance and security functionality with features like prompt caching, PII data obfuscation, and tool calling capabilities.

Tool calling follows OpenAI’s function calling format, making it easy to integrate with existing AI development workflows and tools.

Converse

This endpoint lets you converse with LLMs using the Alpha2 version of the API, which provides enhanced tool calling support and alignment with OpenAI’s interface.

Cryptography API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides cross-platform and cross-language support for encryption and decryption support via the cryptography building block. Besides the language specific SDKs, a developer can invoke these capabilities using the HTTP API endpoints below.

The HTTP APIs are intended for development and testing only. For production scenarios, the use of the SDKs is strongly recommended as they implement the gRPC APIs providing higher performance and capability than the HTTP APIs.

Encrypt Payload

This endpoint lets you encrypt a value provided as a byte array using a specified key and crypto component.

Distributed lock API reference

Mon, 01 Jan 0001 00:00:00 +0000

Lock

This endpoint lets you acquire a lock by supplying a named lock owner and the resource ID to lock.

HTTP Request

POST http://localhost:<daprPort>/v1.0-alpha1/lock/<storename>

URL Parameters

Parameter	Description
`daprPort`	The Dapr port
`storename`	The `metadata.name` field component file. Refer to the component schema

Query Parameters

None

HTTP Response codes

Code	Description
200	Request successful
204	Empty Response
400	Malformed request
500	Request failed

HTTP Request Body

The lock endpoint receives the following JSON payload:

Health API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides health checking probes that can be used as readiness or liveness of Dapr and for initialization readiness from SDKs.

Get Dapr health state

Gets the health state for Dapr by either:

Check for sidecar health
Check for the sidecar health, including component readiness, used during initialization.

Wait for Dapr HTTP port to become available

Wait for all components to be initialized, the Dapr HTTP port to be available and the app channel is initialized. For example, this endpoint is used with Kubernetes liveness probes.

Jobs API reference

Mon, 01 Jan 0001 00:00:00 +0000

Note

The jobs API is currently in alpha.

With the jobs API, you can schedule jobs and tasks in the future.

The HTTP APIs are intended for development and testing only. For production scenarios, the use of the SDKs is strongly recommended as they implement the gRPC APIs providing higher performance and capability than the HTTP APIs. This is because HTTP does JSON marshalling which can be expensive, while with gRPC, the data is transmitted over the wire and stored as-is being more performant.

Metadata API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns the following information.

Runtime version
List of the loaded resources (components, subscriptions and HttpEndpoints)
Registered actor types
Features enabled
Application connection details
Custom, ephemeral attributes with information.

Metadata API

Components

Each loaded component provides its name, type and version and also information about supported features in the form of component capabilities. These features are available for the state store and binding component types. The table below shows the component type and the list of capabilities for a given version. This list might grow in future and only represents the capabilities of the loaded components.

Placement API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr has an HTTP API /placement/state for Placement service that exposes placement table information. The API is exposed on the sidecar on the same port as the healthz. This is an unauthenticated endpoint, and is disabled by default.

To enable the placement metadata in self-hosted mode you can either setDAPR_PLACEMENT_METADATA_ENABLED environment variable or metadata-enabled command line args on the Placement service to true to. See how to run the Placement service in self-hosted mode.

Pub/sub API reference

Mon, 01 Jan 0001 00:00:00 +0000

Publish a message to a given topic

This endpoint lets you publish data to multiple consumers who are listening on a topic. Dapr guarantees At-Least-Once semantics for this endpoint.

HTTP Request

POST http://localhost:<daprPort>/v1.0/publish/<pubsubname>/<topic>[?<metadata>]

HTTP Response codes

Code	Description
204	Message delivered
403	Message forbidden by access controls
404	No pubsub name or topic given
500	Delivery failed

URL Parameters

Parameter	Description
`daprPort`	The Dapr port
`pubsubname`	The name of pubsub component
`topic`	The name of the topic
`metadata`	Query parameters for metadata as described below

Note, all URL parameters are case-sensitive.

Secrets API reference

Mon, 01 Jan 0001 00:00:00 +0000

Get Secret

This endpoint lets you get the value of a secret for a given secret store.

HTTP Request

GET http://localhost:<daprPort>/v1.0/secrets/<secret-store-name>/<name>

URL Parameters

Parameter	Description
daprPort	the Dapr port
secret-store-name	the name of the secret store to get the secret from
name	the name of the secret to get

Note, all URL parameters are case-sensitive.

Query Parameters

Some secret stores support optional, per-request metadata properties. Use query parameters to provide those properties. For example:

Service invocation API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides users with the ability to call other applications that are using Dapr with a unique named identifier (appId), or HTTP endpoints that are not using Dapr. This allows applications to interact with one another via named identifiers and puts the burden of service discovery on the Dapr runtime.

Invoke a method on a remote Dapr app

This endpoint lets you invoke a method in another Dapr enabled app.

State management API reference

Mon, 01 Jan 0001 00:00:00 +0000

Component file

A Dapr statestore.yaml component file has the following structure:

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
 name: <NAME>
 namespace: <NAMESPACE>
spec:
 type: state.<TYPE>
 version: v1
 metadata:
 - name:<KEY>
 value:<VALUE>
 - name: <KEY>
 value: <VALUE>

Setting	Description
`metadata.name`	The name of the state store.
`spec/metadata`	An open key value pair metadata that allows a binding to define connection properties.

Key scheme

Dapr state stores are key/value stores. To ensure data compatibility, Dapr requires these data stores follow a fixed key scheme. For general states, the key format is:

Workflow API reference

Mon, 01 Jan 0001 00:00:00 +0000

Dapr provides users with the ability to interact with workflows through its built-in workflow engine, which is implemented using Dapr Actors.

To interact with the workflow engine, see [how to author]https://v1-18.docs.dapr.io/developing-applications/building-blocks/workflow/howto-author-workflow/ and manage workflows.

HTTP API reference (Deprecated)

Below is the reference for the Dapr Workflow API. This API is deprecated and will eventually be removed.

Start workflow request

Start a workflow instance with the given name and optionally, an instance ID.