> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pixy.art/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Every tool the Pixy MCP server exposes.

Each tool is the REST endpoint of the same name, called in-process. It gets the endpoint's validation, its plan gate, its credit accounting and its line in your request log — so an agent and your backend work against one contract, and neither can drift from the other.

## Reading

<AccordionGroup>
  <Accordion title="get_account" icon="user">
    The organization the key belongs to, its plan, and credits used and remaining in the current billing period.

    No arguments. Worth calling before a long batch of renders.
  </Accordion>

  <Accordion title="list_templates" icon="layout-template">
    Search the public template library. Returns each template's id, size, orientation, fonts and export formats.

    | Argument | Type | |
    | - | - | - |
    | `search` | string | Free-text over names and contents |
    | `category` | enum | `social-media`, `blogs`, `ads`, `announcements`, `certificates`, `tickets`, `invitations`, `menus` |
    | `promoted` | boolean | Only hand-picked templates |
    | `orderBy` | `latest` \| `oldest` | Newest first by default |
    | `includePageThumbnails` | boolean | A rendered image per page, for multi-page templates |
    | `page`, `perPage` | integer | Zero-based; up to 100 per page |
  </Accordion>

  <Accordion title="get_template" icon="file-search">
    One template in full, including the named elements it exposes.

    | Argument | Type | |
    | - | - | - |
    | `template_id` | string | **Required.** From `list_templates` |

    This is how an agent discovers element ids without opening the editor.
  </Accordion>

  <Accordion title="list_designs" icon="folder">
    Your organization's own saved designs, newest first.

    | Argument | Type | |
    | - | - | - |
    | `search` | string | Names and text contents |
    | `userId` | string | Only designs created through the Embed editor with this id |
    | `orderBy` | `latest` \| `oldest` | Most recently updated first by default |
    | `page`, `perPage` | integer | Zero-based; up to 100 per page |
  </Accordion>

  <Accordion title="list_brand_kits" icon="palette">
    Your brand kits — logos, colors and fonts.

    | Argument | Type | |
    | - | - | - |
    | `search` | string | By name |
    | `userId` | string | Only kits created through the Embed editor with this id |
    | `orderBy` | `latest` \| `oldest` | Most recently updated first by default |
    | `page`, `perPage` | integer | Zero-based; up to 100 per page |

    Values come back ready to use: every entry in `colors` is a hex value `fill` takes, every entry in `images` is a URL `src` takes.
  </Accordion>
</AccordionGroup>

## Writing

<AccordionGroup>
  <Accordion title="duplicate_design" icon="copy">
    Copy a template or design into your organization as a new editable design, and return the new id.

    | Argument | Type | |
    | - | - | - |
    | `design_id` | string | **Required.** Template or design to copy |
    | `name` | string | Defaults to the source name |

    Only needed when the layout should be kept and reused. Rendering a template does not change it, so a one-off render does not need this first.
  </Accordion>

  <Accordion title="generate_image" icon="image">
    Apply modifications to a design and render it. Returns the finished file URLs.

    | Argument | Type | |
    | - | - | - |
    | `design_id` | string | **Required.** Design or template to render |
    | `modifications` | array | Element changes. Omit to render as-is |
    | `format` | `png` \| `jpeg` \| `pdf` | Defaults to `jpeg` |

    **Spends credits** — one per image page, one per PDF.
  </Accordion>

  <Accordion title="generate_ai_image" icon="wand-sparkles">
    Render a design after generating its image element from a text prompt.

    | Argument | Type | |
    | - | - | - |
    | `design_id` | string | **Required.** Design or template to render |
    | `prompt` | string | **Required.** What the generated image should show |
    | `modifications` | array | Any other element changes in the same render |
    | `format` | `png` \| `jpeg` \| `pdf` | Defaults to `jpeg` |

    **Spends credits** for both the AI run and the render.
  </Accordion>
</AccordionGroup>

## Modifications

`generate_image` and `generate_ai_image` take an array of modifications. Each one addresses an element by id, and the fields combine — one object can change a headline's text, fill and stroke at once.

| Field | Applies to | |
| - | - | - |
| `id` | any | **Required.** From `get_template` or the editor |
| `text` | text elements | Styling and position survive the change |
| `src` | image elements | Any public URL; scaled to fill the frame and centre-cropped |
| `fill` | text, shapes, SVG | Hex value |
| `stroke` | text, images, shapes | Hex value; visible where stroke width is above zero |

```json theme={null}
[
  { "id": "TITLE_ID", "text": "Autumn drop is live", "fill": "#6c3bf0" },
  { "id": "IMAGE_ID", "src": "https://example.com/cover.jpg" }
]
```

## Errors

The server distinguishes two kinds of failure, and the distinction matters for how an agent recovers.

<AccordionGroup>
  <Accordion title="Protocol errors" icon="circle-x">
    A malformed call — an unknown tool, or arguments that fail validation — comes back as a JSON-RPC error with a reserved code (`-32601`, `-32602`). The call never reached the API. Agents usually stop here, which is correct: the client is wrong.
  </Accordion>

  <Accordion title="Tool errors" icon="triangle-alert">
    Anything the API itself rejects — a design that does not exist, a plan without API access, an exhausted credit allowance — comes back as a **successful** JSON-RPC response whose result is marked `isError`, carrying the API's own message.

    This is deliberate: the model reads the message and can act on it — pick a different design, or tell you the allowance is gone — rather than giving up on a protocol failure.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.