---
title: "Trigger an LLM-based task for a workspace"
method: POST
path: "/workspaces/{workspace_id}/llm"
tags: ["LLM", "Workspaces"]
---

# Trigger an LLM-based task for a workspace

`POST /workspaces/{workspace_id}/llm`

## Request

- Base URL: `https://app.mammoth.io/api/v2`
- URL: `https://app.mammoth.io/api/v2/workspaces/{workspace_id}/llm`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-KEY` and API key in header `X-API-SECRET` and API key in header `X-WORKSPACE-ID`

Initiates an LLM-powered task. The behavior and execution flow vary depending on the `type` field in the request body.

## Path parameters

- `workspace_id` integer, required: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.

## Request body

- UnifiedLlmTaskSpec: LLM task submission request
  - `type` 'rename_columns' | 'generate_dataset' | 'generate_summary' | 'optimise_pipeline', required: Type of LLM operation to perform
  - `params` union, required: Encapsulated parameters for the selected task
    - RenameColumnsParams
      - `project_id` integer, required: Unique identifier of the project. Must be a positive integer.
      - `object_id` integer, required: Unique identifier of the object (dataview, datasource, etc.). Must be a positive integer.
      - `object_type` 'datasource', required: Type of the object. Only 'datasource' is supported.
      - `transform_mode` 'snake_case' | 'camel_case' | 'instruction_based', required: Mode of renaming: 'snake_case', 'camel_case', or 'instruction_based' (LLM-driven).
      - `instruction` string, nullable: Natural language instruction for renaming columns. Required when transform_mode is 'instruction_based', ignored otherwise.
    - OptimisePipelineParams
      - `object_id` integer, required: Unique identifier of the object (dataview, datasource, folder, etc.). Must be a positive integer.
      - `object_type` 'dataview', required: Type of the object to optimise
    - GenerateSummaryParams
      - `object_id` integer, required: Unique identifier of the object (dataview, datasource, folder, etc.). Must be a positive integer.
      - `object_type` string, required: Type of the object (dataview, datasource, label, project, workspace, etc.)
      - `mode` 'llm' | 'raw': Whether to generate summary using LLM ('llm') or return raw summary ('raw')
    - GenerateDatasetParams
      - `intent` string, required: User prompt describing the dataset to be generated
      - `row_count` integer, nullable: Number of rows to generate (1-500)

## Response `201`

Document created, URL follows

- JobResponse
  - `job` JobSchema, required
    - `id` integer, required
    - `status` 'success' | 'failure' | 'processing' | 'error', required: Job status can be success, failure or processing
    - `response` object, required: Result of async task is stored in response
    - `last_updated_at` string, date-time, required: Job last updated at is the time when Job status was last updated
    - `created_at` string, date-time, required: Create at is time when async task was created
    - `path` string, required: API request path of the Job operation
    - `operation` string, required: Operation is async task name which Job is tracking

## Other responses

- `202`: Successfully Submitted
- `400`: Bad request syntax or unsupported method
- `403`: Request forbidden -- authorization will not help

---

[API](https://skmtc.dev/mammoth/apis/mammoth-analytics.md) · [All operations](https://skmtc.dev/mammoth/apis/mammoth-analytics/llms.txt) · [OpenAPI document](https://skmtc.dev/mammoth/apis/mammoth-analytics/revisions/4b2c943a00dc?raw)