canonical: https://jentic.com/apis/magicplan.app/magicplan

# Magicplan App magicplan Cloud API

Jentic publishes the only available OpenAPI specification for magicplan Cloud API, keeping it validated and agent-ready. magicplan is a floor-plan and field-data platform aimed at contractors, restoration companies and real estate professionals. The Cloud API exposes 28 endpoints covering workspaces, teams, projects, plans, forms, estimates, and file management - including presigned upload URLs for syncing scanned floor plans and project photos from the field into the cloud workspace.

## For AI agents

Manage magicplan workspaces, projects, plans, forms and estimates through 28 Cloud endpoints aimed at field teams capturing floor plans and site data.

## Scope

Does not handle invoicing, payments, or scheduling outside magicplan - use for floor-plan project, file, form and estimate operations within a magicplan workspace only.

## Capabilities

- Manage workspace settings and invite members via /workspace endpoints
- Create and update teams plus their memberships through /teams and `/teams/{id}/members`
- Run full project lifecycle operations including create, archive and restore via /projects endpoints
- Upload field-captured files using a presigned URL flow via `/projects/{id}/files` endpoints
- List, retrieve and delete plans through /plans and `/workgroups/plans` for legacy access
- Create, update and delete forms via /forms for structured field data capture
- Pull project estimates via `/projects/{id}/estimates` for cost reporting

## Use cases

### Field Team Project Provisioning

Spin up a magicplan project before a technician heads into the field. POST /projects creates the project record, POST `/workspace/members/invite` adds any temporary contractors, and POST `/teams/{id}/members` assigns the technician to the right team. Suitable for dispatch or scheduling tools that need to pre-stage projects so field captures sync straight into the right workspace.

Example prompt: POST /projects with the customer address, then POST `/teams/{id}/members` to assign the on-site technician

### Floor Plan and Photo Upload Pipeline

Sync large floor-plan files and site photos from a mobile capture tool into the magicplan cloud. The agent first calls POST `/projects/{id}/files/temporary-presigned-url` to obtain a temporary upload URL, uploads the asset directly to that URL, then calls POST `/projects/{id}/files` to register the uploaded artefact. GET `/projects/{id}/files` lists the files and DELETE `/projects/{id}/files/{fileId}` removes obsolete uploads.

Example prompt: Request a presigned URL via POST `/projects/{id}/files/temporary-presigned-url`, upload the floor plan, then call POST `/projects/{id}/files` to register it

### Estimate and Plan Reporting

Pull out the financial and structural deliverables once a project finishes. GET `/projects/{id}/estimates` lists every estimate generated from the project's plan, GET `/projects/{id}/estimates/{estimateId}` fetches the detail, and GET `/plans/get/{id}` returns the underlying plan record. Useful for finance teams reconciling invoices against the field-captured data.

Example prompt: Iterate GET `/projects/{id}/estimates`, fetch each estimate via GET `/projects/{id}/estimates/{estimateId}`, and assemble a finance report

### Forms-Based Inspection Capture

Configure structured field data capture by deploying magicplan forms across projects. POST /forms creates a new form template, GET `/plans/forms/{id}` returns the forms attached to a plan, and PUT `/forms/{id}` amends questions on the fly. Suitable for restoration and inspection companies that need consistent, structured site reports rather than free-form notes.

Example prompt: POST /forms with the inspection template, then GET `/plans/forms/{id}` to confirm it is attached to the active plan

### AI Agent Field Operations

Let an AI dispatcher orchestrate magicplan field operations end-to-end without holding the workspace API key. Through Jentic the agent searches for the project, file, plan or form operation it needs, loads the schema, and executes with credentials brokered by the vault. Useful for restoration coordinators and contractor desks that want a single agent to manage many parallel jobs.

