# Macros

## Get a macro by its ID

> Returns a single macro by ID.\
> \
> \*\*Rate limit:\*\* 60 requests per minute

```json
{"openapi":"3.0.1","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"schemas":{"GetMacroResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Macro"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"},"Macro":{"properties":{"actions":{"description":"The actions that execute when this macro is applied.","items":{"$ref":"#/components/schemas/MacroAction"},"type":"array"},"created_at":{"description":"The time the macro was created.","type":"string"},"has_actions":{"description":"Whether this macro has actions that execute when applied.","type":"boolean"},"id":{"description":"The ID of the macro.","type":"string"},"macro_group_id":{"description":"The ID of the macro group this macro belongs to.","type":"string"},"name":{"description":"The name of the macro.","type":"string"},"text_html":{"description":"The HTML content of the macro.","type":"string"},"text_type":{"description":"The type of text: \"reply\", \"note\", or \"email\".","type":"string"},"updated_at":{"description":"The time the macro was last updated.","type":"string"},"visibility":{"$ref":"#/components/schemas/Visibility"}},"type":"object"},"MacroAction":{"properties":{"type":{"description":"The action type identifier (e.g. \"set_issue_state\", \"set_issue_tags\").","type":"string"}},"type":"object"},"Visibility":{"properties":{"team_ids":{"description":"Team IDs who can access the resource.","items":{"type":"string"},"type":"array"},"type":{"description":"The visibility type.","type":"string"},"user_ids":{"description":"User IDs who can access the resource.","items":{"type":"string"},"type":"array"}},"title":"Visibility represents the visibility settings of a resource in responses.","type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}}},"paths":{"/macros/{id}":{"get":{"description":"Returns a single macro by ID.\n\n**Rate limit:** 60 requests per minute","operationId":"GetMacro","parameters":[{"description":"The ID of the macro.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetMacroResponseBody"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""}},"summary":"Get a macro by its ID","tags":["macros"]}}}}
```

## Get all macros

> Returns all macros for the organization. Optionally filter by macro group ID.\
> \
> \*\*Rate limit:\*\* 60 requests per minute

```json
{"openapi":"3.0.1","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"schemas":{"GetMacrosResponseBody":{"properties":{"data":{"description":"The data payload of the response.","items":{"$ref":"#/components/schemas/Macro"},"type":"array"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"},"Macro":{"properties":{"actions":{"description":"The actions that execute when this macro is applied.","items":{"$ref":"#/components/schemas/MacroAction"},"type":"array"},"created_at":{"description":"The time the macro was created.","type":"string"},"has_actions":{"description":"Whether this macro has actions that execute when applied.","type":"boolean"},"id":{"description":"The ID of the macro.","type":"string"},"macro_group_id":{"description":"The ID of the macro group this macro belongs to.","type":"string"},"name":{"description":"The name of the macro.","type":"string"},"text_html":{"description":"The HTML content of the macro.","type":"string"},"text_type":{"description":"The type of text: \"reply\", \"note\", or \"email\".","type":"string"},"updated_at":{"description":"The time the macro was last updated.","type":"string"},"visibility":{"$ref":"#/components/schemas/Visibility"}},"type":"object"},"MacroAction":{"properties":{"type":{"description":"The action type identifier (e.g. \"set_issue_state\", \"set_issue_tags\").","type":"string"}},"type":"object"},"Visibility":{"properties":{"team_ids":{"description":"Team IDs who can access the resource.","items":{"type":"string"},"type":"array"},"type":{"description":"The visibility type.","type":"string"},"user_ids":{"description":"User IDs who can access the resource.","items":{"type":"string"},"type":"array"}},"title":"Visibility represents the visibility settings of a resource in responses.","type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}}},"paths":{"/macros":{"get":{"description":"Returns all macros for the organization. Optionally filter by macro group ID.\n\n**Rate limit:** 60 requests per minute","operationId":"GetMacros","parameters":[{"description":"Filter macros by macro group ID.","in":"query","name":"macro_group_id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetMacrosResponseBody"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""}},"summary":"Get all macros","tags":["macros"]}}}}
```

## Get all macro groups

> Returns all macro groups for the organization.\
> \
> \*\*Rate limit:\*\* 60 requests per minute

