SveltyCMS dynamically generates the fastest unified OpenAPI 3.1.0 specification in its class. This document acts as the machine-readable “source of truth” for your entire API surface, served through the high-performance unified dispatcher to allow maximum flexibility for complex, multi-client setups.

---

⚡ Quick Access

Feature	Details
JSON Endpoint	GET /api/openapi.json
Specification	OpenAPI 3.1.0
Auth Required	YES (Admin-only: AI Reconnaissance Blinding)
Dispatcher	Unified API Dispatcher (Harmonized Architecture)

---

1. The Goal

Enable Automated SDK Generation and Contract-First Development. By providing a standard OpenAPI spec, SveltyCMS allows developers to generate type-safe clients for any programming language (TypeScript, Python, Go, Rust, etc.) without manually writing HTTP wrappers. The specification is served via the Unified Dispatcher, ensuring perfect parity between documentation and implementation.

---

2. Key Features

🧩 Dynamic Collection Discovery

The specification is not static. Whenever you create a new collection in the Collection Builder, the OpenAPI service (part of the Harmonized API Layer) automatically adds:

• GET /api/collections/{name}: Listing with pagination and filtering.
• POST /api/collections/{name}: Entry creation with full schema validation.
• GET /api/collections/{name}/{id}: Single entry retrieval.
• PATCH /api/collections/{name}/{id}: Partial updates.
• DELETE /api/collections/{name}/{id}: Safe deletion.

🌍 Multilingual Schema Support

For collections with translated fields, the specification accurately describes the multilingual object structure, enabling seamless integration with frontend translation libraries:

"title": {
  "type": "object",
  "additionalProperties": { "type": "string" },
  "description": "Title (Multilingual)"
}
```

### 🛡️ Security Definitions

The spec includes standard security schemes for the **Unified Gatekeeper**:

- **BearerAuth**: JWT-based session tokens.
- **ApiKeyAuth**: Programmatic access via `x-api-key` header.
- **TestSecretAuth**: Secure bypass for CI/automated testing via `x-test-secret`.

---

## 3. How to use it

### A. Automated SDK Generation

Use tools like `openapi-generator-cli` to build a native client in seconds.

```
# Generate a TypeScript Axios client
npx @openapitools/openapi-generator-cli generate \
  -i https://your-cms.com/api/openapi.json \
  -g typescript-axios \
  -o ./src/generated-sdk
```

### B. Interactive Documentation

Import the JSON into tools like **Swagger UI**, **Scalar**, or **Postman** to explore and test your endpoints interactively.

### C. AI Agent Integration

Modern AI coding assistants (like those using the Model Context Protocol) can consume this specification to provide perfect autocomplete and generate integration code for your custom collections.

---

## 🛠 The Mechanics

The `ApiSpecService` introspects your system at runtime:

1. It fetches all active collection definitions via the `ContentSystem`.
2. It maps SveltyCMS widgets to their corresponding JSON Schema types (e.g., `Number` -> `number`, `Date` -> `date-time`).
3. It merges these dynamic paths with static system routes (Auth, Media, Health).
4. It serves the resulting JSON with optimized performance.

---

## Related Documents

- [📚 **Collections Reference**](/docs/reference/api/collections)
- [🔐 **API Access Tokens**](/docs/reference/api/tokens)
- [⚡ **Local SDK vs HTTP API**](/docs/development/local-vs-http-api)