Actors API reference

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.

Invoke an actor method through Dapr.

HTTP Request

HTTP Response Codes

URL Parameters

Examples

Example of invoking a method on an actor:

  -H "Content-Type: application/json"

Example of invoking a method on an actor that takes parameters: You can provided the method parameters and values in the body of the request, for example in curl using -d “{“param”:”value”}”

curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
  -H "Content-Type: application/json"
  -d '{
        "destination": "Hoth"
      }'

or

curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
  -H "Content-Type: application/json"
  -d "{\"destination\":\"Hoth\"}"

The response (the method return) from the remote endpoint is returned in the request body.

Actor state transactions

Persists the changed to the state for an actor as a multi-item transaction.

Note that this operation is dependant on a using state store component that supports multi-item transactions.

HTTP Request

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \
  -H "Content-Type: application/json"
  -d '[
       {
         "operation": "upsert",
         "request": {
           "key": "key1",
           "value": "myData"
         }
       },
       {
         "operation": "delete",
         "request": {
           "key": "key2"
         }
       }
      ]'

Get actor state

Gets the state for an actor using a specified key.

HTTP Request

GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
  -H "Content-Type: application/json"

The above command returns the state:

{
  "location": "Alderaan"
}

Create actor reminder

Creates a persistent reminder for an actor.

HTTP Request

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

Request Body

A JSON object with the following fields:

period field supports time.Duration format and ISO 8601 format (with some limitations). Only duration format of ISO 8601 duration Rn/PnYnMnWnDTnHnMnS is supported for period. Here Rn/ specifies that the reminder will be invoked n number of times. It should be a positive integer greater than zero. If certain values are zero, the can be shortened, for example 10 seconds can be specified in ISO 8601 duration as PT10S. If Rn/ is not specified the reminder will run infinite number of times until deleted.

The following specifies a dueTime of 3 seconds and a period of 7 seconds.

{
  "dueTime":"0h0m3s0ms",
  "period":"0h0m7s0ms"
}

A dueTime of 0 means to fire immediately. The following body means to fire immediately, then every 9 seconds.

{
  "dueTime":"0h0m0s0ms",
  "period":"0h0m9s0ms"
}

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  -H "Content-Type: application/json"
      "data": "someData",
      "dueTime": "1m",
      "period": "20s"
    }'

Gets a reminder for an actor.

HTTP Request

GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

HTTP Response Codes

URL Parameters

Examples

curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  "Content-Type: application/json"

The above command returns the reminder:

{
  "dueTime": "1s",
  "period": "5s",
  "data": "0",
}

Delete actor reminder

Deletes a reminder for an actor.

HTTP Request

DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

curl -X DELETE http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  -H "Content-Type: application/json"

Create actor timer

Creates a timer for an actor.

HTTP Request

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>

Body:

The following specifies a dueTime of 3 seconds and a period of 7 seconds.

{
  "dueTime":"0h0m3s0ms",
  "period":"0h0m7s0ms"
}

A dueTime of 0 means to fire immediately. The following body means to fire immediately, then every 9 seconds.

{
  "dueTime":"0h0m0s0ms",
}

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
    -H "Content-Type: application/json"
-d '{
      "data": "someData",
      "dueTime": "1m",
      "period": "20s",
      "callback": "myEventHandler"
    }'

Delete actor timer

Deletes a timer for an actor.

HTTP Request

DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Gets the registered actors types for this app and the Dapr actor configuration settings.

HTTP Request

GET http://localhost:<appPort>/dapr/config

HTTP Response Codes

URL Parameters

Examples

Example of getting the registered actors:

curl -X GET http://localhost:3000/dapr/config \
  -H "Content-Type: application/json"

The above command returns the config (all fields are optional):

{
  "entities":["actorType1", "actorType2"],
  "actorIdleTimeout": "1h",
  "actorScanInterval": "30s",
  "drainOngoingCallTimeout": "30s",
  "drainRebalancedActors": true
}

Deactivate actor

Deactivates an actor by persisting the instance of the actor to the state store with the specified actorId

HTTP Request

DELETE http://localhost:<appPort>/actors/<actorType>/<actorId>

HTTP Response Codes

URL Parameters

Examples

curl -X DELETE http://localhost:3000/actors/stormtrooper/50 \
  -H "Content-Type: application/json"

Invoke actor method

Invokes a method for an actor with the specified methodName where parameters to the method are passed in the body of the request message and return values are provided in the body of the response message. If the actor is not already running, the app side should it.

HTTP Request

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/<methodName>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

Example of invoking a method for an actor: The example calls the performAction method on the actor type stormtrooper that has actorId of 50

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/performAction \
  -H "Content-Type: application/json"

Invoke reminder

Invokes a reminder for an actor with the specified reminderName. If the actor is not already running, the app side should it.

HTTP Request

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/remind/<reminderName>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

Example of invoking a reminder for an actor: The example calls the checkRebels reminder method on the actor type stormtrooper that has actorId of 50

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/remind/checkRebels \
  -H "Content-Type: application/json"

Invokes a timer for an actor rwith the specified timerName. If the actor is not already running, the app side should activate it.

HTTP Request

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/timer/<timerName>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

Example of invoking a timer for an actor: The example calls the checkRebels timer method on the actor type stormtrooper that has actorId of 50

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/timer/checkRebels \
  -H "Content-Type: application/json"

Health check

Probes the application for a response to signal to Dapr that the app is healthy and running. Any other response status code other than 200 will be considered as an unhealthy response.

A response body is not required.

HTTP Request

HTTP Response Codes

URL Parameters

Examples

Example of getting a health check response from the app:

curl -X GET http://localhost:3000/healthz \

Conceptually, activating an actor means creating the actor’s object and adding the actor to a tracking table. Here is an example from the .NET SDK.

In order to enable visibility into the state of an actor and allow for complex scenarios such as state aggregation, Dapr saves actor state in external state stores such as databases. As such, it is possible to query for an actor state externally by composing the correct key or query.

The state namespace created by Dapr for actors is composed of the following items:

• App ID - Represents the unique ID given to the Dapr application.
• Actor Type - Represents the type of the actor.
• Actor ID - Represents the unique ID of the actor instance for an actor type.

The following example shows how to construct a key for the state of an actor instance under the myapp App ID namespace: myapp||cat||hobbit||food

In the example above, we are getting the value for the state key food, for the actor ID hobbit with an actor type of cat, under the App ID namespace of .