Create Your Own Tools And Extend The Platform With Python and Render

Using the Katapult Pro API, you can create custom mapping tools and app-to-app integrations that interact with Katapult Pro in new, useful ways. One of the ways to make use of the Katapult Pro API is with a Render server with python code. Render defaults as a free service, but you can upgrade your Render account to allow you to run the functions you create with a much better cold start time.

*Note: There is a free option for custom tooling with very low cold start time: Cloudflare Workers with JavaScript. The potential downside to this option is that you will have to learn how to write code in JavaScript. If you are familiar with JavaScript, or if you are willing to take the time to start learning, we would suggest that using Cloudflare Workers is the superior option. For more information and a guide for this option, see this manual.

Writing Source Code For Your Tool

We'll start by writing some code for a simple mapping tool for testing.

Create a new repository in GitHub for your API tool. Then create two new files in the repository: main.py and requirements.txt .

Code for requirements.txt

Enter the following code into requirements.txt . These are the libraries that you will be importing in main.py . Adding them to the requirements.txt file lets Render know which libraries to install when deploying.

uvicorn
fastapi
requests

Code for main.py

In main.py , enter the following code to import the libraries we will be using.

Python
from fastapi import FastAPI, Request, Response
import requests
from fastapi.middleware.cors import CORSMiddleware

Next we'll create the FastAPI application.

Python
app = FastAPI()

# Enable CORS for Katapult Pro
app.add_middleware(
	CORSMiddleware,
	allow_origins=["https://katapultpro.com"], # this should be your
	allow_credentials=True,				  # server's base URL
	allow_methods=["*"],
	allow_headers=["*"]
)

Important Note: Make sure that the allow_origins field contains the URL of your current working server (or you can put in an asterisk as shown in allow_methods and allow_headers fields to allow all origins to access your endpoint).

By adding middleware specs to the FastAPI application, we ensure Katapult Pro will be able to send requests to our endpoint. We also specify that all types of requests are allowed (GET, POST, PATCH, etc.) with the allow_methods field, and we allow the request to contain any headers using the allow_headers field. Each of these fields can contain either a comma separated list of strings or the asterisk (wildcard operator) to allow all.

Now we need to write some code to parse the request that our endpoint will be receiving from our tool in Katapult Pro.

Python
# Specify what subpath should trigger this function
@app.post("/add_welcome_note")
def add_welcome_note(request: Request): 

	# Extract query parameters
	query_params = dict(request.query_params)
	job_id = query_params.get("job_id")
	node_id = query_params.get("node_id")
	api_key = query_params.get("api_key")

	# If any of the necessary parameters are not defined, respond with an 
	# error 400 response
	if not (job_id and node_id and api_key):
		return Response(content="Missing parameters", status_code=400)

Now that we have code to parse the parameters from the request, we need to construct the URL for the call to the Katapult API.

Python
	# Put the URL of the Katapult Pro API endpoint we want to use
	# NOTE: Make sure to replace "katapultpro.com" with your server's
	# base URL, if applicable
	new_request_url = (
		f"https://katapultpro.com/api/v3/jobs/{job_id}/nodes/{node_id}/?api_key={api_key}"
	)

Important note: If your URL is wrong, it will not show a warning pop-up; but there will be an error in the console and your tool will not receive or change any data.

Note the subpaths following katapultpro.com in the URL. These subpaths are how we specify that we are visiting the API and specify which job and node we wish to access. Notice also that we pass our API key through a query parameter so that the Katapult Pro API knows we are an authenticated user.

Let’s send some data to confirm that our tool works. The following code shows how this can be done by constructing a well-formed request body. Here we will be adding a note attribute to the selected node. We also want to create a request header. In this case, all we need to specify is the JSON format for the content.

Python
	# The data we want to send to the Katapult Pro API
	request_body = {
		"add_attributes": {
			"note": "This is a note from my new awesome python API tool!"
		}
	}
	# The request header
	header = {
		"Content-Type": "application/json"
	}

Finally, we need to make a request to the Katapult Pro API with our URL, body, and header, storing the response in a variable to be returned.

Python
	# Make the POST request
	katapult_response = requests.post(new_request_url, json=request_body, 
	headers=header)

	# Return the response
	return Response(
		content = katapult_response.text,
		status_code = katapult_response.status_code
	)

As you may already be familiar with, the execution of Python code depends heavily on the indentation of each line in the file. Make sure that the line indentation in your main.py file is the same as in the following screenshot before proceeding.

Creating And Deploying Your Web Service

Create an account and/or sign into Render. If you choose a different signup method for Render other than GitHub, you will need to link your GitHub account so that Render can access the code in your repository. You can do this by going to your profile in the top right corner of your Render dashboard, clicking on “Account Settings”, and adding your GitHub account in the “Git Deployment Credentials” section (see screenshot below).

Returning to your Render dashboard, from the "+ Add New" or "+ New" button, select "Web Service" to create a new web service.

Under "Git Provider," select the repository you created for this tool we've made.

Make sure that the "Build Command" setting contains the following command. This will ensure that Render installs all of the requirements specified in the requirements.txt file you already created in the repository.

pip install -r requirements.txt

Also make sure to fill in the "Start Command" (Render won't let you deploy without specifying a start command).

Here is a basic start command you can use:

uvicorn main:app --host 0.0.0.0 --port 10000

Select the free option for Instance Type (this can be changed later if you want to upgrade to avoid down time for your application).

No environment variables are necessary for this application.

Click the "Deploy Web Service" button at the bottom of the page to deploy your project.

Creating Your Tool In Katapult Pro

Once the code and web service are set up following the above steps, it is now time to test that this endpoint actually works with a tool in Katapult Pro.

In the Model Editor, select your job model and create a new tool. Select an icon and color, then choose “Run Web Tool” as the Tool Action before pasting the URL of our Render endpoint (see screenshot below).

The URL for our Render service can be found near the top of your service’s page in the Render web service (see screenshot below).

This endpoint URL is the first part of the URL that we need to give our tool. Remember, we need to include the subpath that calls the function from our code that we want to run. We also need to pass the job ID, the node ID, and the user’s Katapult Pro API key through the URL. We can do this by adding the following paths and query parameters to the URL.

/add_welcome_note?job_id=$(job_id)&node_id=$(node_id)&api_key=$(api_key)

Important note: Do not pass your API key explicitly through the URL. Using $(api_key) populates the user’s API key automatically. This allows Katapult Pro to authenticate each user who uses the tool without the URL exposing any specific user’s API key to all other users who have access to the model.

To finish creating the tool, make sure to select “API Call” for the Endpoint Action and select a toolset so that you can access your tool from the toolbar in Katapult Pro Maps.

Now you can open any Katapult Pro job that uses this model and run the tool.

In the screenshot above, there's a modal telling us our mapping tool ran successfully, and we can see the "Note" attribute added to the node with the "This is a note from my new awesome python API tool!" that we assigned to the attribute in our code.

Next Steps

There is much more that can be done with the Katapult Pro API, and Render with Python can be used to leverage the access to data provided through the API. This guide has walked through the basic steps of how to set up code for a tool, deploy the code to a Render web service, and then get a tool in Katapult Pro connected to the Render endpoint. You are set to explore the different functional components of the Katapult Pro API and begin to leverage them to meet your needs.