```json
{"openapi":"3.0.1","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"schemas":{"GetMacroGroupsResponseBody":{"properties":{"data":{"description":"The data payload of the response.","items":{"$ref":"#/components/schemas/MacroGroup"},"type":"array"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"},"MacroGroup":{"properties":{"created_at":{"description":"The time the macro group was created.","type":"string"},"id":{"description":"The ID of the macro group.","type":"string"},"title":{"description":"The title of the macro group.","type":"string"},"updated_at":{"description":"The time the macro group was last updated.","type":"string"}},"type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}}},"paths":{"/macro-groups":{"get":{"description":"Returns all macro groups for the organization.\n\n**Rate limit:** 60 requests per minute","operationId":"GetMacroGroups","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetMacroGroupsResponseBody"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""}},"summary":"Get all macro groups","tags":["macros"]}}}}
```

## Update a macro

> Updates an existing macro by ID. All fields are optional; only provided fields will be updated.\
> \
> \*\*Rate limit:\*\* 60 requests per minute

```json
{"openapi":"3.0.1","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"schemas":{"UpdateMacroRequestBody":{"properties":{"conditions":{"$ref":"#/components/schemas/Filter"},"macro_group_id":{"description":"The ID of the macro group this macro belongs to.","type":"string"},"name":{"description":"The name of the macro.","type":"string"},"text_html":{"description":"The HTML content of the macro.","type":"string"},"text_type":{"description":"The type of text: \"reply\", \"note\", or \"email\".","type":"string"},"visibility":{"$ref":"#/components/schemas/VisibilityInput"}},"type":"object"},"Filter":{"properties":{"field":{"description":"The field for this filter.  For allowed fields, see the documentation for\n\nthe specific endpoint you are using.\n\nFor non-compound filters (any operators other than \"and\" or \"or\"),\n\nField must be set, along with either Value or Values, depending on the operator.","type":"string"},"operator":{"description":"The operator for this filter.\n\n`equals`: Matches objects that are exactly equal to the value in the field.\n\n`not_equals`: Matches objects that are not exactly equal to the value in the field.\n\n`contains`: For a multi-valued field, such as tags, this operator will match  objects that contain any of the values in the field.\n\n`does_not_contain`: For a multi-valued field, such as tags, this operator will match  objects that do not contain any of the values in the field.\n\n`in`: Matches objects if the field is one of several possible values,  as specified in the values array.\n\n`not_in`: Matches objects if the field is none of several possible values,  as specified in the values array.\n\n`and`: Matches objects only if all subfilters match.\n\n`or`: Matches objects if any subfilter matches.\n\n`time_is_after`: Matches objects if the field is after the given time.\n\n`time_is_before`: Matches objects if the field is before the given time.\n\n`time_range`: Matches objects if the field is between the given times.\n\n`string_contains`: Matches objects if the field contains the given string.\n\n`string_does_not_contain`: Matches objects if the field does not contain the given string.\n\n`is_set`: Matches objects if the field is set.\n\n`is_unset`: Matches objects if the field is unset.\n\n`greater_than`: Matches objects if the numeric field is greater than the given value.\n\n`less_than`: Matches objects if the numeric field is less than the given value.\n\n`greater_than_or_equals`: Matches objects if the numeric field is greater than or equal to the given value.\n\n`less_than_or_equals`: Matches objects if the numeric field is less than or equal to the given value.","enum":["equals","not_equals","contains","does_not_contain","in","not_in","and","or","time_is_after","time_is_before","time_range","string_contains","string_does_not_contain","is_set","is_unset","greater_than","less_than","greater_than_or_equals","less_than_or_equals"],"type":"string"},"subfilters":{"description":"Sub-filters for this filter.  Valid only when operator is \"and\" or \"or\".\n\nThe maximum allowed depth for a tree of filters is 3.","items":{"$ref":"#/components/schemas/Filter"},"type":"array"},"value":{"description":"The value for this filter. Only used for single-valued operators\n\n(\"equals\", \"not_equals\", \"contains\", \"does_not_contain\")","type":"string"},"values":{"description":"The values for this filter. Only used for multi-valued operators (\"in\", \"not_in\").","items":{"type":"string"},"type":"array"}},"required":["field","operator"],"type":"object"},"VisibilityInput":{"properties":{"team_ids":{"description":"Team IDs who can access the resource. Required when type is \"team\" or \"users_and_teams\".","items":{"type":"string"},"type":"array"},"type":{"description":"The visibility type: \"org\" (entire organization), \"user\" (specific users),\n\n\"team\" (specific teams), or \"users_and_teams\" (specific users and teams).\n\n`org`: Visible to the entire organization.\n\n`user`: Visible to specific users only.\n\n`team`: Visible to specific teams only.\n\n`users_and_teams`: Visible to specific users and teams.","enum":["org","user","team","users_and_teams"],"type":"string"},"user_ids":{"description":"User IDs who can access the resource. Required when type is \"user\" or \"users_and_teams\".","items":{"type":"string"},"type":"array"}},"required":["type"],"title":"VisibilityInput represents visibility settings for a resource.","type":"object"},"UpdateMacroResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Macro"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"},"Macro":{"properties":{"actions":{"description":"The actions that execute when this macro is applied.","items":{"$ref":"#/components/schemas/MacroAction"},"type":"array"},"created_at":{"description":"The time the macro was created.","type":"string"},"has_actions":{"description":"Whether this macro has actions that execute when applied.","type":"boolean"},"id":{"description":"The ID of the macro.","type":"string"},"macro_group_id":{"description":"The ID of the macro group this macro belongs to.","type":"string"},"name":{"description":"The name of the macro.","type":"string"},"text_html":{"description":"The HTML content of the macro.","type":"string"},"text_type":{"description":"The type of text: \"reply\", \"note\", or \"email\".","type":"string"},"updated_at":{"description":"The time the macro was last updated.","type":"string"},"visibility":{"$ref":"#/components/schemas/Visibility"}},"type":"object"},"MacroAction":{"properties":{"type":{"description":"The action type identifier (e.g. \"set_issue_state\", \"set_issue_tags\").","type":"string"}},"type":"object"},"Visibility":{"properties":{"team_ids":{"description":"Team IDs who can access the resource.","items":{"type":"string"},"type":"array"},"type":{"description":"The visibility type.","type":"string"},"user_ids":{"description":"User IDs who can access the resource.","items":{"type":"string"},"type":"array"}},"title":"Visibility represents the visibility settings of a resource in responses.","type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}}},"paths":{"/macros/{id}":{"patch":{"description":"Updates an existing macro by ID. All fields are optional; only provided fields will be updated.\n\n**Rate limit:** 60 requests per minute","operationId":"UpdateMacro","parameters":[{"description":"The ID of the macro to update.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMacroRequestBody"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMacroResponseBody"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""}},"summary":"Update a macro","tags":["macros"]}}}}
```

