FAQ

General API UsageCopied!

What is this API used for?Copied!

The API enables integrations with magicplan, allowing users to manage projects, exchange data, and automate workflows. Learn more: API Overview.

Who can use this API?Copied!

This API is available to authorized workspaces with valid API Credentials. Access is granted at the workspace level, meaning individual user authentication is not required—only a valid API key and a Customer ID is needed to make requests.

What data format does the API use?Copied!

All requests and responses use JSON format.

Is there a sandbox or test environment?Copied!

Currently, there is no dedicated sandbox environment. However, we can set up a test workspace within the production environment for your account, which you can use for testing purposes. Contact us for more details.

How do I get started with the API?Copied!

To begin using the API:

  1. Generate an API Key – A workspace admin must generate an API key in the magicplan dashboard.

  2. Make your first request – Use your API key to authenticate and retrieve workspace data.

  3. Explore endpoints – Refer to the API documentation to understand available functionalities.


Authentication & SecurityCopied!

What authentication method does the API use?Copied!

The API uses an API key and customer ID for authentication. Every request must include these credentials in the headers to be authorized. See Authentication Guide.

How do I get API credentials?Copied!

API credentials can be generated from the magicplan dashboard. Follow the steps in the API Credentials Guide.

Who can generate API credentials in magicplan?Copied!

Only a workspace admin can generate the API Key for a workspace. This ensures that only authorized users have control over API access. Additionally, once the API Key is generated, only the workspace admin has access to it. Other members of the workspace cannot view or retrieve the API Key.

How should I protect my API key?Copied!

Your API key grants access to your account's data and should be handled securely. Best practices include:

  • Never expose your API key in public repositories or client-side applications.

  • Store API keys in environment variables or secure vaults.

  • Rotate keys periodically and revoke any compromised credentials immediately.

Do API keys expire?Copied!

API keys do not expire by default, but they can be revoked or regenerated by an admin at any time. If your API key stops working, check your API settings to verify its status or generate a new one. Learn more in the API Keys section.

How Do API Keys Work in Workspaces?Copied!

When an API Key is generated, it is specific to a single workspace.

  • If a user is an admin of multiple workspaces, they must generate a separate API Key for each workspace to manage them via the API.

  • The API will only return data within the specific workspace that the API Key belongs to.

  • If a user has a project in Workspace A, but they use an API Key from Workspace B, that project will not be listed in the API response.

    Example Scenario

    ▷ User Admin of Two Workspaces

    • Workspace A (API Key: key_A) → Contains Project X

    • Workspace B (API Key: key_B) → Contains Project Y

    ▷ API Calls:

    • If the user makes a request using key_A, only Project X will be returned.

    • If they make a request using key_B, only Project Y will be returned.

    To manage multiple workspaces via API, the user must authenticate separately with the correct API Key for each workspace.


Requests & ResponsesCopied!

How should I structure API requests?Copied!

Requests must be made using JSON payloads and include the required headers.

What HTTP methods does the API support?Copied!

The API supports standard HTTP methods:

  • GET – Retrieve data

  • POST – Create a new resource

  • PUT – Update a resource

  • DELETE – Remove a resource

What status codes should I expect?Copied!

The API returns standard HTTP status codes, including:

  • 200 OK – Successful request

  • 400 Bad Request – Invalid input

  • 401 Unauthorized – Invalid API credentials

  • 404 Not Found – Resource does not exist

  • 500 Internal Server Error – Unexpected issue

Does the API support pagination?Copied!

Yes, large datasets are paginated. Use the following query parameters to control pagination in your requests:

  • page (integer, default: 1) – Specifies the page number to retrieve. Defaults to 1 if not provided.

    • Example: ?page=1

  • page_size (integer, default: 10, max: 50) – Specifies the number of items per page. Defaults to 10, with a maximum of 50.

    • Example: ?page_size=10

How do I filter or sort results?Copied!

You can use query parameters to filter and sort results. Refer to the API documentation for supported filters.

How do I handle errors?Copied!

Error responses contain a status code, an error message, and details (depending on the issue).


Endpoints & FunctionalityCopied!

How do I create a new project?Copied!

You can create a project via the API by sending a POST request with the required data. See Create Project.

How do I upload files?Copied!

File uploads use presigned URLs. First, request a URL, then upload the file directly. See File Upload Guide.

To link an external project to magicplan, use the external_reference_id when creating a project. This ensures that your local project and the corresponding magicplan project remain synchronized.


API Performance & Rate LimitsCopied!

How can I optimize API performance?Copied!

To improve performance:

  • Use pagination when retrieving lists

  • Cache responses where applicable

  • Reduce unnecessary API calls

What are the rate limits for API requests?Copied!

