---
title: "Intuned Agent - Start"
method: POST
path: "/{workspaceId}/agent/start"
tags: ["agent"]
---

# Intuned Agent - Start

`POST /{workspaceId}/agent/start`

## Request

- Base URL: `https://app.intuned.io/api/v1/workspace`
- URL: `https://app.intuned.io/api/v1/workspace/{workspaceId}/agent/start`
- Auth: API key in header `x-api-key`

Start an autonomous Intuned Agent session on a project. `project.create` is required: set it to true to create a new project (409 if the name is already taken; you may also pass project.longName/tags/language) or false to run on an existing project (404 if it doesn't exist). Runs asynchronously — poll the status/result endpoints.

## Path parameters

- `workspaceId` string, uuid, required

## Request body

- object
  - `message` string, required: Initial prompt for the Intuned Agent.
  - `model` 'sonnet' | 'opus' | 'haiku': LLM the Intuned Agent runs with: sonnet (default), opus, or haiku. Defaults to sonnet when omitted.
  - `project` union, required
    - object
      - `create` true, required: Create a new project. Fails with 409 if a project with this name already exists. Required to pass longName/tags/language.
      - `name` string, required: Name for the new project. Must not already exist.
      - `longName` string: Human-friendly name / source URL for a newly created project.
      - `tags` string[]: Tags to attach to a newly created project.
      - `language` 'typescript' | 'python': Scaffolding language for a newly created project (defaults to typescript).
    - object
      - `create` false, required: Run on an existing project. Fails with 404 if no project with this name exists.
      - `name` string, required: Existing project name. Must already exist in the workspace.
  - `agentConfig` object, required: Deterministic end-of-session behavior. merge:true merges the branch when the Intuned Agent completes its work; deploy:true deploys after merge. No sign-off gate.
    - `merge` boolean, required
    - `deploy` boolean, required

## Response `200`

Intuned Agent session started.

- object
  - `id` string, uuid, required: The Intuned Agent session id.
  - `status` 'IN_PROGRESS', required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `404`: Not Found
- `409`: Conflict

---

[API](https://skmtc.dev/intunedhq/apis/intuned-client.md) - [All operations](https://skmtc.dev/intunedhq/apis/intuned-client/llms.txt) - [OpenAPI document](https://skmtc.dev/intunedhq/apis/intuned-client/revisions/9f87fec44145?raw)