API Reference

OpenAPI 3.1

MNKI API

Generate architectural renders, manage MNKISpace workspaces, and build MNKIpresent decks programmatically. Authenticate with an API key from a Pro or VIP account.

Base URLhttps://api.mnki.ai/v1

Authentication

Send your key (mnki-sk-…) as a bearer token or x-api-key header:

Authorization: Bearer mnki-sk-live-…
# or
x-api-key: mnki-sk-live-…

Get a key in the MNKI app → Account → API & Integrations. Use a test key first — it runs the full path with a mocked render and charges 0 credits.

The direct REST API uses API keys. The Claude / MCP connector authenticates with OAuth 2.0 instead — see OAuth 2.0 below.

The async (job) model

Generation is asynchronous — create → poll. POST returns202 with a job; poll GET …/{id} untilcompleted or failed. Failed jobs are auto-refunded.

curl -X POST https://api.mnki.ai/v1/renders \
  -H "Authorization: Bearer $MNKI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelTier": "pro",
    "input": { "image_url": "https://…/floorplan.png" },
    "settings": { "inputType": "Floor Plan", "renderStyle": "Scandinavian",
                  "lighting": "Golden Hour", "imageSize": "2K" }
  }'
# → 202 { "id": "render_abc", "status": "queued" }

curl https://api.mnki.ai/v1/renders/render_abc -H "Authorization: Bearer $MNKI_KEY"
# → { "status": "completed", "result": { "images": [{ "url": "…" }] } }

Endpoints

Account
GET/meKey owner: plan, email, limits.
GET/creditsWallet balance.
GET/usageUsage history for this key.
Rendering
GET/options/rendersAllowed styles, input types, sizes, and costs.
POST/rendersCreate a render (async → 202). 6/8 credits.
GET/renders/{id}Render status + result (add ?include=base64).
GET/rendersList recent renders.
POST/renders/{id}/cancelBest-effort cancel a queued render.
POST/renders/inpaintInpaint a region via bounding box. 8 credits.
GET/renders/{id}/downloadDownload render as base64 (local copy only).
Uploads
POST/uploadsUpload an image as base64. Returns URL for render input.
POST/files/uploadsGet a presigned upload URL + browser portal link.
GET/files/uploads/{id}Check if an upload landed (status + rejection reason).
Projects
GET/projectsList Studio projects (for targeting renders).
Spaces
GET/spacesList workspaces.
POST/spacesCreate a workspace.
PATCH/spaces/{id}Update a workspace.
DELETE/spaces/{id}Delete a workspace.
POST/spaces/{id}/membersInvite a member by email + role.
POST/spaces/{id}/projectsLink a project to a workspace.
Presentations
POST/presentationsBuild a deck (async). 20/35/60 credits.
GET/presentations/{id}Status + download URL.
GET/presentationsList presentations.
Scenes (3D Sandbox)
GET/scenes/{id}Get a 3D scene by ID.
POST/scenesCreate a new 3D scene.
PATCH/scenes/{id}Update an existing 3D scene.
Jobs & Webhooks
GET/jobs/{id}Engine-agnostic job lookup.
GET/jobsList jobs across engines.
GET/webhooksList webhooks.
POST/webhooksRegister a signed webhook.
DELETE/webhooks/{id}Delete a webhook.

Full request/response schemas live in the OpenAPI 3.1 spec — import it into Scalar, Postman, or Insomnia for an interactive explorer and client codegen.

Credits

Render 1K / 2K6 credits
Render 4K8 credits
Inpaint (masked)8 credits
Canvas draw0 (free) credits
Canvas draw + render6 (same as render) credits
Presentation quick / standard / premium20 / 35 / 60 credits

VIP plans are billed-as-tracked (effectively unlimited). Costs match in-app pricing.

Rate limits & errors

Reads and writes have separate per-key budgets, so status polling never exhausts your generation allowance. Reads (GET): 120/minute, 1,200/hour. Writes (POST/PATCH/DELETE): 20/minute, 200/hour. OAuth-connector access is limited per user across all sessions. Responses carry X-RateLimit-* headers; 429s include Retry-After.

Errors use a typed envelope, always with X-Request-Id:

{ "error": { "type": "plan_forbidden", "message": "…",
            "code": "403", "request_id": "req_…",
            "doc_url": "…" } }

Types: unauthenticated · plan_forbidden · insufficient_scope · insufficient_credits · spend_cap_exceeded · invalid_request · not_found · rate_limited · model_unavailable.

Webhooks

Register an HTTPS endpoint for render.completed, render.failed,presentation.completed, presentation.failed. Deliveries are HMAC-SHA256 signed (X-MNKI-Signature: sha256=…) with your hook secret.

MCP — use MNKI from Claude

MNKI is also an MCP Connector. Add it to Claude (or any MCP client) and drive your design workflow — workspaces, 3D scenes, vector canvas drawings, and presentation decks — in natural language.

MCP URLhttps://mcp.mnki.ai/mcp

Connect with OAuth. Add the URL in Claude → Settings → Connectors → Add custom connector. Claude opens an MNKI sign-in and consent screen — approve the requested scopes and you're connected. Nothing to copy or paste; Claude never sees your MNKI password or API key. A Pro or VIP plan is required.

Claude can build full 3D environments via the mnki_sandbox_* tools, draw floor-plan and diagram sketches on a vector canvas via mnki_canvas_draw, manage MNKISpace workspaces, and assemble MNKIpresent decks. AI image/render generation is not exposed through the connector — it stays in the MNKI web app and the direct REST API above.

OAuth 2.0 (connector authorization)

The connector authenticates with OAuth 2.0 — authorization code with PKCE. MCP clients discover and run the flow automatically; you don't implement anything. For reference:

Authorization server:  https://api.mnki.ai
Discovery metadata:    GET  /.well-known/oauth-authorization-server
Authorize (browser):   GET  /authorize      → MNKI sign-in + consent
Token:                 POST /token           → authorization_code & refresh_token grants
PKCE:                  S256 (required)
Client registration:   Client ID Metadata Documents (CIMD)

Scopes match what a tool needs — reading your account and projects, managing MNKISpace workspaces, building 3D scenes, and assembling presentation decks (plus offline_access to receive a refresh token). Access tokens are short-lived (~1 hour) and refresh automatically; refresh tokens rotate on use and expire after 30 days. The resource server at https://mcp.mnki.ai/mcp returns 401 with a WWW-Authenticate pointer that starts the flow.

To stop access, disconnect the MNKI connector in your MCP client (e.g. Claude → Settings → Connectors); the tokens then go unused and expire.

MNKI · Terms · Privacy