REST-API-Referenz

Q: Welche Anmeldeart soll ich verwenden?

Für alles Automatisierte einen API-Schlüssel (X-API-Key). Der Weg über POST /api/sdk/token funktioniert nur für Konten mit E-Mail und Passwort, und das Token läuft nach einer Stunde ab.

Q: Wie vermeide ich doppelte Abrechnung bei einem Wiederholversuch?

Senden Sie einen idempotency_key mit der Berechnungsanfrage. Eine Wiederholung mit demselben Schlüssel liefert das gespeicherte Ergebnis mit meta.replayed: true, statt erneut zu rechnen; eine gleichzeitige Wiederholung liefert 409.

Jeder Endpunkt unten ist aus jeder Sprache über einfaches HTTP aufrufbar. Modellgrößen sind SI-Basiseinheiten — Meter, Newton und Pascal. Die vollständige maschinenlesbare Spezifikation wird als OpenAPI 3.1 ausgeliefert und lässt sich direkt in einen Client-Generator oder eine ChatGPT-Custom-GPT-Action importieren.

Die maschinenlesbare Spezifikation

Die vollständige Spezifikation liegt unter ferscloud.com/api/openapi.json im Format OpenAPI 3.1. Sie wird mit großzügigem CORS ausgeliefert und ist in der robots.txt ausdrücklich freigegeben, Werkzeuge und Agenten können sie also direkt abrufen.

Authentifizieren Sie sich entweder über den Header X-API-Key (ein dauerhafter Schlüssel von Ihrer Profilseite) oder über ein Bearer-Token aus POST /api/sdk/token. Die Schlüsselvariante funktioniert für jede Anmeldeart, die Tokenvariante nur für Konten mit E-Mail und Passwort.

# The complete machine-readable spec (OpenAPI 3.1).
# Import it into ChatGPT Custom GPT Actions, Postman, or a client generator.
curl https://ferscloud.com/api/openapi.json

Anmeldung und API-Schlüssel

Legen Sie einmal einen Schlüssel an, halten Sie ihn serverseitig und senden Sie ihn bei jeder Anfrage als X-API-Key. Schlüssel werden nur bei der Erstellung angezeigt und sind jederzeit widerrufbar.

POST /api/sdk/token — Kurzlebiges JWT abrufen

{
  "description": "Exchange email + password for a 1-hour Bearer token. Requires an email/password account. Google/GitHub users should use an API key (X-API-Key header) instead.",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/token",
    "body": {
      "email": "you@example.com",
      "password": "your_password"
    }
  },
  "response": {
    "token": "<jwt>",
    "expires_at": "2025-01-01T01:00:00Z",
    "is_premium": false,
    "user": {
      "id": "<uuid>",
      "email": "you@example.com"
    }
  }
}

GET /api/sdk/me — Schlüssel prüfen und Nutzerdaten abrufen

{
  "description": "Check the currently authenticated SDK user. Works with both X-API-Key and Bearer token.",
  "request": {
    "method": "GET",
    "url": "https://ferscloud.com/api/sdk/me",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": {
    "user_id": "<uuid>",
    "email": "you@example.com",
    "is_premium": false,
    "token_expires_at": "2026-01-01T01:00:00.000Z"
  }
}

POST /api/sdk/api-keys — Dauerhaften API-Schlüssel anlegen

{
  "description": "Create a named API key (returned once, store it securely). Optionally set expiresInDays for auto-expiry.",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/api-keys",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "name": "My laptop",
      "scopes": [],
      "expiresInDays": null
    }
  },
  "response": {
    "id": "<keyId>",
    "name": "My laptop",
    "key": "<keyId>.<secret>",
    "scopes": [],
    "created_at": "2026-01-01T00:00:00.000Z",
    "expires_at": null,
    "message": "Store this key securely. It will not be shown again."
  }
}

GET /api/sdk/api-keys — API-Schlüssel auflisten

{
  "description": "List all active (non-revoked) API keys. Secrets are never returned.",
  "request": {
    "method": "GET",
    "url": "https://ferscloud.com/api/sdk/api-keys",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": {
    "keys": [
      {
        "id": "<keyId>",
        "name": "My laptop",
        "scopes": [],
        "createdAt": "2026-01-01T00:00:00.000Z",
        "lastUsedAt": null,
        "expiresAt": null
      }
    ]
  }
}

DELETE /api/sdk/api-keys?id=<keyId> — API-Schlüssel widerrufen