To ensure system stability and prevent excessive usage, the API enforces rate limits.

Rate Limits:
  • Standard API Endpoints: 500 requests per 5 minutes

  • High-Throughput Endpoints: 2000 requests per 5 minutes

If you exceed these limits, the API will return a 429 Too Many Requests response.

What should I do if I exceed my rate limit?Copied!

If your API requests exceed the allowed threshold:

  • Implement Exponential Backoff – Introduce a delay before retrying requests, increasing the wait time after each failure.

  • Optimize API Calls – Avoid unnecessary requests by caching results where applicable and fetching only the required data.

  • Use Bulk Operations – If possible, retrieve larger sets of data in fewer requests instead of making frequent small requests.


WebhookCopied!

How do I set up the webhook?Copied!

Webhooks allow your system to receive real-time notifications when specific events occur in magicplan. To set up a webhook:

  1. Define the webhook endpoint – This is the URL in your system that will receive webhook payloads.

  2. Register the webhook – Send a request to the API to register your endpoint, specifying the event types you want to receive.

  3. Validate the setup – Ensure your system is correctly receiving and processing webhook payloads.

Once registered, magicplan will send an HTTP POST request to your endpoint whenever the specified event occurs. Your server must be able to handle these incoming requests and respond appropriately. See Webhook Documentation.

What events trigger the webhook?Copied!

Currently, magicplan provides a single webhook event, which is triggered when the user presses the Custom Export button in the application.

When this happens:

  • A webhook request is sent to the configured endpoint with relevant data about the export.

  • The payload includes details such as the project ID, email and such.

  • This allows your system to process the exported data in real time.

Since this is the only webhook event available, ensure your system is set up to handle it properly, including validating the incoming request and processing the export data efficiently.

What happens if my server is down when a webhook is sent?Copied!

If your server is unavailable or fails to respond when the webhook is triggered, magicplan will not retry the request automatically.

Instead:

  • An error message will be displayed to the user in the app, informing them that the export failed.

  • The user will need to manually retry the export process later.

To prevent missed exports, ensure that your webhook endpoint is always accessible, responds quickly, and handles incoming requests efficiently. If needed, implement logging on your end to track failed webhook requests for further troubleshooting.


TroubleshootingCopied!

Why am I getting a 401 Unauthorized error?Copied!

A 401 Unauthorized error indicates that the request is not authenticated properly. Common causes include:

  • Invalid API Key or Customer ID – Ensure that you are using the correct credentials.

  • Missing Authentication Headers – The request must include the required authentication headers.

  • Revoked API Key – If your key has been revoked, generate a new one.

  • Workspace Restrictions – API keys are workspace-specific, so ensure you are using the correct key for the workspace you are trying to access.Why is my project not appearing in magicplan?

Why is my project not appearing in magicplan?Copied!

If a project does not appear in magicplan, consider the following possibilities:

  • Project creation failed – If the API request did not return a 201 Created response, the project was not successfully created.

  • Wrong workspace – If the project was created under a different workspace, it will not appear in another workspace’s project list.

  • Sync Delay – While changes usually appear instantly, there may be a short delay before projects become visible in the UI.

  • Device is not connected to the internet – If the user’s device is offline, the project created via the API has not yet been downloaded onto the device. The user must reconnect to the internet and sync their magicplan app to retrieve the project.

To troubleshoot:

  1. Use the GET /projects endpoint with the external_reference_id to confirm if the project exists.

  2. Check the API response logs for errors during creation.

  3. Ensure you are using the correct API Key associated with the workspace where the project was created.

Why am I getting a 500 Internal Server Error?Copied!

A 500 Internal Server Error indicates an unexpected issue on the server. Possible reasons include:

  • Temporary API outage – The service may be experiencing downtime.

  • Malformed request payload – Incorrect JSON structure, missing required fields, or invalid data types.

  • Database or backend issues – The API may be facing internal processing errors.

To resolve:

  1. Check the API status page (if available) for any known issues or outages.

  2. Review your request payload to ensure all required fields are correctly formatted.

  3. Retry the request after a short delay in case it was a temporary issue.

  4. If the issue persists, contact us with the request details and response logs.

How can I debug failed requests?Copied!

If your API request fails, follow these steps to identify and fix the issue:

  1. Inspect the API response – Check the status code and error message for clues.

  2. Review request headers – Ensure authentication headers, content type, and required fields are present.

  3. Validate the request payload – Confirm the JSON format and required parameters.

  4. Check API rate limits – If you exceed the allowed requests, you may receive a 429 Too Many Requests error.

  5. Monitor webhook logs – If using webhooks, verify that the receiving server is properly handling requests.

  6. Use logging – Keep logs of request attempts and responses for easier debugging.