Reference

API Documentation

Everything you need to integrate InstantFocus into your application. RESTful JSON API with Bearer token authentication.

Quick start

terminal
# Install the SDK
npm install @instantfocus/sdk

# Or use the REST API directly
curl -X POST https://api.instantfocus.dev/v1/evaluate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"study_type":"concept_test","stimulus":"Your concept here","audience":{"size":50}}'

Authentication

Bearer token

All authenticated endpoints require a Bearer token in the Authorization header. API keys are prefixed with if_ for easy identification.

headers
{
  "Authorization": "Bearer if_live_abc123...",
  "Content-Type": "application/json"
}

Endpoints

POST/v1/evaluate

Run a synthetic panel study. This is the primary endpoint.

Request body

Field	Type	Required	Description
study_type	string	Yes	One of: concept_test, sentiment, nps, survey, ab_test
stimulus	string	Yes	The product description, copy, or concept to evaluate (max 2000 chars)
stimulus_b	string	ab_test only	Second variant for A/B comparison
questions	string[]	survey only	Array of up to 10 open-ended questions
audience	object	No	Panel configuration (see below). Defaults to 100 personas, US national.

Audience object (optional)

Field	Type	Default	Description
size	number	100	Number of personas (10–10,000)
age_range	[min, max]	[18, 80]	Age range for the panel
gender	string	"all"	all \| male \| female \| nonbinary
region	string	"us_national"	Geographic region
income_bracket	string	"all"	all \| low \| middle \| upper_middle \| high
education	string	"all"	all \| high_school \| bachelors \| graduate
tech_adoption	string	"all"	innovator \| early_adopter \| early_majority \| laggard

GET/v1/health

Service health check. No authentication required.

response
{ "status": "ok", "version": "1.0.0" }

GET/v1/usage

Check current credit balance and usage. Requires Bearer token.

response
{
  "credits_remaining": 4900,
  "credits_used": 100,
  "plan": "free",
  "reset_date": "2026-05-01T00:00:00Z"
}

Response Format

Envelope

All successful responses follow this envelope. Error responses include ok: false and an error object.

success response
{
  "ok": true,
  "data": { /* study-type-specific results */ },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-...",
    "study_type": "concept_test",
    "panel_size": 100,
    "credits_used": 100,
    "credits_remaining": 4900,
    "latency_ms": 3420,
    "_meta": { "generated_by": "ai" }
  }
}

Errors

Status codes

Code	Meaning
200	Success
400	Invalid request body — check study_type and required fields
401	Missing or invalid API key
402	Insufficient credits
429	Rate limit exceeded — wait and retry
500	Internal server error — retry with exponential backoff