Skip to main content

​
API architecture & versioning

The Starfire Developer Platform is designed around a versioned API surface so external software can depend on documented contracts without tracking every internal platform refactor.

​
Versioned base

The Alpha developer architecture uses a /v1 resource model. Where the public API is enabled, the intended base is:
This is an Alpha contract. A documented resource family may exist in the platform design before it is enabled for general external use. Check the active developer portal and status surfaces before treating a route as production-ready.

​
Resource families

The v1 architecture groups capabilities by resource rather than exposing one oversized chat endpoint:

​
Compatibility and native APIs

Starfire is designed to support a familiar chat-completions compatibility surface for existing software while also exposing Starfire-native APIs for richer platform concepts. The native surface is important for features such as:
  • long-running runs
  • Deep Research
  • FORGE builds
  • artifacts
  • project-aware work
  • knowledge queries
  • Starfire-specific reasoning and tool modes

​
Request IDs

Developer requests should expose a Starfire request identifier that can be used in logs and support workflows. A request ID gives developers and administrators a shared reference for investigating one exact operation without requiring sensitive request bodies to be copied into support channels.

​
Idempotency

Operations that should not be duplicated—especially build creation and other state-changing actions—can use an idempotency mechanism as the v1 contract is finalized. The goal is simple: retrying a request after a network failure should not accidentally create multiple copies of the same expensive operation.

​
Breaking changes

The versioning rule is:
Starfire can add optional fields or new resources within v1 without redefining existing documented behavior.

​
Deprecation

The developer architecture includes a deprecation model so integrations can receive advance notice of API changes rather than breaking without warning.

Responses & runs

Use native response and long-running job concepts.

Rate limits & errors

Build resilient clients around predictable limits and failure formats.