{
  "openapi": "3.1.0",
  "info": {
    "title": "Elejo Cloud API",
    "version": "0.2.0",
    "description": "Project-scoped translation, speech-to-text and text-to-speech APIs. Requires an approved cloud entitlement and a configured HTTPS upstream. No model is bundled."
  },
  "paths": {
    "/api/platform/v1/translate": {
      "post": {
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["text", "source", "target"],
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 5000
                  },
                  "source": {
                    "type": "string",
                    "pattern": "^[a-z]{2,3}(?:-[A-Z]{2})?$"
                  },
                  "target": {
                    "type": "string",
                    "pattern": "^[a-z]{2,3}(?:-[A-Z]{2})?$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Translated text",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["translation"],
                  "properties": {
                    "translation": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid key"
          },
          "403": {
            "description": "No entitlement"
          },
          "429": {
            "description": "Rate limited"
          },
          "502": {
            "description": "Upstream failure"
          },
          "503": {
            "description": "Upstream not configured"
          },
          "504": {
            "description": "Upstream timeout"
          }
        }
      }
    },
    "/api/platform/status": {
      "get": {
        "summary": "Read sanitized service and cluster monitoring status",
        "description": "No fabricated metrics. Unknown when monitoring is unreachable. Cached for at most 30 seconds.",
        "responses": {
          "200": {
            "description": "Current configured monitoring targets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["configured", "services", "checkedAt", "note"],
                  "properties": {
                    "configured": {
                      "type": "boolean"
                    },
                    "services": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ServiceStatus"
                      }
                    },
                    "checkedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "note": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/platform/v1/audio/transcriptions": {
      "post": {
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["audioBase64", "mimeType"],
                "properties": {
                  "audioBase64": {
                    "type": "string",
                    "contentEncoding": "base64",
                    "minLength": 4,
                    "maxLength": 6990508,
                    "description": "Canonical Base64 audio, no data URL prefix; decoded audio at most 5 MiB; file signature must match mimeType."
                  },
                  "mimeType": {
                    "type": "string",
                    "enum": ["audio/wav", "audio/mpeg", "audio/ogg", "audio/webm", "audio/mp4"]
                  },
                  "language": {
                    "type": "string",
                    "pattern": "^[a-z]{2,3}(?:-[A-Z]{2})?$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Actual inference output",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["text"],
                  "properties": {
                    "text": {
                      "type": "string",
                      "maxLength": 50000
                    },
                    "language": {
                      "type": "string",
                      "pattern": "^[a-z]{2,3}(?:-[A-Z]{2})?$"
                    },
                    "segments": {
                      "type": "array",
                      "maxItems": 1000,
                      "items": {
                        "type": "object",
                        "required": ["start", "end", "text"],
                        "properties": {
                          "start": {
                            "type": "number",
                            "minimum": 0
                          },
                          "end": {
                            "type": "number",
                            "minimum": 0
                          },
                          "text": {
                            "type": "string",
                            "maxLength": 5000
                          },
                          "speaker": {
                            "type": "string",
                            "maxLength": 80
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid key"
          },
          "403": {
            "description": "Cloud entitlement missing or expired"
          },
          "413": {
            "description": "Request too large"
          },
          "415": {
            "description": "JSON required"
          },
          "429": {
            "description": "Organization or project quota exceeded"
          },
          "502": {
            "description": "Invalid upstream response"
          },
          "503": {
            "description": "Inference upstream not configured"
          },
          "504": {
            "description": "Upstream timeout"
          }
        }
      }
    },
    "/api/platform/v1/audio/speech": {
      "post": {
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["text"],
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 5000
                  },
                  "language": {
                    "type": "string",
                    "pattern": "^[a-z]{2,3}(?:-[A-Z]{2})?$"
                  },
                  "voice": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{1,80}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Actual inference output",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["audioBase64", "mimeType"],
                  "properties": {
                    "audioBase64": {
                      "type": "string",
                      "contentEncoding": "base64",
                      "minLength": 4,
                      "maxLength": 6990508,
                      "description": "Canonical Base64 audio, no data URL prefix; decoded audio at most 5 MiB; file signature must match mimeType."
                    },
                    "mimeType": {
                      "type": "string",
                      "enum": ["audio/wav", "audio/mpeg", "audio/ogg", "audio/webm", "audio/mp4"]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Invalid key"
          },
          "403": {
            "description": "Cloud entitlement missing or expired"
          },
          "413": {
            "description": "Request too large"
          },
          "415": {
            "description": "JSON required"
          },
          "429": {
            "description": "Organization or project quota exceeded"
          },
          "502": {
            "description": "Invalid upstream response"
          },
          "503": {
            "description": "Inference upstream not configured"
          },
          "504": {
            "description": "Upstream timeout"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "ServiceStatus": {
        "type": "object",
        "required": ["id", "name", "region", "status", "checkedAt", "latencyMs", "note"],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "region": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["operational", "degraded", "outage", "unknown"]
          },
          "latencyMs": {
            "type": ["number", "null"],
            "description": "Monitoring endpoint response time, not inference latency."
          },
          "checkedAt": {
            "type": "string",
            "format": "date-time"
          },
          "note": {
            "type": "string"
          },
          "metrics": {
            "type": "object",
            "properties": {
              "healthyNodes": {
                "type": "integer",
                "minimum": 0
              },
              "totalNodes": {
                "type": "integer",
                "minimum": 0
              },
              "queueDepth": {
                "type": "integer",
                "minimum": 0
              },
              "utilization": {
                "type": "number",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        }
      }
    }
  }
}
