{
  "openapi": "3.0.1",
  "info": {
    "title": "The Igbo API",
    "description": "An API that enables developers to interact with African language models and fetch Igbo word data",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://igboapi.com/api/v2"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/speech-to-text": {
      "post": {
        "description": "Transcribe Igbo audio to text. Returns a string of text representing the audio passed into the endpoint.",
        "requestBody": {
          "description": "The audio URL to be transcribed is sent in the request body",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "$ref": "#/components/schemas/TranscriptionInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The transcribed Igbo text of the given input",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/TranscriptionOutput"
                }
              }
            }
          }
        }
      }
    },
    "/translate": {
      "post": {
        "description": "Translate text from one language to another. Returns a string of text representing the translation of a given input.",
        "requestBody": {
          "description": "The inputs to the translation model describe what language you're translating from and to",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "$ref": "#/components/schemas/TranslationInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The translated text of the given input",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/TranslationOutput"
                }
              }
            }
          }
        }
      }
    },
    "/words": {
      "get": {
        "description": "Returns requested words from the database",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "description": "Keyword for querying words",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "page",
            "in": "query",
            "description": "Current page of results, the default max number of words on a page is 10",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "range",
            "in": "query",
            "description": "A selected range of words to return, the max range is 25",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "strict",
            "in": "query",
            "description": "Searches strictly for words matching with provided diacritics",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dialects",
            "in": "query",
            "description": "Includes dialect information in each document",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "examples",
            "in": "query",
            "description": "Includes examples associated with each document",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "wordClasses",
            "in": "query",
            "description": "Comma-separated string of word classes that filters words that match the word class (a.k.a. part of speech)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Word response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Word"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/words/{id}": {
      "get": {
        "description": "Returns one requested word from the database",
        "parameters": [
          {
            "name": "dialects",
            "in": "query",
            "description": "Includes dialect information in each document",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "examples",
            "in": "query",
            "description": "Includes examples associated with each document",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "wordClasses",
            "in": "query",
            "description": "Comma-separated string of word classes that filters words that match the word class (a.k.a. part of speech)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Words response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/Word"
                }
              }
            }
          },
          "400": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/examples": {
      "get": {
        "description": "Returns requested examples from the database",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "description": "Keyword for querying words",
            "schema": {
              "type": "string"
            },
            "required": true
          },
          {
            "name": "page",
            "in": "query",
            "description": "Current page of results, the default max number of words on a page is 10",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "range",
            "in": "query",
            "description": "A selected range of words to return, the max range is 25",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "style",
            "in": "query",
            "description": "Style for requested example sentences",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Words response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Example"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/examples/{id}": {
      "get": {
        "description": "Returns one requested example from the database",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Example response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/Example"
                }
              }
            }
          },
          "400": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/nsibidi/{id}": {
      "get": {
        "description": "Returns one requested Nsịbịdị from the database",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Nsịbịdị response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "$ref": "#/components/schemas/Nsibidi"
                }
              }
            }
          },
          "400": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Word": {
        "required": [
          "id",
          "word",
          "wordClass",
          "pronunciation",
          "definitions",
          "attributes",
          "nsibidi"
        ],
        "type": "object",
        "properties": {
          "id": {
            "description": "Id of word",
            "type": "string"
          },
          "word": {
            "description": "The headword",
            "type": "string"
          },
          "wordClass": {
            "description": "The part of speech",
            "type": "string"
          },
          "pronunciation": {
            "description": "Audio URI of word recording",
            "type": "string"
          },
          "definitions": {
            "description": "The English definitions",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "attributes": {
            "description": "The word attributes",
            "type": "object",
            "required": [
              "isStandardIgbo",
              "isAccented",
              "isSlang",
              "isConstructedTerm",
              "isBorrowedTerm",
              "isStem",
              "isCommon"
            ],
            "properties": {
              "isStandardIgbo": {
                "description": "Is the word in Standard Igbo",
                "type": "boolean"
              },
              "isAccented": {
                "description": "Is the word fully accented with diacritic marks",
                "type": "boolean"
              },
              "isSlang": {
                "description": "Is the word slang",
                "type": "boolean"
              },
              "isConstructedTerm": {
                "description": "Is the word newly conceptually created",
                "type": "boolean"
              },
              "isBorrowedTerm": {
                "description": "Is the word a borrowed word from another language",
                "type": "boolean"
              },
              "isStem": {
                "description": "Is the word a stem",
                "type": "boolean"
              },
              "isCommon": {
                "description": "Is the word common in daily usage",
                "type": "boolean"
              }
            }
          },
          "relatedTerms": {
            "description": "Ids of related word documents",
            "type": "string"
          },
          "nsibidi": {
            "description": "Nsịbịdị representation of the text",
            "type": "string"
          },
          "dialects": {
            "description": "Dialectal variations of the word",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Dialect"
            }
          },
          "variations": {
            "description": "Spelling variations of the headword",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "examples": {
            "description": "Associated example Igbo sentences",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Example"
            }
          }
        }
      },
      "Dialect": {
        "type": "object",
        "required": ["word", "dialects", "pronunciation"],
        "properties": {
          "word": {
            "description": "Headword for the dialectal variation",
            "type": "string"
          },
          "dialects": {
            "description": "Enums of dialect regions",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pronunciation": {
            "description": "Audio URI of the dialectal variation",
            "type": "string"
          },
          "variations": {
            "description": "Spelling variations of the dialectal headword",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Example": {
        "required": [
          "id",
          "igbo",
          "english",
          "pronunciation",
          "meaning",
          "style"
        ],
        "type": "object",
        "properties": {
          "id": {
            "description": "Id of word",
            "type": "string"
          },
          "igbo": {
            "description": "The Igbo translation of the sentence",
            "type": "string"
          },
          "english": {
            "description": "The English translation of the sentence",
            "type": "string"
          },
          "pronunciation": {
            "description": "Audio URI of sentence recording",
            "type": "string"
          },
          "meaning": {
            "description": "The conceptual meaning of the sentence in English",
            "type": "string"
          },
          "style": {
            "description": "The style of the sentence",
            "type": "object"
          },
          "associatedWords": {
            "description": "Ids of words present in the sentence",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "nsibidi": {
            "description": "Nsịbịdị representation of the text",
            "type": "string"
          }
        }
      },
      "Nsibidi": {
        "required": [
          "id",
          "nsibidi",
          "definitions",
          "wordClass",
          "pronunciation",
          "radicals"
        ],
        "type": "object",
        "properties": {
          "id": {
            "description": "Id of word",
            "type": "string"
          },
          "nsibidi": {
            "description": "The Nsịbịdị character the sentence",
            "type": "string"
          },
          "definitions": {
            "description": "Definitions of the character",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string"
                }
              }
            }
          },
          "wordClass": {
            "description": "The part of speech",
            "type": "string"
          },
          "pronunciation": {
            "description": "Text representation of character pronunciation",
            "type": "string"
          },
          "radicals": {
            "description": "Ids to other Nsịbịdị character that are radicals",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "TranscriptionInput": {
        "required": ["audioUrl"],
        "type": "object",
        "properties": {
          "audioUrl": {
            "type": "string"
          }
        }
      },
      "TranscriptionOutput": {
        "required": ["transcription"],
        "type": "object",
        "properties": {
          "transcription": {
            "type": "string"
          }
        }
      },
      "TranslationInput": {
        "required": ["text", "sourceLanguageCode", "destinationLanguageCode"],
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "sourceLanguageCode": {
            "type": "string",
            "enum": ["eng", "ibo"]
          },
          "destinationLanguageCode": {
            "type": "string",
            "enum": ["eng", "ibo"]
          }
        }
      },
      "TranslationOutput": {
        "required": ["translation"],
        "type": "object",
        "properties": {
          "translation": {
            "type": "string"
          }
        }
      },
      "Error": {
        "required": ["error", "message"],
        "type": "object",
        "properties": {
          "error": {
            "type": "integer",
            "format": "int32"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}