# AI Mindmap LLM Integration Guide

Last updated: 2026-04-22

## Purpose

This guide is for LLM agents and integration services that create temporary AI Mindmap app links for users.

## Canonical references

- Human API docs: `/docs/import-api`
- OpenAPI schema: `/docs/import-api.openapi.json`
- Discovery file: `/llms.txt`

## Core flow

1. Build a compatible import payload.
2. Call `POST /api/imports`.
3. Receive `{ success, id, openUrl, title, expiresAt }`.
4. Open the returned `openUrl` for the user.
5. User opens the map in editor; map is then saved locally in that browser.

## Request format (recommended envelope)

```json
{
  "title": "AI Product Strategy",
  "source": "agent",
  "data": {
    "topic": "AI Product Strategy",
    "children": [
      { "topic": "User Value", "children": [{ "topic": "Speed" }, { "topic": "Clarity" }] },
      { "topic": "Business Model", "children": [{ "topic": "Pricing tiers" }, { "topic": "Expansion path" }] }
    ]
  }
}
```

## Accepted payload families

- Native node array (`[{ id, text, parentId, x, y, type, ... }]`)
- Tree payload (`topic/title/name/text` + `children/subtopics/items/nodes`)
- Wrapper payloads where the real payload is nested under keys such as `data`, `result`, `response`, `output`, `content`, `mindmap`, `map`, `tree`, or `root`

## Response contract

```json
{
  "success": true,
  "id": "abc123xy",
  "openUrl": "/?import=payload&id=abc123xy",
  "title": "AI Product Strategy",
  "expiresAt": "2026-04-17T12:00:00.000Z"
}
```

## Behavior and retention

- Temporary import links expire after 7 days by default.
- A link can expire even if a user still has a local copy.
- Imported maps are private by default.
- A map becomes public only if the user explicitly shares it to the Library.

## Error handling

- `400`: invalid or unsupported request payload.
- `404`: import payload not found or expired (for GET by id).
- `500`: unexpected server error.

## Integration guardrails

- Do not claim imports are public by default.
- Do not assume links are permanent.
- Prefer passing payload inside `data` when also sending metadata (`title`, `source`, `expiresInSeconds`).