Skip to content →
Docs
Connect systemsConfigure an HTTP connector
GitHub
Connect systems

Configure an HTTP connector

Describe a JSON-over-HTTP API in config/connectors.json without writing integration code.

Create the file

  1. Copy the example

    Terminal
    cp config/connectors.example.json config/connectors.json

  2. Set an id and base URL

    Ids must be lowercase kebab-case. The id is also the value used in simulation transports.

  3. Describe each supported endpoint

    Set its HTTP method, path, optional JSON body template, and optional response id path.

  4. Restart and select it

    Registered connectors appear in the panel’s transport pickers. The desktop app creates the files for you; use Setup → Config folder to open them. From source, the default is config/connectors.json.

Authentication

SchemeBehavior
noneNo auth header is added
bearerAdds Authorization: Bearer <token>
headerAdds the token under the configured header name
Recommended secret reference
{
  "auth": {
    "scheme": "bearer",
    "tokenEnv": "ACME_CRM_TOKEN"
  }
}

Use tokenEnv to keep secrets out of the file. A literal token is accepted for local experiments, and static non-secret headers can be added under headers.

Capability endpoints

connectors.json
{
  "connectors": [{
    "id": "acme-crm",
    "label": "Acme CRM",
    "baseUrl": "https://api.acme.example/v2",
    "auth": { "scheme": "bearer", "tokenEnv": "ACME_CRM_TOKEN" },
    "capabilities": {
      "actor.create": {
        "method": "POST",
        "path": "/customers",
        "body": {
          "name": "{{profile.givenName}} {{profile.familyName}}",
          "email": "{{profile.email}}"
        },
        "remoteIdPath": "customer.id"
      },
      "booking.create": {
        "method": "POST",
        "path": "/appointments",
        "body": {
          "customerId": "{{remoteActorId}}",
          "startsAt": "{{appointment.startsAt}}"
        }
      },
      "booking.cancel": {
        "method": "DELETE",
        "path": "/appointments/{{remoteBookingId}}"
      },
      "message.send": {
        "method": "POST",
        "path": "/messages",
        "body": { "customerId": "{{remoteActorId}}", "text": "{{body}}" }
      }
    }
  }]
}

Reachability and bookings

Two optional top-level endpoints add operational visibility:

  • ping supports GET or POST and powers the live status pill.
  • bookings.path supports remote listing and pull-based observation.
Optional observation endpoints
{
  "ping": { "method": "GET", "path": "/health" },
  "bookings": { "path": "/appointments" }
}