Custom API Functions

Your datastores already produce endpoints. A custom API function adds one of your own design, at a path and method you choose.

Where to find it

Architect Panel → Integration & Connections:

• API Server — the custom functions and their actions
• OpenAPI Specification — where your endpoint appears alongside the generated ones

Architect Panel → Data:

• Datastores — the generated endpoints these supplement

What one is

• A name.
• A path.
• An HTTP method — GET, POST, PUT, DELETE or PATCH.

Beneath it sit one or more actions, which are what the endpoint actually does when it is called.

Check you need one first

Most integration requirements are met by the generated endpoints, and a custom function is a thing you then own and maintain. Before building one, ask whether the caller could achieve the same with the endpoints that already exist.

The honest test: if a custom function would just be "fetch these rows", it is not earning its place.

When one is genuinely warranted

• An operation spanning several datastores that should succeed or fail as a unit.
• A caller you cannot change, that expects a particular shape.
• An action rather than a record — something the API should do, not something it should return.
• A deliberately narrow endpoint for an external party, exposing exactly one operation.

That last is a good pattern: rather than granting a partner access to a datastore, give them one endpoint that does one thing.

Choose the method honestly

Use GET for reads, POST to create, PUT and PATCH to update, DELETE to remove. Callers, proxies and caches all make assumptions from the method — a GET that changes data will eventually be retried or cached by something in the middle, with results nobody intended.

Paths should not collide

Keep custom paths clearly distinguishable from generated ones so nobody has to guess which they are calling. A prefix for your own endpoints makes the spec far easier to read.

Permissions still apply

A custom function runs as the calling key's identity, so the underlying data access is governed the same way. It is not a route around permissions — but it can easily be a route around your intent if it does something broader than the caller could do directly.

Look at what the actions touch, not just at what the endpoint is called.

They appear in the spec

Custom endpoints show up in the OpenAPI specification alongside the generated ones, so an integrator sees one description of everything available.

Document what it does

A generated endpoint is self-explanatory from the datastore. A custom one is not — it does whatever its actions do, and the next person will not be able to infer that from its name. Write down the intent, the expected body and what it returns.

Worked example

A partner needs to submit a referral, which creates a record in one datastore, a contact in another and a task for a team. As three generated calls it is three round trips that can half-fail. One custom endpoint takes the referral, performs all three, and returns the new reference — and the partner is granted nothing else.

Recommendations

• Prove the generated endpoints cannot do it first.
• One narrow endpoint per external operation, rather than broad datastore access.
• Match the HTTP method to the effect.
• Document the intent — the name will not carry it.