# Macros

## Overview

Macros are plain-text prompt templates (e.g. canned responses). Content is stored as-is with no schema validation. Access the text via `prompt.raw_text`.

***

## Convenience methods

These methods automatically apply the folder prefix and `type="macro"`, so you don't have to.

## `get_macro` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3912)

Get a macro prompt by name.

Automatically prefixes the name with `macros/` and sets `type="macro"`.

```python
get_macro(
    name: str,
    *,
    version: int | None = None,
    label: str | None = None,
    cache_ttl_seconds: int | None = None,
    fallback: str | None = None,
    max_retries: int | None = None,
    fetch_timeout_seconds: int | None = None,
) -> MacroPromptClient
```

**Parameters**

* `name` — Macro name (without the `macros/` prefix).
* `version` — Optional version number.
* `label` — Optional label filter.
* `cache_ttl_seconds` — Cache TTL override.
* `fallback` — Fallback YAML/JSON content string.
* `max_retries` — Maximum number of retries.
* `fetch_timeout_seconds` — Fetch timeout override.

**Returns**

MacroPromptClient

***

## `create_macro` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3950)

Create a macro prompt.

Automatically prefixes the name with `macros/` and sets `type="macro"`.

```python
create_macro(
    *,
    name: str,
    prompt: str,
    labels: List[str] | None = None,
    tags: List[str] | None = None,
    config: Any | None = None,
    commit_message: str | None = None,
) -> MacroPromptClient
```

**Parameters**

* `name` — Macro name (without the `macros/` prefix).
* `prompt` — YAML or JSON content string.
* `labels` — Labels to assign.
* `tags` — Tags to assign.
* `config` — Additional config dict.
* `commit_message` — Optional commit message.

**Returns**

MacroPromptClient

***

## `update_macro` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L3985)

Update a macro prompt version.

Automatically sets `type="macro"` and routes through the type-specific endpoint.

```python
update_macro(
    *,
    name: str,
    version: int,
    new_labels: List[str] | None = None,
) -> Any
```

**Parameters**

* `name` — Macro name (without the `macros/` prefix).
* `version` — The version number of the prompt to update.
* `new_labels` — New labels to assign to the prompt version.

**Returns**

The updated prompt from the InteractiveAI API.

***

## `list_macros` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L4009)

List macro prompts.

```python
list_macros(
    *,
    label: str | None = None,
    tag: str | None = None,
    page: int | None = None,
    limit: int | None = None,
) -> PromptMetaListResponse
```

**Parameters**

* `label` — Optional label filter.
* `tag` — Optional tag filter.
* `page` — Page number.
* `limit` — Items per page.

**Returns**

PromptMetaListResponse

***

## `delete_macro` [(source)](https://github.com/interactive-ai/interactiveai-python-sdk/blob/main/interactiveai/_client/client.py#L4030)

Delete a macro prompt.

Automatically prefixes the name with `macros/`.

```python
delete_macro(
    name: str,
    *,
    label: str | None = None,
    version: int | None = None,
) -> None
```

**Parameters**

* `name` — Macro name (without the `macros/` prefix).
* `label` — If set, deletes versions carrying this label.
* `version` — If set, deletes only this specific version.

***

## Fetching macros

```python
macro = client.get_macro("thanks")

print(macro.raw_text)
```

***

## Creating macros

```python
content = "Thank you for contacting us. Your request has been forwarded."

macro = client.create_macro(
    name="thanks",
    prompt=content,
    labels=["production"],
)
```

***

## `MacroPromptClient`

Returned by `get_macro()` and `create_macro()`.

**Attributes**

* `name` — Prompt name.
* `version` — Prompt version number.
* `labels` — List of labels (e.g. `["production"]`).
* `tags` — List of tags.
* `config` — Arbitrary config dict stored with the prompt.
* `is_fallback` — `True` if this was returned from a fallback value.
* `raw_content` — The original unparsed text content.
* `raw_text` — `str` (property).

**Methods**

* `compile()` — Returns the parsed `MacrosContent` dataclass. Template variable substitution does not apply to structured prompts.
* `variables` — Always returns an empty list.

***

## Content format

Macros can be authored in YAML or JSON. YAML is recommended for readability.

```
Thank you for contacting us. Your request has been forwarded.
```