Pulumi Neo API

openapi: 3.0.3
info:
  description: APIs and Definitions for the Pulumi Cloud product.
  title: Pulumi APIs AccessTokens Neo API
  version: 1.0.0
tags:
- name: Neo
paths:
  /api/preview/agents/{orgName}/tasks:
    get:
      description: 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.
      operationId: ListTasks
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: Token for retrieving the next page of results
        in: query
        name: continuationToken
        schema:
          type: string
      - description: Number of results per page
        in: query
        name: pageSize
        schema:
          format: int64
          type: integer
      - description: Field to sort the results by. Defaults to lastEvent.
        in: query
        name: sortBy
        schema:
          enum:
          - lastEvent
          - created
          - status
          - name
          type: string
          x-pulumi-model-property:
            enumComments: The field used to sort Neo agent tasks in list results.
            enumFieldComments:
            - Sort by the time of the most recent event on the task.
            - Sort by when the task was created.
            - Sort by task status, with running ordered before idle when ascending.
            - Sort by task name.
            enumTypeName: AgentTaskSortField
      - description: Direction to sort the results in. Defaults to desc.
        in: query
        name: sortDirection
        schema:
          enum:
          - asc
          - desc
          type: string
          x-pulumi-model-property:
            enumComments: The direction used when sorting Neo agent tasks.
            enumFieldComments:
            - Sort in ascending order.
            - Sort in descending order.
            enumTypeName: AgentTaskSortDirection
      - description: Task type to filter by
        in: query
        name: taskType
        schema:
          enum:
          - sync
          - async
          type: string
          x-pulumi-model-property:
            enumComments: The origin category for a Neo agent task.
            enumFieldComments:
            - A task started directly by a user in an interactive flow.
            - A task started asynchronously by background signal infrastructure.
            enumTypeName: AgentTaskType
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentTasksResponse'
          description: OK
        '400':
          description: pageSize must be between 1 and 1000
      summary: ListTasks
      tags:
      - Neo
      x-pulumi-route-property:
        Visibility: Preview
    post:
      description: 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.
      operationId: CreateTasks
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentTaskRequest'
        x-originalParamName: body
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAgentTaskResponse'
          description: Created
        '400':
          description: prompt is required
      summary: CreateTasks
      tags:
      - Neo
      x-pulumi-route-property:
        Visibility: Preview
  /api/preview/agents/{orgName}/tasks/{taskID}:
    get:
      description: 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.
      operationId: GetTask
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The agent task identifier
        in: path
        name: taskID
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTask'
          description: OK
        '404':
          description: task
      summary: GetTask
      tags:
      - Neo
      x-pulumi-route-property:
        Visibility: Preview
    patch:
      description: Updates the settings or metadata of an agent task. Only the user who created the task can modify it.
      operationId: UpdateTask
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The agent task identifier
        in: path
        name: taskID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTask'
          description: OK
        '403':
          description: feature not enabled for organization
        '404':
          description: task not found or not owned by user
      summary: UpdateTask
      tags:
      - Neo
      x-pulumi-route-property:
        Visibility: Preview
    post:
      description: 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.
      operationId: RespondToTask
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The agent task identifier
        in: path
        name: taskID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRespondToTaskRequest'
        x-originalParamName: body
      responses:
        '202':
          description: Accepted
        '400':
          description: event field is required
        '404':
          description: task
        '409':
          description: cannot respond while a request is still ongoing
      summary: RespondToTask
      tags:
      - Neo
      x-pulumi-route-property:
        Visibility: Preview
  /api/preview/agents/{orgName}/tasks/{taskID}/events:
    get:
      description: 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).
      operationId: GetTaskEvents
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The agent task identifier
        in: path
        name: taskID
        required: true
        schema:
          type: string
      - description: Token for retrieving the next page of results
        in: query
        name: continuationToken
        schema:
          type: string
      - description: Number of results per page
        in: query
        name: pageSize
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentTaskEventsResponse'
          description: OK
        '400':
          description: pageSize must be between 1 and 1000
        '404':
          description: task
      summary: GetTaskEvents
      tags:
      - Neo
      x-pulumi-route-property:
        Visibility: Preview
  /api/preview/agents/{orgName}/tasks/{taskID}/events/stream:
    get:
      description: 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.
      operationId: StreamTaskEvents
      parameters:
      - description: The organization name
        in: path
        name: orgName
        required: true
        schema:
          type: string
      - description: The agent task identifier
        in: path
        name: taskID
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AgentConsoleEvent'
          description: OK
        '404':
          description: task
      summary: StreamTaskEvents
      tags:
      - Neo
      x-pulumi-route-property:
        Visibility: Preview
