API Reference

Quick Start

Send a JSON problem to POST /solve and get back variable assignments. No API key required for the demo tier.

curl -X POST https://solver.fastflowtech.ai/solve \
  -H "Content-Type: application/json" \
  -d '{
  "variables": [
    {"name": "x", "type": "int",
     "domain": {"min": 0, "max": 10}},
    {"name": "y", "type": "int",
     "domain": {"min": 0, "max": 10}}
  ],
  "constraints": [
    {"type": "expression",
     "expression": "x + y <= 15"},
    {"type": "expression",
     "expression": "x > y"}
  ],
  "objective": {
    "target": "x", "goal": "maximize"
  }
}'

{
  "status": "optimal",
  "solution": {
    "x": 10,
    "y": 5
  },
  "stats": {
    "solver": "scip",
    "solve_time_us": 412,
    "routing_reason": "Pure linear arithmetic"
  }
}

Authentication

Requests without authentication use the demo tier (50 variables, 2s timeout, 10 req/min). To unlock higher limits, include an API key or JWT token.

API Key

After subscribing, you'll receive an API key starting with ak_solver-. Include it in the Authorization header:

curl -X POST https://solver.fastflowtech.ai/solve \
  -H "Authorization: Bearer ak_solver-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Alternatively, use the X-Api-Key header: X-Api-Key: ak_solver-your-key-here

JWT (FF Auth)

If your application uses FF Auth, pass the JWT token directly:

curl -X POST https://solver.fastflowtech.ai/solve \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'

JWTs are validated against the FF Auth JWKS endpoint. The tier is determined by the organization's subscription.

Endpoints

Request Format

The request body is a JSON object with variables, constraints, and optional objective and settings fields.

{
  "version": 2,               // optional, defaults to 2
  "variables": [ ... ],      // required
  "constraints": [ ... ],    // required
  "objective": { ... },      // optional
  "settings": { ... }        // optional
}

Variables

Each variable has a name, type, and type-specific fields. Names must match ^[a-zA-Z_]\w*$.

Integer variables

Use domain.min/domain.max for a contiguous range, or domain.intervals for disjoint ranges.

{
  "name": "x",
  "type": "int",
  "domain": { "min": 0, "max": 100 }
}

{
  "name": "shift",
  "type": "int",
  "domain": {
    "intervals": [[0,10], [20,30]]
  }
}

Boolean variables

{ "name": "active", "type": "bool" }

Enum variables

Enums are encoded as integers internally (0-indexed). You can reference values by label in expressions using string syntax: hero == 'dense'.

{
  "name": "hero",
  "type": "enum",
  "values": ["minimal", "dense", "video"]
}

Objective

Optional. Specify a variable to maximize or minimize. Without an objective, the solver finds any feasible assignment (satisfaction mode).

{
  "target": "profit",
  "goal": "maximize"   // or "minimize"
}

Settings

Expression Language

Expressions are strings used in expression and implication constraints. They support arithmetic, comparisons, and built-in functions.

Operators

Functions

Enum Labels

Reference enum values by label using single-quoted strings. The label is resolved to its index before solving.

// Variable: hero with values ["minimal", "dense", "video"]
"hero == 'dense'"      // resolved to: hero == 1
"hero != 'minimal'"   // resolved to: hero != 0

Constraint Types

Each constraint in the constraints array must have a type field. Six types are available:

{ "type": "expression", "expression": "x + y <= 10" }

{ "type": "all_different", "vars": ["a", "b", "c"] }

{
  "type": "implication",
  "if": "hero == 'dense'",
  "then": "density > 5"
}

// At most 2 of these variables can equal 1
{
  "type": "cardinality",
  "mode": "at_most",
  "vars": ["a", "b", "c", "d"],
  "count": 2,
  "value": 1
}

{
  "type": "any_of",
  "constraints": [
    { "type": "expression", "expression": "x <= 5" },
    { "type": "expression", "expression": "y >= 10" }
  ]
}

// Only these (x, y) combinations are allowed
{
  "type": "table",
  "mode": "allowed",
  "vars": ["x", "y"],
  "tuples": [[0,1], [1,0], [2,2]]
}

Solver Routing

Problems are automatically analyzed and routed to the best solver engine. You can override this with settings.solver_hint.

Response Format

{
  "status": "optimal",
  "solution": {
    "x": 10,
    "y": 5,
    "hero": "dense",
    "active": true
  },
  "stats": {
    "solver": "cpsat",
    "solve_time_us": 1234.5,
    "total_time_us": 2500.1,
    "num_variables": 10,
    "num_constraints": 25,
    "routing_reason": "Global constraints detected: all_different",
    "preprocessing": {
      "variables_fixed": 2,
      "domains_tightened": 3,
      "symmetries_broken": 1,
      "constraints_removed": 0,
      "iterations": 2
    }
  }
}

Status Values

Tier Limits

Each tier defines resource limits enforced per request. Exceeding a limit returns a resource_limit error.

Error Handling

Errors are returned with "status": "error" and an errors array. Each error has a type, field, and message.

{
  "status": "error",
  "solution": null,
  "stats": null,
  "errors": [
    {
      "type": "validation",
      "field": "constraints[0].expression",
      "message": "unknown variable: z"
    }
  ]
}

Error Types

Rate Limiting

Rate limits are enforced per organization (or per anonymous client) using a 60-second sliding window. All /solve responses include rate limit headers:

When the rate limit is exceeded, the API returns HTTP 429:

{
  "status": "error",
  "errors": [{
    "type": "rate_limit",
    "field": "request",
    "message": "rate limit exceeded (30/min)"
  }]
}