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)

Get a macro prompt by name.

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

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)

Create a macro prompt.

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

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)

Update a macro prompt version.

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

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)

List macro prompts.

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)

Delete a macro prompt.

Automatically prefixes the name with macros/.

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

macro = client.get_macro("thanks")

print(macro.raw_text)

---

Creating macros

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.