Create a Site via API

Overview

Creating a site is asynchronous. The first endpoint (POST /api/v1/trial-sites) accepts your configuration and returns a siteId and pollToken immediately. Provisioning continues in the background. The second endpoint (GET /api/v1/trial-sites/{siteId}) lets you poll for status until the site is ready or failed.

Each trial site has a fixed 4-hour lifetime and is permanently deleted on expiry with no backup. The exact deletion time is in result.expiresAt.

Authentication

All requests require an API key sent as a Bearer token. Get your key at Settings → Application API Key (signed-in dashboard). One active key per account; the full key is shown once at creation.

Authorization: Bearer ij_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Treat the key like a password — it authorises site creation against your account quota. Rotate it from Settings if it is ever exposed.

• Missing, malformed, or revoked key → 401 Unauthorized.
• One active key per account.

Base URL

All requests go to the production base URL https://jinstant.com. Every example in this guide uses it.

Endpoint 1 — Create a trial site

Reserves a provisioning job and returns immediately. Every request body field is optional — send an empty JSON object ({}) or no body at all to use all defaults.

Request body

Examples

curl -X POST "https://jinstant.com/api/v1/trial-sites" \
  -H "Authorization: Bearer $JINSTANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "joomlaVersion": "6",
    "phpVersion": "8.3"
  }'

Response — 202 Accepted

{
  "siteId": "4db53b6f-b1a6-4e46-a793-9a15a9dbf9ef",
  "pollToken": "uG0Q6Zq4xv9M3v3q8c2m4mS0nLQh4x2M",
  "status": "queued",
  "progressStage": "queued",
  "progressMessage": "Your site is in line. We are setting up Joomla 6 / PHP 8.3."
}

Endpoint 2 — Check status / get result

Requires the same Authorization: Bearer key and the token query parameter. The job must belong to the authenticated user. Responses are always Cache-Control: no-store.

Parameters

Example request

curl "https://jinstant.com/api/v1/trial-sites/$SITE_ID?token=$POLL_TOKEN" \
  -H "Authorization: Bearer $JINSTANT_API_KEY"

Status lifecycle

The status field moves through these values while you poll:

progressStage provides finer-grained machine-readable stages:queued → leasing_warm_instance → creating_files → starting_containers → waiting_for_joomla → configuring_routing → ready / failed.

Response examples

In progress

{
  "status": "provisioning",
  "progressStage": "waiting_for_joomla",
  "progressMessage": "Almost there. Finishing setup for Joomla 6 / PHP 8.3.",
  "error": null,
  "result": null
}

Ready

{
  "status": "ready",
  "progressStage": "ready",
  "progressMessage": "Joomla 6 / PHP 8.3 is ready.",
  "error": null,
  "result": {
    "slug": "ab3k9m2q8n",
    "siteUrl": "https://ab3k9m2q8n.jinstant.com",
    "expiresAt": "2026-06-20T21:05:00.000Z",
    "credentials": {
      "username": "admin",
      "password": "s3cr3t-one-time-pw",
      "administratorUrl": "https://ab3k9m2q8n.jinstant.com/administrator/",
      "magicLoginUrl": "https://ab3k9m2q8n.jinstant.com/administrator/instant-login-xxxx.php"
    }
  }
}

Failed

{
  "status": "failed",
  "progressStage": "failed",
  "progressMessage": "Provisioning failed",
  "error": "Provisioning failed",
  "result": null
}

Response fields

Polling strategy

• Poll endpoint 2 every ~2 seconds.
• Stop when status === "ready" (capture credentials immediately) or status === "failed" (read error).
• Recommended timeout budget: 2–5 minutes. Most sites provision in under a minute when a warm-pool instance is available.

Complete example (Node.js)

This script creates a site, polls until it is ready, and logs the result. Credentials are captured on the first ready response.

const BASE = "https://jinstant.com";
const KEY  = process.env.JINSTANT_API_KEY;

async function createTrialSite() {
  // 1) Create the job
  const create = await fetch(`${BASE}/api/v1/trial-sites`, {
    method: "POST",
    headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ joomlaVersion: "6", phpVersion: "8.3" }),
  });
  if (create.status !== 202) throw new Error(`Create failed: ${create.status}`);
  const { siteId, pollToken } = await create.json();

  // 2) Poll until ready or failed (≈5 min budget)
  const deadline = Date.now() + 5 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(
      `${BASE}/api/v1/trial-sites/${siteId}?token=${encodeURIComponent(pollToken)}`,
      { headers: { Authorization: `Bearer ${KEY}` } }
    );
    const body = await res.json();

    if (body.status === "ready") {
      // 3) Capture credentials NOW — they are returned only once.
      console.log("Site URL:", body.result.siteUrl);
      console.log("Login:",    body.result.credentials);
      return body.result;
    }
    if (body.status === "failed") throw new Error(body.error ?? "Provisioning failed");

    await new Promise((r) => setTimeout(r, 2000));
  }
  throw new Error("Timed out waiting for the site to become ready.");
}

Site lifetime

Trial sites created via the API have a fixed 4-hour lifetime. They are automatically and permanently deleted on expiry, with no backups, consistent with the Terms of Use. The exact deletion time is in result.expiresAt.

Versions reference

Joomla / PHP matrix

You choose the major line ("5" or "6") and always get the latest release we support on it. Unsupported combinations (e.g. joomlaVersion: "6" with phpVersion: "8.1") return 400 Bad Request.

Errors

All error responses use JSON: { "error": "message" }.

Rate limits & quotas

• Create rate limit: 3 POST attempts per 60-minute window, per IP. Exceeding this returns 429.
• Concurrent-site quota:3 active sites per account (a site is "active" when its status is queued, provisioning, ready, failed, or deleting). Exceeding this returns 409. Delete a site from your dashboard to free a slot.

Next steps

• Open your dashboard to manage sites and create an API key.
• Terms of Use — usage policy, site lifetime, and prohibited use.
• Privacy Policy.