{
  "openapi": "3.0.1",
  "info": {
    "title": "Streaming Speech-To-Text API Documentation",
    "version": "v1",
    "description": "Rev AI Streaming Speech-To-Text API Documentation"
  },
  "servers": [
    {
      "url": "https://api.rev.ai",
      "description": "Rev AI API"
    }
  ],
  "security": [
    {
      "AccessToken": []
    }
  ],
  "tags": [
    {
      "name": "Vocabularies"
    }
  ],
  "paths": {
    "/vocabularies": {
      "post": {
        "summary": "Submit Custom Vocabulary",
        "operationId": "SubmitCustomVocabulary",
        "tags": [
          "Vocabularies"
        ],
        "description": "Submits a Custom Vocabulary for asynchronous processing.\n",
        "requestBody": {
          "description": "Custom Vocabulary Definition",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "type": "object",
                    "required": [
                      "custom_vocabularies"
                    ],
                    "properties": {
                      "metadata": {
                        "description": "Optional metadata that was provided during submission"
                      },
                      "callback_url": {
                        "$ref": "#/components/schemas/CallbackUrlField"
                      },
                      "notification_config": {
                        "$ref": "#/components/schemas/NotificationConfig"
                      },
                      "strict": {
                        "$ref": "#/components/schemas/Strict"
                      }
                    }
                  },
                  {
                    "$ref": "#/components/schemas/CustomVocabulariesProperties"
                  },
                  {
                    "$ref": "#/components/schemas/DescriptionlessMetadataProperties"
                  }
                ]
              },
              "examples": {
                "Example": {
                  "value": {
                    "metadata": "example metadata",
                    "notification_config": {
                      "url": "https://www.example.com/callback",
                      "auth_headers": {
                        "Authorization": "Bearer <token>"
                      }
                    },
                    "custom_vocabularies": [
                      {
                        "phrases": [
                          "Paul McCartney",
                          "Amelia Earhart",
                          "Weiss-Bergman",
                          "BLM"
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/CustomVocabularyDetailsResponse"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestProblemDetails"
                },
                "example": {
                  "parameter": {
                    "custom_vocabularies": [
                      "The custom_vocabularies field is required"
                    ]
                  },
                  "type": "https://www.rev.ai/api/v1/errors/invalid-parameters",
                  "title": "Your request parameters didn't validate",
                  "status": 400
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenDeployment"
          },
          "404": {
            "$ref": "#/components/responses/DeploymentUnsupported"
          }
        }
      },
      "get": {
        "summary": "Get List of Custom Vocabularies",
        "operationId": "GetCustomVocabularies",
        "tags": [
          "Vocabularies"
        ],
        "description": "Gets a list of most recent custom vocabularies' processing information\n",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000
            },
            "required": false,
            "description": "Limits the number of custom vocabulary details returned, default is 100, max is 1000"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/CustomVocabulariesDetailsResponse"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestProblemDetails"
                },
                "example": {
                  "parameter": {
                    "limit": [
                      "The field limit must be between 0 and 1000."
                    ]
                  },
                  "type": "https://www.rev.ai/api/v1/errors/invalid-parameters",
                  "title": "Your request parameters didn't validate",
                  "status": 400
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenDeployment"
          },
          "404": {
            "$ref": "#/components/responses/DeploymentUnsupported"
          }
        }
      }
    },
    "/vocabularies/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/vocabulary_id"
        }
      ],
      "get": {
        "summary": "Get Custom Vocabulary",
        "operationId": "GetCustomVocabulary",
        "tags": [
          "Vocabularies"
        ],
        "description": "Gets the custom vocabulary processing information\n",
        "responses": {
          "200": {
            "$ref": "#/components/responses/CustomVocabularyDetailsResponse"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenDeployment"
          },
          "404": {
            "$ref": "#/components/responses/CustomVocabularyNotFound"
          }
        }
      },
      "delete": {
        "summary": "Delete Custom Vocabulary",
        "operationId": "DeleteCustomVocabulary",
        "tags": [
          "Vocabularies"
        ],
        "description": "Deletes a custom vocabulary. All data related to the custom vocabulary, such as webhooks and metadata, will be permanently deleted. A custom vocabulary can only be deleted once it's completed (either with success or failure).\n",
        "responses": {
          "204": {
            "description": "Custom vocabulary was successfully deleted"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenDeployment"
          },
          "404": {
            "$ref": "#/components/responses/CustomVocabularyNotFound"
          },
          "409": {
            "$ref": "#/components/responses/CustomVocabularyInvalidDeletionState"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AccessToken": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "CustomVocabularyDetails": {
        "type": "object",
        "description": "Custom Vocabulary Details\n***\nNote: properties are not displayed in the returned object if they are null\n",
        "properties": {
          "id": {
            "type": "string",
            "description": "Id of the Custom Vocabulary",
            "example": "cvUmx5c6F7pH7r"
          },
          "status": {
            "type": "string",
            "enum": [
              "in_progress",
              "complete",
              "failed"
            ],
            "description": "Current status of the custom vocabulary",
            "example": "complete"
          },
          "created_on": {
            "type": "string",
            "format": "dateTime",
            "description": "The date and time the custom vocabulary was submitted in ISO-8601 UTC form",
            "example": "2018-05-05T23:23:22.29Z"
          },
          "completed_on": {
            "type": "string",
            "format": "dateTime",
            "description": "The date and time the custom vocabulary was completed on, whether successful or failure, in ISO-8601 UTC form",
            "nullable": true,
            "example": "2018-05-05T23:28:22.29Z"
          },
          "metadata": {
            "type": "string",
            "description": "Optional metadata that was provided during custom vocabulary submission",
            "maxLength": 512,
            "nullable": true,
            "example": "sample metadata"
          },
          "callback_url": {
            "$ref": "#/components/schemas/CallbackUrlField"
          },
          "failure": {
            "type": "string",
            "description": "Simple reason of why the transcription job failed. Check `failure_detail` for specific details and solutions",
            "enum": [
              "internal_processing"
            ],
            "nullable": true,
            "example": "internal_processing"
          },
          "failure_detail": {
            "type": "string",
            "description": "Human-readable reason why the job failed",
            "nullable": true,
            "example": "Failed to process. Please check your url and file type"
          }
        },
        "example": {
          "id": "cvUmx5c6F7pH7r",
          "status": "in_progress",
          "created_on": "2018-05-05T23:23:22.29Z"
        }
      },
      "CustomVocabulariesDetails": {
        "type": "array",
        "description": "List of Custom Vocabularies' Details\n",
        "items": {
          "type": "object",
          "$ref": "#/components/schemas/CustomVocabularyDetails"
        },
        "example": [
          {
            "id": "cvUmx5c6F7pH7r",
            "status": "in_progress",
            "created_on": "2018-05-05T23:23:22.29Z",
            "callback_url": "https://www.example.com/callback"
          },
          {
            "id": "cvx5c6F7pcvUmH",
            "status": "complete",
            "created_on": "2018-05-05T23:23:22.29Z",
            "completed_on": "2018-05-05T23:45:13.41Z",
            "callback_url": "https://www.example.com/callback"
          },
          {
            "id": "cv6F7aspH7rUmx",
            "status": "failed",
            "created_on": "2018-05-05T23:23:22.29Z",
            "completed_on": "2018-05-05T23:23:24.11Z",
            "failure": "internal_processing",
            "failure_detail": "Internal processing failure"
          }
        ]
      },
      "CallbackUrlField": {
        "deprecated": true,
        "type": "string",
        "maxLength": 1024,
        "description": "*Deprecated. Use notification_config instead*. Optional callback url to invoke when processing is complete.\nIf this parameter is used to pass in the callback url, the callback url will be visible in the response.\nIt is recommended to provide webhooks with the `notification_config` parameter as authorization headers can be included\nand both the callback url and auth headers will be encrypted when stored.\n",
        "nullable": true,
        "example": "https://www.example.com/callback"
      },
      "BaseProblemDetails": {
        "type": "object",
        "description": "Problem details object returned on errors",
        "properties": {
          "title": {
            "type": "string",
            "description": "Short, human-readable summary of the problem type"
          },
          "type": {
            "type": "string",
            "description": "URI that identifies the problem"
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code of the error"
          }
        }
      },
      "BadRequestProblemDetails": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseProblemDetails"
          },
          {
            "type": "object",
            "properties": {
              "parameters": {
                "description": "Invalid properties object where each property is the key, mapped to a list of reasons why the property is invalid",
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        ]
      },
      "NotificationConfig": {
        "type": "object",
        "nullable": true,
        "description": "Optional configuration for a callback url to invoke when processing is complete, in addition to auth\nheaders if they are needed to invoke the callback url.\nCannot be set if `callback_url` is set.\nThis option will not be visible in the submission response.\n",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "Optional callback url to invoke when processing is complete",
            "maxLength": 2048,
            "example": "https://www.example.com/callback"
          },
          "auth_headers": {
            "description": "Optional authorization headers, if they are needed to invoke the callback. There are a few constraints: 1) the “Authorization” header is the only header that can be passed in, and 2) the header value must be of the form `<scheme> <token>`. For example: `{\"Authorization\": \"Bearer $BEARER_TOKEN\"}`",
            "type": "object",
            "nullable": true,
            "properties": {
              "Authorization": {
                "type": "string",
                "example": "Bearer <token>"
              }
            },
            "required": [
              "Authorization"
            ],
            "maxLength": 1000
          }
        }
      },
      "Strict": {
        "type": "boolean",
        "example": true,
        "description": "If true, only exact phrases will be used as custom vocabulary, i.e. phrases will not be split into individual words for processing. By default is enabled."
      },
      "CustomVocabulariesField": {
        "type": "array",
        "minItems": 1,
        "maxItems": 50,
        "items": {
          "type": "object",
          "description": "Contains a collection of phrases. Custom vocabulary informs and biases the speech recognition to find those phrases (at the cost of slightly slower transcription).",
          "required": [
            "phrases"
          ],
          "properties": {
            "phrases": {
              "type": "array",
              "minItems": 1,
              "maxItems": 6000,
              "description": "Array of phrases not found in normal dictionary. Add technical jargon, proper nouns and uncommon phrases as strings in this array to add them to the lexicon for this job.\n\nA phrase must contain at least 1 alpha character but may contain any non-numeric character from the Basic Latin set. A phrase can contain up to 12 words. Each word can contain up to 34 characters.\n\n**Note**: Only 6000 phrases can be used per transcription job. For more details, check [Custom Vocabularies](https://docs.rev.ai/api/features/#custom-vocabularies).\n",
              "items": {
                "type": "string",
                "title": "phrase"
              },
              "example": [
                "Paul McCartney",
                "Amelia Earhart",
                "Weiss-Bergman",
                "BLM"
              ]
            }
          }
        }
      },
      "CustomVocabulariesProperties": {
        "type": "object",
        "properties": {
          "custom_vocabularies": {
            "$ref": "#/components/schemas/CustomVocabulariesField"
          }
        }
      },
      "DescriptionlessMetadataProperties": {
        "type": "object",
        "properties": {
          "metadata": {
            "type": "string",
            "maxLength": 512,
            "nullable": true,
            "example": "sample metadata"
          }
        }
      }
    },
    "parameters": {
      "vocabulary_id": {
        "name": "id",
        "in": "path",
        "description": "Id of a custom vocabulary",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "CustomVocabularyDetailsResponse": {
        "description": "Custom Vocabulary Job Details",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/CustomVocabularyDetails"
            },
            "examples": {
              "New Submission for CustomVocabulary": {
                "value": {
                  "id": "cvUmx5c6F7pH7r",
                  "status": "in_progress",
                  "created_on": "2018-05-05T23:23:22.29Z",
                  "callback_url": "https://www.example.com/callback"
                }
              },
              "Complete CustomVocabulary": {
                "value": {
                  "id": "cvUmx5c6F7pH7r",
                  "status": "complete",
                  "created_on": "2018-05-05T23:23:22.29Z",
                  "completed_on": "2018-05-05T23:45:13.41Z",
                  "callback_url": "https://www.example.com/callback"
                }
              },
              "Failed CustomVocabulary": {
                "value": {
                  "id": "cvUmx5c6F7pH7r",
                  "status": "failed",
                  "created_on": "2018-05-05T23:23:22.29Z",
                  "completed_on": "2018-05-05T23:23:24.11Z",
                  "callback_url": "https://www.example.com/callback",
                  "failure": "internal_processing",
                  "failure_detail": "Internal processing failure"
                }
              }
            }
          }
        }
      },
      "CustomVocabulariesDetailsResponse": {
        "description": "List of Custom Vocabularies' Processing Details",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/CustomVocabulariesDetails"
            }
          }
        }
      },
      "CustomVocabularyNotFound": {
        "description": "Custom Vocabulary Not Found",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/BaseProblemDetails"
            },
            "example": {
              "type": "https://www.rev.ai/api/v1/errors/custom-vocabulary-not-found",
              "title": "could not find custom vocabulary",
              "status": 404
            }
          }
        }
      },
      "CustomVocabularyInvalidDeletionState": {
        "description": "Invalid Deletion State",
        "content": {
          "application/problem+json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/BaseProblemDetails"
                },
                {
                  "type": "object",
                  "properties": {
                    "current_value": {
                      "type": "string",
                      "description": "Value passed in given request"
                    },
                    "allowed_values": {
                      "type": "array",
                      "description": "Allowed values for this request",
                      "items": {
                        "type": "string"
                      }
                    },
                    "detail": {
                      "type": "string",
                      "description": "Human-readable explanation specific to this occurrence of the problem"
                    }
                  }
                }
              ]
            },
            "example": {
              "allowed_values": [
                "complete",
                "failed"
              ],
              "current_value": "in_progress",
              "type": "https://rev.ai/api/v1/errors/invalid-custom-vocabulary-state",
              "title": "Custom vocabulary is in invalid state",
              "detail": "Custom vocabulary is in invalid state to be deleted",
              "status": 409
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Request Unauthorized\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "properties": {
                "title": {
                  "type": "string",
                  "description": "Short, human-readable summary of the problem type"
                },
                "status": {
                  "type": "integer",
                  "description": "HTTP status code of the error"
                }
              }
            },
            "example": {
              "title": "Authorization has been denied for this request",
              "status": 401
            }
          }
        }
      },
      "ForbiddenDeployment": {
        "description": "User does not have permission to access this deployment",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/BaseProblemDetails"
            },
            "example": {
              "type": "https://www.rev.ai/api/v1/errors/access-denied",
              "title": "Permisson has been denied for this request - access to this deployment is not allowed",
              "status": 403
            }
          }
        }
      },
      "DeploymentUnsupported": {
        "description": "Deployment does not support this API",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/BaseProblemDetails"
            },
            "example": {
              "type": "https://www.rev.ai/api/v1/errors/unsupported-api",
              "title": "This api is not supported in this deployment",
              "status": 404
            }
          }
        }
      }
    }
  }
}