Edit Connected Systems with Builder API

Use this page when you (or an AI assistant helping you) need to change an existing Connected System safely — without guessing fields, skipping repair, or pasting secrets into the wrong place.

What this page is for

AI Fabrix integrations are JSON manifests (Connected System + Business Entities). You can edit them three ways:

This page is the shared safe loop for file and API editing. Humans and agents follow the same rules.

Prerequisites

• Developer workstation setup complete
• aifabrix auth status succeeds
• An integration workspace exists (integration/<systemKey>/), or you edit that system through Builder API
• You know which Connected System and Business Entity you are changing

Where it lives

Manifest JSON lives in your integration folder. Builder CLI validates, repairs, tests, and uploads those files. Builder API edits the same workspace one section at a time (authentication, metadata, capabilities, and similar). After upload, live secrets finish in the dataplane Authentication UI.

Tab names ↔ section keys: UI terminology map.

How to set

Read the section → fill missing required inputs → change with a clear reason → repair → validate and test → upload → add secrets in Authentication UI

1. Read first — open the section you will change (API: keep the section read token). Never patch blind.
2. Ask when required inputs are missing — primary keys and entity types come from a person, not guesswork.
3. Change with a clear reason — API patches record intent; use the same discipline in notes or commits when editing files.
4. Repair derived sections — after metadata, capabilities, or exposure changes, run aifabrix repair <systemKey> or named repair hooks.
5. Validate and test before upload — green schema and integration tests; upload is a separate decision.
6. Upload configuration — not secrets — API keys go in Connected Systems → Authentication after upload.
7. Re-check with live credentials — then certify when your scope is ready.

If you prefer CLI only

aifabrix validate <systemKey>
aifabrix repair <systemKey>
aifabrix test-integration <systemKey>
aifabrix upload <systemKey> --probe

That is the same loop. Builder API is for agents and automation — not a different product path.

Defaults and examples

Everyday example: add a field mapping → read the section → confirm the vendor field name with the integrator → patch with intent → repair → validate/test → upload → confirm Authentication secrets.

Example intent text when using Builder API (plain language — API wraps this in a patch body):

{
  "sectionKey": "datasource.fieldMappings",
  "intent": "Map vendor owner id to ownerId for Sales Manager visibility",
  "mode": "merge"
}

Builder help topics (API / agents): start with overview and workflow, then section for the area you edit. Also useful: dependencyGraph, repairRules, goldenExample, connectedSystemUi, cipOverview.

Adoption checklist: GitHub integration golden path. Auth detail: Configure authentication.

After upload — Authentication UI

Do not put live vendor secrets in Builder API or workspace env files when UI auth is the path. Upload may pre-fill non-secret values (base URL, header name, token URL). A person opens Authentication, adds only required secrets, then re-runs tests. Agents can use help topic connectedSystemUi for the correct UI path.

Validate

aifabrix auth status
aifabrix validate <systemKey>
aifabrix repair <systemKey>
aifabrix test-integration <systemKey>
aifabrix upload <systemKey> --probe

Done looks like: validate green, repair after structural edits, upload probe OK, Authentication secrets saved.

Common mistakes

Limits

Builder API does not register vendor apps (GitHub App, CRM private apps, and similar). Channel install and secret rotation stay outside this loop. Role Assistants activate only after certification — see From integrations to Role Assistant.