Custom backend — bring your own API

The Custom connector lets you migrate from any REST API the platform-specific connectors don't already cover — internal CMSes, headless stores running on bespoke backends, legacy Drupal/Joomla/Craft installs, in-house data platforms. Studio doesn't assume your schema; we negotiate it during the build.

What you give us#

1. Base URL

   A base URL — the root of your API (e.g. https://api.your-backend.com).

2. Authorization header value

   An Authorization header value if your API requires one. Studio sends the value verbatim in the Authorization header on every request (e.g. Bearer abc123, Basic xyz==, or a custom scheme). Leave blank for unauthenticated read endpoints.

3. List of endpoints

   A list of endpoints we should pull, mapped to Insites entity types — pages, posts, products, orders, contacts, media, forms, submissions. We work this out together during the build kickoff.

Expected response shape#

Endpoints should return JSON. Each list endpoint returns either a bare array or an envelope with the records under a documented key (data, items, results, etc.) — we configure which one per endpoint.

GET /products?limit=100&offset=0
 
{
  "items": [
    {
      "id": "prod_123",
      "name": "Black T-shirt",
      "price": "29.00",
      "currency": "AUD",
      "images": ["https://cdn.your-backend.com/tshirt-1.jpg"],
      "variants": [{ "sku": "TS-BLK-S", "stock": 12 }]
    }
  ],
  "pagination": { "total": 1240, "offset": 0, "limit": 100 }
}

Pagination#

Studio supports the three common pagination styles. We configure which one each endpoint uses:

• Offset / limit — ?offset=0&limit=100, with pagination.total in the response so we know when to stop.
• Page / per-page — ?page=1&per_page=100, with either a total or a link header.
• Cursor — response includes nextCursor (or similar) and we pass it back as ?cursor=....

Asset handling#

Any URL Studio sees during ingestion (in image fields, body HTML, file references) is run through the asset pipeline: downloaded, deduped by sha256, and rewritten to assets.insites.io. Your asset URLs need to be publicly readable, or accessible with the same Authorization header you give us.

Auth patterns we support#

Pattern	How
No auth	Public read-only endpoints. Leave the auth field blank.
Bearer token	Paste Bearer xyz as the auth header value.
Basic auth	Paste Basic base64(username:password) as the auth header value.
API key header	Custom header schemes (e.g. X-API-Key) need a build-time hook. Flag this during kickoff.
OAuth flows	Mint a long-lived token offline and paste it as a Bearer header. Studio doesn't currently run the OAuth handshake itself for custom backends.

During the build#

For the Custom connector specifically, the migration kickoff is more collaborative than the platform connectors. Expect to:

• Walk through your API's endpoints together so we can map each to an Insites module.
• Decide which fields on each record map to Insites fields (title, slug, publishedAt, etc.) and which become custom fields.
• Test the connection against a small subset (one record per type) before kicking off the full migration.

Token storage (alpha)#

Credentials are kept in your browser's localStorage so a refresh or shared link doesn't lose the migration session. They're sent to the Insites server only at the moment of a connection test or import run, and are never logged. Before GA we'll switch to a server-side token exchange.

Rotate the credential after the migration completes — see other connector guides.