Public beta
Public solver API
Use GroupMixer from scripts and integrations. Get a free account key with 120 compute seconds per day, use 300 seconds per day with your regular Pro subscription, or try ordinary scenarios without a key using the shared anonymous pool.
Working in ChatGPT or another assistant that shows apps? The interactive GroupMixer connector opens the editor in the chat instead of solving headlessly.
- Base URL
- https://api.groupmixer.app/v1
- Compute endpoints
- POST /auto-solve
- Auth
- Optional Bearer API key. Idempotency-Key required for every solve.
One solve endpoint
Send scenario JSON to POST /auto-solve. The server chooses Auto settings and a bounded execution budget.
Fixed compute allowance
Keys share an account allowance of 120 seconds per day on Free or 300 seconds on Pro. Anonymous callers share 600 seconds per day, with 60 seconds per client. Budgets reset at midnight UTC.
Account-owned keys
Create and revoke keys under Account → API access. Keep secrets on your server, never in browser code.
Quickstart
Create a free key under Account → API access after verifying your email. To use the anonymous pool, omit the Authorization header. Use a new, unpredictable Idempotency-Key for each solve and reuse it with the exact request body for retries.
curl -X POST https://api.groupmixer.app/v1/auto-solve \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Idempotency-Key: unique-request-0001' \
-H 'Content-Type: application/json' \
-H 'X-GroupMixer-Caller-Type: ai-agent' \
-H 'X-GroupMixer-Task-Origin: human-delegated' \
-d '{
"schema_version": "v1",
"scenario": {
"people": [
{"id": "alice", "attributes": {}},
{"id": "bob", "attributes": {}}
],
"groups": [{"id": "team-1", "capacity": 2}],
"session_count": 1
}
}'Tell us when an agent is calling
Automated clients can optionally send X-GroupMixer-Caller-Type, X-GroupMixer-Task-Origin, and X-GroupMixer-Agent-Family. Use ai-agent with human-delegated when an agent calls GroupMixer for a task requested by a person. Omit unknown values and never send user, session, prompt, or model identifiers.
Declarations are voluntary aggregate analytics only and never affect solver behavior, access, or quotas. API telemetry stores a coarse client-software family and Cloudflare-derived two-character country code, but not raw IP addresses, raw User-Agent values, or scenario payloads.
Request shape
The request uses the same scenario concepts as the app: people, groups, sessions, objectives, and constraints.
{
"schema_version": "v1",
"scenario": {
"people": [
{"id": "alice", "attributes": {"team": "a"}},
{"id": "bob", "attributes": {"team": "b"}}
],
"groups": [
{"id": "g1", "capacity": 2}
],
"session_count": 1
},
"objectives": [
{"type": "maximize_unique_contacts", "weight": 1.0}
],
"constraints": []
}Response shape
Responses include the solution plus policy and limit metadata so automated callers can branch on observed behavior.
{
"status": "solved",
"solution": {
"schedule": {
"session_0": {
"g1": ["alice", "bob"]
}
},
"unique_contacts": 1,
"total_cost": 0.0,
"repeat_penalty_units": 0,
"attribute_penalty": 0.0,
"other_preference_penalty_units": 0,
"repeat_penalty": 0.0,
"other_preference_penalty": 0.0
},
"policy": {
"policy_id": "hosted_auto",
"solver_family": "auto",
"solver_settings": {
"logging": {
"debug_dump_invariant_context": false,
"debug_validate_invariants": false,
"display_final_schedule": false,
"log_duration_and_score": false,
"log_frequency": null,
"log_initial_score_breakdown": false,
"log_initial_state": false,
"log_stop_condition": false,
"log_total_cost_breakdown": false
},
"move_policy": null,
"mutable_session_indices": null,
"seed": null,
"solver_params": {
"construction_budget_fraction": 0.3,
"extreme_effort": {
"adaptive_tuning": {
"enabled": true,
"max_batch_length_seconds": 300
},
"auto_temperature_target_excess_percent": 100.0,
"batch_length_seconds": 1,
"enabled": false,
"final_temperature": 0.01,
"initial_temperature": 1.0,
"repeat_objective_strategy": "alternate_on_stall",
"settle_after_non_improving_runs": 0,
"temperature_mode": "auto_walk_excess"
},
"max_iterations": 1000000000,
"max_total_budget_seconds": 2.0,
"min_construction_budget_seconds": 0.1,
"min_total_budget_seconds": 1.0,
"no_improvement_grace_seconds": 0.5,
"parallel_lanes": 1,
"scaffold_budget_fraction": 0.3,
"solver_type": "auto",
"total_budget_multiplier": 1.0,
"ultra_extreme_effort": {
"enabled": false,
"extreme_effort": {
"adaptive_tuning": {
"enabled": true,
"max_batch_length_seconds": 300
},
"auto_temperature_target_excess_percent": 100.0,
"batch_length_seconds": 1,
"enabled": false,
"final_temperature": 0.01,
"initial_temperature": 1.0,
"repeat_objective_strategy": "alternate_on_stall",
"settle_after_non_improving_runs": 0,
"temperature_mode": "auto_walk_excess"
},
"growth": {
"step_sessions": 1
},
"ruin_recreate": {
"enabled": true,
"initial_removed_sessions": 1,
"stall_attempts_before_escalation": 5
},
"seed_polish": {
"settle_after_non_improving_runs": 2,
"use_improvement_curve_pruning": true
},
"source_policy": {
"include_general_constructors": true,
"include_pure_sgp_designs": true
}
}
},
"solver_type": "auto",
"stop_conditions": {
"max_iterations": null,
"no_improvement_iterations": null,
"stop_on_optimal_score": true,
"time_limit_seconds": 2
},
"telemetry": {
"best_schedule_every_n_callbacks": 5,
"emit_best_schedule": false
}
},
"used_default_objective": false,
"effective_objectives": [
{"type": "maximize_unique_contacts", "weight": 1.0}
]
},
"limits": {
"quota_scope": "account",
"charged_solve_time_ms": 250,
"remaining_daily_solve_time_ms": 99750,
"max_solve_time_ms": 2000
}
}Retries and privacy
A repeated key recovers a completed response for up to 24 hours without starting another solve. Anonymous retries must come from the same client network identity; use a key for account-scoped recovery. A running or interrupted request returns an explicit conflict. Request scenarios are processed in memory; responses are retained privately for retry recovery and then expire. API keys are stored only as hashes.
Discovery endpoints
Beta limits
Both free tiers follow the ordinary webapp limits. Single-session scenarios can have any size within the request limits below. Multi-session scenarios allow up to 50 active participants, full attendance, and group occupancy limits that stay the same across sessions. Unequal group sizes are supported. Your regular Pro subscription includes Pro API scenarios and 300 compute seconds per account per day, with no separate API purchase.
All tiers accept up to 200 total people, 100 groups, 20 sessions, 200 constraints, and 256 KiB. Auto gets two seconds within a five-second worker limit. One solve runs at a time; Free accounts can start 100 requests per day, Pro accounts 1,000, and anonymous clients 20 per minute. Handle quota and concurrency errors using Retry-After.