> ## Documentation Index > Fetch the complete documentation index at: https://docs.sequentum.com/llms.txt > Use this file to discover all available pages before exploring further. # Start an Agent Builder session > **Session Lifecycle** 1. **POST /start** (this endpoint) — create a session from a prompt → returns `sessionId`. 2. **GET /{sessionId}/status** — poll every few seconds until `status` is `"completed"` (the AI finished building the agent successfully), `"ready"` (the AI finished its turn but the agent may not have been saved yet), or `"error"`. On any terminal status the response also contains `agentId` and `agentName`; **stop polling at that point**. Subsequent calls may return the same terminal response or `404` — both mean the build is done. 3. **POST /{sessionId}/stop** *(optional)* — abort the session early if you no longer want the build to continue. Returns `204 No Content`. Has no effect once the session has already reached a terminal state. > **Note:** The session tears down automatically a short time after reaching a terminal > status — no explicit teardown call is required. The agent draft is saved in your > workspace as soon as the AI creates it (before the session ends). The draft persists > whether or not you call `/stop`; use the standard agents API to delete unwanted drafts. If `spaceId` is provided, it must be an existing Space you have write access to, or the call returns `403`. Omit `spaceId` to save the agent to your Personal space. ## OpenAPI ````yaml POST /api/v1/agent-builder/start openapi: 3.0.1 info: title: Sequentum Cloud API description: API endpoints for Sequentum Cloud version: v1 servers: [] security: - ApiKey: [] Bearer: [] paths: /api/v1/agent-builder/start: post: tags: - ApiAgentBuilder summary: Start a new agent building session description: >- **Session Lifecycle** 1. **POST /start** (this endpoint) — create a session from a prompt → returns `sessionId`. 2. **GET /{sessionId}/status** — poll every few seconds until `status` is `"completed"` (the AI finished building the agent successfully), `"ready"` (the AI finished its turn but the agent may not have been saved yet), or `"error"`. On any terminal status the response also contains `agentId` and `agentName`; **stop polling at that point**. Subsequent calls may return the same terminal response or `404` — both mean the build is done. 3. **POST /{sessionId}/stop** *(optional)* — abort the session early if you no longer want the build to continue. Returns `204 No Content`. Has no effect once the session has already reached a terminal state. > **Note:** The session tears down automatically a short time after reaching a terminal > status — no explicit teardown call is required. The agent draft is saved in your > workspace as soon as the AI creates it (before the session ends). The draft persists > whether or not you call `/stop`; use the standard agents API to delete unwanted drafts. If `spaceId` is provided, it must be an existing Space you have write access to, or the call returns `403`. Omit `spaceId` to save the agent to your Personal space. operationId: AgentBuilder_StartSession requestBody: description: The prompt and optional Space to save to content: application/json: schema: $ref: '#/components/schemas/ExternalStartAgentBuildRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ExternalStartAgentBuildResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '403': description: >- Agent Builder is disabled for your organization, or you do not have write access to the requested Space content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableError' x-codeSamples: - lang: curl label: cURL source: |- curl https://dashboard.sequentum.com/api/v1/agent-builder/start \ -H "Authorization: ApiKey $SEQUENTUM_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Build an agent that extracts product names and prices from example.com." }' - lang: node label: Node.js source: >- const res = await fetch("https://dashboard.sequentum.com/api/v1/agent-builder/start", { method: "POST", headers: { "Authorization": `ApiKey ${process.env.SEQUENTUM_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ prompt: "Build an agent that extracts product names and prices from example.com.", // Optional: an existing Space id you have write access to. Omit to save to your // Personal space; an id you cannot write to (or that doesn't exist) returns 403. // spaceId: 42, }), }); const { sessionId } = await res.json(); console.log(`Started session ${sessionId}`); - lang: python label: Python source: |- import os import requests response = requests.post( "https://dashboard.sequentum.com/api/v1/agent-builder/start", headers={ "Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}", "Content-Type": "application/json", }, json={ "prompt": "Build an agent that extracts product names and prices from example.com.", # Optional: an existing Space id you have write access to. Omit to save to your # Personal space; an id you cannot write to (or that doesn't exist) returns 403. # "spaceId": 42, }, ) response.raise_for_status() session_id = response.json()["sessionId"] print(f"Started session {session_id}") components: schemas: ExternalStartAgentBuildRequest: required: - prompt type: object properties: prompt: maxLength: 5000 minLength: 10 type: string description: "Natural language prompt describing the automation to build.\r\nMust be between 10 and 5000 characters (trimmed)." x-minTrimmedLength: 10 spaceId: type: integer description: >- Optional space ID to save the agent to. Uses the default space if omitted. format: int32 nullable: true additionalProperties: false description: Request to start an agent building session via the external API. ExternalStartAgentBuildResponse: required: - sessionId type: object properties: sessionId: minLength: 1 type: string description: Session ID to use for status polling and subsequent calls. additionalProperties: false description: Response when starting an agent build session via the external API. BadRequestError: type: object properties: statusCode: type: integer format: int32 statusDescription: type: string nullable: true message: type: string nullable: true readOnly: true severity: $ref: '#/components/schemas/ErrorSeverity' errorCode: type: string description: "Optional machine-readable error code. When present, clients should switch on this\r\nvalue rather than parsing Sequentum.Enterprise.Core.ControllerError.Message. Omitted from the response when null." nullable: true additionalProperties: false ProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true additionalProperties: {} TooManyRequestsError: type: object properties: statusCode: type: integer format: int32 statusDescription: type: string nullable: true message: type: string nullable: true readOnly: true severity: $ref: '#/components/schemas/ErrorSeverity' errorCode: type: string description: "Optional machine-readable error code. When present, clients should switch on this\r\nvalue rather than parsing Sequentum.Enterprise.Core.ControllerError.Message. Omitted from the response when null." nullable: true additionalProperties: false InternalServerError: type: object properties: statusCode: type: integer format: int32 statusDescription: type: string nullable: true message: type: string nullable: true readOnly: true severity: $ref: '#/components/schemas/ErrorSeverity' errorCode: type: string description: "Optional machine-readable error code. When present, clients should switch on this\r\nvalue rather than parsing Sequentum.Enterprise.Core.ControllerError.Message. Omitted from the response when null." nullable: true additionalProperties: false ServiceUnavailableError: type: object properties: statusCode: type: integer format: int32 statusDescription: type: string nullable: true message: type: string nullable: true readOnly: true severity: $ref: '#/components/schemas/ErrorSeverity' errorCode: type: string description: "Optional machine-readable error code. When present, clients should switch on this\r\nvalue rather than parsing Sequentum.Enterprise.Core.ControllerError.Message. Omitted from the response when null." nullable: true additionalProperties: false ErrorSeverity: enum: - 0 - 1 - 2 - 3 - 4 type: integer description: >- `0` = `Error`; `1` = `Unexpected`; `2` = `Fatal`; `3` = `Warning`; `4` = `Info` format: int32 securitySchemes: ApiKey: type: apiKey description: >- API Key authorization header. Example: "Authorization: ApiKey {your-api-key}" name: Authorization in: header Bearer: type: http description: 'OAuth 2.0 Bearer token. Example: "Authorization: Bearer {access-token}"' scheme: bearer bearerFormat: JWT ````