Public beta

Public solver API

GroupMixer now has a free public solver API for scripts, automations, and agent integrations that need automatic scenario solves or compact Social Golfer runs.

OpenAPI JSON Capabilities

Base URL: https://api.groupmixer.app/v1
Compute endpoints: POST /auto-solve
GET /sgp/{instance}/solve
Auth: No account or API key for v1.

Two narrow compute endpoints

Use POST /auto-solve for full scenarios or GET /sgp/{instance}/solve for compact uniform SGP and adjacent-size SGA problems.

Free shared limits

Requests use an anonymous global beta pool with payload, scenario-size, concurrency, and solve-time caps.

Projection, not hidden policy

The SGP endpoint expands terse g-p-w or vN-gG-wW input into normal Auto settings; arbitrary solver settings remain outside the hosted public surface.

Quickstart

Send a scenario and let the public auto policy select a conservative runtime budget, or use the compact SGP endpoint when an agent only needs a Social Golfer-family instance such as 8-4-10 or v34-g8-w10.

auto-solve curl

curl -X POST https://api.groupmixer.app/v1/auto-solve \
  -H 'Content-Type: application/json' \
  -d '{
    "schema_version": "v1",
    "scenario": {
      "people": [
        {"id": "alice", "attributes": {}},
        {"id": "bob", "attributes": {}}
      ],
      "groups": [{"id": "team-1", "size": 2}],
      "num_sessions": 1
    }
  }'

compact SGP curl

# Uniform SGP: 8 groups × 4 people × 10 weeks
curl 'https://api.groupmixer.app/v1/sgp/8-4-10/solve?objective=squared&seed=42'

# Adjacent-size SGA: 34 people, 8 groups, 10 weeks
curl 'https://api.groupmixer.app/v1/sgp/v34-g8-w10/solve?objective=squared&seed=42'

Request shape

The request uses the same scenario concepts as the app: people, groups, sessions, objectives, and constraints.

auto-solve request

{
  "schema_version": "v1",
  "scenario": {
    "people": [
      {"id": "alice", "attributes": {"team": "a"}},
      {"id": "bob", "attributes": {"team": "b"}}
    ],
    "groups": [
      {"id": "g1", "size": 2}
    ],
    "num_sessions": 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.

auto-solve response

{
  "status": "solved",
  "solution": {
    "schedule": {
      "session_0": {
        "g1": ["alice", "bob"]
      }
    },
    "unique_contacts": 1,
    "final_score": 1.0
  },
  "policy": {
    "id": "free_auto_v1",
    "solver_family": "auto"
  },
  "limits": {
    "quota_scope": "anonymous_ip_and_global",
    "per_request_solve_time_ms": 2000
  }
}

Compact SGP endpoint

Social Golfer callers can skip scenario JSON and call GET /sgp/{instance}/solve. Use 8-4-10 for uniform SGP or v34-g8-w10 for adjacent-size SGA; the response keeps quota metadata and returns a zero-based schedule projection that is easy for agents to parse.

sgp response

{
  "status": "solved",
  "result": {
    "instance": "v5-g2-w2",
    "shape": "adjacent",
    "group_size": null,
    "group_sizes": [2, 3],
    "linear_repeat_excess": 0,
    "squared_repeat_excess": 0,
    "schedule": [
      [[0, 1], [2, 3, 4]],
      [[0, 2], [1, 3, 4]]
    ]
  },
  "policy": {
    "projection": "sgp",
    "solver_family": "auto",
    "repeat_objective": "squared"
  }
}

Discovery endpoints

Beta limits

The API is free and anonymous in v1. Per-client/IP request, solve-time, and active-solve limits sit in front of a global daily solve-time pool.

Render free hosting can cold-start. Callers should handle normal HTTP errors, quota exhaustion, rate limits, and retry-after metadata explicitly.