---
title: "Create a new agent instruction"
method: POST
path: "/agentInstruction"
tags: ["AgentInstruction"]
---

# Create a new agent instruction

`POST /agentInstruction`

Creates a new agent instruction for a workspace

## Request body

- CreateAgentInstructionRequest — Request body for creating a new agent instruction
  - `workspace_id` string, required — The workspace to create the instruction in
  - `name` string, required — A short name or title for the instruction
  - `instruction_text` string, required — The instruction itself (plain text)
  - `disabled` boolean — Whether the instruction is disabled
  - `capabilities` AgentInstructionCapability[] — Capabilities this instruction applies to
  - `test_types` TestTypeEnum[] — Test types this instruction applies to
  - `environment_ids` string[] — Environment IDs this instruction applies to
  - `application_ids` string[] — Application IDs this instruction applies to

## Response `201`

The created agent instruction

- AgentInstruction — A user-defined instruction that tailors agent behavior for a workspace
  - `instruction_id` string — Unique identifier for the instruction
  - `workspace_id` string — The workspace this instruction belongs to
  - `name` string — A short name or title for the instruction
  - `instruction_text` string — The instruction itself (plain text)
  - `disabled` boolean — Whether the instruction is disabled. Disabled instructions are not injected into agent prompts.
  - `capabilities` AgentInstructionCapability[] — Capabilities this instruction applies to
  - `test_types` TestTypeEnum[] — Test types this instruction applies to
  - `environment_ids` string[] — Environment IDs this instruction applies to
  - `application_ids` string[] — Application IDs this instruction applies to
  - `created_by_id` string — The user who created this instruction
  - `created_time` integer — Creation timestamp in epoch milliseconds
  - `last_updated_by_id` string — The user who last updated this instruction
  - `last_updated_time` integer — Last update timestamp in epoch milliseconds

## Other responses

- `400` — Invalid or missing parameter
- `401` — User not authenticated
- `403` — User not authorized
- `default` — Unknown error

---

[API](https://skmtc.net/mabl/apis/mabl-api.md) · [All operations](https://skmtc.net/mabl/apis/mabl-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mabl/mabl-api/revisions/d0fc0114da66/schema)