coder · DanielleMaywood · Aug 12, 2025 · Aug 11, 2025 · Aug 11, 2025 · Aug 11, 2025
diff --git a/coderd/aitasks.go b/coderd/aitasks.go
@@ -1,13 +1,19 @@
 package coderd
 
 import (
+	"database/sql"
+	"errors"
 	"fmt"
 	"net/http"
 	"strings"
 
 	"github.com/google/uuid"
 
+	"github.com/coder/coder/v2/coderd/audit"
+	"github.com/coder/coder/v2/coderd/database"
 	"github.com/coder/coder/v2/coderd/httpapi"
+	"github.com/coder/coder/v2/coderd/httpmw"
+	"github.com/coder/coder/v2/coderd/rbac"
 	"github.com/coder/coder/v2/codersdk"
 )
 
@@ -61,3 +67,79 @@ func (api *API) aiTasksPrompts(rw http.ResponseWriter, r *http.Request) {
 		Prompts: promptsByBuildID,
 	})
 }
+
+// This endpoint is experimental and not guaranteed to be stable, so we're not
+// generating public-facing documentation for it.
+func (api *API) aiTasksCreate(rw http.ResponseWriter, r *http.Request) {
+	var (
+		ctx     = r.Context()
+		apiKey  = httpmw.APIKey(r)
+		auditor = api.Auditor.Load()
+	)
+
+	var req codersdk.CreateAITasksRequest
+	if !httpapi.Read(ctx, rw, r, &req) {
+		return
+	}
+
+	user, err := api.Database.GetUserByID(ctx, apiKey.UserID)
+	if httpapi.Is404Error(err) {
+		httpapi.ResourceNotFound(rw)
+		return
+	}
+	if err != nil {
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error fetching user.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+
+	hasAITask, err := api.Database.GetTemplateVersionHasAITask(ctx, req.TemplateVersionID)
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) || rbac.IsUnauthorizedError(err) {
+			httpapi.ResourceNotFound(rw)
+			return
+		}
+
+		httpapi.Write(ctx, rw, http.StatusInternalServerError, codersdk.Response{
+			Message: "Internal error fetching whether the template version has an AI task.",
+			Detail:  err.Error(),
+		})
+		return
+	}
+	if !hasAITask {
+		httpapi.Write(ctx, rw, http.StatusBadRequest, codersdk.Response{
+			Message: `Template does not have required parameter "` + codersdk.AITaskPromptParameterName + `"`,
+		})
+		return
+	}
+
+	createReq := codersdk.CreateWorkspaceRequest{
+		Name:                    req.Name,
+		TemplateVersionID:       req.TemplateVersionID,
+		TemplateVersionPresetID: req.TemplateVersionPresetID,
+		RichParameterValues: []codersdk.WorkspaceBuildParameter{
+			{Name: codersdk.AITaskPromptParameterName, Value: req.Prompt},
+		},
+	}
+
+	owner := workspaceOwner{
+		ID:        user.ID,
+		Username:  user.Username,
+		AvatarURL: user.AvatarURL,
+	}
+
+	aReq, commitAudit := audit.InitRequest[database.WorkspaceTable](rw, &audit.RequestParams{
+		Audit:   *auditor,
+		Log:     api.Logger,
+		Request: r,
+		Action:  database.AuditActionCreate,
+		AdditionalFields: audit.AdditionalFields{
+			WorkspaceOwner: owner.Username,
+		},
+	})
+
+	defer commitAudit()
+	createWorkspace(ctx, aReq, apiKey.UserID, api, owner, createReq, rw, r)
+}
diff --git a/coderd/aitasks_test.go b/coderd/aitasks_test.go
@@ -1,9 +1,11 @@
 package coderd_test
 
 import (
+	"net/http"
 	"testing"
 
 	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	"github.com/coder/coder/v2/coderd/coderdtest"
@@ -139,3 +141,125 @@ func TestAITasksPrompts(t *testing.T) {
 		require.Empty(t, prompts.Prompts)
 	})
 }
