Dapr State API

openapi: 3.1.0
info:
  title: Dapr Actors State API
  description: The Dapr Actors API provides virtual actor capabilities for distributed applications, including actor method invocation, state management, timers, and reminders. Actors provide a single-threaded programming model with guaranteed message ordering.
  version: 1.0.0
  contact:
    name: Dapr
    url: https://dapr.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:3500
  description: Dapr Sidecar
tags:
- name: State
  description: State management operations.
paths:
  /v1.0/state/{storename}:
    post:
      summary: Dapr Save State
      description: Saves an array of state objects to the specified state store.
      operationId: saveState
      tags:
      - State
      parameters:
      - name: storename
        in: path
        required: true
        description: The name of the state store.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/StateItem'
      responses:
        '204':
          description: State saved successfully.
        '400':
          description: State store is missing or misconfigured.
        '500':
          description: Failed to save state.
  /v1.0/state/{storename}/{key}:
    get:
      summary: Dapr Get State
      description: Retrieves the state for a specific key from the state store.
      operationId: getState
      tags:
      - State
      parameters:
      - name: storename
        in: path
        required: true
        description: The name of the state store.
        schema:
          type: string
      - name: key
        in: path
        required: true
        description: The key of the desired state.
        schema:
          type: string
      - name: consistency
        in: query
        description: Read consistency level (eventual or strong).
        schema:
          type: string
          enum:
          - eventual
          - strong
      responses:
        '200':
          description: State retrieved successfully.
          headers:
            ETag:
              description: ETag of the state value.
              schema:
                type: string
          content:
            application/json:
              schema: {}
        '204':
          description: Key is not found.
        '400':
          description: State store is missing or misconfigured.
        '500':
          description: Failed to get state.
    delete:
      summary: Dapr Delete State
      description: Deletes the state for a specific key from the state store.
      operationId: deleteState
      tags:
      - State
      parameters:
      - name: storename
        in: path
        required: true
        description: The name of the state store.
        schema:
          type: string
      - name: key
        in: path
        required: true
        description: The key of the state to delete.
        schema:
          type: string
      - name: concurrency
        in: query
        description: Concurrency mode (first-write or last-write).
        schema:
          type: string
          enum:
          - first-write
          - last-write
      - name: consistency
        in: query
        description: Consistency level (eventual or strong).
        schema:
          type: string
          enum:
          - eventual
          - strong
      responses:
        '204':
          description: State deleted successfully.
        '400':
          description: State store is missing or misconfigured.
        '500':
          description: Failed to delete state.
  /v1.0/state/{storename}/bulk:
    post:
      summary: Dapr Get Bulk State
      description: Retrieves multiple state values from the state store in a single request.
      operationId: getBulkState
      tags:
      - State
      parameters:
      - name: storename
        in: path
        required: true
        description: The name of the state store.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                keys:
                  type: array
                  items:
                    type: string
                  description: List of keys to retrieve.
                parallelism:
                  type: integer
                  description: Number of parallel operations for retrieving state.
      responses:
        '200':
          description: Bulk state retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BulkStateItem'
        '400':
          description: State store is missing or misconfigured.
        '500':
          description: Failed to get bulk state.
  /v1.0/state/{storename}/transaction:
    post:
      summary: Dapr Execute State Transaction
      description: Executes a multi-item transactional operation on the state store. Supports upsert and delete operations within a single transaction.
      operationId: executeStateTransaction
      tags:
      - State
      parameters:
      - name: storename
        in: path
        required: true
        description: The name of the state store.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                operations:
                  type: array
                  items:
                    $ref: '#/components/schemas/TransactionalStateOperation'
                metadata:
                  type: object
                  additionalProperties:
                    type: string
      responses:
        '204':
          description: Transaction executed successfully.
        '400':
          description: State store is missing or misconfigured.
        '500':
          description: Failed to execute transaction.
  /v1.0/state/{storename}/query:
    post:
      summary: Dapr Query State
      description: Queries the state store using a query expression.
      operationId: queryState
      tags:
      - State
      parameters:
      - name: storename
        in: path
        required: true
        description: The name of the state store.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: object
                  description: Query filter expression.
                sort:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                      order:
                        type: string
                        enum:
                        - ASC
                        - DESC
                page:
                  type: object
                  properties:
                    limit:
                      type: integer
                    token:
                      type: string
      responses:
        '200':
          description: Query executed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        data: {}
                        etag:
                          type: string
                  token:
                    type: string
        '400':
          description: Bad request.
        '500':
          description: Failed to query state.
components:
  schemas:
    TransactionalStateOperation:
      type: object
      properties:
        operation:
          type: string
          enum:
          - upsert
          - delete
        request:
          $ref: '#/components/schemas/StateItem'
    BulkStateItem:
      type: object
      properties:
        key:
          type: string
        data: {}
        etag:
          type: string
        error:
          type: string
    StateItem:
      type: object
      required:
      - key
      - value
      properties:
        key:
          type: string
          description: State key.
        value:
          description: State value (any JSON serializable value).
        etag:
          type: string
          description: ETag for optimistic concurrency.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Additional key/value metadata.
        options:
          type: object
          properties:
            concurrency:
              type: string
              enum:
              - first-write
              - last-write
            consistency:
              type: string
              enum:
              - eventual
              - strong
externalDocs:
  description: Dapr Actors API Reference
  url: https://docs.dapr.io/reference/api/actors_api/