# SDM-1 API

> Proposes the next settings to evaluate, from a parameter space and the values observed so far.

Base URL: `https://api.provigen.ai` · Updated 2026-11-20 · This page: https://provigen.ai/sdm1/api

## Overview

A request states the parameter space and every setting already evaluated with its observed value. The response returns the next settings to evaluate.

| Item | Kind | Notes |
| --- | --- | --- |
| `https://api.provigen.ai` | base url | All paths are relative to it. The service answers over HTTPS only. |
| `POST /v1/propose` | endpoint | The single endpoint of the optimization loop. GET /v1/status and GET /v1/usage report service state and token consumption. |
| `Authorization: Bearer <token>` | required header | On every call to /v1. Tokens are issued by the Get access form on the release page and are held in an environment variable. |
| `Content-Type: application/json` | required header | On POST /v1/propose. The response is JSON in all cases, including errors. |
| `GET / and GET /llms.txt` | no token | A JSON index of the endpoints and limits, and an abridged form of this page carrying a first call. Both are served from the API host, so an agent holding only a token can begin from either. |

Service status; each call counts toward the per-token limit:

```bash
curl https://api.provigen.ai/v1/status -H "Authorization: Bearer $SDM1_TOKEN"
# {"state":"ok"}
```

Four settings proposed in a two-parameter space, from one observed value:

```bash
curl https://api.provigen.ai/v1/propose \
  -H "Authorization: Bearer $SDM1_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "space": [
      {"name": "temperature", "type": "continuous", "low": 20, "high": 80},
      {"name": "catalyst", "type": "categorical", "choices": ["c0", "c1", "c2"]}
    ],
    "history": [{"params": {"temperature": 45, "catalyst": "c1"}, "value": 0.62}],
    "batch": 4,
    "goal": "maximize"
  }'
```

Response:

```json
{
  "proposals": [
    {"params": {"temperature": 71.4, "catalyst": "c0"}},
    {"params": {"temperature": 23.8, "catalyst": "c1"}},
    {"params": {"temperature": 56.1, "catalyst": "c2"}},
    {"params": {"temperature": 79.2, "catalyst": "c0"}}
  ],
  "model": "sdm-1",
  "version": "sdm-1-3f9a0c2b7d41"
}
```

## The optimization loop

A campaign proceeds as a loop: propose, run the experiments, append the measured results, propose again. Three properties of the service determine how that loop is implemented.

- It is stateless. Every call carries the whole history, which is the only state the service works from.
- It is deterministic. An unchanged request returns the same proposals, and a repeated request without new results returns the same batch.
- The history is authoritative. It contains every proposal that was run, including those that failed.

A campaign loop; run_experiment is supplied by the caller:

```python
import os, requests

TOKEN = os.environ["SDM1_TOKEN"]
space = [
    {"name": "temperature", "type": "continuous", "low": 20, "high": 80},
    {"name": "catalyst", "type": "categorical", "choices": ["c0", "c1", "c2"]},
]
history = []

for _ in range(10):
    answer = requests.post(
        "https://api.provigen.ai/v1/propose",
        headers={"Authorization": f"Bearer {TOKEN}"},
        json={"space": space, "history": history, "batch": 4, "goal": "maximize"},
        timeout=60,
    )
    answer.raise_for_status()
    for proposal in answer.json()["proposals"]:
        params = proposal["params"]
        value = run_experiment(params)          # None when the run failed
        history.append({"params": params, "value": value})
```

A first call with an empty history is permitted and returns a starting design.

## Failed runs

A failed run is recorded in the history as null: with one objective, value null; with two or more, values null. The record marks the setting as attempted and infeasible: the model excludes the point from further proposals and uses it to locate the boundaries of the feasible region. The history contains measured runs and failed runs; a run still in progress is submitted once an outcome is available.

Two measured results and one failed run, with one objective:

```json
"history": [
  {"params": {"temperature": 45, "catalyst": "c1"}, "value": 0.62},
  {"params": {"temperature": 72, "catalyst": "c0"}, "value": 0.81},
  {"params": {"temperature": 79, "catalyst": "c2"}, "value": null}
]
```

With two or more objectives there are two distinct cases. A row reporting some objectives and leaving others null counts for the objectives it reports, and those left null count as not measured. A row where every objective is null, and a row whose values is null, are failed runs.

A full result, a partial one and a failed run, with two objectives:

```json
"history": [
  {"params": {"temperature": 35, "time_min": 30},
   "values": {"yield": 0.62, "cost": 0.22}},
  {"params": {"temperature": 50, "time_min": 60},
   "values": {"yield": 0.71, "cost": null}},
  {"params": {"temperature": 70, "time_min": 90}, "values": null}
]
```

Every row carries the key its form requires, with a number or null. Leaving the key out answers 400 naming the row: "history[0]: value is required: a number, or null for a failed run" with one objective, and "history[0]: values is required: an object naming every objective, or null for a failed run" with two or more. The request requires correction before it is sent again.

