> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/sdk/macros.md).

# 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#L3917)

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#L3955)

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#L3990)

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#L4014)

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#L4035)

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.
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.interactive.ai/sdk/macros.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.