{
  "description": "Revoke an API key by its ID. Pass the key ID as a query parameter, not a path segment.",
  "request": {
    "method": "DELETE",
    "url": "https://ferscloud.com/api/sdk/api-keys?id=<keyId>",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": {
    "message": "API key revoked"
  }
}

Solver

solve und check-beam werden abgerechnet: Jeder erfolgreiche Aufruf verbraucht eine Ihrer 100 kostenlosen Wochenberechnungen, danach Guthaben zu 0,01 € je Berechnung. validate ist kostenlos und wird nicht gezählt.

Es sind die REST-Zwillinge der MCP-Werkzeuge solve_model und check_beam, ein Agent und ein Skript treffen also exakt denselben Codepfad.

POST /api/sdk/solve — Den FEM-Solver ausführen

{
  "description": "Solve a FERS model JSON (SI units: metres, newtons, pascals) and get displacements, member forces and reactions. Metered: uses your weekly free solves or prepaid credits (Pro: unlimited). REST twin of the MCP solve_model tool. Errors: 422 solver_error, 402 insufficient_credit, 429 daily_limit / rate_limited, 409 in_flight (same idempotency_key already running).",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/solve",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "model": "<FERS model JSON object or string>",
      "idempotency_key": "optional-unique-id"
    }
  },
  "response": {
    "result": "<solver results: displacements, member forces, reactions, unity checks>",
    "meta": {
      "funding": "free_tier",
      "cost_cents": 0,
      "balance_cents": 0,
      "replayed": false
    }
  }
}

POST /api/sdk/validate — Ein Modell ohne Berechnung prüfen

{
  "description": "Validate a FERS model JSON's structure (required keys, basic integrity) without running the solver. Free and unmetered.",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/validate",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "model": "<FERS model JSON object or string>"
    }
  },
  "response": {
    "valid": false,
    "errors": [
      "Missing required key: \"model.materials\""
    ]
  }
}

POST /api/sdk/check-beam — Schlüsselfertiger Stahlnachweis nach EN 1993-1-1

{
  "description": "Build a single-span steel beam, solve it, and return the EN 1993-1-1 utilizations (bending, shear, N+M, lateral-torsional buckling). Units: span_m in metres, udl in kN/m, point_load in kN (downward). Counts as one solve. REST twin of the MCP check_beam tool. The example below reproduces the published IPE 400 worked example.",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/check-beam",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "span_m": 7.5,
      "section": "IPE400",
      "material": "steel_S355",
      "udl": 13,
      "uls_factor": 1.35,
      "restrained": false
    }
  },
  "response": {
    "check": {
      "section": "IPE400",
      "span_m": 7.5,
      "status": "Yellow",
      "governing_utilization": 0.822,
      "governing_check": "LTB (6.3.2)",
      "passes": true,
      "checks": {
        "Bending z (6.2.5)": 0.266,
        "Shear y (6.2.6)": 0.071,
        "Combined N+M (6.2.1)": 0.266,
        "LTB (6.3.2)": 0.822
      },
      "advice": "Passes (UC 0.822) with lateral-torsional buckling governing. …"
    },
    "meta": {
      "funding": "free_tier",
      "cost_cents": 0,
      "balance_cents": 0,
      "replayed": false
    }
  }
}

Ein vollständiger Aufruf

Der schlüsselfertige Trägernachweis ist der schnellste Weg, den eigenen Schlüssel zu bestätigen — er baut, rechnet und prüft ein Einfeld in einer Anfrage.

curl -X POST https://ferscloud.com/api/sdk/check-beam \
  -H "X-API-Key: <keyId>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "span_m": 7.5,
    "section": "IPE400",
    "material": "steel_S355",
    "udl": 13,
    "uls_factor": 1.35,
    "restrained": false
  }'

Die Einheiten dieses Endpunkts sind pragmatisch statt SI: span_m in Metern, udl in kN/m und point_load in kN nach unten. Die Modell-Endpunkte arbeiten durchgängig in SI.

Gespeicherte Modelle

Die Cloud-Speicherung ist eine Pro-Funktion. Im kostenlosen Tarif halten Sie Modelle als lokales JSON — in genau dem Format, das diese Endpunkte annehmen und zurückgeben.

GET /api/sdk/models — Gespeicherte Modelle auflisten

{
  "description": "List all models saved to the authenticated account",
  "request": {
    "method": "GET",
    "url": "https://ferscloud.com/api/sdk/models",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": {
    "models": [
      {
        "id": "<modelId>",
        "name": "My cantilever",
        "description": null,
        "createdAt": "2025-01-01T00:00:00Z",
        "updatedAt": "2025-01-01T00:00:00Z"
      }
    ]
  }
}