## Create a new macro

> Creates a new macro within the specified macro group.\
> \
> \*\*Rate limit:\*\* 60 requests per minute

```json
{"openapi":"3.0.1","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer <token>","scheme":"bearer","type":"http"}},"schemas":{"CreateMacroRequestBody":{"properties":{"conditions":{"$ref":"#/components/schemas/Filter"},"macro_group_id":{"description":"The ID of the macro group this macro belongs to.","type":"string"},"name":{"description":"The name of the macro.","type":"string"},"text_html":{"description":"The HTML content of the macro.","type":"string"},"text_type":{"description":"The type of text: \"reply\", \"note\", or \"email\". Defaults to \"reply\".","type":"string"},"visibility":{"$ref":"#/components/schemas/VisibilityInput"}},"required":["macro_group_id","name","text_html"],"type":"object"},"Filter":{"properties":{"field":{"description":"The field for this filter.  For allowed fields, see the documentation for\n\nthe specific endpoint you are using.\n\nFor non-compound filters (any operators other than \"and\" or \"or\"),\n\nField must be set, along with either Value or Values, depending on the operator.","type":"string"},"operator":{"description":"The operator for this filter.\n\n`equals`: Matches objects that are exactly equal to the value in the field.\n\n`not_equals`: Matches objects that are not exactly equal to the value in the field.\n\n`contains`: For a multi-valued field, such as tags, this operator will match  objects that contain any of the values in the field.\n\n`does_not_contain`: For a multi-valued field, such as tags, this operator will match  objects that do not contain any of the values in the field.\n\n`in`: Matches objects if the field is one of several possible values,  as specified in the values array.\n\n`not_in`: Matches objects if the field is none of several possible values,  as specified in the values array.\n\n`and`: Matches objects only if all subfilters match.\n\n`or`: Matches objects if any subfilter matches.\n\n`time_is_after`: Matches objects if the field is after the given time.\n\n`time_is_before`: Matches objects if the field is before the given time.\n\n`time_range`: Matches objects if the field is between the given times.\n\n`string_contains`: Matches objects if the field contains the given string.\n\n`string_does_not_contain`: Matches objects if the field does not contain the given string.\n\n`is_set`: Matches objects if the field is set.\n\n`is_unset`: Matches objects if the field is unset.\n\n`greater_than`: Matches objects if the numeric field is greater than the given value.\n\n`less_than`: Matches objects if the numeric field is less than the given value.\n\n`greater_than_or_equals`: Matches objects if the numeric field is greater than or equal to the given value.\n\n`less_than_or_equals`: Matches objects if the numeric field is less than or equal to the given value.","enum":["equals","not_equals","contains","does_not_contain","in","not_in","and","or","time_is_after","time_is_before","time_range","string_contains","string_does_not_contain","is_set","is_unset","greater_than","less_than","greater_than_or_equals","less_than_or_equals"],"type":"string"},"subfilters":{"description":"Sub-filters for this filter.  Valid only when operator is \"and\" or \"or\".\n\nThe maximum allowed depth for a tree of filters is 3.","items":{"$ref":"#/components/schemas/Filter"},"type":"array"},"value":{"description":"The value for this filter. Only used for single-valued operators\n\n(\"equals\", \"not_equals\", \"contains\", \"does_not_contain\")","type":"string"},"values":{"description":"The values for this filter. Only used for multi-valued operators (\"in\", \"not_in\").","items":{"type":"string"},"type":"array"}},"required":["field","operator"],"type":"object"},"VisibilityInput":{"properties":{"team_ids":{"description":"Team IDs who can access the resource. Required when type is \"team\" or \"users_and_teams\".","items":{"type":"string"},"type":"array"},"type":{"description":"The visibility type: \"org\" (entire organization), \"user\" (specific users),\n\n\"team\" (specific teams), or \"users_and_teams\" (specific users and teams).\n\n`org`: Visible to the entire organization.\n\n`user`: Visible to specific users only.\n\n`team`: Visible to specific teams only.\n\n`users_and_teams`: Visible to specific users and teams.","enum":["org","user","team","users_and_teams"],"type":"string"},"user_ids":{"description":"User IDs who can access the resource. Required when type is \"user\" or \"users_and_teams\".","items":{"type":"string"},"type":"array"}},"required":["type"],"title":"VisibilityInput represents visibility settings for a resource.","type":"object"},"CreateMacroResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/Macro"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"},"Macro":{"properties":{"actions":{"description":"The actions that execute when this macro is applied.","items":{"$ref":"#/components/schemas/MacroAction"},"type":"array"},"created_at":{"description":"The time the macro was created.","type":"string"},"has_actions":{"description":"Whether this macro has actions that execute when applied.","type":"boolean"},"id":{"description":"The ID of the macro.","type":"string"},"macro_group_id":{"description":"The ID of the macro group this macro belongs to.","type":"string"},"name":{"description":"The name of the macro.","type":"string"},"text_html":{"description":"The HTML content of the macro.","type":"string"},"text_type":{"description":"The type of text: \"reply\", \"note\", or \"email\".","type":"string"},"updated_at":{"description":"The time the macro was last updated.","type":"string"},"visibility":{"$ref":"#/components/schemas/Visibility"}},"type":"object"},"MacroAction":{"properties":{"type":{"description":"The action type identifier (e.g. \"set_issue_state\", \"set_issue_tags\").","type":"string"}},"type":"object"},"Visibility":{"properties":{"team_ids":{"description":"Team IDs who can access the resource.","items":{"type":"string"},"type":"array"},"type":{"description":"The visibility type.","type":"string"},"user_ids":{"description":"User IDs who can access the resource.","items":{"type":"string"},"type":"array"}},"title":"Visibility represents the visibility settings of a resource in responses.","type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}}},"paths":{"/macros":{"post":{"description":"Creates a new macro within the specified macro group.\n\n**Rate limit:** 60 requests per minute","operationId":"CreateMacro","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMacroRequestBody"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMacroResponseBody"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""}},"summary":"Create a new macro","tags":["macros"]}}}}
```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.usepylon.com/pylon-docs/developer/api/api-reference/macros.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.