> ## Documentation Index
> Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# API Architecture & Versioning

> Understand the Starfire AI v1 API resource model, compatibility surface, native APIs, request IDs, and versioning policy.

# 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:

```text theme={null}
https://api.ethanbragdon.icu/v1/
```

<Warning>
  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.
</Warning>

## Resource families

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

```text theme={null}
models
chat/completions
responses
runs
research
files
artifacts
builds
projects
knowledge
embeddings
usage
webhooks
```

## 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:

```text theme={null}
Backward-compatible additions → remain in v1
Breaking contract changes      → new major API version
```

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.

<CardGroup cols={2}>
  <Card title="Responses & runs" icon="play" href="/developers/responses-runs">Use native response and long-running job concepts.</Card>
  <Card title="Rate limits & errors" icon="triangle-exclamation" href="/developers/rate-limits-errors">Build resilient clients around predictable limits and failure formats.</Card>
</CardGroup>