gixointegration guide

Test six products with the free simulator.

The simulator covers Quill articles, Lumen decks and Lumen stories (Stanza), Prism visuals, Arc proposals, Business documents and Lex legal drafts: seven workflows across six products. Books (Folio) and video are not yet available through the API.

Production recipes use saved item IDs with source receipts and out-of-date markers; the simulator tests each workflow independently. Arc converts to a Lumen sales deck; a Business report is a separate source, not an Arc conversion.

Use the playground to test a module, then download the full example in your language. The examples below call deterministic integration fixtures. They make no model calls and consume no allowance.

1. Choose your runtime

Download one full example from the playground. Each file contains its own submit, poll and download flow. Use a clean working directory for the example and its output.

LanguageRun the downloaded example
JavaScriptnode quill.mjs (Node.js 22 or later)
TypeScriptnode --experimental-strip-types quill.ts (Node.js 22.6 or later)
Pythonpython3 quill.py (Python 3.11 or later, standard library)
C#dotnet run --file quill.cs (.NET SDK 10.0.400 or compatible .NET 10)
JavaJava 17 or later. Download the dependency pom.xml, run mvn org.apache.maven.plugins:maven-dependency-plugin:3.8.1:copy-dependencies -DoutputDirectory=lib, then java -cp 'lib/*' quill.java. Jackson is pinned in the POM.
Gogo run quill.go (Go 1.22 or later, standard library)
PHPphp quill.php (PHP 8.1 or later; HTTP stream wrappers enabled)
Rubyruby quill.rb (Ruby with JSON, OpenSSL and Net::HTTP)
cURLbash quill.sh (Bash, cURL and jq)

Examples default to https://gixo.ai. To test a local or staging instance, set GIXO_BASE_URL to its origin before running. Do not point examples at an untrusted service. No API key is required for simulation. To exercise a scoped platform credential, supply it as the GIXO_PLATFORM_KEY environment variable through your secret manager; every full example forwards it on submit, poll and download. Use a trusted Gixo HTTPS origin (or your loopback fixture), since the example sends the credential to GIXO_BASE_URL. The key never appears in the example source or URL. If Python reports CERTIFICATE_VERIFY_FAILED, update the trusted certificates supplied by your Python distribution; keep certificate checks enabled.

2. Submit, poll, download

  1. POST the module's JSON input to /api/platform/sandbox/{module}, where {module} is one of quill, lumen, stanza, prism, arc, business or lex. A successful request returns 202, an ID and statusUrl.
  2. GET that status URL until status is succeeded or failed. There is no completion webhook or callback; poll the status URL. Real generation is asynchronous; the deterministic simulator completes on the first poll.
  3. On success, download one of exports. Fixture downloads are HTML samples. The real API reports each module's supported native formats separately.
  4. Keep review findings alongside the output. A completed draft with findings stays available; a no-output provider failure has no export.

Simulation IDs identify public constant fixtures, not stored copies of your submitted text. The simulator performs bounded envelope checks; the real adapter also applies its complete product validation. Simulation is useful for integration testing, not evidence of generation quality, production idempotency or paid fulfilment.

3. Exercise the failure paths

Use ?scenario=provider-error for a simulated provider failure with no usable output, or ?scenario=review-findings for completed output with a visible finding. The default is success. Change the scenario in the playground to copy the corresponding request.

400 INVALID_REQUEST means input needs correction. An unknown module or fixture ID returns 404. Simulator input can be up to 150,000 characters, in a request body of up to 256,000 bytes.

429 means the simulator's request limit is reached: a burst of 30 requests, then 15 a minute, counted per signed-in user, otherwise per browser visitor or IP address. Respect Retry-After where returned and wait before trying again. The limit applies even though simulation costs no allowance.

For real requests, preserve the accepted ID and status URL through reloads or connection loss. Reuse the same idempotency key and body when explicitly retrying submission; generate a new key for a new request. Never blindly restart a paid generation because a status request timed out.

4. Move to real output

Free for 14 days: one real run of each product. After the trial you pay per run, priced from what the run actually uses (inputs and outputs), with the maximum shown before you start. Paid runs are charged to a prepaid balance that you top up by card.

The trial needs a Gixo account with a work email address; free consumer addresses such as Gmail are refused. Trial outputs stay available for 30 days after your trial ends. To prevent repeat trials, Gixo keeps a one-way hash of the email address used. Trial sizes, rate limits and error codes are in the API guide, which describes quote and acceptance, polling, saved-operation recovery, source IDs and protected downloads. Select real-output mode in the playground for individual request examples in nine languages.

The Enterprise API reference documents a separate API for Gixo Enterprise plan holders, with gixo_live_ keys and /api/v1 routes. Platform keys do not work there. A retail subscription does not become a platform purchase because the same account owns it.

Platform keys

Sign in at the Gixo key console to create, list or revoke your own platform keys. Choose an environment and explicit module read/write permissions. The environment is stored on the server; request headers cannot change it. These keys are separate from Enterprise keys and cannot access retail, checkout or key-management routes. Creating a key grants no trial allowance and adds no funds: real runs also need an active trial (evaluation keys) or funds in your prepaid platform balance (production keys).

Send exactly one credential, in Authorization: Bearer <key> or X-Gixo-Api-Key. Call GET /api/platform/credentials/current to check its environment, expiry and permissions. A permitted module's simulator accepts the same header; simulation also remains available without credentials. A .write permission allows submission, and .read allows polling and downloading its simulated output. Stanza and Lumen have separate platform permissions.

Save the returned secret immediately in a server-side secret manager. It is shown once, never returned by the key list and never embedded in downloaded examples. Revoke a key in the console to end access on its next request. Evaluation keys expire after one day; sandbox and production keys after 1–90 days. Disabled and closing accounts lose access immediately. A paid run also needs enough prepaid balance for its maximum and an accepted quote.

Other tools

Import the Postman collection and run each workflow folder in order. It stores the current status and download URLs in collection variables; it contains no credentials. The platform OpenAPI document describes the compiled public routes.

Questions about an integration: support@gixo.ai.

Open-source notices