---
title: "HeliosDB OpenAPI 3.0 Specification"
---

# HeliosDB OpenAPI 3.0 Specification

**Version:** 1.0

---

## Overview

```yaml
openapi: 3.0.0
info:
  title: HeliosDB REST API
  version: "1.0"
  description: Multi-protocol database with REST endpoint support
servers:
  - url: https://api.heliosdb.com/v1
    description: Production
  - url: http://localhost:5432/v1
    description: Local Development
```

---

## Authentication

```yaml
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - apiKey: []
  - bearer: []
```

---

## Endpoints

### List Resources

```yaml
/api/{collection}:
  get:
    summary: List resources
    parameters:
      - name: limit
        in: query
        schema:
          type: integer
        description: Number of records
      - name: offset
        in: query
        schema:
          type: integer
        description: Offset for pagination
    responses:
      200:
        description: Success
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Resource'
```

### Create Resource

```yaml
  post:
    summary: Create resource
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceInput'
    responses:
      201:
        description: Created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Resource'
```

### Get Resource

```yaml
/api/{collection}/{id}:
  get:
    summary: Get resource by ID
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    responses:
      200:
        description: Success
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Resource'
      404:
        description: Not found
```

---

## Data Models

```yaml
components:
  schemas:
    Resource:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - name

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
```

---

## Generated Documentation

```bash
# Export OpenAPI spec
curl https://api.heliosdb.com/v1/openapi.json > openapi.json

# Generate client libraries
npm install @openapitools/openapi-generator-cli
openapi-generator-cli generate \
  -i openapi.json \
  -g typescript-axios \
  -o ./client
```

---

## Try It Out

[Interactive API Explorer](https://api.heliosdb.com/docs)

---

**Related Documentation:**