FICO publishes substantial Xpress Optimization REST/SDK reference material under fico.com/fico-xpress-optimization/docs/..., but the developer experience is fragmented across multiple parallel docsets, depends on a customer-installed Swagger UI for the canonical spec, hides critical limits and contradictions across pages, and routes its training/community surfaces through a JS-only Salesforce Community shell that doesn't render to non-JS clients (including AI agents and search indexers).
1. No public OpenAPI/Swagger spec — the canonical reference lives only inside customer installs (critical)
Location:/fico-xpress-optimization/docs/latest/insight5/compute/GUID-DBCF30B3-EF31-4BEC-B98F-CA6785F111C9.html and /fico-xpress-optimization/docs/latest/insight5_dev_guide/GUID-93C9E5A2-F2FC-4C18-8EB2-ACF976F64BEB.html
Problem: Both the Compute Interface REST page and the Dev Guide redirect developers to "Live Swagger API documentation [...] available at <INSIGHTURL>/swagger-ui/ on running Insight 5 installations." The Executor 4 REST overview likewise points to a Swagger UI but hosts no spec on fico.com. There is no machine-readable OpenAPI/Swagger file anywhere on the public docs surface.
Consequence: Anyone evaluating Xpress, building a client, or asking an AI agent to scaffold integrations cannot programmatically discover endpoints, schemas, parameters, or error shapes. Third-party indexers (e.g., apitracker.io) advertise "OpenAPI/Swagger specification" support for FICO that doesn't actually exist publicly, propagating misinformation FICO hasn't corrected.
The fix: Publish the Insight 5 and Executor 4 OpenAPI specs at stable URLs (e.g., /fico-xpress-optimization/docs/latest/insight5/openapi.json), link them from every REST overview page, and host a public Swagger UI rendering of them.
2. maxAge token parameter contradicts itself across pages (critical)
Location:/fico-xpress-optimization/docs/latest/insight5/rest_api/tag-Authentication.html vs /fico-xpress-optimization/docs/latest/insight5_dev_guide/GUID-1FC4AD9B-11D3-4457-9DF3-6F8FFAA6874F.html vs /fico-xpress-optimization/docs/latest/insight5/compute/GUID-A0FA6543-4691-4D7D-B4FE-115463A1C205.html
Problem: Three pages disagree about a single auth parameter:
The Authentication REST reference defines maxAge as integer - seconds until token expiration.
The "Generate the Bearer Token" dev guide describes only as "the length of time that the requested token will be valid" — no unit, and the JSON example wraps the value in quotes (), implying a string.
The "Refreshing the Bearer Token" page caps token lifetime at 15 minutes by default and 60 minutes via insight.server.security.rest-token-max-age, but neither generation page mentions the cap or the property.
Consequence: A developer following the dev guide may pass maxAge as a string, request 24h tokens that get silently clamped to 15 minutes, and chase 401s in production with no clue that an admin-side property governs the ceiling. AI agents will pick whichever page they read first and produce broken clients.
The fix: Standardize on integer seconds everywhere, fix the dev guide JSON example to drop quotes, and surface the 15/60-minute ceiling and insight.server.security.rest-token-max-age property on the Generate page, not just the Refresh page.
3. Authentication reference says "no error codes are specified" for the auth endpoints (critical)
Problem: The Authentication resource reference lists GET /api/authentication/current-user, GET /api/authentication/token, and POST /api/authentication/token and explicitly notes "No error codes are specified in the documentation provided." Meanwhile, other resources (Scenarios, Folders, Attachments) document 403/404/422/423 codes, and the Refresh page mentions a 401 will be returned on token expiry.
Consequence: The single most important endpoint to handle correctly — token issuance — has no documented failure modes. A client cannot tell from the reference whether bad credentials yield 401, 403, or 422, whether a malformed clientId is a 400, or what error envelope to parse. Every integrator has to discover this by trial.
The fix: Document the full set of error responses and bodies for each authentication endpoint, including the canonical ErrorResponse/OuterError envelope and HTTP codes for invalid credentials, missing fields, expired tokens, and rate-limit conditions.
4. /api/jobs DELETE overloads three different deletion semantics on one endpoint (critical)
Problem: A single endpoint description reads: "Cancel all jobs, all jobs owned by the current user, or all jobs for a given scenario." The reference page does not specify which query parameters disambiguate the three behaviors, what the default is when no parameter is supplied, or whether an unscoped DELETE /api/jobs will cancel every job in the system.
Consequence: A developer testing "delete my own jobs" can plausibly cancel every running job for every user. This is a footgun on a destructive endpoint, on the most prominent jobs collection — and unlike a 401 you get to debug, this one silently nukes other tenants' work.
The fix: Document each variant separately (or with explicit query-param tables: scenarioId=…, ownedByCurrentUser=true, all=true), state the default, and require confirm=true (or similar) for the unscoped form.
5. Two error-envelope shapes coexist across the same API surface (significant)
Problem: The Folders reference describes an ErrorResponse containing error with code, description, message, timestamp, traceId, spanId, parentId, and additionally describes OuterError/InnerError "hierarchical error structures." The Health-Check page repeats the same OuterError/InnerError shape. The Apps page summarizes "ErrorResponse: Contains error details with codes, descriptions, and trace information" without enumerating fields. The Executor 4 overview says "Error responses contain outer and nested inner errors." There is no central error-model page reconciling the two shapes or stating when each is returned.
Consequence: Clients can't write a single error parser. Generic SDK code that extracts error.message may miss nested inner.error.code, and vice versa. Agents generating retry/backoff logic will guess.
The fix: Add a single canonical "Error responses" page documenting the unified envelope (or both envelopes with a precise rule for which endpoint returns which) and link it from every resource page.
6. Critical limits and platform caveats are scattered, never centralized (significant)
Problem: Hard, integration-breaking constraints live one-page-deep with no cross-reference:
Attachment file size cap (300 MB), max 250 attachments per app/scenario, 1 GB total — only on the Attachments page.
Filename rules (1–255 UTF-16 chars, prohibited \ / ? * : | < > ") — only on the Attachments page.
Compute integration "unavailable on Solaris platforms" and "no migration support for earlier Insight versions" — buried in the Compute Intro.
Community license: solver capped at 5,000 rows+columns combined, 200 vars for QP, 1,000 nonlinear tokens; Insight is Windows-64-only, single-user, no Tableau — only on the marketing license page.
Consequence: A developer planning a 400 MB upload, a Solaris customer planning a Compute migration, or a researcher modeling a 6,000-variable LP under the community license each discovers the blocker after building the wrong thing. There is no "Limits & Quotas" reference to consult.
The fix: Publish a single /docs/latest/limits.html enumerating all size caps, count caps, platform exclusions, and license-tier ceilings, and link it from every relevant resource page.
7. Web Socket lifecycle requirements buried in one page (significant)
Problem: Several reliability-critical websocket constraints exist only on the "Creating the Web Socket Connection" page: the UPDATE_TOKEN message that must be sent before the bearer token expires, the 5-minute ping/pong idle disconnect, the rule that disconnected clients must create a new socket (no reconnection to the same one), and the requirement that the connection-id header be threaded into job submissions to receive progress events. None of these surface on the Jobs reference, the Compute-Jobs reference, or the Authentication pages where a developer building the client would actually look.
Consequence: Clients drop connections in production after 5 minutes of idle, lose progress events because they never wired up connection-id, or attempt to reconnect to a dead socket and silently miss JOB_STATUS_UPDATED messages.
The fix: Cross-reference the websocket lifecycle rules from the Jobs and Compute-Jobs reference pages, and add the UPDATE_TOKEN flow to the Authentication "Refreshing the Bearer Token" page so the token-refresh story is told in one place for both REST and websocket clients.
8. Parallel/stale docsets coexist under different base paths with no version map (significant)
Location:/fico-xpress-optimization/docs/latest/... vs /fico-xpress-optimization/docs/dms2024-03/mosel/Executor/...
Problem: The Mosel Executor authentication page lives under dms2024-03 and references concepts ("DMP Solution," "Client Apps page," executorinit, executorinitlocal()) that do not appear in the latest docs. Meanwhile the latest overview describes "FICO Platform 2026-01" with Insight 5.17, Executor 3 and 4, Solver 9.8.1, and Workbench 3.18 — four products on four version tracks — with no compatibility matrix.
Consequence: A developer searching Google lands on a dms2024-03 page that may be authoritative or obsolete; nothing on the page tells them. AI agents indexing both versions will mix concepts (DMP Solution vs the newer FICO Platform) and emit hybrid, broken instructions.
The fix: Add a banner on every non-latest page indicating it is archived and linking to the current equivalent. Publish a top-level compatibility matrix mapping FICO Platform release → Insight/Executor/Solver/Workbench versions.
Location:/fico-xpress-optimization/docs/latest/executor4/relnotes.html (404) and /fico-xpress-optimization/docs/latest/executor/GUID-A5A6DCDF-... (Executor 3 "What's New")
Problem: REST API Overview lives at executor4/... paths, implying a separate Executor 4 docset, but executor4/relnotes.html returns 404. The Executor 3 "What's New" page lists entries like "Version 3.0.x (February 2024): Executes models using Xpress 9.3.0" and "Version 3.0.x (August 2023)" — literal x placeholders instead of patch numbers — and mixes them in the same list as 3.0.22 (October 2025). Executor 4 release history is nowhere to be found.
Consequence: Developers can't pin to a specific Executor patch version, can't audit what changed when, and can't even find a changelog for the new major version they're being routed to.
The fix: Replace 3.0.x with the actual patch numbers, publish executor4/relnotes.html (or wire the existing redirect to the real GUID page), and link both changelogs from the Executor overview.
10. Compute API has both /api/jobs and /api/compute-jobs with overlapping verbs and no comparison page (significant)
Location:/insight5/rest_api/tag-Jobs.html vs /insight5/rest_api/tag-Compute-jobs.html
Problem: The Insight REST API exposes /api/jobs ("Create a job for a scenario") and/api/compute-jobs ("Create a compute job"). Both have GET/POST/DELETE and messages/{id}/file style sub-paths. Nothing in the resource indexes explains when to use which, what the relationship is, or whether one is preferred for new integrations.
Consequence: Integrators guess. The "deprecated endpoint" note on /api/jobs/{jobId}/messages/{appMessageId}/file hints at evolution but stops there. AI agents scaffolding clients may pick either resource arbitrarily.
The fix: Add a side-by-side resource comparison at the top of both pages explaining: Jobs = Insight scenario jobs; Compute Jobs = Compute Interface direct submissions. Mark deprecations explicitly with replacement endpoints.
11. Workbench Web Services page lists SOAP and REST endpoints with no decision matrix (significant)
Problem: The Workbench "Web Services" index introduces three parallel surfaces — the Insight 5 REST API, "Component Web Services" delivered as "either SOAP or REST endpoints," and "DMN Web Services" — but provides no comparison table, no guidance on which surface serves which use case, and no link from the SOAP mention to any SOAP reference. The same class of problem as the Jobs / Compute-Jobs overlap, but across protocol families.
Consequence: An integrator picking between SOAP and REST has no basis for the choice; an AI agent scaffolding a client will arbitrarily pick whichever it sees a snippet for. The DMN Web Services line ("additional details are available through FICO Platform Web Services documentation") points at no resolvable URL.
The fix: Add a decision matrix at the top of the Web Services page (use case → which API surface → reference link) and link the SOAP and DMN references explicitly.
12. Media-type versioning scheme (vnd.com.fico.xpress.insight.v2+json) is undocumented (significant)
Problem: Every resource page specifies request/response Content-Types like application/vnd.com.fico.xpress.insight.v2+json (Insight) and application/vnd.com.fico.executor.v2+octet-stream, application/vnd.com.fico.executor.v2+json (Executor 4). No page on the public docs surface explains the media-type versioning scheme: what v1 looked like, how +v2 relates to the URL/path versioning ("major.minor … '2.1'"), whether Accept-header negotiation can downgrade to a previous version, what happens when a client sends application/json instead, or how clients should pin a specific minor version.
Consequence: Clients send the wrong Accept header and either get 406s or silently negotiate down. Forward-compatibility guidance ("clients should be lenient to minor changes") gives no concrete rule for how to express that leniency in headers. Agents generating SDK code will guess.
The fix: Publish a single "Media types and versioning" page covering the vnd.com.fico.* family, the relationship between media-type version and URL/path version, header-negotiation behavior, and an explicit policy for pinning vs. floating.
13. "Local authentication" required for several admin endpoints, never defined (significant)
Problem: The User Admin reference annotates several endpoints — including POST /api/admin/users (create user) and DELETE /api/admin/users/{id} (delete user) — with the constraint "requires local authentication" or "local login." Nowhere in the public docs is "local authentication" defined: how it differs from SSO/SAML/OAuth, how an admin running an SSO-only tenant can perform user creation, how to route between local and federated auth at runtime, or whether the bearer token flow is considered "local."
Consequence: Admins on SSO-only deployments hit forbidden errors when calling these endpoints and have no documentation path to resolve it. Integrators building user-provisioning flows can't tell whether they need a separate credential store.
The fix: Define "local authentication" on a top-level Authentication concept page, document how to obtain local credentials when SSO is the primary auth method, and list every endpoint that imposes this constraint in one place.
14. community.fico.com and learn.fico.com are JS-only Salesforce Community shells; non-JS clients see "CSS Error" (significant)
Problem: Every community and learning URL fetched returns only a FICO Community header, a "Loading" indicator, and a "Sorry to interrupt — CSS Error" message. The Platform FAQ, Decision Modeler Overview, and the entire training portal are invisible without a JavaScript-rendering browser.
Consequence: Search indexers, AI agents (Claude Code, Cursor, Copilot indexing pipelines), and accessibility tooling cannot read FICO's official FAQ or training material. The marketing homepage advertises learn.fico.com and community.fico.com as the developer-resource entry points, and both are opaque.
The fix: Render community/learn content server-side, expose a static no-JS fallback for crawlers, or mirror the canonical FAQ/Decision Modeler pages under fico.com/docs/ where they will actually render.
15. No llms.txt, no docs sitemap; robots.txt and sitemap.xml ignore the /docs/ tree (significant)
Problem: Neither llms.txt nor llms-full.txt exists. robots.txt lists eight sitemaps — four fico.com Drupal sitemaps (root, video, blogs, sabf) and four third-party globalsiteseo.com GSM sitemaps — none of which target the /fico-xpress-optimization/docs/ tree. The root sitemap.xml itself is just an index pointing at three Drupal-paginated pages (/default/sitemap.xml?page=1..3). No docs sitemap is referenced anywhere.
Consequence: AI agents have no efficient way to discover or index FICO's developer docs. The most useful content (Xpress REST API, Insight dev guide, Compute Interface guide) is invisible to LLM indexing pipelines that rely on llms.txt conventions or sitemap discovery.
The fix: Publish llms.txt and llms-full.txt enumerating the canonical Xpress doc URLs, add a docs-sitemap.xml covering the /fico-xpress-optimization/docs/latest/... tree, and reference it from robots.txt.
16. index.html and relnotes.html are redirect stubs that break direct linking (significant)
Location:/fico-xpress-optimization/docs/latest/insight5/rest_api/index.html and /fico-xpress-optimization/docs/latest/xpress-relnotes/relnotes.html
Problem: The REST API index.html is a "Redirecting..." stub that points at main.html. The Xpress release notes URL is also just a redirect to a GUID-85032F3B-...html filename. Tools like search engines, AI agents, and human bookmarks pointing at the obvious paths land on a near-empty document.
Consequence: Direct deep-links rot or break. Crawlers may index the redirect stub instead of the real content, and LLMs that fetch index.html get nothing useful.
The fix: Serve the actual content at index.html and relnotes.html (or use HTTP 301 redirects with Location headers, not in-page meta redirects, so crawlers and web_fetch-class tools follow them).
17. "Portation" is used as a primary resource name with no glossary entry (minor)
Problem: The Portations resource page introduces a non-standard noun — "portation" — to describe exports, imports, and upgrades, and uses it as the URL stem (/api/portations/...). Neither the resource page itself nor any platform glossary defines the term, distinguishes it from "import/export," or explains why the API doesn't simply expose /api/exports, /api/imports, and /api/upgrades.
Consequence: Developers have to infer the abstraction from endpoint behavior; AI agents asked to "import an app" won't search for "portation."
The fix: Define "portation" once on the Portations page (or in a shared glossary) and add import/export/upgrade aliases or cross-references so search lands on the right resource.
18. "Generating API Credentials" referenced with no resolvable link (minor)
Problem: The "Authenticating via the REST API" page tells developers that "For details on obtaining Client ID and Client secret credentials, the page directs users to the Generating API Credentials section of the documentation" — but no link is provided from the page itself, and no top-level "Generating API Credentials" page is reachable from the Compute Interface index.
Consequence: Developers reading the auth page top-to-bottom can't follow the bread-crumb to credential setup; they have to search.
The fix: Either inline the credential-generation steps on the auth page or add an explicit hyperlink to the "Generating API Credentials" section.
19. Python client docs hardcode http://localhost:8080/ and document credential storage only for Windows/Mac (minor)
Problem: The xpressinsight.scenario quickstart shows client = ins.InsightRestClient('http://localhost:8080/') (plaintext HTTP) as the default, and tells users credentials are read from "Windows credential manager or Mac keychain using the entry ficoxpress:<insight_server_url>" — with no Linux equivalent (e.g., keyring/libsecret) despite the broader product supporting Linux.
Consequence: Copy-paste users start with insecure HTTP and may keep it. Linux users can't follow the standard credential path at all and aren't told what to do instead.
The fix: Use https:// in all examples, and document the Linux credential-storage path (or the explicit-credential fallback) alongside Windows/Mac.
Problem: A common Drupal-style legal/footer URL on fico.com returns HTTP 404.
Consequence: Inbound links from third-party sites, partner documents, or older FICO marketing assets that target this URL break silently. Trust-related URLs going dead is a bad signal.
The fix: Either restore a legal index page at this path or 301-redirect it to the current legal/terms hub.
21. Inconsistent file-name casing across REST tag files (minor)
Problem: REST tag files mix conventions across compound names: tag-Health-Check.html and tag-User-Admin.html use CamelCase on every word, while tag-Compute-jobs.html and tag-Job-Log-Admin.html lower-case the trailing word. There is no obvious rule, and no case-insensitive redirect is provided for likely typos.
Consequence: Anyone constructing tag URLs by pattern (or any AI agent generating links from the resource list) will guess wrong on a case-sensitive web server and 404.
The fix: Normalize tag-file naming to a single convention (e.g., tag-health-check.html) and serve case-insensitive redirects for legacy URLs.
What they do well
The Insight 5 REST resource pages do publish detailed schemas (Job, Scenario, Attachment, Portation) with parameter types and constraints, which is more than many enterprise vendors expose.
Versioning policy is explicitly stated ("major.minor … breaking changes will not be introduced without a major version change") on multiple pages.
The Attachment resource page documents concrete numeric limits — file size, count, total bytes, filename rules — that competitors often hide.
Top 3 recommendations
Publish a public OpenAPI spec for Insight 5 and Executor 4 at stable URLs, plus a hosted Swagger UI on fico.com, instead of pointing developers at a Swagger that only exists inside running customer installs.
Reconcile the contradictions and centralize the cross-cutting references: unify the maxAge definition, document auth-endpoint error codes, pick one error envelope, define the vnd.com.fico.* media-type versioning scheme, define "local authentication," and add a single limits.html page covering attachments, payload sizes, platform exclusions, and license-tier ceilings.
Make the developer surface readable to non-JS clients: publish llms.txt/llms-full.txt and a docs sitemap, render community.fico.com and learn.fico.com content server-side (or mirror canonical pages under fico.com/docs/), and replace index.html/relnotes.html redirect stubs with real content.