Custom Endpoints: design your own API

Where to find it #

Open your app and go to Settings > Custom Endpoints, just below API Keys. If you see "Custom Endpoints is not enabled for this app", contact support and we'll switch it on for your account.

When to use it #

The standard API gives you one table per call, with Tadabase's own field names. That's fine for your own scripts. Custom Endpoints are better when:

• A partner needs a clean contract. They get readable keys like customer.name instead of field_42, only the fields you chose, and docs that are generated for them.
• One call should return related data. For example a policyholder with their sales rep and their claims, instead of three calls stitched together.
• One call should write related data. For example a partner posts a claim and it links to an existing policyholder by their external ID, or creates the policyholder if they're new.
• You want to limit what a key can do. An API key can be set to answer only on your Custom Endpoints, so a partner can't reach the rest of your app.

Endpoints read and write records. After a write, your table rules, workflows, formulas and outgoing webhooks run as usual, so any extra logic belongs in a workflow.

Create an endpoint #

1. Press New Endpoint Under Settings > Custom Endpoints, press New Endpoint.
2. General: name it and pick the table Give it a Name and a URL slug (lower-case letters, digits and dashes). Choose the Root data table: the main table this endpoint works on. You can't change the root table later, and changing the slug later breaks anyone already calling it.
3. Choose the methods GET to read records, POST to create (or create-or-update) from a payload, PUT to update an existing record. Deleting is never allowed through a Custom Endpoint.
4. Read: shape the response Pick the Output fields and the key each one appears under. A key with a dot nests the value, so customer.name comes back as {"customer": {"name": ...}}. Add Embedded connected records to include related records (up to 3 levels deep). Add Pinned filters for records that must always be excluded; callers can narrow results further but never widen them.
5. Write: decide how saving works Turn on Accept writes on this endpoint if it takes POST or PUT. See How writes work below.
6. Access: choose who can call it Tick the API keys allowed to call this endpoint. Optionally add an IP allowlist and a custom Rate limit.
7. Test, then set it to Active Use the Test tab to try it (see below). New endpoints save as Draft, which can't be called. Set Status to Active when you're ready.

Let an API key use it #

Three things must all be on before a call works: Custom Endpoints for the app, Allow Custom Endpoints on the key, and that key ticked on an Active endpoint.

1. Open the key Go to Settings > API Keys and open (or create) the key you'll give out.
2. Allow Custom Endpoints Turn on Allow Custom Endpoints.
3. Decide about the standard API Allow Standard API decides whether the same key can also use the regular table API. For a partner key, leave it off so the key only answers on your Custom Endpoints.

Calling it #

Every endpoint lives under one base URL, shown with a Copy button at the top of the Custom Endpoints list:

https://api.tadabase.io/api/v1.2/{appId}/{slug}

Send the key and secret as headers on every call:

curl https://api.tadabase.io/api/v1.2/YOUR_APP_ID/claims?limit=20 \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET"

A list comes back with items, plus total_items, total_pages, current_page and limit. You can add page, limit, sort_by, sort_dir and filters[...] to a list call, limited to the fields and operators you allowed on the Read tab.

The Docs tab generates a full reference for each endpoint (headers, fields, filters, an example body) and Export docs downloads it, so you can send it straight to a partner. Each row in the list also has Copy curl.

How writes work #

On the Write tab you map each key in the incoming JSON to a field, and decide what happens when the record already exists:

• Match an existing record when: pick the field(s) that identify a record, such as an external ID. Then choose what happens when a record matches (update it, skip it, or fail), when nothing matches (create it or fail), and when several match.
• Connected records: for a nested object such as "policyholder": {"external_id": "P-100"}, choose whether to link an existing record, create it if it's missing, or fail. For lists of connections, choose whether to add to the existing links or replace them.
• All or nothing: when on, if any part of the payload fails, nothing is saved.
• Clean-up steps: trim spaces, change case, convert to a number, yes/no or text, read a date in a given format, join values, or use a fixed value.
• Unknown keys: ignore keys you didn't map, or reject the whole request.
• Full payload: optionally keep the raw request body in a long text field, handy for troubleshooting.

Test, versions and logs #

• Test runs the endpoint as you, without an API key. Writes are a dry run unless you tick Commit for real.
• Versions keeps every save. Compare two versions, add a note, or Restore an earlier one.
• Logs shows every call: when, how long it took, which key called, which record, and the result. Filter to failed calls to find problems quickly. Calls are kept for 30 days.

Row-level security and access #

On the Access tab, Row-level security is set to Same as the table API by default. The call is treated like a signed-out visitor: only records and fields your public rules allow are returned, and blocked writes are refused. This is the safe choice.

Only the app owner can switch an endpoint to Bypass row-level security. Do that only when the key is held by a trusted system that may see everything the endpoint returns.

• The Users table can be read through an endpoint but never written.
• Collaborators can be given Manage custom endpoints in the app's sharing settings.
• When you copy an app, its endpoints come across as Draft with no keys ticked.

Limits #

Your plan's API rate limit still applies, and an endpoint can have its own lower limit per key. Each error response has a short code and a request_id; quote the request_id when you contact support. If a key isn't valid, every call returns "not found" so an outsider can't tell which endpoints exist.