POST /api/sdk/models — Neues Modell speichern

{
  "description": "Save a structural model JSON to your account",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/models",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "name": "My cantilever",
      "description": "5 m IPE 180 cantilever with −1 kN tip load",
      "model": "<model JSON object>"
    }
  },
  "response": {
    "id": "<modelId>",
    "name": "My cantilever",
    "description": "5 m IPE 180 cantilever with −1 kN tip load",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

GET /api/sdk/models/{id} — Ein Modell herunterladen

{
  "description": "Retrieve the full model JSON for a saved model",
  "request": {
    "method": "GET",
    "url": "https://ferscloud.com/api/sdk/models/<modelId>",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": {
    "id": "<modelId>",
    "name": "My cantilever",
    "description": null,
    "model": "<full model JSON object>",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
  }
}

PUT /api/sdk/models/{id} — Ein Modell aktualisieren

{
  "description": "Update the name, description, and/or JSON of an existing model. Send only the fields you want to change.",
  "request": {
    "method": "PUT",
    "url": "https://ferscloud.com/api/sdk/models/<modelId>",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "name": "Updated name"
    }
  },
  "response": {
    "id": "<modelId>",
    "name": "Updated name",
    "description": null,
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-02T00:00:00Z"
  }
}

DELETE /api/sdk/models/{id} — Ein Modell löschen

{
  "description": "Permanently delete a saved model",
  "request": {
    "method": "DELETE",
    "url": "https://ferscloud.com/api/sdk/models/<modelId>",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    }
  },
  "response": "204 No Content"
}

Fehlerantworten

Die abgerechneten Endpunkte unterscheiden über HTTP-Statuscodes, warum ein Aufruf nicht durchlief, damit ein Client gezielt wiederholen kann, statt jeden Fehler gleich zu behandeln.

Status	Code	Bedeutung
422	`solver_error`	Das Modell erreichte den Solver und ließ sich nicht lösen.
402	`insufficient_credit`	Kostenloses Kontingent aufgebraucht und kein Guthaben mehr vorhanden.
429	`daily_limit` / `rate_limited`	Kontingent oder Ratenbegrenzung erreicht. Warten und erneut versuchen.
409	`in_flight`	Eine Anfrage mit demselben `idempotency_key` läuft bereits.

Übergeben Sie solve einen idempotency_key, damit eine wiederholte Anfrage erneut ausgeliefert statt doppelt berechnet wird; meta.replayed in der Antwort sagt Ihnen, was passiert ist.

Andere Zugänge

MCP-Server — dieselben Fähigkeiten als Werkzeuge, die ein KI-Agent direkt aufrufen kann.
JavaScript-Paket — im Browser rechnen, ganz ohne HTTP-Aufruf.
Python-Paket — Modelle mit Objekten statt mit rohem JSON aufbauen.

Siehe auch

Häufige Fragen

Welche Anmeldeart soll ich verwenden?

Für alles Automatisierte einen API-Schlüssel (X-API-Key). Der Weg über POST /api/sdk/token funktioniert nur für Konten mit E-Mail und Passwort, und das Token läuft nach einer Stunde ab.

Welche Einheiten verwendet das Modell-JSON?

SI-Basiseinheiten: Meter, Newton und Pascal; Winkel in Grad. Der Komfort-Endpunkt check-beam ist die Ausnahme — er erwartet Meter, kN/m und kN.

Was kostet ein Aufruf?

100 erfolgreiche Berechnungen je rollierender Woche sind kostenlos. Danach 0,01 € je Berechnung aus dem Guthaben, oder unbegrenzt mit Pro für 19.95 € im Monat. validate und die Schlüssel-Endpunkte werden nie abgerechnet.

Kann ich das in ChatGPT oder Postman importieren?

Ja. /api/openapi.json ist ein vollständiges OpenAPI-3.1-Dokument, ausdrücklich dafür gedacht, als ChatGPT-Custom-GPT-Action oder in ein beliebiges OpenAPI-Werkzeug importiert zu werden.

Wie vermeide ich doppelte Abrechnung bei einem Wiederholversuch?

Senden Sie einen idempotency_key mit der Berechnungsanfrage. Eine Wiederholung mit demselben Schlüssel liefert das gespeicherte Ergebnis mit meta.replayed: true, statt erneut zu rechnen; eine gleichzeitige Wiederholung liefert 409.

Gibt es eine Ratenbegrenzung?

Ja, je Konto und Minute, um eine außer Kontrolle geratene Agentenschleife zu bremsen. Wird sie überschritten, kommt 429 mit rate_limited zurück; warten und erneut versuchen.