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 bekomme ich die Ergebnisse in meinen Code?

Nicht über diese API: FERS Cloud führt keinen Solver aus, solve liefert daher einen Link statt Ergebnissen. Rechnen Sie stattdessen dort, wo Ihr Code läuft — mit dem Python-Paket (pip install FERS, dann fers solve model.json), dem JavaScript-Paket im Browser oder in Node oder für einen Agenten mit dem lokalen MCP-Server @ferscloud/fers-mcp. check-beam liefert zusätzlich das erzeugte model, bereit für jeden dieser Wege.

Jeder Endpunkt unten ist aus jeder Sprache über einfaches HTTP aufrufbar, und die vollständige Spezifikation wird als OpenAPI 3.1 für Client-Generatoren und ChatGPT-Custom-GPT-Actions ausgeliefert. Der Server führt keinen Solver aus: solve und check-beam validieren das Modell und liefern einen Link, der es im Browser berechnet. Modellgrößen sind SI-Basiseinheiten.

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"
  }
}

Berechnen

FERS Cloud führt keinen Solver aus. solve validiert das Modell, legt es als öffentlichen Entwurf ab und antwortet mit HTTP 200, status: "solve_in_browser" und einer open_url. Beim Öffnen dieses Links wird das Modell im Browser berechnet, im Tarif des Kontos, das ihn öffnet: kostenlos bis 100 Stäbe, Pro bis 10,000. Der Link bleibt 24 Stunden gültig. Ein Modell, das die Validierung nicht besteht, erhält statt eines Links 422 invalid_model mit den Fehlern.

check-beam baut einen Träger mit seinem Nachweis nach EN 1993-1-1 auf, antwortet genauso und liefert zusätzlich das erzeugte model. Um Ergebnisse im eigenen Code zu erhalten, rechnen Sie dort, wo der Code läuft: mit dem Python-Paket (fers solve model.json), dem JavaScript-Paket oder dem lokalen MCP-Server.

Keiner dieser Endpunkte wird abgerechnet. Es sind die REST-Zwillinge der Werkzeuge solve_model und check_beam des gehosteten MCP-Servers, und sie liefern dieselbe Antwort.

POST /api/sdk/solve — Einen Link erhalten, der ein Modell im Browser berechnet

{
  "description": "Validate a FERS model JSON (SI units: metres, newtons, pascals) and get a link that solves it in a browser. FERS Cloud runs no solver: the model is parked as a public draft for 24 hours and solved by whoever opens open_url, at that account's tier. Not metered. A model that fails validation gets 422 { code: \"invalid_model\", errors, warnings } instead. REST twin of the hosted MCP solve_model tool.",
  "request": {
    "method": "POST",
    "url": "https://ferscloud.com/api/sdk/solve",
    "headers": {
      "X-API-Key": "<keyId>.<secret>"
    },
    "body": {
      "model": "<FERS model JSON object or string>"
    }
  },
  "response": {
    "status": "solve_in_browser",
    "open_url": "https://ferscloud.com/share/<slug>",
    "expires_at": "2026-01-02T00:00:00.000Z",
    "model_ref": "draft_<id>",
    "members": 1,
    "tier": {
      "free_member_limit": 100,
      "free_use": "non-commercial use only",
      "pro_member_limit": 10000,
      "pro_use": "commercial and non-commercial use",
      "solves_at": "the tier of the account that opens the link"
    },
    "validation": {
      "valid": true,
      "warnings": []
    },
    "local_server": {
      "npx": "npx -y @ferscloud/fers-mcp",
      "claude_code": "claude mcp add --transport stdio fers --env FERS_API_KEY=<your key> -- npx -y @ferscloud/fers-mcp",
      "claude_desktop": "https://ferscloud.com/mcp#local",
      "docs": "https://ferscloud.com/mcp#local"
    },
    "python": "pip install FERS && fers solve model.json",
    "note": "This server does not run solves. Open open_url: the model solves in the browser and shows its results there; they are not returned to this chat. For results in the chat, install the local FERS MCP server (local_server) or use the Python SDK. The link lives as long as the draft: 24 hours, or until 50 newer drafts exist."
  }
}

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 — Trägernachweis nach EN 1993-1-1 aufbauen und seinen Berechnungslink erhalten

