Dust Apps API
List Dust Apps in a space and create or retrieve App runs. Dust Apps are chained-block LLM/code pipelines defined in the Dust Builder and executable as parameterized "functions" from agents, code, or webhooks.
OpenAPI Specification
openapi: 3.0.0
info:
title: Dust Apps API
version: 1.0.2
description: Run Dust Apps — chained LLM/code blocks defined in the Dust Builder — and inspect their runs.
contact:
name: Dust Support
url: https://docs.dust.tt
license:
name: MIT
url: https://github.com/dust-tt/dust/blob/main/LICENSE
servers:
- url: https://dust.tt
description: Dust.tt API (us-central1)
- url: https://eu.dust.tt
description: Dust.tt API (europe-west1)
tags:
- name: Apps
description: Dust apps
paths:
/api/v1/w/{wId}/spaces/{spaceId}/apps/{aId}/runs/{runId}:
get:
summary: Get an App Run
description: Retrieve a run for an app in the space identified by {spaceId}.
tags:
- Apps
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: Unique string identifier for the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: aId
required: true
description: ID of the app
schema:
type: string
- in: path
name: runId
required: true
description: ID of the run
schema:
type: string
responses:
'200':
description: The run
content:
application/json:
schema:
type: object
properties:
run:
$ref: '#/components/schemas/Run'
'400':
description: Bad Request. Missing or invalid parameters.
'401':
description: Unauthorized. Invalid or missing authentication token.
/api/v1/w/{wId}/spaces/{spaceId}/apps/{aId}/runs:
post:
summary: Create an App Run
description: Create and execute a run for an app in the space specified by {spaceId}.
tags:
- Apps
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: Unique string identifier for the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
- in: path
name: aId
required: true
description: Unique identifier of the app
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- specification_hash
- config
- inputs
properties:
specification_hash:
type: string
description: Hash of the app specification. Ensures API compatibility across app iterations.
config:
type: object
description: Configuration for the app run
properties:
model:
type: object
description: Model configuration
properties:
provider_id:
type: string
description: ID of the model provider
model_id:
type: string
description: ID of the model
use_cache:
type: boolean
description: Whether to use caching
use_stream:
type: boolean
description: Whether to use streaming
inputs:
type: array
description: Array of input objects for the app
items:
type: object
additionalProperties: true
stream:
type: boolean
description: If true, the response will be streamed
blocking:
type: boolean
description: If true, the request will block until the run is complete
block_filter:
type: array
items:
type: string
description: Array of block names to filter the response
responses:
'200':
description: App run created and executed successfully
content:
application/json:
schema:
type: object
properties:
run:
$ref: '#/components/schemas/Run'
'400':
description: Bad Request. Missing or invalid parameters.
'401':
description: Unauthorized. Invalid or missing authentication token.
'404':
description: Workspace or app not found.
'405':
description: Method not supported.
'500':
description: Internal Server Error.
/api/v1/w/{wId}/spaces/{spaceId}/apps:
get:
summary: List Apps
description: Get all apps in the space identified by {spaceId}.
tags:
- Apps
security:
- BearerAuth: []
parameters:
- in: path
name: wId
required: true
description: Unique string identifier for the workspace
schema:
type: string
- in: path
name: spaceId
required: true
description: ID of the space
schema:
type: string
responses:
'200':
description: Apps of the workspace
content:
application/json:
schema:
type: object
properties:
apps:
type: array
items:
type: object
properties:
id:
type: integer
description: Unique identifier for the app
sId:
type: string
description: Unique string identifier for the app
name:
type: string
description: Name of the app
description:
type: string
description: Description of the app
savedSpecification:
type: string
description: Saved specification of the app
savedConfig:
type: string
description: Saved configuration of the app
savedRun:
type: string
description: Saved run identifier of the app
dustAPIProjectId:
type: string
description: ID of the associated Dust API project
'400':
description: Bad Request. Missing or invalid parameters.
'401':
description: Unauthorized. Invalid or missing authentication token.
'404':
description: Workspace not found.
'405':
description: Method not supported.
'500':
description: Internal Server Error.
components:
schemas:
Run:
type: object
properties:
run_id:
type: string
description: The ID of the run
example: 4a2c6e8b0d
app_id:
type: string
description: The ID of the app
example: 9f1d3b5a7c
status:
type: object
properties:
run:
type: string
description: The status of the run
example: succeeded
build:
type: string
description: The status of the build
example: succeeded
results:
type: object
description: The results of the run
example: {}
specification_hash:
type: string
description: The hash of the app specification
example: 8c0a4e6d2f
traces:
type: array
items:
type: array
items:
type: object
properties:
timestamp:
type: number
description: The timestamp of the trace
example: 1234567890
trace:
type: object
description: The trace
example: {}
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Your DUST API key is a Bearer token.