Skip to main content
Sign in Dashboard Get started
  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.

    Get Org Neo Token Budget

    ▼
    GET /api/orgs/{orgName}/neo/token-budget

    Returns the current Neo-token allowance and consumption for an organization. Returns 404 when no Neo-token cap applies to this organization.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    200 OK
    Schema: OrgNeoTokenBudget
    • windowKind enum required
      Kind of cap window applied to the org.
      Values: trial, individual
    • baseAllowanceTokens integer required
      Plan-derived base allowance for the current window, in Neo tokens.
    • effectiveAllowanceTokens integer required
      Allowance for the current window, in Neo tokens. Includes any active bonus on top of the base allowance.
    • consumedTokens integer required
      Total Neo tokens consumed in the current window.
    • windowEnd integer required
      Unix epoch timestamp (seconds) when the current window ends and the consumed counter resets. Zero when the window does not reset.
    • exhausted boolean required
      True when consumedTokens has reached effectiveAllowanceTokens for the current window.
    Errors: 404 No Neo-token cap applies to this organization

    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
    • sortBy string query optional
      Field to sort the results by. Defaults to lastEvent.
    • sortDirection string query optional
      Direction to sort the results in. Defaults to desc.
    • taskType string query optional
      Task type to filter by

    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.
    • ↳ taskType enum required
      Whether the task was started synchronously by a user or asynchronously by background automation.
      Values: sync, async
    • ↳ asyncTriggerType enum optional
      The async trigger source for this task. Null for sync tasks.
      Values: scheduled, external_signal
    • ↳ 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
    • ↳ lastHeartbeat string optional
      When the task runtime last reported a heartbeat. Null if the runtime has never checked in.
    • ↳ 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.
    • ↳ contextCompactionThresholdPercent integer optional
      Percentage of the context window (1-100) at which the agent triggers conversation compaction. Populated alongside contextWindowTokens when token usage data is available; omitted otherwise.
    • ↳ tokensUsed integer required
      Total Neo tokens consumed across all model invocations for this task. Neo tokens are the priced unit used for billing — distinct from the raw model input tokens surfaced in contextUsedTokens / contextWindowTokens.
    • ↳ toolExecutionMode enum optional
      Where tools are executed for this task. Valid values: ‘cloud’, ‘cli’.
      Values: cloud, cli
    • ↳ sourceAutomationID string optional
      The automation that spawned this task, if the task was created by an automation run.
    • ↳ source enum optional
      The origin that triggered this task. Valid values: ‘console’, ‘cli’, ‘slack’, ‘schedule’, ‘api’, ‘github’.
      Values: api, console, cli, slack, schedule, github
    • 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
    • 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.
    • source enum optional
      The origin that triggered this task. Defaults to ‘api’ if omitted.
      Values: api, console, cli, slack, schedule, github
    • cliIntegrations array[CLIIntegrationRef] optional
      Optional filter for CLI integrations to enable for this task. Semantics: omitted/null → enable all CLI integrations connected for the org; empty list → explicit opt-out (no CLI integrations for this task); populated list → whitelist by (catalogId, name) of the configured instances to enable. Entries with missing or unknown catalogId, missing name, or referencing a (catalogId, name) pair that is not connected for the organization are rejected with a 400 response. catalogId matching is case-insensitive.

    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.
    • taskType enum required
      Whether the task was started synchronously by a user or asynchronously by background automation.
      Values: sync, async
    • asyncTriggerType enum optional
      The async trigger source for this task. Null for sync tasks.
      Values: scheduled, external_signal
    • 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
    • lastHeartbeat string optional
      When the task runtime last reported a heartbeat. Null if the runtime has never checked in.
    • 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.
    • contextCompactionThresholdPercent integer optional
      Percentage of the context window (1-100) at which the agent triggers conversation compaction. Populated alongside contextWindowTokens when token usage data is available; omitted otherwise.
    • tokensUsed integer required
      Total Neo tokens consumed across all model invocations for this task. Neo tokens are the priced unit used for billing — distinct from the raw model input tokens surfaced in contextUsedTokens / contextWindowTokens.
    • toolExecutionMode enum optional
      Where tools are executed for this task. Valid values: ‘cloud’, ‘cli’.
      Values: cloud, cli
    • sourceAutomationID string optional
      The automation that spawned this task, if the task was created by an automation run.
    • source enum optional
      The origin that triggered this task. Valid values: ‘console’, ‘cli’, ‘slack’, ‘schedule’, ‘api’, ‘github’.
      Values: api, console, cli, slack, schedule, github
    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

    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.
    • taskType enum required
      Whether the task was started synchronously by a user or asynchronously by background automation.
      Values: sync, async
    • asyncTriggerType enum optional
      The async trigger source for this task. Null for sync tasks.
      Values: scheduled, external_signal
    • 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
    • lastHeartbeat string optional
      When the task runtime last reported a heartbeat. Null if the runtime has never checked in.
    • 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.
    • contextCompactionThresholdPercent integer optional
      Percentage of the context window (1-100) at which the agent triggers conversation compaction. Populated alongside contextWindowTokens when token usage data is available; omitted otherwise.
    • tokensUsed integer required
      Total Neo tokens consumed across all model invocations for this task. Neo tokens are the priced unit used for billing — distinct from the raw model input tokens surfaced in contextUsedTokens / contextWindowTokens.
    • toolExecutionMode enum optional
      Where tools are executed for this task. Valid values: ‘cloud’, ‘cli’.
      Values: cloud, cli
    • sourceAutomationID string optional
      The automation that spawned this task, if the task was created by an automation run.
    • source enum optional
      The origin that triggered this task. Valid values: ‘console’, ‘cli’, ‘slack’, ‘schedule’, ‘api’, ‘github’.
      Values: api, console, cli, slack, schedule, github
    Errors: 403 feature not enabled for organization 404 task not found or not owned by user

    Cancel Task

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

    Cancels an agent task. When force is true, immediately terminates the runtime session and resets the task to idle. This is the escalation path when a graceful cancel (via the user_cancel event in RespondToTask) is insufficient or the task is stuck. Unlike graceful cancel, force-cancel does not attempt to notify the agent runtime — it kills the session directly and resets the task state. Currently only force cancellation is supported; the force field must be set to true. Returns 409 if the session was stopped but the task status could not be reset to idle.

    Request Parameters

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

    Request Body

    Schema: CancelAgentTaskRequest
    • force boolean required
      If true, immediately terminate the runtime session and reset the task to idle without attempting a graceful cancel. Required to be true in the current implementation.

    Responses

    204 Task cancelled successfully
    Errors: 400 force must be true (graceful cancel not yet supported via this endpoint) 404 task 409 session stopped but task status could not be reset to idle

    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