## Request parameters

POST /v1/propose takes a JSON object of at most 256 KB. Unknown keys anywhere in the body are refused with 400, including "seed", "n" and "bounds".

A request takes one of two forms. One measured outcome per run carries goal, and every history row carries value. Two or more carry objectives, and every history row carries values. The forms are exclusive: a request carrying goal together with objectives is refused with 400, as is one carrying neither.

| Field |  | Rule |
| --- | --- | --- |
| `space` | required | 1 to 24 parameters. Each is {"type": "continuous", "low", "high", "log"?}, {"type": "integer", "low", "high"} or {"type": "categorical", "choices": [...]}. "name" is optional and must be unique; unnamed parameters are x1, x2, … by position. For log, low must be above 0. Categorical choices are distinct strings. |
| `history` | required | Up to 200 rows, every run so far with failed runs included. May be empty. params names exactly every parameter, numbers within [low, high], whole numbers for integer parameters, the exact string for categorical. Each row then carries value with one objective, or values with two or more. |
| `batch` | required | How many settings to propose: 1 to 8. |
| `goal` | one objective | "maximize" or "minimize", the direction for the value in every history row. Present for one measured outcome, and refused alongside objectives. |
| `objectives` | two or more | 2 to 24 entries of {"name"?, "goal", "weight"?, "reference"?}. Unnamed ones are y1, y2, … by position, and names are unique. Every history row then carries values. One measured outcome is sent as goal. |
| `noise` | one objective | How much repeated measurements of the same setting vary, as a standard deviation in the units of value; finite and at least 0, with 0 for exact. Present with goal, and refused alongside objectives. |
| `mode` | two or more | "weighted" (default) or "pareto". Present with objectives, and refused alongside goal. |

The answer is {"proposals": [{"params": {...}}, …], "model": …, "version": …}. Proposal params carry the names from the request, or x1, x2, … for unnamed parameters. version is an opaque identifier of the served model and changes whenever the model changes: the same request with the same version returns the same proposals, which is what makes a campaign reproducible.

## Multiple objectives

Two or more measured outcomes are listed under objectives, each with a goal of its own. Every history row then carries values, an object naming every objective, each a number or null. One measured outcome is sent as goal, with value in every row.

Mode weighted is the default, and there every objective carries a weight above 0: the worth of one unit of that objective against one unit of the others. A weight left out is refused with 400 and the message names the objective, because the trade-off between quantities in different units is stated by the request alone. Mode pareto proposes along every trade-off between the objectives; there weight is refused, and reference, the worst value still worth having, is given for every objective or for none.

Two objectives, maximized and minimized, as one weighted search:

```json
{
  "space": [
    {"name": "temperature", "type": "continuous", "low": 20, "high": 80},
    {"name": "time_min", "type": "integer", "low": 5, "high": 120}
  ],
  "objectives": [
    {"name": "yield", "goal": "maximize", "weight": 10},
    {"name": "cost", "goal": "minimize", "weight": 1}
  ],
  "history": [
    {"params": {"temperature": 35, "time_min": 30},
     "values": {"yield": 0.62, "cost": 0.22}},
    {"params": {"temperature": 50, "time_min": 60},
     "values": {"yield": 0.71, "cost": null}},
    {"params": {"temperature": 70, "time_min": 90}, "values": null}
  ],
  "batch": 2
}
```

The same two objectives along every trade-off, each with a reference:

```json
{
  "space": [
    {"name": "temperature", "type": "continuous", "low": 20, "high": 80},
    {"name": "pressure_bar", "type": "continuous", "low": 1, "high": 10}
  ],
  "objectives": [
    {"name": "yield", "goal": "maximize", "reference": 0},
    {"name": "cost", "goal": "minimize", "reference": 10}
  ],
  "mode": "pareto",
  "history": [
    {"params": {"temperature": 30, "pressure_bar": 8},
     "values": {"yield": 0.5, "cost": 4.0}},
    {"params": {"temperature": 70, "pressure_bar": 2},
     "values": {"yield": 0.9, "cost": 7.5}}
  ],
  "batch": 2
}
```

values names every objective of the request. A name left out, and a name that is not among the objectives, are each refused with 400, the message listing both sets: "history[0]: values must name every objective (missing …, unknown …); null marks an objective not measured". This rule is enforced by the service and cannot be expressed in the schema, since the names are given elsewhere in the same request: a request that validates against the schema alone can still be refused on this ground.

## Usage and quota

GET /v1/usage reports what the token has consumed and what remains. The call counts toward the limit of ten calls a minute and leaves the budget it reports untouched. An agent managing its own rate reads it before a campaign and at intervals during one.

```bash
curl https://api.provigen.ai/v1/usage -H "Authorization: Bearer $SDM1_TOKEN"
```

A trial token:

```json
{
  "tier": "trial",
  "trial": {"used": 7, "limit": 20, "remaining": 13},
  "trial_pool_open_today": true,
  "per_minute": 10
}
```

