{
  "openapi": "3.0.3",
  "info": {
    "title": "Langbly Translation API",
    "description": "Context-aware translation API that is a drop-in replacement for the Google Translate v2 API. Same request and response format, so switching takes one endpoint change and no code rewrite. Supports 100+ languages with translation that reads full sentences instead of word by word.",
    "version": "2.0.0",
    "termsOfService": "https://langbly.com/terms",
    "contact": {
      "name": "Langbly Support",
      "email": "hello@langbly.com",
      "url": "https://langbly.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://langbly.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.langbly.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "API documentation",
    "url": "https://langbly.com/docs"
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Translation",
      "description": "Translate text and detect languages"
    }
  ],
  "paths": {
    "/language/translate/v2": {
      "post": {
        "tags": ["Translation"],
        "summary": "Translate text",
        "description": "Translates one or more strings into the target language. The request and response shape match the Google Translate v2 API.",
        "operationId": "translateText",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TranslateRequest"
              },
              "examples": {
                "single": {
                  "summary": "Single string",
                  "value": {
                    "q": "Hello world",
                    "target": "nl"
                  }
                },
                "batch": {
                  "summary": "Multiple strings",
                  "value": {
                    "q": ["Hello world", "How are you?"],
                    "source": "en",
                    "target": "de",
                    "format": "text"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Translation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranslateResponse"
                },
                "example": {
                  "data": {
                    "translations": [
                      {
                        "translatedText": "Hallo wereld",
                        "detectedSourceLanguage": "en"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/language/translate/v2/detect": {
      "post": {
        "tags": ["Translation"],
        "summary": "Detect language",
        "description": "Detects the language of one or more strings.",
        "operationId": "detectLanguage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DetectRequest"
              },
              "example": {
                "q": "Bonjour le monde"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Detection result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DetectResponse"
                },
                "example": {
                  "data": {
                    "detections": [
                      [
                        {
                          "language": "fr",
                          "isReliable": true,
                          "confidence": 0.98
                        }
                      ]
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/language/translate/v2/languages": {
      "get": {
        "tags": ["Translation"],
        "summary": "List supported languages",
        "description": "Returns the list of supported languages. Pass target to receive language names in that language.",
        "operationId": "listLanguages",
        "parameters": [
          {
            "name": "target",
            "in": "query",
            "required": false,
            "description": "Language code to return the language names in.",
            "schema": {
              "type": "string",
              "example": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Supported languages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LanguagesResponse"
                },
                "example": {
                  "data": {
                    "languages": [
                      { "language": "nl", "name": "Dutch" },
                      { "language": "de", "name": "German" }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Pass your API key as a bearer token: Authorization: Bearer YOUR_API_KEY"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request was malformed or missing required fields.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The API key is missing or invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests. Slow down and retry after a short delay.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "TranslateRequest": {
        "type": "object",
        "required": ["q", "target"],
        "properties": {
          "q": {
            "description": "The text to translate. A single string or an array of strings.",
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "string" } }
            ],
            "example": "Hello world"
          },
          "target": {
            "type": "string",
            "description": "Target language code (ISO 639-1, for example nl, de, fr).",
            "example": "nl"
          },
          "source": {
            "type": "string",
            "description": "Source language code. Omit to auto-detect.",
            "example": "en"
          },
          "format": {
            "type": "string",
            "description": "Whether the text is plain text or HTML. HTML markup is preserved.",
            "enum": ["text", "html"],
            "default": "text"
          },
          "formality": {
            "type": "string",
            "description": "Formality of the translation, where the language supports it.",
            "enum": ["formal", "informal", "neutral"]
          }
        }
      },
      "TranslateResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "translations": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "translatedText": {
                      "type": "string",
                      "example": "Hallo wereld"
                    },
                    "detectedSourceLanguage": {
                      "type": "string",
                      "example": "en"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "DetectRequest": {
        "type": "object",
        "required": ["q"],
        "properties": {
          "q": {
            "description": "The text to detect. A single string or an array of strings.",
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "string" } }
            ],
            "example": "Bonjour le monde"
          }
        }
      },
      "DetectResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "detections": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "language": { "type": "string", "example": "fr" },
                      "isReliable": { "type": "boolean", "example": true },
                      "confidence": { "type": "number", "format": "float", "example": 0.98 }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "LanguagesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "languages": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "language": { "type": "string", "example": "nl" },
                    "name": { "type": "string", "example": "Dutch" }
                  }
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "integer", "example": 400 },
              "message": { "type": "string", "example": "Required parameter target is missing." },
              "status": { "type": "string", "example": "INVALID_ARGUMENT" }
            }
          }
        }
      }
    }
  }
}