Example prompt: Search Jentic for 'create a magicplan project', load POST /projects, and execute with the customer's site address from the dispatch system

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/projects` | Create a new project |
| POST | `/projects/{id}/files/temporary-presigned-url` | Request a presigned upload URL |
| POST | `/projects/{id}/files` | Register an uploaded file |
| GET | `/projects/{id}/estimates` | List project estimates |
| POST | `/forms` | Create a form template |
| POST | `/teams` | Create a team |
| POST | `/workspace/members/invite` | Invite workspace members |
| POST | `/plans/{id}/custom-export` | Trigger a custom plan export |

## Key resources

- **Workspace** — Workspace settings and member management via /workspace
- **Teams** — Create teams and manage memberships via /teams
- **Projects** — Full project lifecycle including archive and restore via /projects
- **Files** — Presigned upload flow plus list, register and delete via `/projects/{id}/files`
- **Forms** — Form templates managed via /forms
- **Plans** — Read plans, statistics, attached forms and trigger custom exports via /plans
- **Estimates** — Project estimates retrieved via `/projects/{id}/estimates`

## Why Jentic

- **Setup:** Wiring the magicplan Cloud API by hand means sending its API key on every request and coordinating the presigned-upload dance across project, file, form, and estimate paths on the cloud.magicplan.app host. Through Jentic you install once, import the magicplan Cloud API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** magicplan puts the project id in the URL path (`/projects/{id}/...`), so a rule can pin your agent to one project: it can request presigned upload URLs, register files, and read estimates for that project and nothing else. You choose the operations it may call, so workspace-wide ones like inviting members are not included unless you add them.
- **Credential handling:** Your magicplan key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a magicplan project' or 'upload a floor plan', and Jentic returns the matching magicplan operation with its input schema so the agent calls the right endpoint without browsing apidocs.magicplan.app.

## Related APIs

- **Asana API** — Track field service tasks tied to magicplan projects
- **monday.com API** — Operations and dispatch boards that mirror magicplan project status
- **Smartsheet API** — Spreadsheet-style estimate and schedule tracking
- **Trello API** — Lightweight kanban for tracking site visits and follow-ups

## FAQ

### Why is there no official OpenAPI spec for magicplan Cloud API?

magicplan publishes documentation at apidocs.magicplan.app but does not ship a curated OpenAPI specification. Jentic generates and maintains this spec so AI agents and developers can call the magicplan Cloud API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the magicplan Cloud API use?

The API uses two API key schemes - apiKeyAuth for workspace-level keys and customerAuth for customer-scoped tokens - passed in request headers. Through Jentic the credentials are stored encrypted in your Jentic One instance, so an agent calls /projects or /forms with a scoped token rather than handling raw keys.

### How do I upload a floor plan file via the magicplan Cloud API?

Use the two-step presigned URL flow. POST `/projects/{id}/files/temporary-presigned-url` returns a short-lived upload URL, you upload the binary directly to that URL, then POST `/projects/{id}/files` registers the uploaded artefact against the project. GET `/projects/{id}/files` confirms the file appears in the project record.

### What are the rate limits for the magicplan Cloud API?

Per-endpoint rate limits are not declared in the OpenAPI spec; magicplan typically applies workspace-level fair-use ceilings agreed at contract level. For high-volume sync workloads such as restoration fleets, coordinate with magicplan on dedicated quota.

### How do I create a new magicplan project through Jentic?

Run pip install jentic, search for 'create a magicplan project', and Jentic surfaces POST /projects with its input schema. Execute with the project name and site address fields, then chain to POST `/workspace/members/invite` if a temporary contractor needs access.

### Can the magicplan Cloud API export a plan to a custom format?

Yes. POST `/plans/{id}/custom-export` triggers a custom export job for the specified plan, and GET `/images/plan/{id}/svg/{fileName}` returns rendered SVG assets attached to the plan. Combine the two to build a finance-friendly report once the field capture finishes.

### Can I limit what my agent is allowed to do with the magicplan Cloud API?

Yes. Because you run Jentic One yourself, your own rules decide which magicplan operations and credentials the agent may use. Since magicplan puts the project id in the URL path (`/projects/{id}/...`), you can pin the agent to a single project so it only requests presigned upload URLs, registers files, and reads estimates for that project and nothing else. You choose the exact operations it may call, so workspace-wide actions like inviting members via `/workspace/members/invite` are excluded unless you add them.