A confirmed token:

```json
{
  "tier": "full",
  "daily": {"used": 12, "limit": 50, "remaining": 38, "resets_at": "2026-11-18T00:00:00Z"},
  "total": {"used": 120, "limit": 500, "remaining": 380},
  "per_minute": 10
}
```

The route reports on a personal token only. A request made with an environment secret, as this site’s own pages do, receives 403 forbidden.

## Limits

- Parameters: 24. History: 200 rows. Batch: 8. Body: 256 KB.
- Calls: 10 per minute per token. A trial token is allowed 20 calls, counted against the address it was issued to; a confirmed token is allowed 50 per day, resetting at 00:00 UTC, and 500 in total.
- Time: a client timeout of at least 60 seconds is required, and a pending call completes before another is sent. A request that would run past the service's own limit is refused at once with 400, naming the limit; such a request succeeds with fewer parameters, less history or a smaller batch, and fails again unchanged.

## Responses and error handling

| Status | Body | Handling |
| --- | --- | --- |
| 200 | {"proposals": …, "model": …, "version": …} | The proposals are returned. Their measured results are appended to the history for the following call. |
| 400 | {"error": "invalid_request", "message": …} | The request is invalid. The message names the field or the limit; an unchanged body fails again. |
| 401 | {"error": "unauthorized", "message": …, "docs": …} | No Authorization header was sent. The message states where a token is obtained. |
| 403 | {"error": "forbidden", "message": …, "docs": …} | The token is unknown, retired or revoked. A replaced token remains valid for approximately 5 minutes. |
| 404 | {"error": "not_found", "message": …, "docs": …} | The route does not exist. The message states the index from which to start. |
| 429 | {"error": "rate_limited", "retry_after_s": N} | The per-minute limit is reached. The same call succeeds after the Retry-After interval. |
| 429 | {"error": "quota_exceeded", "message": …} | The budget is exhausted. Where retry_after_s is present, the call succeeds after that interval. |
| 503 | {"error": "high_demand", "retry_after_s": N} | The service is under load. The same call succeeds after the Retry-After interval. |
| 503 | {"error": "paused", "retry_after_s": 60} | The model is paused. The same call succeeds once service resumes. |

For unattended operation: 429 and 503 indicate a wait, the Retry-After header stating its length. Every other 4xx is final and requires correction of the request before it is sent again.

Every error body carries a docs field pointing at this contract, so an agent meeting an unfamiliar answer can fetch the whole of it from the answer itself.

## Troubleshooting

### Why does a repeated request return the same settings?

The service is deterministic, so an unchanged request produces an unchanged response. Further settings are proposed for a request whose history carries the values observed in the meantime.

### Why is a setting that has already been evaluated proposed a second time?

A run absent from the history is unknown to the service. A run that failed is recorded as value null with one objective, or as values null with two or more, which marks the setting as evaluated and withholds it from later proposals.

### What causes the message history[0]: value is required, or values is required?

A row of the history states params and omits the key its form requires. With one objective every row carries value: a number for a completed run, and null for a failed one. With two or more every row carries values: an object naming every objective, and null for a failed run.

### What causes the message history[0]: values must name every objective?

The row’s values omits an objective of the request, or names something that is not among them; the message lists the missing names and the unknown ones. Every objective appears as a key, and an objective that was not measured appears with null. A request validated against the schema alone passes this check, because the names are given elsewhere in the same request.

### Is goal sent alongside objectives?

A request carries one of the two: goal for one measured outcome, or objectives for two or more. A request carrying both is refused with 400, the message reading "Send goal for one objective or objectives for two or more, not both." A request carrying neither is refused on the same ground.

### What causes the message weight is required in mode weighted?

An objective carries no weight while the default mode is in force. Every objective carries a weight above 0, stating the worth of one unit of that objective against one unit of the others. A request that states no such trade-off uses mode pareto, where weight is refused and reference is given for every objective or for none.

### What causes the message mode applies with objectives only, or noise applies with goal only?

mode belongs to a request carrying objectives and noise to one carrying goal. Each is refused in the other form.

### How is a key outside the schema handled?

The request is refused with status 400. This applies at every level of the body.

### How are parameters addressed when the entries of space carry no name?

Parameters are addressed as x1, x2 and onward, in the order space gives them, and objectives as y1, y2 and onward. The same identifiers address them in the params object of a history row.

### Which parameter values are refused?

A value outside the interval given by low and high is refused. An integer parameter accepts a whole number, written either as 2 or as 2.0, and refuses 2.5.

### Do calls to /v1/status count toward the rate limit?

Repeated calls to /v1/status count toward the limit of 10 calls a minute.

## Authentication

Tokens are issued by the Get access form on the release page. A token is valid immediately and permits up to 20 calls, counted against the address it was issued to. Opening the confirmation link sent to that address raises the allowance to 50 calls per day, resetting at 00:00 UTC, and 500 calls in total.
