REST API reference

The hosted API has one managed model: GQI. A fit creates private, task-specific state from text/number pairs. Prediction accepts either the immutable handle returned by fit or the literal "GQI" for an intentional zero-shot call.

Base URL: https://gqilabs.com/api

Python users should normally use the dependency-free gqi-labs SDK. This page documents the underlying HTTP contract.

Guarantees

• Every finite target is valid, including zero and negative values.
• Accepted request payloads are retained for 30 days for debugging and product evaluation, then deleted. Fitted model artifacts are stored separately.
• The only public model name is GQI. Retired names resolve to GQI with a warning.
• Prediction never silently falls back to an untuned model. model is required: use the complete fitted handle, or explicitly send "GQI" for zero-shot.
• Inputs are measured before training or prediction. The service selects 512, 1,024, 2,048, or 4,096 tokens and reports every truncated row.

Authentication and idempotency

Create a key in the account console and send it as a bearer token. Every fit or prediction submission also requires a unique Idempotency-Key. Repeating the same request with the same key returns the same job; reusing it for different content returns 409.

Fit → poll → predict

1. Submit a fit

Fits require at least eight labeled rows.

curl -X POST https://gqilabs.com/api/v1/fits \
  -H "Authorization: Bearer gqi_sk_test_..." \
  -H "Idempotency-Key: fit_ticket_priority_001" \
  -H "Content-Type: application/json" \
  -d '{
    "task_name": "ticket-priority",
    "model": "GQI",
    "X": [
      "checkout fails for every user", "minor copy edit", "refund is stuck",
      "password reset email delayed", "production API is down", "feature request",
      "invoice has the wrong address", "documentation link is broken"
    ],
    "y": [10, 1, 7, 4, 10, 2, 5, 2],
    "config": {}
  }'

The API returns 202 and a job whose ID starts with gqijob_.

2. Poll the job

curl https://gqilabs.com/api/v1/jobs/gqijob_... \
  -H "Authorization: Bearer gqi_sk_test_..."

States are queued, running, retrying, cancel_requested, succeeded, failed, and cancelled. A successful fit contains:

{
  "state": "succeeded",
  "result": {
    "model": {
      "model_id": "ticket-priority-...",
      "revision": "sha256:...",
      "kind": "adapter",
      "base_revision": "sha256:...",
      "uri": "gqi://adapter/..."
    },
    "training_rows": 8,
    "fit_rows": 8,
    "validation_rows": 0,
    "context_length": 512,
    "truncated_rows": 0,
    "optimizer_steps": 1,
    "warnings": []
  }
}

Save result.model exactly as returned. The handle is opaque and immutable.

3. Submit a prediction

curl -X POST https://gqilabs.com/api/v1/predictions \
  -H "Authorization: Bearer gqi_sk_test_..." \
  -H "Idempotency-Key: pred_ticket_priority_001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": {
      "model_id": "ticket-priority-...",
      "revision": "sha256:...",
      "kind": "adapter",
      "base_revision": "sha256:..."
    },
    "X": ["payments fail for every customer"],
    "row_ids": ["ticket-42"],
    "config": {"num_samples": 16, "return_samples": true}
  }'

Poll the returned job in the same way. Its successful result contains one row per input:

{
  "rows": [{
    "row_id": "ticket-42",
    "prediction": 8.75,
    "samples": [8.5, 9.0],
    "finite_samples": 16,
    "iqr": 0.5,
    "input_tokens": 9,
    "truncated": false
  }],
  "context_length": 512,
  "warnings": []
}

prediction is the median of the finite samples. iqr and the saved samples describe decoding spread, not guaranteed error coverage; validate them on a representative holdout.

Configuration

Fit configuration is optional:

Key	Default	Behavior
method	lora	lora or full; full fits return a dedicated handle
learning_rate	managed	1e-7–1e-2
batch_size	token-aware	1–256
effective_batch_size	128	1–4,096
epochs	managed	complete shuffled passes
max_steps	unset	explicit cap; do not combine with epochs
context_length	automatic	512, 1,024, 2,048, or 4,096
seed	0	data order and fitting seed
validation_fraction	0.1	used only for small datasets
rank, alpha	16, 32	LoRA-only adapter configuration

Prediction configuration supports num_samples from 1–32, seed, an optional context bucket, and return_samples.

Initial alpha limits

• 16,384 fit rows and 5,000 prediction rows per request.
• At most 80,000 expanded prediction samples per request.
• Two fits and 50 predictions per account per UTC day.
• One active fit and four active predictions per account.
• Payloads expire after 30 days.

These are safety limits for the initial hosted alpha, not a pricing contract.

Cancellation and evaluation

Cancel a non-terminal job with:

curl -X POST https://gqilabs.com/api/v1/jobs/gqijob_.../cancel \
  -H "Authorization: Bearer gqi_sk_test_..."

Keep labels client-side and calculate R², Spearman, MAE, or task-specific metrics from the returned prediction rows. For temporal, grouped, or entity-linked data, construct the holdout before calling GQI; random row splits can leak future or same-entity information.