1. Docs
  2. Reference
  3. Pulumi Cloud REST API
  4. Neo

Neo

    The Agent Tasks API allows you to create and manage AI agent tasks in Pulumi Cloud. These endpoints enable you to create tasks, monitor their status, respond to agent requests, and retrieve task events.

    Agent Task Operations

    The API provides endpoints for the following operations:

    • Creating new agent tasks
    • Listing available tasks
    • Getting task details and metadata
    • Updating task settings and metadata
    • Responding to agent requests
    • Retrieving task events

    Create a New Task

    Creates a new agent task for the specified organization.

    POST /api/preview/agents/{orgName}/tasks

    Parameters

    ParameterTypeInDescription
    orgNamestringpathThe organization name

    Request Body

    {
  "message": {
    "type": "user_message",
    "content": "Help me optimize my Pulumi stack",
    "timestamp": "2025-01-15T10:30:00Z",
    "entity_diff": {
      "add": [
        {
          "type": "stack",
          "name": "my-stack",
          "project": "my-project"
        }
      ],
      "remove": []
    }
  },
  "approvalMode": "balanced",
  "planMode": true,
  "permissionMode": "default"
}

    Request fields

    FieldTypeRequiredDescription
    messageobjectYesThe user event message to start the task
    message.typestringYesType of event (must be “user_message”)
    message.contentstringYesThe exact natural language instruction from the user
    message.timestampstring (ISO 8601)YesWhen the event occurred
    message.entity_diffobjectNoEntities to add or remove from the agent. See Entity Types for details. Note: Pull request entities cannot be added via this API.
    approvalModestringNoApproval mode override for this task. If omitted, the organization default is used. See approval modes for valid values.
    planModebooleanNoWhether to enable plan mode for this task. In plan mode, the agent performs detailed research before execution and allows user iteration on the plan.
    permissionModestringNoControls the permission scope for the task. Valid values: default (the agent uses the creating user’s full permissions), read-only. Defaults to default if omitted.

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  --request POST \
  --data '{"message":{"type":"user_message","content":"Help me optimize my Pulumi stack","timestamp":"2025-01-15T10:30:00Z"},"approvalMode":"balanced","planMode":true}' \
  https://api.pulumi.com/api/preview/agents/my-org/tasks

    Response

    Status: 201 Created

    {
  "taskId": "task_abc123"
}

    Response Fields

    FieldTypeDescription
    taskIdstringUnique identifier for the created task

    Error Responses

    • 400 Bad Request: Missing required fields or invalid request body
    • 401 Unauthorized: Invalid or missing authentication token
    • 403 Forbidden: Insufficient permissions to create tasks in this organization

    Get Task Metadata

    Retrieves metadata for a specific task.

    GET /api/preview/agents/{orgName}/tasks/{taskID}

    Parameters

    ParameterTypeInDescription
    orgNamestringpathThe organization name
    taskIDstringpathThe task identifier

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  https://api.pulumi.com/api/preview/agents/my-org/tasks/task_abc123

    Response

    Status: 200 OK

    {
  "id": "task_abc123",
  "name": "Task name",
  "status": "running",
  "createdAt": "2025-01-15T00:00:00Z",
  "approvalMode": "balanced",
  "entities": [
    {
      "type": "stack",
      "name": "my-stack",
      "project": "my-project"
    }
  ],
  "planMode": true,
  "isShared": false,
  "createdBy": {
    "name": "Jane Doe",
    "githubLogin": "janedoe",
    "avatarUrl": "https://api.pulumi.com/static/avatars/J-E91E63.png"
  },
  "permissionMode": "default",
  "runtimePhase": "ready",
  "contextUsedTokens": 43272,
  "contextWindowTokens": 1000000
}

    Response fields

    FieldTypeDescription
    idstringUnique identifier for the task
    namestringHuman-readable name for the task
    statusstringCurrent status of the task (running or idle)
    createdAtstring (ISO 8601)When the task was created
    approvalModestringApproval mode for this task. See approval modes for values.
    entitiesarrayList of entities associated with the task
    planModebooleanWhether the task is in plan mode
    isSharedbooleanWhether this task is shared with other organization members
    sharedAtstring (ISO 8601)When the task was first shared (null if never shared)
    createdByobjectInformation about the user who created this task
    permissionModestringThe permission scope for the task (default or read-only)
    runtimePhasestringThe current runtime phase (booting, ready, or running). Null until the runtime checks in.
    contextUsedTokensintegerTotal input tokens consumed across all model invocations for this task
    contextWindowTokensintegerMaximum context window size in tokens for the primary model used by this task

    Error Responses

    • 401 Unauthorized: Invalid or missing authentication token
    • 403 Forbidden: Insufficient permissions to view this task
    • 404 Not Found: Task not found

    List Tasks

    Lists all tasks for the specified organization.

    GET /api/preview/agents/{orgName}/tasks

    Parameters

    ParameterTypeInDescription
    orgNamestringpathThe organization name
    continuationTokenstringqueryOptional. Token to fetch the next page of results
    pageSizeintegerqueryOptional. Number of items per page (1-1000, default: 100)

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  https://api.pulumi.com/api/preview/agents/my-org/tasks?pageSize=50

    Response

    Status: 200 OK

    {
  "tasks": [
    {
      "id": "task_abc123",
      "name": "Task name",
      "status": "running",
      "createdAt": "2025-01-15T00:00:00Z",
      "approvalMode": "balanced",
      "entities": [],
      "planMode": true,
      "isShared": false,
      "createdBy": {
        "name": "Jane Doe",
        "githubLogin": "janedoe",
        "avatarUrl": "https://api.pulumi.com/static/avatars/J-E91E63.png"
      },
      "permissionMode": "default",
      "runtimePhase": "ready"
    }
  ],
  "continuationToken": "next_page_token"
}

    Response fields

    FieldTypeDescription
    tasksarrayList of tasks for this page. Each task object has the same fields as the Get Task Metadata response.
    continuationTokenstringToken to fetch the next page (null if no more results)

    Error Responses

    • 400 Bad Request: Invalid pageSize parameter
    • 401 Unauthorized: Invalid or missing authentication token
    • 403 Forbidden: Insufficient permissions to list tasks in this organization

    Update a task

    Updates the settings or metadata of an existing task. Only the user who created the task can modify it.

    PATCH /api/preview/agents/{orgName}/tasks/{taskID}

    Parameters

    ParameterTypeInDescription
    orgNamestringpathThe organization name
    taskIDstringpathThe task identifier

    Request body

    All fields are optional. Omitted fields are left unchanged.

    {
  "name": "New task name",
  "isShared": true,
  "approvalMode": "auto",
  "permissionMode": "read-only"
}

    Request fields

    FieldTypeRequiredDescription
    namestringNoA new display name for the task. Must be between 1 and 255 characters after trimming whitespace.
    isSharedbooleanNoWhether to share the task with other organization members.
    approvalModestringNoApproval mode for this task. See approval modes for valid values.
    permissionModestringNoThe permission scope for the task. Valid values: default, read-only.

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  --request PATCH \
  --data '{"approvalMode":"auto","isShared":true}' \
  https://api.pulumi.com/api/preview/agents/my-org/tasks/task_abc123

    Response

    Status: 200 OK

    Returns the updated task object with the same fields as the Get Task Metadata response.

    {
  "id": "task_abc123",
  "name": "New task name",
  "status": "running",
  "createdAt": "2025-01-15T00:00:00Z",
  "approvalMode": "auto",
  "entities": [],
  "planMode": false,
  "isShared": true,
  "sharedAt": "2025-01-15T10:40:00Z",
  "createdBy": {
    "name": "Jane Doe",
    "githubLogin": "janedoe",
    "avatarUrl": "https://api.pulumi.com/static/avatars/J-E91E63.png"
  },
  "permissionMode": "read-only",
  "runtimePhase": "ready",
  "contextUsedTokens": 43272,
  "contextWindowTokens": 1000000
}

    Error responses

    • 403 Forbidden: Feature not enabled for organization
    • 404 Not Found: Task not found or not owned by user

    Respond to an Existing Task

    Allows users to respond to an ongoing agent task with additional input or instructions.

    POST /api/preview/agents/{orgName}/tasks/{taskID}

    Parameters

    ParameterTypeInDescription
    orgNamestringpathThe organization name
    taskIDstringpathThe task identifier

    Request Body

    The request body contains an event object with different subtypes based on the type of response. See the User Event Types section for detailed information about each event type.

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  --request POST \
  --data '{"event":{"type":"user_message","content":"Yes, please proceed with the optimization","timestamp":"2025-01-15T10:35:00Z"}}' \
  https://api.pulumi.com/api/preview/agents/my-org/tasks/task_abc123

    Response

    Status: 202 Accepted

    Error Responses

    • 400 Bad Request: Missing event field or invalid entities mentioned
    • 401 Unauthorized: Invalid or missing authentication token
    • 403 Forbidden: Insufficient permissions to respond to this task
    • 404 Not Found: Task not found
    • 409 Conflict: Cannot respond while a request is still ongoing

    List Events from a Task

    Retrieves the event stream for a specific task.

    GET /api/preview/agents/{orgName}/tasks/{taskID}/events

    Parameters

    ParameterTypeInDescription
    orgNamestringpathThe organization name
    taskIDstringpathThe task identifier
    continuationTokenstringqueryOptional. Token to fetch the next page of results
    pageSizeintegerqueryOptional. Number of items per page (1-1000, default: 100)

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  https://api.pulumi.com/api/preview/agents/my-org/tasks/task_abc123/events?pageSize=50

    Response

    Status: 200 OK

    {
  "events": [
    {
      "id": "event_123",
      "type": "agentResponse",
      "eventBody": {
        "content": "I'll help you optimize your Pulumi stack. Let me analyze the current configuration...",
        "timestamp": "2025-01-15T10:30:00Z"
      }
    },
    {
      "id": "event_124",
      "type": "userInput",
      "eventBody": {
        "content": "Continue with optimization",
        "timestamp": "2025-01-15T10:35:00Z"
      }
    }
  ],
  "continuationToken": "next_page_token"
}

    Response Fields

    FieldTypeDescription
    eventsarrayList of events for this page
    events[].idstringUnique identifier for the event
    events[].typestringType of event (“agentResponse” or “userInput”)
    events[].eventBodyobjectThe event content and metadata
    continuationTokenstringToken to fetch the next page (null if no more results)

    Error Responses

    • 400 Bad Request: Invalid pageSize parameter
    • 401 Unauthorized: Invalid or missing authentication token
    • 403 Forbidden: Insufficient permissions to view events for this task
    • 404 Not Found: Task not found

    User Event Types

    When responding to agent tasks, you can send different types of user events. Each event type has specific fields and use cases.

    User Message Event

    Send a user message event to provide additional instructions or responses to the agent.

    {
  "event": {
    "type": "user_message",
    "content": "Yes, please proceed with the optimization",
    "timestamp": "2025-01-15T10:35:00Z",
    "entity_diff": {
      "add": [
        {
          "type": "stack",
          "name": "my-stack",
          "project": "my-project"
        }
      ],
      "remove": []
    }
  }
}

    Fields

    FieldTypeRequiredDescription
    typestringYesMust be “user_message”
    contentstringYesThe user’s response or additional instructions
    timestampstring (ISO 8601)YesWhen the event occurred
    entity_diffobjectNoEntities to add or remove from the agent context. See Entity Types for details. Note: Pull request entities cannot be added via this API.

    User Confirmation Event

    Send a user confirmation event to respond to an agent’s approval request.

    {
  "event": {
    "type": "user_confirmation",
    "approval_request_id": "req_123",
    "timestamp": "2025-01-15T10:35:00Z"
  }
}

    Fields

    FieldTypeRequiredDescription
    typestringYesMust be “user_confirmation”
    approval_request_idstringYesID to correlate the question the user is responding to
    timestampstring (ISO 8601)YesWhen the event occurred

    User Cancel Event

    Send a user cancel event to cancel the current agent task.

    {
  "event": {
    "type": "user_cancel",
    "timestamp": "2025-01-15T10:35:00Z"
  }
}

    Fields

    FieldTypeRequiredDescription
    typestringYesMust be “user_cancel”
    timestampstring (ISO 8601)YesWhen the event occurred

    Entity Types

    Entities represent resources that the agent can work with. Different entity types provide different capabilities and context to the agent.

    Stack Entity

    Represents a Pulumi stack that the agent can analyze and modify.

    {
  "type": "stack",
  "name": "my-stack",
  "project": "my-project"
}

    Fields

    FieldTypeRequiredDescription
    typestringYesMust be “stack”
    namestringYesThe name of the Pulumi stack
    projectstringYesThe project name containing the stack

    Repository Entity

    Represents a source code repository that the agent can analyze and work with.

    {
  "type": "repository",
  "name": "my-repo",
  "org": "my-org",
  "forge": "github"
}

    Fields

    FieldTypeRequiredDescription
    typestringYesMust be “repository”
    namestringYesThe name of the repository
    orgstringYesThe organization owning the repository
    forgestringYesThe forge/provider where the repository is hosted (e.g., “github”)

    Pull Request Entity

    Represents a pull request that the agent can analyze and work with.

    Note: Pull request entities cannot be added using the create task or respond to task APIs. They are managed by the system and associated with tasks through other mechanisms.

    {
  "type": "pull_request",
  "number": 123,
  "repository": {
    "name": "my-repo",
    "org": "my-org",
    "forge": "github"
  },
  "merged": true
}

    Fields

    FieldTypeRequiredDescription
    typestringYesMust be “pull_request”
    numberintegerYesThe pull request number
    mergedbooleanYesIf the PR has been merged already
    repositoryobjectYesThe repository information
    repository.namestringYesThe name of the repository
    repository.orgstringYesThe organization owning the repository
    repository.forgestringYesThe forge/provider where the repository is hosted

    Policy Issue Entity

    Represents a policy issue that the agent can analyze and help resolve.

    {
  "type": "policy_issue",
  "id": "issue_123"
}

    Fields

    FieldTypeRequiredDescription
    typestringYesMust be “policy_issue”
    idstringYesThe unique identifier for the policy issue

    Approval modes

    Approval modes control how much autonomy the agent has during task execution.

    ValueDescription
    manualThe agent requests approval before running pulumi preview, running pulumi up, and opening a pull request. This is the most conservative mode.
    balancedThe agent requests approval only before running pulumi up. Previews and pull requests proceed without approval.
    autoThe agent does not request any approvals and executes the entire task autonomously.

    For more details, see task modes.

    Preview Status

    These endpoints are currently in preview status (/api/preview/agents/...). The API may change before general availability. Please check the documentation regularly for updates.