Toolkit Endpoints

back to toolkits /// home

Custom API routes defined by toolkits. These live under /tk/app/{toolkit}/ or /tk/lib/{toolkit}/ depending on the toolkit type.

Route format

POST /tk/app/beepzone/kiosk/scan
GET  /tk/lib/opensigma/status

The path after the toolkit name is matched against endpoint definitions in the toolkit config.

Endpoint types

Internal

Runs logic within the server process. Can use pseudo_querys to execute database queries based on the request payload. No external service needed.

HTTP

Proxies the request to an external HTTP service. The server wraps the payload in a context object (user info, DB context etc), sends it to the upstream URL and returns the response.

Can return JSON (wrapped in the standard envelope) or passthrough (raw bytes with the upstream content type, useful for file downloads).

Executable

Runs a shell command on the server. The request context is passed as a JSON string argument. Output is parsed as JSON or wrapped in { "output": "..." } if its not valid JSON.

Request flow

1. verify the toolkit exists and is enabled (404 if not)
2. match the endpoint path in config (404 if not found)
3. check endpoint level permissions for your power level (403 if denied)
4. validate payload against client_filter rules (400 if invalid)
5. fetch inject_db_context values from the database
6. resolve your toolkit group
7. build the request context
8. apply overwrite_wrapping transformations
9. execute based on endpoint type

Request context

The context object sent to backends looks like this:

{
  "user_id": 1,
  "username": "admin",
  "power": 100,
  "core_group_id": 1,
  "core_group_name": "administrators",
  "toolkit_group": "managers",
  "request_id": "abc123",
  "payload": { ... },
  "db_context": { "key": "value" }
}

toolkit_group is the users group within this specific toolkit (resolved via jde_associations or toolkit_overrides).

db_context contains values fetched via inject_db_context config.

Client filter

Validates the incoming request payload before anything else happens.

[endpoints.0.client_filter]
allowed_fields = ["barcode", "quantity"]
required_fields = ["barcode"]
max_body_bytes = 4096

Per field rules example:

[endpoints.0.client_filter.field_rules.barcode]
type = "string"
max_length = 50
pattern = "^[A-Z0-9-]+$"

Database context injection

inject_db_context lets you pull values from the database and include them in the request context.

Simple: pull a value by column name

inject_db_context = ["users.email"]

Filtered: pull specific rows based on payload values

inject_db_context = ["items.name?id=$payload.item_id"]

The $payload.field syntax references fields from the clients request body.

Overwrite wrapping

Modify the context envelope before sending it to the backend.

• prefix with - to remove a field: "-power" removes the power level from context
• without prefix: promotes a db_context value to a top level field

Success response

{
  "success": true,
  "request_id": "abc123",
  "endpoint": "/tk/app/beepzone/kiosk/scan",
  "data": { ... }
}

Error responses