---
title: "Create an AI Inbox Manager guidance"
method: POST
path: "/api/v2/ai-agents/inbox-manager/{id}/guidances"
tags: ["AIInboxManager"]
---

# Create an AI Inbox Manager guidance

`POST /api/v2/ai-agents/inbox-manager/{id}/guidances`

## Request

- Base URL: `https://api.instantly.ai`
- URL: `https://api.instantly.ai/api/v2/ai-agents/inbox-manager/{id}/guidances`
- Auth: HTTP bearer

Create a guidance for an AI Inbox Manager. The BASICS category is an upsert: it carries tone/length options instead of an instruction, is always active, and an agent has at most one — creating a second one updates the existing guidance in place.


Requires one of the following scopes: `ai_agents:all`, `all:create`, `all:all`

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `label` string, required: Label of the guidance
  - `category` 0 | 1 | 2 | 3 | 4, required: Category of the guidance
  - `instruction` string: Instruction text. Required for every category except BASICS, where it must be empty.
  - `status` 1 | 0: Status of the guidance. Required for every category except BASICS, which is always active.
  - `basic_guidance_options` object: Tone and length options. Required for the BASICS category, rejected for every other category.
    - `tone` 'friendly' | 'neutral' | 'matter_of_fact' | 'professional' | 'humorous', required: Tone of voice for the agent
    - `length` 'concise' | 'standard' | 'thorough', required: Response length preference

## Response `200`

The created (or, for BASICS, updated) guidance

- AIAgentGuidance: A guidance category or input box for an AI agent
  - `id` string, uuid, required: Unique identifier for the AI agent guidance
  - `organization_id` string, uuid, required: Organization ID
  - `agent_id` string, uuid, required: Associated AI Agent ID
  - `label` string, required: Label of the AI agent guidance
  - `instruction` string, required: Instruction text for the AI agent guidance. Should be empty string for BASICS category.
  - `status` 1 | 0, required: Status of the AI agent guidance
  - `category` 0 | 1 | 2 | 3 | 4, required: Category of the AI agent guidance
  - `basic_guidance_options` object: Basic guidance options (tone, length, etc.) - only for BASICS category
    - `tone` 'friendly' | 'neutral' | 'matter_of_fact' | 'professional' | 'humorous', required: Tone of voice for the AI agent
    - `length` 'concise' | 'standard' | 'thorough', required: Response length preference
  - `timestamp_created` string, required: Timestamp when the AI agent guidance was created
  - `timestamp_updated` string, required: Timestamp when the AI agent guidance was updated

## Other responses

- `400`: The request is invalid (e.g. missing required fields, invalid field values, or an invalid state for the operation)
- `401`: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
- `402`: This request cannot be fulfilled because the workspace does not have an active paid plan
- `404`: The requested resource was not found
- `429`: You have exceeded the rate limit. Please check the rate limit docs for more information.

## Changes

- **2026-11-03** `c781051105a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/instantly/apis/api-explorer/changes/api/v2/ai-agents/inbox-manager/:id/guidances/post.md)

---

[API](https://skmtc.dev/instantly/apis/api-explorer.md) - [All operations](https://skmtc.dev/instantly/apis/api-explorer/llms.txt) - [OpenAPI document](https://skmtc.dev/instantly/apis/api-explorer/revisions/3daaa5f6b0be?raw)