Making Your First API Call

This page will help you verify that your credentials are set up correctly and that you can successfully communicate with the magicplan REST API.

Before You Begin Copied!

Ensure you have the following:

• Customer ID: Obtained from your magicplan Cloud account.

• API Key: Also generated within your magicplan Cloud account.

• HTTP Client: Such as curl, Postman, or a similar tool that allows you to set custom request headers and send HTTPS requests.

Step 1: Prepare Your Headers Copied!

Unlike some APIs that require a single combined, encoded authorization string, the magicplan REST API uses two separate headers to authenticate requests:

• customer: Your Customer ID

• key: Your API Key

Step 2: Make a Test GET Request Copied!

First, confirm your connectivity by calling an endpoint that doesn't require a resource ID, such as /workspace:

Example:

curl -X GET "https://cloud.magicplan.app/api/v2/workspace" \
  -H "customer: YOUR_CUSTOMER_ID" \
  -H "key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

If you have a plan ID, you can also try the /plans/get/{plan-id} endpoint. Always use https:// to ensure secure transmission of your credentials.

Step 3: Check the Response Copied!

A 200 OK status indicates a successful call. If you see workspace details or plan data returned as JSON, your credentials are valid.

Troubleshooting Tips:

If you receive an error response, consider the following:

• 401 Unauthorized

  • Invalid Credentials: Double-check that your customer and key headers are correct and that the API Key has not been revoked. If issues persist, consider regenerating your credentials.

  • Insufficient Permissions: If you included an acting_user parameter in your request, ensure that this user has the necessary permissions to perform the requested action. If not, update the user’s role or omit the acting_user parameter if it’s not required for the operation.

• 400 Bad Request or 404 Not Found: Verify the endpoint’s URL and parameters.

• 500 or Other Server Errors: Try again after a short delay. If the issue persists, contact support.

Step 4: Next Steps Copied!

With a successful test call, you have confirmed that your credentials are valid and your environment is set up correctly. You can now:

• Retrieve and manage projects with the /projects endpoints.

• Work with floor plans using the /plans endpoints.

• Manage teams and workspaces with the /workspace and /teams endpoints.

• Export or retrieve additional data, including images and forms.

Refer to the full API Documentation for in-depth details on parameters, request bodies, and available endpoints. With a working API call in place, you can start integrating magicplan’s capabilities into your existing systems and workflows.