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.

    List Neo Member Usage Caps

    ▼
    GET /api/console/orgs/{orgName}/neo/member-usage-caps

    Returns every organization member joined with their per-member monthly Neo usage cap, their month-to-date Neo spend, and their effective limit (the smaller of the per-member and org-level caps). Caps are denominated in cents.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    200 OK
    Schema: NeoMemberUsageCaps
    • orgCapCents integer optional
      The org-level monthly Neo usage cap in US-dollar cents, or null when the organization has no org-level cap. Provided for context — a member’s effective limit is the smaller of their per-member cap and this.
    • members array[NeoMemberUsageCapEntry] required
      One entry per organization member.
    • ↳ userID string required
      The member’s user ID. This is the identifier the PUT and DELETE per-member cap endpoints key on (SSO-safe, unlike login).
    • ↳ login string required
      The member’s login.
    • ↳ name string required
      The member’s display name.
    • ↳ avatarURL string required
      URL of the member’s avatar image.
    • ↳ email string required
      The member’s email address.
    • ↳ perMemberCapCents integer optional
      The member’s per-member monthly Neo usage cap in US-dollar cents, or null when no per-member cap is set (the member is bounded only by the org-level cap, if any).
    • ↳ amountUsedCents integer required
      The member’s Neo spend in US-dollar cents so far in the current monthly cap window.
    • ↳ effectiveLimitCents integer optional
      The limit that binds first: the smaller of the per-member and org-level caps in US-dollar cents. Null when the member has neither cap (unbounded).

    Update Neo Member Usage Cap

    ▼
    PUT /api/console/orgs/{orgName}/neo/member-usage-caps/{userID}

    Creates or replaces the monthly Neo usage cap for a single member of an organization. The cap must be at least $10/month. To remove the cap, call DeleteNeoMemberUsageCap.

    Request Parameters

    • orgName string path required
      The organization name
    • userID string path required
      The member’s user ID

    Request Body

    Schema: UpdateNeoMemberUsageCapRequest
    • capCents integer required
      Monthly cap in US-dollar cents. Must be at least 1000 ($10, the self-serve floor) and at most 100_000_000 ($1M). Outside that range the call returns 400.

    Responses

    200 OK
    Schema: NeoMemberUsageCap
    • userID string required
      The user the cap applies to.
    • capCents integer required
      Monthly cap in US-dollar cents. Always strictly positive; “no cap” is the absence of a row (removed via DeleteNeoMemberUsageCap).
    • updatedAt string required
      Time when the cap was last updated.
    Errors: 400 Invalid cap configuration or user is not a member of the organization

    Delete Neo Member Usage Cap

    ▼
    DELETE /api/console/orgs/{orgName}/neo/member-usage-caps/{userID}

    Removes the monthly Neo usage cap for a single member, returning them to only the org-level cap (if any). Idempotent — deleting when no cap is set returns 204.

    Request Parameters

    • orgName string path required
      The organization name
    • userID string path required
      The member’s user ID

    Responses

    204 No Content

    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

    Get Neo Usage Cap

    ▼
    GET /api/orgs/{orgName}/neo/usage-cap

    Returns the org admin-configured monthly Neo usage cap for an organization, or 204 (no content) when no cap is configured (the default). Caps are denominated in cents.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    200 OK
    Schema: NeoUsageCap
    • capCents integer required
      Monthly cap in US-dollar cents. Always strictly positive; “no cap” is the absence of a row (GetNeoUsageCap returns 204).
    • updatedAt string required
      Time when the cap was last updated.
    • notificationsEnabled boolean required
      Whether threshold-warning emails (50/80/95/100% of the cap) are sent to billing admins. True unless the admin has turned them off.
    204 No cap configured for this organization

    Update Neo Usage Cap

    ▼
    PUT /api/orgs/{orgName}/neo/usage-cap

    Creates or replaces the monthly Neo usage cap for an organization. The cap must be at least $10/month. To remove the cap, call DeleteNeoUsageCap.

    Request Parameters

    • orgName string path required
      The organization name

    Request Body

    Schema: UpdateNeoUsageCapRequest
    • capCents integer required
      Monthly cap in US-dollar cents. Must be at least 1000 ($10, the self-serve floor) and at most 100_000_000 ($1M). Outside that range the call returns 400.
    • notificationsEnabled boolean optional
      Whether to send threshold-warning emails (50/80/95/100% of the cap) to billing admins. Omit (null) to leave the current setting unchanged; new caps default to enabled.

    Responses

    200 OK
    Schema: NeoUsageCap
    • capCents integer required
      Monthly cap in US-dollar cents. Always strictly positive; “no cap” is the absence of a row (GetNeoUsageCap returns 204).
    • updatedAt string required
      Time when the cap was last updated.
    • notificationsEnabled boolean required
      Whether threshold-warning emails (50/80/95/100% of the cap) are sent to billing admins. True unless the admin has turned them off.
    Errors: 400 Invalid cap configuration

    Delete Neo Usage Cap

    ▼
    DELETE /api/orgs/{orgName}/neo/usage-cap

    Removes the monthly Neo usage cap for an organization, returning it to the uncapped default. Idempotent — deleting when no cap is set returns 204.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    204 No Content

    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
    • ↳ role string optional
      The id of the RBAC role this task assumes. Null when the task runs with the creating user’s own permissions (no assumed role).
    • ↳ 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, worker
    • ↳ 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’, ‘code-review’.
      Values: api, console, cli, slack, schedule, github, code-review
    • ↳ vcsProvider enum optional
      The version control system this task operates against. Set for tasks that target a specific VCS platform (e.g. code reviews). Null for tasks with no VCS context.
      Values: github, gitlab, bitbucket, azure_devops, custom, github_enterprise
    • 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. The message is a user message, so its discriminator field must be set to “type”: “user_message”. 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. This is the first event in the conversation and must be a user message, so its discriminator field must be set to “type”: “user_message”.
    • 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
    • role string optional
      Optional RBAC role the task assumes, identified by role id. When set, the task operates with that role’s permissions in place of the creating user’s own assignments. You may only assume a role that is assigned to you, directly or through a team; a role you do not hold is rejected with a 403. Omitted/null means no assumed role: the task uses the creating user’s full permissions. Orthogonal to permissionMode, which controls the read-only behavior posture independently.
    • toolExecutionMode enum optional
      Where tools should be executed. Defaults to ‘cloud’ if omitted.
      Values: cloud, cli, worker
    • 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, code-review
    • 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
    • role string optional
      The id of the RBAC role this task assumes. Null when the task runs with the creating user’s own permissions (no assumed role).
    • 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, worker
    • 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’, ‘code-review’.
      Values: api, console, cli, slack, schedule, github, code-review
    • vcsProvider enum optional
      The version control system this task operates against. Set for tasks that target a specific VCS platform (e.g. code reviews). Null for tasks with no VCS context.
      Values: github, gitlab, bitbucket, azure_devops, custom, github_enterprise
    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
    • role string optional
      The id of the RBAC role this task assumes. Null when the task runs with the creating user’s own permissions (no assumed role).
    • 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, worker
    • 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’, ‘code-review’.
      Values: api, console, cli, slack, schedule, github, code-review
    • vcsProvider enum optional
      The version control system this task operates against. Set for tasks that target a specific VCS platform (e.g. code reviews). Null for tasks with no VCS context.
      Values: github, gitlab, bitbucket, azure_devops, custom, github_enterprise
    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