{
  "description": "Build a single-span steel beam with a ULS combination and its EN 1993-1-1 member check (bending, shear, N+M, lateral-torsional buckling), and get a link that evaluates it in a browser, plus the built model so a caller with the FERS engine can solve it directly. Units: span_m in metres, udl in kN/m, point_load in kN (downward). Not metered. REST twin of the hosted MCP check_beam tool. The request below is 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": {
    "status": "solve_in_browser",
    "open_url": "https://ferscloud.com/share/<slug>",
    "expires_at": "2026-01-02T00:00:00.000Z",
    "model_ref": "draft_<id>",
    "members": 1,
    "tier": {
      "free_member_limit": 100,
      "free_use": "non-commercial use only",
      "pro_member_limit": 10000,
      "pro_use": "commercial and non-commercial use",
      "solves_at": "the tier of the account that opens the link"
    },
    "local_server": {
      "npx": "npx -y @ferscloud/fers-mcp",
      "claude_code": "claude mcp add --transport stdio fers --env FERS_API_KEY=<your key> -- npx -y @ferscloud/fers-mcp",
      "claude_desktop": "https://ferscloud.com/mcp#local",
      "docs": "https://ferscloud.com/mcp#local"
    },
    "python": "pip install FERS && fers solve model.json",
    "note": "This server does not run solves. Open open_url: the model solves in the browser and shows its results there; they are not returned to this chat. For results in the chat, install the local FERS MCP server (local_server) or use the Python SDK. The link lives as long as the draft: 24 hours, or until 50 newer drafts exist.",
    "model": "<the built FERS model: the beam, its ULS combination and the EC3 check>"
  }
}

Ein vollständiger Aufruf

Der Trägernachweis ist der schnellste Weg, den eigenen Schlüssel zu bestätigen: Eine Anfrage baut ein Einfeld mit seinem Nachweis nach EN 1993-1-1 auf und liefert den Link, der ihn auswertet, zusammen mit dem erzeugten Modell.

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

Der Statuscode sagt einem Client, warum ein Aufruf keinen Link geliefert hat, damit er die Eingabe korrigieren kann, statt blind zu wiederholen.

Status	Code	Bedeutung
400	—	Ein Parameter fehlt oder widerspricht sich, oder ein Profil, Werkstoff oder Lager ist unbekannt.
401	—	Fehlende oder ungültige Zugangsdaten.
413	—	Das Modell-JSON überschreitet die Größengrenze.
422	`invalid_model`	Nur `solve`: Das Modell besteht die Validierung nicht. `errors` und `warnings` zeigen, wo.

Nichts wird abgerechnet und es gibt kein Berechnungskontingent, also auch keine Guthaben- oder Kontingentfehler, und eine Wiederholung kostet nichts.

Andere Zugänge

MCP-Server — dieselben Werkzeuge für KI-Agenten, mit einem lokalen Server, der auf Ihrem Rechner rechnet.
JavaScript-Paket — im Browser rechnen, ganz ohne HTTP-Aufruf.
Python-Paket — Modelle mit Objekten statt mit rohem JSON aufbauen und lokal berechnen.

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?

Nichts. Kein Endpunkt wird abgerechnet, und es gibt kein Berechnungskontingent: solve und check-beam liefern einen Link, und die Berechnung läuft in dem Browser, der ihn öffnet. Der Tarif legt Modellgröße und Nutzung fest: kostenlos bis 100 Stäbe für die nicht-kommerzielle Nutzung, Pro bis 10,000 für 19.95 € im Monat, einschließlich kommerzieller Nutzung.

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 bekomme ich die Ergebnisse in meinen Code?

Nicht über diese API: FERS Cloud führt keinen Solver aus, solve liefert daher einen Link statt Ergebnissen. Rechnen Sie stattdessen dort, wo Ihr Code läuft — mit dem Python-Paket (pip install FERS, dann fers solve model.json), dem JavaScript-Paket im Browser oder in Node oder für einen Agenten mit dem lokalen MCP-Server @ferscloud/fers-mcp. check-beam liefert zusätzlich das erzeugte model, bereit für jeden dieser Wege.

Wie lange gilt ein Berechnungslink?

24 Stunden oder bis Sie 50 neuere angelegt haben. Der Link ist öffentlich — jeder, der ihn hat, kann das Modell öffnen —, und die Berechnung läuft im Tarif des Kontos, das ihn öffnet.