# Imejis API

> Imejis generates images from design templates via a JSON API and an MCP
> server. Agents authenticate with OAuth2 and render images with dynamic,
> per-request data as the authenticated user.

## Docs

- [API documentation](https://www.imejis.io/apis): human-readable API reference
- [Agent auth guide](https://api.imejis.io/auth.md): OAuth2 registration and token flow for agents

## Agent surface

- [MCP server card](https://api.imejis.io/.well-known/mcp/server-card.json): live MCP endpoint at https://api.imejis.io/api/mcp
- [Agent card](https://api.imejis.io/.well-known/agent.json): capabilities and discovery index
- [Agent skills](https://api.imejis.io/.well-known/agent-skills/index.json): how to render images step by step
- [API catalog](https://api.imejis.io/.well-known/api-catalog): RFC 9727 catalog of this API

## Rendering flow (expanded)

1. Authenticate: fetch https://api.imejis.io/.well-known/oauth-protected-resource/api/mcp,
   register via the advertised authorization server (PKCE, no secret needed for
   public clients), and obtain a Bearer token bound to the
   https://api.imejis.io resource.
2. Connect to the MCP server at https://api.imejis.io/api/mcp (Streamable HTTP).
3. Pick a design (list_designs) or instantiate a template
   (list_templates → create_design_from_template).
4. get_design_render_config returns the design's render URL plus the dynamic
   fields (texts, images, colors) overridable per render.
5. Render either with export_design (design as saved) or by POSTing dynamic
   field values to the render URL with a dma-api-key header
   (create_api_key provisions one).
6. Renders consume quota/credits of the authenticated user — check
   get_quota_usage and get_credit_balance (workspace id from list_workspaces).

# Imejis API

Generate images from design templates via the imejis API and MCP server.

## Connect

- MCP endpoint: https://api.imejis.io/api/mcp (Streamable HTTP, MCP 2025-06-18)
- Auth: OAuth2 Bearer token — see https://api.imejis.io/auth.md. Public clients
  self-register with PKCE; discovery starts at
  https://api.imejis.io/.well-known/oauth-protected-resource/api/mcp
- Human docs: https://www.imejis.io/apis

## Generate an image

1. Find a design: `list_designs` (your designs) or `list_templates` +
   `create_design_from_template` (start from a template).
2. Read its render contract: `get_design_render_config` returns the render
   URL and the dynamic fields you can override per render.
3. Render:
   - `export_design` renders the design as saved and returns the image, or
   - provision a render key with `create_api_key` and POST the dynamic-field
     values to the render URL with the `dma-api-key` header for programmatic,
     data-driven renders.
4. Pick an output format: append `?format=png|jpeg|webp|pdf` (default jpeg)
   to the render URL, and `?quality=1-100` for JPEG. `export_design` takes the
   same `format`/`quality` arguments.
5. Need a URL instead of image bytes? Add `?delivery=` to the render URL:
   `?delivery=hosted` for a permanent public URL, or `?delivery=signed` for a
   private expiring URL (`?expiresIn=` minutes). Useful for `<img>` tags and
   chat/webhook image blocks that need a public link. Over MCP, use
   `get_stored_image_url`.
6. One design, many sizes: add a size with `create_design_variation` (it
   reflows the master's layout onto the new canvas), then render it by passing
   that `variation` id to `export_design` / `preview_design` /
   `get_render_url` / `get_stored_image_url`, or by appending
   `?variation=<id>` to the render URL. Any format, PDF included. The sizes
   are listed in `get_design_render_config`.

## Other tools

- Authoring reference: `get_design_guide` (prose guide),
  `list_component_types` (structured component catalog — property specs,
  defaults, ready-to-render sample designs, variants)
- Designs: `list_designs`, `get_design`, `create_design`,
  `create_design_from_template`, `export_design`
- Sizes (multi-dimension): `create_design_variation`,
  `delete_design_variation`
- Templates: `list_templates`, `get_template`
- API keys: `list_api_keys`, `create_api_key`
- Analytics: `get_api_usage`
- Account state (read-only): plan, subscription, credit balance, and quota
  usage — call `list_workspaces` first for a workspace id.

Every call runs as the authenticated user; renders consume the user's quota
and credits, so check `get_quota_usage` / `get_credit_balance` before bulk
rendering.