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

Neo

    The Neo API provides endpoints for creating and managing AI agent tasks in Pulumi Cloud. Use these endpoints to create tasks, monitor their status, respond to agent requests, and retrieve task events.

    List Tasks

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/agents/{orgName}/tasks

    Lists all agent tasks for the specified organization. Supports pagination via continuationToken with a configurable pageSize (1-1000, default 100). Returns task metadata including ID, name, status, and creation timestamp.

    Request Parameters

    • orgName string path required
      The organization name
    • continuationToken string query optional
      Token for retrieving the next page of results
    • pageSize integer query optional
      Number of results per page

    Responses

    200 OK
    Schema: ListAgentTasksResponse
    • tasks array[AgentTask] required
      Tasks contains the list of tasks for this page.
    • ↳ id string required
      Unique identifier for the task.
    • ↳ name string required
      Display name for the task, typically auto-generated from the initial user message.
    • ↳ status enum required
      Current execution status of the task.
      Values: running, idle
    • ↳ createdAt string required
      When the task was created, in ISO 8601 format.
    • ↳ approvalMode enum required
      Approval mode for this task. Valid values: ‘manual’, ‘auto’, ‘balanced’.
      Values: manual, auto, balanced
    • ↳ entities array[AgentEntity] required
      Pulumi entities (stacks, projects, etc.) that provide context for the agent.
    • ↳ planMode boolean required
      Whether the task is in plan mode. Set based on the first user message.
    • ↳ isShared boolean required
      Whether this task is shared with other org members.
    • ↳ sharedAt string optional
      When the task was first shared. Null if never shared.
    • ↳ createdBy UserInfo required
      Information about the user who created this task.
    • ↳ permissionMode enum optional
      The permission scope for the task.
      Values: default, read-only
    • ↳ runtimePhase enum optional
      The current runtime phase for this task. Null until the runtime checks in.
      Values: booting, ready, running
    • ↳ contextUsedTokens integer optional
      Total input tokens consumed across all model invocations for this task. Approximate context window usage.
    • ↳ contextWindowTokens integer optional
      Maximum context window size in tokens for the primary model used by this task.
    • ↳ toolExecutionMode enum optional
      Where tools are executed for this task. Valid values: ‘cloud’, ‘cli’.
      Values: cloud, cli
    • continuationToken string optional
      ContinuationToken can be used to fetch the next page of results. If null, there are no more results available.
    Errors: 400 pageSize must be between 1 and 1000

    Create Tasks

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/preview/agents/{orgName}/tasks

    Creates a new agent task for the specified organization. The request must include a prompt (the user event message) that initiates the task. Set the ‘permissionMode’ field in the request body to restrict the agent to read-only operations. Returns the created task details including task ID, name, status, and timestamp.

    Request Parameters

    • orgName string path required
      The organization name

    Request Body

    Schema: CreateAgentTaskRequest
    • message AgentUserEventMessage optional
      The message content
    • ↳ content string required
      The exact natural language instruction from the user.
    • ↳ entity_diff AgentEntityDiff optional
      Entities to add or remove from the agent.
    • ↳ commands map[string]AgentSlashCommand optional
      Slash Commands the user selected when creating their message.
    • ↳ timestamp string required
      When the event occurred.
    • ↳ type string required
    • approvalMode enum optional
      Optional approval mode override for this task. If omitted, org default is used.
      Values: manual, auto, balanced
    • planMode boolean optional
      Whether to enable plan mode for this task.
    • permissionMode enum optional
      Controls the permission scope for the task. When omitted, defaults to ‘default’ (the agent uses the creating user’s full permissions).
      Values: default, read-only
    • toolExecutionMode enum optional
      Where tools should be executed. Defaults to ‘cloud’ if omitted.
      Values: cloud, cli
    • enabledIntegrations array[AgentTaskIntegrationRef] optional
      Optional list of integrations to enable for this task. Semantics: omitted/null → inherit all org-enabled integrations; empty list → explicit opt-out (no integration credentials for this task); populated list → whitelist of specific integrations by ID. Modeled as an object array rather than a bare string array so multi-instance support (instance_name, scope, etc.) can be added later without a wire break.
    • ↳ id string required
      The catalog integration ID (e.g. ‘honeycomb’, ‘datadog’).

    Responses

    201 Created
    Schema: CreateAgentTaskResponse
    • taskId string required
      The task identifier
    Errors: 400 prompt is required

    Get Task

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/agents/{orgName}/tasks/{taskID}

    Retrieves metadata for a specific agent task, including its ID, name, status, creation timestamp, and associated entities. Returns 404 if the task does not exist.

    Request Parameters

    • orgName string path required
      The organization name
    • taskID string path required
      The agent task identifier

    Responses

    200 OK
    Schema: AgentTask
    • id string required
      Unique identifier for the task.
    • name string required
      Display name for the task, typically auto-generated from the initial user message.
    • status enum required
      Current execution status of the task.
      Values: running, idle
    • createdAt string required
      When the task was created, in ISO 8601 format.
    • approvalMode enum required
      Approval mode for this task. Valid values: ‘manual’, ‘auto’, ‘balanced’.
      Values: manual, auto, balanced
    • entities array[AgentEntity] required
      Pulumi entities (stacks, projects, etc.) that provide context for the agent.
    • ↳ type string required
    • planMode boolean required
      Whether the task is in plan mode. Set based on the first user message.
    • isShared boolean required
      Whether this task is shared with other org members.
    • sharedAt string optional
      When the task was first shared. Null if never shared.
    • createdBy UserInfo required
      Information about the user who created this task.
    • ↳ name string required
      The user’s display name.
    • ↳ githubLogin string required
      The user’s login name.
    • ↳ avatarUrl string required
      The URL of the user’s avatar image.
    • ↳ email string optional
      IMPORTANT: The email address of the user is only included on a few admin-only APIs. For nearly all APIs that return a UserInfo object, this will not be provided. considered sensitive information.
    • permissionMode enum optional
      The permission scope for the task.
      Values: default, read-only
    • runtimePhase enum optional
      The current runtime phase for this task. Null until the runtime checks in.
      Values: booting, ready, running
    • contextUsedTokens integer optional
      Total input tokens consumed across all model invocations for this task. Approximate context window usage.
    • contextWindowTokens integer optional
      Maximum context window size in tokens for the primary model used by this task.
    • toolExecutionMode enum optional
      Where tools are executed for this task. Valid values: ‘cloud’, ‘cli’.
      Values: cloud, cli
    Errors: 404 task

    Respond To Task

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/preview/agents/{orgName}/tasks/{taskID}

    Sends a response to an ongoing agent task. Supported event types include user_message, user_confirmation, and user_cancel. Returns 409 if the task already has a pending request that has not completed.

    Request Parameters

    • orgName string path required
      The organization name
    • taskID string path required
      The agent task identifier

    Request Body

    Schema: AgentRespondToTaskRequest
    • event AgentUserEvent optional
      The event
    • ↳ entity_diff AgentEntityDiff optional
      Entities to add or remove from the agent.
    • ↳ timestamp string required
      When the event occurred.
    • ↳ type string required

    Responses

    202 Accepted
    Errors: 400 event field is required 404 task 409 cannot respond while a request is still ongoing

    Update Task

    ▼
    Preview. This endpoint is in preview and may change without notice.
    PATCH /api/preview/agents/{orgName}/tasks/{taskID}

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

    Request Parameters

    • orgName string path required
      The organization name
    • taskID string path required
      The agent task identifier

    Request Body

    Schema: UpdateTaskRequest
    • name string optional
      A new display name for the task. Null means no change. Must be between 1 and 255 characters after trimming whitespace.
    • isShared boolean optional
      Whether to share the task with other org members. Null means no change.
    • approvalMode enum optional
      Approval mode for this task. Null means no change. Valid values: ‘manual’, ‘auto’, ‘balanced’.
      Values: manual, auto, balanced
    • permissionMode enum optional
      The permission scope for the task. Null means no change.
      Values: default, read-only

    Responses

    200 OK
    Schema: AgentTask
    • id string required
      Unique identifier for the task.
    • name string required
      Display name for the task, typically auto-generated from the initial user message.
    • status enum required
      Current execution status of the task.
      Values: running, idle
    • createdAt string required
      When the task was created, in ISO 8601 format.
    • approvalMode enum required
      Approval mode for this task. Valid values: ‘manual’, ‘auto’, ‘balanced’.
      Values: manual, auto, balanced
    • entities array[AgentEntity] required
      Pulumi entities (stacks, projects, etc.) that provide context for the agent.
    • ↳ type string required
    • planMode boolean required
      Whether the task is in plan mode. Set based on the first user message.
    • isShared boolean required
      Whether this task is shared with other org members.
    • sharedAt string optional
      When the task was first shared. Null if never shared.
    • createdBy UserInfo required
      Information about the user who created this task.
    • ↳ name string required
      The user’s display name.
    • ↳ githubLogin string required
      The user’s login name.
    • ↳ avatarUrl string required
      The URL of the user’s avatar image.
    • ↳ email string optional
      IMPORTANT: The email address of the user is only included on a few admin-only APIs. For nearly all APIs that return a UserInfo object, this will not be provided. considered sensitive information.
    • permissionMode enum optional
      The permission scope for the task.
      Values: default, read-only
    • runtimePhase enum optional
      The current runtime phase for this task. Null until the runtime checks in.
      Values: booting, ready, running
    • contextUsedTokens integer optional
      Total input tokens consumed across all model invocations for this task. Approximate context window usage.
    • contextWindowTokens integer optional
      Maximum context window size in tokens for the primary model used by this task.
    • toolExecutionMode enum optional
      Where tools are executed for this task. Valid values: ‘cloud’, ‘cli’.
      Values: cloud, cli
    Errors: 403 feature not enabled for organization 404 task not found or not owned by user

    Get Task Events

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/agents/{orgName}/tasks/{taskID}/events

    Retrieves the event stream for a specific agent task. Events include agent messages, tool calls, status changes, and user interactions. Supports pagination via continuationToken with a configurable pageSize (1-1000).

    Request Parameters

    • orgName string path required
      The organization name
    • taskID string path required
      The agent task identifier
    • continuationToken string query optional
      Token for retrieving the next page of results
    • pageSize integer query optional
      Number of results per page

    Responses

    200 OK
    Schema: ListAgentTaskEventsResponse
    • events array[AgentConsoleEvent] required
      Events contains the list of events for this page.
    • ↳ id string required
      The UUID of the event
    • ↳ isSynthetic boolean required
      True when the event was synthesized by the backend rather than submitted directly by the user or agent runtime.
    • ↳ type string required
    • continuationToken string optional
      ContinuationToken can be used to fetch the next page of results. If null, there are no more results available.
    Errors: 400 pageSize must be between 1 and 1000 404 task

    Stream Task Events

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/preview/agents/{orgName}/tasks/{taskID}/events/stream

    Streams events for a specific agent task as Server-Sent Events. Each SSE data frame contains a JSON-encoded AgentConsoleEvent. The stream delivers existing events immediately, then keeps the connection open to deliver new events in real time until the task completes.

    Request Parameters

    • orgName string path required
      The organization name
    • taskID string path required
      The agent task identifier

    Responses

    200 OK
    Errors: 404 task