Developers

API Reference

The Moxial API lets you create the same self-contained mockup documents the editor produces — programmatically. Pick a template, send your content, and get back a fully-resolved mockup you can open, refine, and export from the app.

• Base URL: https://mxl.on-forge.com/api/v1
• All requests and responses are JSON.
• Authentication: Authorization: Bearer <token> — see below.

Authentication

Every endpoint requires a personal access token. Create one in Settings → API Access — the plain-text token is shown once at creation. Send it on every request:

curl https://mxl.on-forge.com/api/v1/templates \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json"

Tokens act on behalf of your account and workspace: mockups created through the API belong to your team, appear in your library, and can only be read back by your own tokens. Revoking a token in Settings immediately invalidates it.

Errors & rate limits

The API always answers JSON, even without an Accept header. Requests are limited to 60 per minute per token.

GET/api/v1/templates

Lists the available templates. Use it to discover the id to pass as template_id when creating a mockup, and the devices, color schemes, and locales each template supports.

{
  "data": [
    {
      "id": "665f2a1b8c9d4e0012345678",
      "name": "X Single 2025",
      "platform": "x",
      "view": "single",
      "archetype": "post",
      "year": 2025,
      "device_ids": ["iphone15", "iphone15plus", "iphone15pro", "iphone15promax", "iphone16", "iphone16plus", "iphone16pro", "iphone16promax", "iphone17", "iphone17e", "iphone17pro", "iphone17promax", "iphoneair", "desktop"],
      "color_schemes": ["light", "dark"],
      "locales": ["en", "fr"],
      "description": "X (Twitter) single mockup for 2025"
    }
  ]
}

GET/api/v1/templates/{id}

One template, including its field_schema — the machine-readable contract for the content payload. The schema is a list of groups, each with typed fields (field types), and every field carries a one-line description of what it renders. Your content is validated against this exact schema on creation, so you can generate forms or payloads from it instead of hard-coding the field lists below.

{
  "id": "665f2a1b8c9d4e0012345678",
  "name": "X Single 2025",
  "platform": "x",
  "view": "single",
  "archetype": "post",
  "year": 2025,
  "device_ids": ["iphone15", "iphone15plus", "iphone15pro", "iphone15promax", "iphone16", "iphone16plus", "iphone16pro", "iphone16promax", "iphone17", "iphone17e", "iphone17pro", "iphone17promax", "iphoneair", "desktop"],
  "color_schemes": ["light", "dark"],
  "locales": ["en", "fr"],
  "description": "X (Twitter) single mockup for 2025",
  "field_schema": {
    "groups": [
      { "key": "post", "label": "Post", "fields": [
        { "key": "text", "type": "text", "label": "Text", "max": 1000 },
        { "key": "media", "type": "media[]", "label": "Media", "max": 4 }
      ] }
    ]
  }
}

POST/api/v1/mockups

Creates a mockup in one call. Only template_id is required: Moxial resolves the default device, operating system, color scheme, and locale, binds your default profile as the author, and seeds the content with the template defaults. Everything else is an optional override merged on top — omitted content keys keep their seeded values.

Request body

Example — an X post

curl -X POST https://mxl.on-forge.com/api/v1/mockups \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "665f2a1b8c9d4e0012345678",
    "name": "Launch announcement",
    "device_value": "iphone16pro",
    "content": {
      "author": {
        "name": "Ada Lovelace",
        "username": "adalovelace",
        "avatar": "https://example.com/ada.png",
        "verification": "blue"
      },
      "text": "Just shipped our new analytics dashboard 🚀",
      "media": [
        { "type": "image", "url": "https://example.com/dashboard.png", "aspect": "16/9" }
      ],
      "posted_at": "2025-07-17T09:41",
      "likes_count": 1284,
      "reposts_count": 96,
      "comments_count": 47,
      "views_count": 38200
    },
    "presentation": { "color_scheme": "dark" }
  }'

Returns 201 Created with the mockup document.

GET/api/v1/mockups/{id}

Retrieves one of your mockups as the mockup document — the same shape POST /mockups returns. Mockups belonging to another workspace answer 404.

The content payload

content is archetype-shaped:

• post (single views) — the post's fields sit at the content root, next to an author object.
• timeline (feed views) — the content root holds one posts array; each item carries the same per-post fields, including its own author (every post can be a different account).

