Skip to main content
Sign in Dashboard Get started
  1. Docs
  2. Reference
  3. REST API Docs
  4. AI Agents

AI Agents

    Claim

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

    Previews the agent claim (dryRun=true) or starts its commit. The response shape is identical in both cases. Commit transfers the agent’s stacks to the destination organization, soft-deletes the agent’s organization, and soft-deletes the agent’s access token. If there are unresolved conflicts or failures, it returns them and does not perform any state mutations.

    Request Parameters

    • orgName string path required
      The organization name
    • dryRun boolean query optional
      If set, perform a dry run without committing changes

    Request Body

    Schema: AgentClaimRequest
    • claimToken string required
      The opaque single-use claim token embedded in the claim URL the agent surfaces to its human. Returned by /api/agents/signup as part of the claim URL.
    • conflictsResolution array[TransferEntity] optional
      Renaming instructions for the entities flagged in the response’s conflicts list. Failures cannot be resolved this way.

    Responses

    200 OK (preview, successful commit, or commit blocked); inspect conflicts and failures to distinguish
    Schema: AgentClaimResponse
    • agent AgentAccountSummary required
      Identity and metadata for the agent account being claimed.
    • ↳ login string required
      The agent user’s Pulumi login (e.g. “agent-abc123”). This is what pulumi whoami returns while the agent’s access token is in use.
    • ↳ orgName string required
      Slug of the agent’s individual organization. This appears in the // identity of any stack the agent created.
    • ↳ createdAt string required
      When the agent account was created (i.e. when /api/agents/signup ran).
    • entities array[TransferEntity] required
      Inventory of Pulumi entities owned by the agent in the source organization. If the claim completes, these transfer to the destination organization. A non-empty conflicts or failures list prevents the claim from completing.
    • ↳ kind string required
    • conflicts array[TransferEntity] required
      Name collisions with the destination organization that the client can resolve by supplying conflictsResolution in a follow-up request. Both preview and a blocked commit return 200 with this body populated; the commit does not mutate state when any conflict is present.
    • ↳ kind string required
    • failures array[TransferEntityFailure] required
      Entities the service cannot transfer (e.g. Insights accounts at launch, which have no transfer primitive yet). Unlike conflicts, failures are not user-resolvable.
    • ↳ entity TransferEntity required
      The reference of the entity that cannot be transferred.
    • ↳ failureDetails string required
      Service-side reason the entity cannot be transferred.
    • claimExpiresAt string required
      When the claim window closes. After this time the claim token expires and the claim cannot complete.
    • transferToken string optional
      On successful start of a claim, the token needed to check for progress.
    Errors: 400 Missing claimToken or unsupported conflictsResolution 403 Caller has no role in the destination organization, or is the agent itself 404 Claim token is unknown, expired, or already canceled

    Claim Status

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

    Fetches details from recent agent claims.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    200 OK
    Schema: AgentClaimsStatus
    Errors: 403 Caller has no role in the destination organization, or is the agent itself

    Signup Challenge

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/agents/signup

    Issues a proof-of-work challenge for the agent signup flow. The caller computes the proof over the returned challengeData and submits the result to POST /api/agents/signup along with the returned challengeID. The challenge expires after a short window if not consumed.

    Responses

    200 OK
    Schema: AgentSignupChallenge
    • challengeID string required
      An ID identifying this challenge. Pass back to POST /api/agents/signup as challengeID.
    • challengeData string required
      Input data for the proof-of-work computation. Compute the proof over this and submit the result to POST /api/agents/signup as challengeResult.

    Signup

    ▼
    Preview. This endpoint is in preview and may change without notice.
    POST /api/agents/signup

    Creates a new Pulumi Cloud account programmatically, without human intervention, and returns an access token plus a claim URL. The caller must first obtain a challenge from GET /api/agents/signup/challenge and submit the computed proof of work here. Intended for agent contexts: a CLI that detects it is running on behalf of an agent and finds no local credentials issues the challenge call, solves it, then calls this endpoint, writes the returned access token to its credentials file, and surfaces the claim URL to its human so the human can take ownership of the account later. The account is a Pulumi Individual Account in a pre-claim state; operations that require a verified email (such as creating agent tasks) are unavailable until the account is claimed.

    Request Body

    Schema: AgentSignupRequest
    • challengeID string required
      An ID identifying the challenge issued by GET /api/agents/signup/challenge.
    • challengeResult string required
      Output of the proof-of-work computation over the challengeData returned by GET /api/agents/signup/challenge.

    Responses

    200 OK
    Schema: AgentSignupResponse
    • accessToken string required
      The Pulumi access token to use for authenticating future API requests as the new user.
    • accessTokenValidUntil string required
      When the temporary access token expires.
    • claimToken string required
      An opaque single-use token the human submits to claim ownership of the account. The CLI surfaces a claim URL embedding this token to the human; the path is a CLI/UI concern.
    • claimTokenValidUntil string required
      When the claim token expires.
    • userInfo User required
      The newly-created user’s profile information.
    • ↳ id string required
      The unique identifier of the user.
    • ↳ githubLogin string required
      The user’s login name (originally from GitHub).
    • ↳ name string required
      The user’s display name.
    • ↳ email string required
      The user’s email address.
    • ↳ avatarUrl string required
      The URL of the user’s avatar image.
    • ↳ organizations array[OrganizationSummaryWithRole] required
      Organizations is the list of Pulumi organizations the user is a member of.
    • ↳ potentialOrganizations array[OrganizationSummaryWithRole] optional
      PotentialOrganizations is the list of Pulumi organizations the user is a potential member of.
    • ↳ identities array[string] required
      Identities is the array of identities a Pulumi user’s account is tied to.
    • ↳ siteAdmin boolean optional
      SiteAdministrator is whether or not the user is a site administrator.
    • ↳ registryAdmin boolean optional
      RegistryAdmin is whether or not the user is a registry administrator.
    • ↳ tokenInfo TokenInfo optional
      TokenInfo is contains metadata, set only for machine tokens & to be used only in the CLI
    • ↳ hasMFA boolean required
      Whether the user has multi-factor authentication enabled.
    • ↳ isOrgManaged boolean required
      Whether the user’s account is managed by an organization.
    • ↳ isManagedByMultiOrg boolean required
      Whether the user’s account is managed by multiple organizations.
    • ↳ isAgent boolean optional
      Whether the user is a synthetic agent account. Agent accounts cannot be authenticated except via their issued access token until a human claims the account via the claim URL.
    Errors: 400 Missing or invalid challengeID / challengeResult, or proof-of-work verification failed.

    Signup Validate

    ▼
    Preview. This endpoint is in preview and may change without notice.
    GET /api/agents/signup/validate/{claimToken}

    Verifies the claim token is still valid. It returns the details about the agent and the resources it created

    Request Parameters

    • claimToken string path required
      The claim token generated by the Agent Signup

    Responses

    200 OK
    Schema: AgentClaimResponse
    • agent AgentAccountSummary required
      Identity and metadata for the agent account being claimed.
    • ↳ login string required
      The agent user’s Pulumi login (e.g. “agent-abc123”). This is what pulumi whoami returns while the agent’s access token is in use.
    • ↳ orgName string required
      Slug of the agent’s individual organization. This appears in the // identity of any stack the agent created.
    • ↳ createdAt string required
      When the agent account was created (i.e. when /api/agents/signup ran).
    • entities array[TransferEntity] required
      Inventory of Pulumi entities owned by the agent in the source organization. If the claim completes, these transfer to the destination organization. A non-empty conflicts or failures list prevents the claim from completing.
    • ↳ kind string required
    • conflicts array[TransferEntity] required
      Name collisions with the destination organization that the client can resolve by supplying conflictsResolution in a follow-up request. Both preview and a blocked commit return 200 with this body populated; the commit does not mutate state when any conflict is present.
    • ↳ kind string required
    • failures array[TransferEntityFailure] required
      Entities the service cannot transfer (e.g. Insights accounts at launch, which have no transfer primitive yet). Unlike conflicts, failures are not user-resolvable.
    • ↳ entity TransferEntity required
      The reference of the entity that cannot be transferred.
    • ↳ failureDetails string required
      Service-side reason the entity cannot be transferred.
    • claimExpiresAt string required
      When the claim window closes. After this time the claim token expires and the claim cannot complete.
    • transferToken string optional
      On successful start of a claim, the token needed to check for progress.
    Errors: 404 Claim token is unknown, expired, or already canceled