components:
  schemas:
    AgentEntityDiff:
      description: Represents agent entity diff.
      properties:
        add:
          description: 'Entities to add to the Agent''s context.

            Entities must be valid, and will be automatically deleted if they are invalid.'
          items:
            $ref: '#/components/schemas/AgentEntity'
          type: array
          x-order: 1
        remove:
          description: Entities to remove from the Agent's context.
          items:
            $ref: '#/components/schemas/AgentEntity'
          type: array
          x-order: 2
      type: object
    ListAgentTasksResponse:
      description: Response containing a paginated list of agent tasks.
      properties:
        continuationToken:
          description: 'ContinuationToken can be used to fetch the next page of results.

            If null, there are no more results available.'
          type: string
          x-order: 2
        tasks:
          description: Tasks contains the list of tasks for this page.
          items:
            $ref: '#/components/schemas/AgentTask'
          type: array
          x-order: 1
      required:
      - tasks
      type: object
    AgentUserEvent:
      description: Represents an agent user event.
      discriminator:
        mapping:
          exec_tool_call: '#/components/schemas/AgentUserEventExecToolCall'
          tool_result: '#/components/schemas/AgentUserEventToolResult'
          user_cancel: '#/components/schemas/AgentUserEventCancel'
          user_confirmation: '#/components/schemas/AgentUserEventConfirmation'
          user_message: '#/components/schemas/AgentUserEventMessage'
        propertyName: type
      properties:
        entity_diff:
          $ref: '#/components/schemas/AgentEntityDiff'
          description: Entities to add or remove from the agent.
          x-order: 1
        timestamp:
          description: When the event occurred.
          format: date-time
          type: string
        type:
          type: string
      required:
      - timestamp
      - type
      type: object
    UpdateTaskRequest:
      description: Request to update a task.
      properties:
        approvalMode:
          description: 'Approval mode for this task. Null means no change. Valid values: ''manual'', ''auto'', ''balanced''.'
          enum:
          - manual
          - auto
          - balanced
          type: string
          x-order: 3
          x-pulumi-model-property:
            enumTypeName: NeoApprovalMode
            enumComments: NeoApprovalMode represents the default approval mode for Neo AI agent tasks in an organization
        isShared:
          description: Whether to share the task with other org members. Null means no change.
          type: boolean
          x-order: 2
        name:
          description: A new display name for the task. Null means no change. Must be between 1 and 255 characters after trimming whitespace.
          type: string
          x-order: 1
        permissionMode:
          description: The permission scope for the task. Null means no change.
          enum:
          - default
          - read-only
          type: string
          x-order: 4
          x-pulumi-model-property:
            enumTypeName: NeoPermissionMode
            enumComments: Permission scope for a Neo agent task. Controls the level of access the agent has when acting on behalf of the user.
            enumFieldNames:
            - Default
            - ReadOnly
      type: object
    ListAgentTaskEventsResponse:
      description: 'TODO: add polling support (via lastSeen)'
      properties:
        continuationToken:
          description: 'ContinuationToken can be used to fetch the next page of results.

            If null, there are no more results available.'
          type: string
          x-order: 2
        events:
          description: Events contains the list of events for this page.
          items:
            $ref: '#/components/schemas/AgentConsoleEvent'
          type: array
          x-order: 1
      required:
      - events
      type: object
    AgentConsoleEvent:
      description: A console event in an agent task conversation, either a user input or an agent response.
      discriminator:
        mapping:
          agentResponse: '#/components/schemas/AgentConsoleEventAgentResponse'
          userInput: '#/components/schemas/AgentConsoleEventUserInput'
        propertyName: type
      properties:
        id:
          description: The UUID of the event
          type: string
          x-order: 1
        isSynthetic:
          description: True when the event was synthesized by the backend rather than submitted directly by the user or agent runtime.
          type: boolean
          x-order: 2
        type:
          type: string
      required:
      - id
      - isSynthetic
      - type
      type: object
    AgentUserEventMessage:
      allOf:
      - $ref: '#/components/schemas/AgentUserEvent'
      - description: Represents an agent user event.
        properties:
          commands:
            additionalProperties:
              $ref: '#/components/schemas/AgentSlashCommand'
            description: Slash Commands the user selected when creating their message.
            type: object
            x-order: 2
          content:
            description: The exact natural language instruction from the user.
            type: string
            x-order: 1
        required:
        - content
        type: object
    AgentSlashCommand:
      description: An agent slash command.
      properties:
        builtIn:
          description: Whether this is a built-in system command (true) or user-created (false).
          type: boolean
          x-order: 4
        description:
          description: Human-readable description shown to users in the command palette.
          type: string
          x-order: 3
        modifiedAt:
          description: When the command was last modified, in ISO 8601 format.
          format: date-time
          type: string
          x-order: 5
        name:
          description: The slash command name (e.g. '/fix', '/explain'). Used to invoke the command.
          type: string
          x-order: 1
        prompt:
          description: The system prompt text sent to the AI when this command is invoked.
          type: string
          x-order: 2
        tag:
          description: Version tag for optimistic concurrency control.
          type: string
          x-order: 6
      required:
      - builtIn
      - description
      - modifiedAt
      - name
      - prompt
      - tag
      type: object
    AgentEntity:
      description: Represents agent entity.
      discriminator:
        mapping:
          policy_issue: '#/components/schemas/AgentEntityPolicyIssue'
          pull_request: '#/components/schemas/AgentEntityPR'
          repository: '#/components/schemas/AgentEntityRepository'
          stack: '#/components/schemas/AgentEntityStack'
        propertyName: type
      properties:
        type:
          type: string
      required:
      - type
      type: object
    AgentRespondToTaskRequest:
      description: The API payload for users responding to an existing agent task.
      properties:
        event:
          $ref: '#/components/schemas/AgentUserEvent'
          description: The event
          x-order: 1
      type: object
    CreateAgentTaskResponse:
      description: Response body for creating an agent task.
      properties:
        taskId:
          description: The task identifier
          type: string
          x-order: 1
      required:
      - taskId
      type: object
    UserInfo:
      description: 'UserInfo contains just the display information for a user.  This information may be returned from public APIs,

        and as such this structure must not contain sensitive information.  Please refer to User for this sort of thing.'
      properties:
        avatarUrl:
          description: The URL of the user's avatar image.
          type: string
          x-order: 3
        email:
          description: '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.'
          type: string
          x-order: 4
        githubLogin:
          description: The user's login name.
          type: string
          x-order: 2
        name:
          description: The user's display name.
          type: string
          x-order: 1
      required:
      - avatarUrl
      - githubLogin
      - name
      type: object
    AgentTask:
      description: A Pulumi Copilot agent task representing a conversation and its associated context.
      properties:
        approvalMode:
          description: 'Approval mode for this task. Valid values: ''manual'', ''auto'', ''balanced''.'
          enum:
          - manual
          - auto
          - balanced
          type: string
          x-order: 7
          x-pulumi-model-property:
            enumTypeName: NeoApprovalMode
            enumComments: NeoApprovalMode represents the default approval mode for Neo AI agent tasks in an organization
        asyncTriggerType:
          description: The async trigger source for this task. Null for sync tasks.
          enum:
          - scheduled
          - external_signal
          type: string
          x-order: 4
          x-pulumi-model-property:
            enumTypeName: AgentAsyncTriggerType
            enumComments: The async trigger source for a Neo agent task.
            enumFieldNames:
            - Scheduled
            - ExternalSignal
            enumFieldComments:
            - The task was started by a cron-driven scheduled signal.
            - The task was started in reaction to an external signal payload.
        contextUsedTokens:
          description: Total input tokens consumed across all model invocations for this task. Approximate context window usage.
          format: int32
          type: integer
          x-order: 16
        contextWindowTokens:
          description: Maximum context window size in tokens for the primary model used by this task.
          format: int32
          type: integer
          x-order: 17
        createdAt:
          description: When the task was created, in ISO 8601 format.
          format: date-time
          type: string
          x-order: 6
        createdBy:
          $ref: '#/components/schemas/UserInfo'
          description: Information about the user who created this task.
          x-order: 12
        entities:
          description: Pulumi entities (stacks, projects, etc.) that provide context for the agent.
          items:
            $ref: '#/components/schemas/AgentEntity'
          type: array
          x-order: 8
        id:
          description: Unique identifier for the task.
          type: string
          x-order: 1
        isShared:
          description: Whether this task is shared with other org members.
          type: boolean
          x-order: 10
        lastHeartbeat:
          description: When the task runtime last reported a heartbeat. Null if the runtime has never checked in.
          format: date-time
          type: string
          x-order: 15
        name:
          description: Display name for the task, typically auto-generated from the initial user message.
          type: string
          x-order: 2
        permissionMode:
          description: The permission scope for the task.
          enum:
          - default
          - read-only
          type: string
          x-order: 13
          x-pulumi-model-property:
            enumTypeName: NeoPermissionMode
            enumComments: Permission scope for a Neo agent task. Controls the level of access the agent has when acting on behalf of the user.
            enumFieldNames:
            - Default
            - ReadOnly
        planMode:
          description: Whether the task is in plan mode. Set based on the first user message.
          type: boolean
          x-order: 9
        runtimePhase:
          description: The current runtime phase for this task. Null until the runtime checks in.
          enum:
          - booting
          - ready
          - running
          type: string
          x-order: 14
          x-pulumi-model-property:
            enumTypeName: AgentTaskRuntimePhase
            enumComments: Runtime lifecycle phase for a Neo agent task runtime.
        sharedAt:
          description: When the task was first shared. Null if never shared.
          format: date-time
          type: string
          x-order: 11
        source:
          description: 'The origin that triggered this task. Valid values: ''console'', ''cli'', ''slack'', ''schedule'', ''api'', ''github''.'
          enum:
          - api
          - console
          - cli
          - slack
          - schedule
          - github
          type: string
          x-order: 20
          x-pulumi-model-property:
            enumTypeName: AgentTaskSource
            enumComments: Identifies the origin that triggered a Neo agent task.
            enumFieldComments:
            - Task created via the REST API without a more specific origin.
            - Task created from the Pulumi Cloud web console.
            - Task created from the Pulumi CLI.
            - Task created from the Slack integration.
            - Task created by a scheduled automation.
            - Task triggered from a GitHub integration.
        sourceAutomationID:
          description: The automation that spawned this task, if the task was created by an automation run.
          type: string
          x-order: 19
        status:
          description: Current execution status of the task.
          enum:
          - running
          - idle
          type: string
          x-order: 5
          x-pulumi-model-property:
            enumTypeName: AgentTaskStatus
            enumComments: 'Execution status of an agent task. Valid values: ''running'', ''idle''.'
        taskType:
          description: Whether the task was started synchronously by a user or asynchronously by background automation.
          enum:
          - sync
          - async
          type: string
          x-order: 3
          x-pulumi-model-property:
            enumTypeName: AgentTaskType
            enumComments: The origin category for a Neo agent task.
            enumFieldComments:
            - A task started directly by a user in an interactive flow.
            - A task started asynchronously by background signal infrastructure.
        toolExecutionMode:
          description: 'Where tools are executed for this task. Valid values: ''cloud'', ''cli''.'
          enum:
          - cloud
          - cli
          type: string
          x-order: 18
          x-pulumi-model-property:
            enumTypeName: ToolExecutionMode
            enumComments: Where tools are executed for an agent task.
      required:
      - approvalMode
      - createdAt
      - createdBy
      - entities
      - id
      - isShared
      - name
      - planMode
      - status
      - taskType
      type: object
    AgentTaskIntegrationRef:
      description: A reference to an integration enabled for an agent task. Structured as an object (rather than a bare string) so additional fields like instance name or scope can be added later without breaking the wire format.
      properties:
        id:
          description: The catalog integration ID (e.g. 'honeycomb', 'datadog').
          type: string
          x-order: 1
      required:
      - id
      type: object
    CreateAgentTaskRequest:
      description: Create a new task by sending the first event in the conversation.
      properties:
        approvalMode:
          description: Optional approval mode override for this task. If omitted, org default is used.
          enum:
          - manual
          - auto
          - balanced
          type: string
          x-order: 2
          x-pulumi-model-property:
            enumTypeName: NeoApprovalMode
            enumComments: NeoApprovalMode represents the default approval mode for Neo AI agent tasks in an organization
        enabledIntegrations:
          description: '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.'
          items:
            $ref: '#/components/schemas/AgentTaskIntegrationRef'
          type: array
          x-order: 6
        message:
          $ref: '#/components/schemas/AgentUserEventMessage'
          description: The message content
          x-order: 1
        permissionMode:
          description: Controls the permission scope for the task. When omitted, defaults to 'default' (the agent uses the creating user's full permissions).
          enum:
          - default
          - read-only
          type: string
          x-order: 4
          x-pulumi-model-property:
            enumTypeName: NeoPermissionMode
            enumComments: Permission scope for a Neo agent task. Controls the level of access the agent has when acting on behalf of the user.
            enumFieldNames:
            - Default
            - ReadOnly
        planMode:
          description: Whether to enable plan mode for this task.
          type: boolean
          x-order: 3
        source:
          description: The origin that triggered this task. Defaults to 'api' if omitted.
          enum:
          - api
          - console
          - cli
          - slack
          - schedule
          - github
          type: string
          x-order: 7
          x-pulumi-model-property:
            enumTypeName: AgentTaskSource
            enumComments: Identifies the origin that triggered a Neo agent task.
            enumFieldComments:
            - Task created via the REST API without a more specific origin.
            - Task created from the Pulumi Cloud web console.
            - Task created from the Pulumi CLI.
            - Task created from the Slack integration.
            - Task created by a scheduled automation.
            - Task triggered from a GitHub integration.
        toolExecutionMode:
          description: Where tools should be executed. Defaults to 'cloud' if omitted.
          enum:
          - cloud
          - cli
          type: string
          x-order: 5
          x-pulumi-model-property:
            enumTypeName: ToolExecutionMode
            enumComments: Where tools are executed for an agent task.
      type: object