Quickstart

Call a published junction in three steps. Examples use $JUNCTREE_HOST (your Junctree API host) and $JUNCTREE_API_KEY (a per-principal bearer key).

Authenticate

Every tenant request carries a per-principal API key as a bearer token. Keys look like jt_<tier>_<random> and are issued to you through the admin API. Treat them like passwords — they grant the ability to run your junctions.

export JUNCTREE_HOST="api.example.com"
export JUNCTREE_API_KEY="jt_org_…"

Check connectivity

A quick unauthenticated health check confirms you can reach the API.

curl https://$JUNCTREE_HOST/api/health

To confirm who your key authenticates as, call whoami:

curl https://$JUNCTREE_HOST/api/v1/whoami \
  -H "Authorization: Bearer $JUNCTREE_API_KEY"

Run a junction

Post the junction slug, the trigger name, and a typed input object. The slug can be dotted (acmefx.quote) or split into integration + junction.

curl https://$JUNCTREE_HOST/api/v1/execute \
  -H "Authorization: Bearer $JUNCTREE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "junction": "acmefx.quote",
    "trigger": "get_quote",
    "input": { "base": "USD", "quote": "EUR", "amount": 100 }
  }'

A successful run returns the execution record:

{
  "execution_id": "b1c2…",
  "status": "succeeded",
  "output": { "rate": 0.92, "converted": 92.0 },
  "error": null,
  "duration_ms": 143,
  "request_id": "F1a…"
}

The error model

Junctree distinguishes a junction failure from a platform error:

200 with status: "failed" — the platform ran your junction, but a step failed. The error object explains which step and why.
4xx — a platform-level problem before or around the run: 401 bad credentials, 403 not allowed, 404 unknown junction/trigger, 422 input failed its schema, 429 rate limited.

Idempotency

Send an Idempotency-Key header to make a call safe to retry. Within a 24-hour window, the same key returns the original execution instead of running again — so a network retry never double-charges or double-sends.

curl https://$JUNCTREE_HOST/api/v1/execute \
  -H "Authorization: Bearer $JUNCTREE_API_KEY" \
  -H "Idempotency-Key: order-4821" \
  -H "Content-Type: application/json" \
  -d '{ "junction": "acmefx.quote", "trigger": "get_quote", "input": {} }'

Full endpoint reference

Every tenant-facing endpoint, with request and response schemas, lives in the API reference.

Open the API reference