Every field is optional — anything you omit keeps the template's seeded default. Unknown keys are rejected-by-omission: only fields declared in the template's field_schema survive validation.

X — post fields

Used at the content root of X Single and inside each posts[] item of X Timeline.

X — the author object

Instagram — post fields

Used inside each posts[] item of Instagram Timeline.

Timelines — the posts array

For timeline templates, wrap the per-post objects in content.posts. Sending posts replaces the whole array (it is not merged item-by-item):

{
  "template_id": "<x-timeline-template-id>",
  "content": {
    "posts": [
      {
        "author": { "name": "Acme", "username": "acme", "verification": "org" },
        "text": "We are hiring! Join a team that ships.",
        "likes_count": 210, "reposts_count": 18, "comments_count": 9, "views_count": 12400
      },
      {
        "author": { "name": "Jane Doe", "username": "janedoe", "verification": "blue" },
        "text": "Hot take: dashboards are the new landing pages.",
        "media": [ { "type": "image", "url": "https://example.com/chart.png" } ],
        "likes_count": 3400, "reposts_count": 240, "comments_count": 85, "views_count": 96000
      }
    ]
  }
}

Field types

Every field in a field_schema uses one of these types — the closed registry the validator enforces:

The media object

{ "type": "image", "url": "https://example.com/visual.png", "aspect": "16/9" }

The presentation object

Controls framing and styling around the content. Every key is optional; top-level keys you send replace the resolved defaults wholesale.

The mockup document (response)

Both mockup endpoints return the fully-resolved document — everything the renderer needs, frozen. The viewer and content blocks are snapshots: editing a saved Profile later never rewrites an existing mockup.

{
  "id": "6672be40a1b2c3d4e5f60789",
  "name": "Launch announcement",
  "viewer_profile_id": "665f9f001122334455667788",
  "template": {
    "id": "665f2a1b8c9d4e0012345678",
    "platform": "x",
    "view": "single",
    "archetype": "post",
    "year": 2025,
    "renderer": "platforms-x-2025-single",
    "field_schema": { "groups": [ … ] }
  },
  "device": { "value": "iphone16pro", "family": "ios", "frame": { … } },
  "system": { "slug": "ios-18", "family": "ios", "major": 18, "status_bar": { … } },
  "system_slug": "ios-18",
  "presentation": {
    "color_scheme": "dark",
    "locale": "en",
    "device_settings": { "hour": "9:41", "battery": "100%", "wifi": 3, "cellular": 4 },
    "interface": { "notifications_count": null, "dms_count": null, "show_home_dot": false, "show_profile_dot": false },
    "export": { "frame": true, "device_ui": true, "scale": 3 }
  },
  "viewer": { "profile_id": "665f9f00…", "name": "Ada Lovelace", "username": "adalovelace", "avatar": "…" },
  "content": {
    "author": { "name": "Ada Lovelace", "username": "adalovelace", "verification": "blue" },
    "text": "Just shipped our new analytics dashboard 🚀",
    "media": [ { "type": "image", "url": "https://example.com/dashboard.png", "aspect": "16/9" } ],
    "posted_at": "2025-07-17T09:41",
    "likes_count": 1284, "reposts_count": 96, "comments_count": 47, "views_count": 38200, "saves_count": 58
  }
}

MCP server

Moxial also speaks the Model Context Protocol, so AI clients (Claude, Cursor, and other MCP-compatible agents) can create mockups conversationally. Connect over streamable HTTP with OAuth — add the URL and your client walks you through signing in and approving access. No token to copy:

https://mxl.on-forge.com/mcp

# e.g. Claude Code:
claude mcp add --transport http moxial https://mxl.on-forge.com/mcp

The client registers itself automatically (dynamic client registration) and uses the authorization-code flow with PKCE. Approved applications are listed under Settings → AI clients, where you can revoke access at any time. API tokens are for the REST endpoints above — they do not authenticate MCP.

The server covers the full loop — discover, create, iterate, render:

It also publishes two resources — moxial://guide (workflow guide) and moxial://templates/{id}/fields (the per-template content field reference) — and a compose-mockup prompt that turns a plain-language brief into the full create → refine → export loop.