+
+func TestAITasksCreate(t *testing.T) {
+	t.Parallel()
+
+	t.Run("OK", func(t *testing.T) {
+		t.Parallel()
+
+		var (
+			ctx = testutil.Context(t, testutil.WaitShort)
+
+			taskName   = "task-foo-bar-baz"
+			taskPrompt = "Some task prompt"
+		)
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		user := coderdtest.CreateFirstUser(t, client)
+
+		// Given: A template with an "AI Prompt" parameter
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, &echo.Responses{
+			Parse:          echo.ParseComplete,
+			ProvisionApply: echo.ApplyComplete,
+			ProvisionPlan: []*proto.Response{
+				{Type: &proto.Response_Plan{Plan: &proto.PlanComplete{
+					Parameters: []*proto.RichParameter{{Name: "AI Prompt", Type: "string"}},
+					HasAiTasks: true,
+				}}},
+			},
+		})
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+
+		expClient := codersdk.NewExperimentalClient(client)
+
+		// When: We attempt to create a Task.
+		workspace, err := expClient.AITasksCreate(ctx, codersdk.CreateAITasksRequest{
+			Name:              taskName,
+			TemplateVersionID: template.ActiveVersionID,
+			Prompt:            taskPrompt,
+		})
+		require.NoError(t, err)
+		coderdtest.AwaitWorkspaceBuildJobCompleted(t, client, workspace.LatestBuild.ID)
+
+		// Then: We expect a workspace to have been created.
+		assert.Equal(t, taskName, workspace.Name)
+		assert.Equal(t, template.ID, workspace.TemplateID)
+
+		// And: We expect it to have the "AI Prompt" parameter correctly set.
+		parameters, err := client.WorkspaceBuildParameters(ctx, workspace.LatestBuild.ID)
+		require.NoError(t, err)
+		require.Len(t, parameters, 1)
+		assert.Equal(t, codersdk.AITaskPromptParameterName, parameters[0].Name)
+		assert.Equal(t, taskPrompt, parameters[0].Value)
+	})
+
+	t.Run("FailsOnNonTaskTemplate", func(t *testing.T) {
+		t.Parallel()
+
+		var (
+			ctx = testutil.Context(t, testutil.WaitShort)
+
+			taskName   = "task-foo-bar-baz"
+			taskPrompt = "Some task prompt"
+		)
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		user := coderdtest.CreateFirstUser(t, client)
+
+		// Given: A template without an "AI Prompt" parameter
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, nil)
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		template := coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+
+		expClient := codersdk.NewExperimentalClient(client)
+
+		// When: We attempt to create a Task.
+		_, err := expClient.AITasksCreate(ctx, codersdk.CreateAITasksRequest{
+			Name:              taskName,
+			TemplateVersionID: template.ActiveVersionID,
+			Prompt:            taskPrompt,
+		})
+
+		// Then: We expect it to fail.
+		var sdkErr *codersdk.Error
+		require.Error(t, err)
+		require.ErrorAsf(t, err, &sdkErr, "error should be of type *codersdk.Error")
+		assert.Equal(t, http.StatusBadRequest, sdkErr.StatusCode())
+	})
+
+	t.Run("FailsOnInvalidTemplate", func(t *testing.T) {
+		t.Parallel()
+
+		var (
+			ctx = testutil.Context(t, testutil.WaitShort)
+
+			taskName   = "task-foo-bar-baz"
+			taskPrompt = "Some task prompt"
+		)
+
+		client := coderdtest.New(t, &coderdtest.Options{IncludeProvisionerDaemon: true})
+		user := coderdtest.CreateFirstUser(t, client)
+
+		// Given: A template
+		version := coderdtest.CreateTemplateVersion(t, client, user.OrganizationID, nil)
+		coderdtest.AwaitTemplateVersionJobCompleted(t, client, version.ID)
+		_ = coderdtest.CreateTemplate(t, client, user.OrganizationID, version.ID)
+
+		expClient := codersdk.NewExperimentalClient(client)
+
+		// When: We attempt to create a Task with an invalid template version ID.
+		_, err := expClient.AITasksCreate(ctx, codersdk.CreateAITasksRequest{
+			Name:              taskName,
+			TemplateVersionID: uuid.New(),
+			Prompt:            taskPrompt,
+		})
+
+		// Then: We expect it to fail.
+		var sdkErr *codersdk.Error
+		require.Error(t, err)
+		require.ErrorAsf(t, err, &sdkErr, "error should be of type *codersdk.Error")
+		assert.Equal(t, http.StatusNotFound, sdkErr.StatusCode())
+	})
+}
diff --git a/coderd/coderd.go b/coderd/coderd.go
@@ -994,6 +994,8 @@ func New(options *Options) *API {
 		r.Use(apiKeyMiddleware)
 		r.Route("/aitasks", func(r chi.Router) {
 			r.Get("/prompts", api.aiTasksPrompts)
+
+			r.With(apiRateLimiter).Post("/", api.aiTasksCreate)
 		})
 		r.Route("/mcp", func(r chi.Router) {
 			r.Use(

diff --git a/coderd/database/dbauthz/dbauthz.go b/coderd/database/dbauthz/dbauthz.go
@@ -2874,6 +2874,17 @@ func (q *querier) GetTemplateVersionByTemplateIDAndName(ctx context.Context, arg
 	return tv, nil
 }
 
+func (q *querier) GetTemplateVersionHasAITask(ctx context.Context, id uuid.UUID) (bool, error) {
+	// If we can successfully call `GetTemplateVersionByID`, then
+	// we know the actor has sufficient permissions to know if the
+	// template has an AI task.
+	if _, err := q.GetTemplateVersionByID(ctx, id); err != nil {
+		return false, err
+	}
+
+	return q.db.GetTemplateVersionHasAITask(ctx, id)
+}
+
 func (q *querier) GetTemplateVersionParameters(ctx context.Context, templateVersionID uuid.UUID) ([]database.TemplateVersionParameter, error) {
 	// An actor can read template version parameters if they can read the related template.
 	tv, err := q.db.GetTemplateVersionByID(ctx, templateVersionID)

diff --git a/coderd/database/dbauthz/dbauthz_test.go b/coderd/database/dbauthz/dbauthz_test.go
@@ -1443,6 +1443,20 @@ func (s *MethodTestSuite) TestTemplate() {
 		})
 		check.Args(now.Add(-time.Hour)).Asserts(rbac.ResourceTemplate.All(), policy.ActionRead)
 	}))
+	s.Run("GetTemplateVersionHasAITask", s.Subtest(func(db database.Store, check *expects) {
+		o := dbgen.Organization(s.T(), db, database.Organization{})
+		u := dbgen.User(s.T(), db, database.User{})
+		t := dbgen.Template(s.T(), db, database.Template{
+			OrganizationID: o.ID,
+			CreatedBy:      u.ID,
+		})
+		tv := dbgen.TemplateVersion(s.T(), db, database.TemplateVersion{
+			OrganizationID: o.ID,
+			TemplateID:     uuid.NullUUID{UUID: t.ID, Valid: true},
+			CreatedBy:      u.ID,
+		})
+		check.Args(tv.ID).Asserts(t, policy.ActionRead)
+	}))
 	s.Run("GetTemplatesWithFilter", s.Subtest(func(db database.Store, check *expects) {
 		o := dbgen.Organization(s.T(), db, database.Organization{})
 		u := dbgen.User(s.T(), db, database.User{})

diff --git a/coderd/database/dbmetrics/querymetrics.go b/coderd/database/dbmetrics/querymetrics.go
diff --git a/coderd/database/dbmock/dbmock.go b/coderd/database/dbmock/dbmock.go
diff --git a/coderd/database/querier.go b/coderd/database/querier.go
diff --git a/coderd/database/queries.sql.go b/coderd/database/queries.sql.go
diff --git a/coderd/database/queries/templateversions.sql b/coderd/database/queries/templateversions.sql
@@ -234,3 +234,10 @@ FROM
 WHERE
 	template_versions.id IN (archived_versions.id)
 RETURNING template_versions.id;
+
+-- name: GetTemplateVersionHasAITask :one
+SELECT EXISTS (
+	SELECT 1
+	FROM template_versions
+	WHERE id = $1 AND has_ai_task = TRUE
+);
diff --git a/codersdk/aitasks.go b/codersdk/aitasks.go
@@ -44,3 +44,29 @@ func (c *ExperimentalClient) AITaskPrompts(ctx context.Context, buildIDs []uuid.
 	var prompts AITasksPromptsResponse
 	return prompts, json.NewDecoder(res.Body).Decode(&prompts)
 }
+
+type CreateAITasksRequest struct {
+	Name                    string    `json:"name"`
+	TemplateVersionID       uuid.UUID `json:"template_version_id" format:"uuid"`
+	TemplateVersionPresetID uuid.UUID `json:"template_version_preset_id,omitempty" format:"uuid"`
+	Prompt                  string    `json:"prompt"`
+}
+
+func (c *ExperimentalClient) AITasksCreate(ctx context.Context, request CreateAITasksRequest) (Workspace, error) {
+	res, err := c.Request(ctx, http.MethodPost, "/api/experimental/aitasks", request)
+	if err != nil {
+		return Workspace{}, err
+	}
+	defer res.Body.Close()
+
+	if res.StatusCode != http.StatusCreated {
+		return Workspace{}, ReadBodyAsError(res)
+	}
+
+	var workspace Workspace
+	if err := json.NewDecoder(res.Body).Decode(&workspace); err != nil {
+		return Workspace{}, err
+	}
+
+	return workspace, nil
+}