openapi: "3.0.0"


info:
    title: Math Detective API
    version: 0.30.0.466
    description: |
        # Introduction
        The Math Detective image processing API identifies and transforms images containing math equations into accessible math formats.
        Additionally the Math Detective text processing API identifies and transforms 'ASCII math' strings within XML documents into equivalent MathML.
        
        ## About This Documentation
        The API functionality is documented in [OpenAPI 3.0 format](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md).This
        documentation is created automatically by [Redoc](https://github.com/Rebilly/ReDoc) from the [Math Detective OpenAPI 3.0 spec file](https://oas.dev.mathdetective.ai).
        If you would like to make changes to the OpenAPI spec or possibly this documentation you'll need to request access to [the GitHub repository](https://github.com/benetech/ImageProcessingApi).
        
        ## Authentication
        An API Key is required to access this API. Your API Key must be presented as the value of the x-api-key HTTP header on every request.
        
        ## Software Development Kit (SDK)
        
        ### Java SDK
        There is a Java SDK [available on Benetech's Artifactory instance](https://artifactory.benetech.org/artifactory/webapp/#/artifacts/browse/tree/General/libs-snapshots-benetech/ai/mathdetective/md-java-sdk/0.30.0.466-SNAPSHOT)
        and designed to be consumed as a Maven Artifact. If you have your local Maven installation configured to use Benetech's
        Artifactory instance as a repository you can use the pom.xml snippet below to add the Math Detective Java SDK as a project
        dependency.
        
        #### Maven pom.xml example
        ```
        <dependency>
            <groupId>ai.mathdetective</groupId>
            <artifactId>md-java-sdk</artifactId>
            <version>0.30.0.466-SNAPSHOT</version>
        </dependency>
        ```

        ## Size Constraints

        ### Request Payload Compression
        Clients making use of the Math Detective SDK for Java will have their request payloads gzipped by default. The limits listed below do not
        account for compression.

        ### Request Encoding
        Implementation Note: During request handing the raw bytes are temporarily encoded using base64. In the worst case this encoding can cause the binary body
        to be inflated up to 4/3 its original size. If your binary data was not quite at that limit, with the base64 encoding it may exceed that limit. This will
        manifest as a 502 Bad Gateway error.

        ### Payload Size Constraints
        Due to various architectural constraints the Math Detective API may return an HTTP status code 500 (Internal Server Error)
        instead of the expected status code 413 (Entity Too Large) for requests within a specific size range. The table below details
        the expected HTTP status code based on endpoint and payload size.
        
        | Endpoint | Payload Size Range | HTTP Status Code Returned |
        |----------|--------------------|---------------------------|
        | /image-processing/images | <6MB | Acceptable size, see endpoint documentation for details. |
        | /image-processing/images | >6MB, <10MB | 500 Internal Server Error or 502 Bad Gateway |
        | /image-processing/images | >10MB | 413 Entity Too Large |
        | /image-processing/batches | <256KB | Acceptable size, see endpoint documentation for details. |
        | /image-processing/batches | >256KB, <10MB | 500 Internal Server Error or 502 Bad Gateway |
        | /image-processing/batches | >10MB | 413 Entity Too Large |

        ### Image Size Constraints
        Images larger than 5MB will not be accepted for math equation OCR.

servers:

  - url: https://api.mathdetective.ai/v1
    description: Live environment API endpoint

  - url: https://api.test.mathdetective.ai/v1
    description: Test environment API endpoint

  - url: https://api.dev.mathdetective.ai/v1
    description: Dev environment API endpoint


paths: 

    /image-processing/images:
        post:
            summary: 'Submit an image for processing'
            operationId: submitImage
            tags:
              - ImageProcessing
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ImageProcessingRequest'
            responses:
                '201':
                    description: Response returned after an individual image has been successfully processed
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ImageProcessingResponse'
                    links:
                        GetImageStatusBySha256Sum:
                            description: >
                                The `sha256_sum` value returned in the response can be used as the `sha256_sum`
                                parameter in `GET /image-processing/images/{imageSha256Sum}`.
                            operationId: getImageStatus
                            parameters:
                                imageSha256Sum: $response.body/#/sha256_sum
                '403':
                    description: 'Response returned if you are not authorized to access this resource'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
            x-code-samples:
                $ref: 'images-code-samples.yml#/codeSamples'
                    
    /image-processing/images/{imageSha256Sum}:
        get:
            summary: 'Retrieve image processing status as well as output if it is available'
            operationId: getImageStatus
            tags:
              - ImageProcessing
            parameters:
              - name: imageSha256Sum
                in: path
                required: true
                description: SHA-256 checksum of the image to check the status of
                schema:
                    type: string
            responses:
                '202':
                    description: 'Response returned when an image is still being processed'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ImageProcessingResponse'
                '200':
                    description: 'Response returned after an image has completed processing containing image status and image output'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ImageProcessingResponse'
                    links:
                        GetBatchStatusByUuid:
                            description: >
                                The `batch_uuid` value returned in the response can be used as the `batch_uuid`
                                parameter in `GET /image-processing/batches/{batchUuid}`.
                            operationId: getBatchStatus
                            parameters:
                                batchUuid: $response.body/#/batch_uuid
                '403':
                    description: 'Response returned if you are not authorized to access this resource'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                '404':
                    description: 'Response returned when the requested image SHA-256 checksum could not be found'

    /image-processing/batches:
        post:
            summary: 'Submit an image batch for processing'
            operationId: submitBatch
            tags:
              - ImageProcessing
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/BatchSubmissionRequest'
            responses:
                '201':
                    description: Response returned after a batch has been submitted for processing
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BatchSubmissionResponse'
                '403':
                    description: 'Response returned if you are not authorized to access this resource'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                '413':
                    description: Response returned if a batch request exceeds the maximum allowed size of 256KB
            callbacks:
                batchCompleteWebhook:
                    '{$request.body#/callback/url}':
                        post:
                            requestBody:
                                description: Callback payload containing the batch results
                                content: 
                                    'application/json':
                                        schema:
                                            $ref: '#/components/schemas/BatchStatusResponse'
                            responses:
                                '200':
                                    description: Webhook successfully processed and no retries will be performed

    /image-processing/batches/{batchUuid}:
        get:
            summary: 'Retrieve batch processing status as well as batch output if it is available'
            operationId: getBatchStatus
            tags:
              - ImageProcessing
            parameters:
              - name: batchUuid
                in: path
                required: true
                description: UUID of the batch to check the status of
                schema:
                    type: string
            responses:
                '200':
                    description: 'Response returned when an image batch errored'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BatchStatusResponse'
                '202':
                    description: 'Response returned when an image batch is still being processed'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BatchStatusResponse'
                '303':
                    description: 'Response returned after an image batch has completed containing a presigned s3 redirection url to the batch output'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BatchStatusResponse'
                    headers:
                        'Location':
                            $ref: '#/components/headers/Location'
                '403':
                    description: 'Response returned if you are not authorized to access this resource'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                '404':
                    description: 'Response returned when the requested batch UUID could not be found'
            x-code-samples:
                $ref: 'batches-code-samples.yml#/codeSamples'

    /text-processing/texts:
        post:
            summary: 'Submit a URL to an XML file for processing'
            operationId: submitText
            tags:
              - TextProcessing
            requestBody:
              required: true
              content:
                application/json:
                    schema:
                      $ref: '#/components/schemas/TextProcessingRequest'
            responses:
                '201':
                    description: Response returned after the text has submitted for processing
                    content:
                        applicaiton/json:
                            schema:
                                $ref: '#/components/schemas/TextProcessingResponse'
                '403':
                    description: Response returned if you are not authorized to access this resourse
                    content: 
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                '413':
                    description: Response returned if a text request exceeds the maximum allowed size of 256KB
                

    /text-processing/texts/{textSha256sum}:
         get:
            summary: 'Retrieve text processing status as well as JSON metadata if available'
            operationId: getTextJson
            tags:
              - TextProcessing
            parameters:
              - name: textSha256sum
                in: path
                required: true
                description: sha256sum of the text to check the status of and potentially grab JSON metadata
                schema:
                    type: string
            responses:
                '200':
                    description: 'Response returned when text has errored'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TextStatusResponse'
                '202':
                    description: 'Response returned when a text request is still being processed'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TextStatusResponse'
                '303':
                    description: 'Response returned when a text request has been completed, redirecting to a URL containing the metadata json'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TextStatusResponse'
                '403':
                    description: 'Response returned if you are not authorized to access this resource'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                '404':
                    description: 'Response returned when the requested text sha256sum could not be found'
        
    /text-processing/texts/{textSha256sum}/wrapped:
         get:
            summary: 'Retrieve XML file containing math strings wrapped with uniquely identified tags'
            operationId: getTextXml
            tags:
              - TextProcessing
            parameters:
              - name: textSha256sum
                in: path
                required: true
                description: sha256sum of the text to check the status of and potentially grab XML
                schema:
                    type: string
            responses:
                '200':
                    description: 'Response returned when the XML has succeeded, returns the XML file'
                    content:
                        application/xml:
                            schema:
                                type: string
                                format: binary

                '202':
                    description: 'Response returned when the endpoint is pinged but the XML is not ready'

    /text-processing/strings:
        post:
            summary: 'Submit a string for ascii math identification and classification'
            operationId: submitString
            tags:
              - TextProcessing
            requestBody:
              required: true
              content:
                application/json:
                    schema:
                      $ref: '#/components/schemas/StringProcessingRequest'
            responses:
                '200':
                    description: Response returned after the string has been processed
                    content:
                        applicaiton/json:
                            schema:
                                $ref: '#/components/schemas/StringStatusResponse'
                '403':
                    description: Response returned if you are not authorized to access this resourse
                    content: 
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'


    /text-processing/strings/{stringSha256Sum}:
        get:
            summary: 'Retrieve string processing status as well as output if it is available'
            operationId: getStringStatus
            tags:
              - TextProcessing
            parameters:
              - name: stringSha256Sum
                in: path
                required: true
                description: SHA-256 checksum of the string to check the status of
                schema:
                    type: string
            responses:
                '202':
                    description: 'Response returned when an image is still being processed'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/StringStatusResponse'
                '200':
                    description: 'Response returned after a string has completed processing containing string output'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/StringStatusResponse'
                '403':
                    description: 'Response returned if you are not authorized to access this resource'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UnauthorizedError'
                '404':
                    description: 'Response returned when the requested string SHA-256 checksum could not be found'


components:

    headers:
        Location:
            schema:
                type: string
                description: Redirection URL

    securitySchemes:
        ApiKeyAuth:
            type: apiKey
            in: header
            name: x-api-key

    schemas:
        ImageProcessingRequest:
            required:
              - url
            properties:
                name:
                    type: string
                    example: lena.jpg
                url:
                    description: Supports both http and data URLs for jpeg/png type images
                    type: string
                    example: data:image/jpeg;base64,BASE64_ENCODED_DATA
                skip_ocr:
                    description: Boolean that if set will cause the OCR process to be skipped
                    type: boolean
                    example: false
                force_reprocess:
                    description: Boolean that if set will force the given image to be reprocessed
                    type: boolean
                    example: false

        ImageProcessingResponse:
            properties:
                name:
                    type: string
                sha256_sum:
                    type: string
                labels:
                    type: array
                    items:
                        $ref: "#/components/schemas/Label"
                ocr_confidence:
                    type: number
                    format: float
                mathml:
                    type: string
                latex:
                    type: string
                error:
                    type: string
                    example: null
                status:
                    type: string
                    enum: [running, completed, error]
                    example: running
                spokentext:
                    type: string

        Label:
            description: Object containing a label name and confidence value
            required:
                - name
                - confidence
            properties:
                name:
                    type: string
                    enum: [circle, equation, graph, square, table, triangle, unknown]
                confidence:
                    type: number
                    format: float

        BatchSubmissionRequest:
            properties:
                images:
                    type: array
                    items:
                        $ref: "#/components/schemas/ImageProcessingRequest"
                callback:
                    $ref: "#/components/schemas/HttpCallback"
                smoke_test_flag:
                    description: Boolean to put batch processing into smoke test mode. This is only respected in test environments.
                    type: boolean
                    example: false
                skip_ocr:
                    description: Boolean that if set will cause the OCR process to be skipped. This is generally useful if you want
                    type: boolean
                    example: false
                force_reprocess:
                    description: Boolean that if set will force the given image to be reprocessed
                    type: boolean
                    example: false

        BatchSubmissionResponse:
            required:
              - batch_uuid
            properties:
                batch_uuid:
                    type: string
                    description: UUID of the created image batch

        BatchStatusResponse:
            required:
              - status
            properties:
                batch_uuid:
                    type: string
                    example: c3194755-afa8-40ee-998a-dfc3ac4661b1
                status:
                    type: string
                    enum: [running, completed, errored]
                    example: running
                output:
                    type: array
                    items:
                        $ref: "#/components/schemas/ImageProcessingResponse"

        TextProcessingRequest:
            required: 
                - url
            properties:
                url:
                    description: An http  or base64 encoded data url pointing at an .xml file
                    type: string 
                    example: data:application/xml;base64,BASE64_ENCODED_DATA
                wrap_tag:
                    description: A string indicating what kind of tag should wrap equations in returned xml file. Default is "span".
                    type: string           
        
        TextProcessingResponse:
            required:
                - text_sha256sum
            properties:
                text_sha256sum:
                    type: string
                    description: sha256sum of the text data

        TextStatusResponse:
            required: 
                - status
            properties:
                status:
                    type: string
                    enum: [running, completed, errored]
                    example: running   
                output:
                    type: array
                    items: 
                        $ref: "#/components/schemas/TextStatusResponseItem"

        TextStatusResponseItem:
            required:
                - original_string
                - equations
            properties:
                original_string:
                    type: string
                equations:
                    type: array
                    items:
                        $ref: "#/components/schemas/StringEquationResponseItem"
                sha256_sum:
                    type: string

        StringStatusResponse:
            required:
                - status
            properties:
                status:
                    type: string
                original_string:
                    type: string
                equations:
                    type: array
                    items:
                        $ref: "#/components/schemas/StringEquationResponseItem"
                sha256_sum:
                    type: string

        StringEquationResponseItem:
            required:
                - element
                - bounds
                - conf_score
            properties:
                element:
                    type: string
                bounds:
                    type: array
                    items:
                        type: integer
                conf_score:
                    type: number
                    format: float
                mathml: 
                    type: string
                spokentext:
                    type: string
                tag_id:
                    type: string

        StringProcessingRequest:
            required: 
                - math_string
            properties:
                math_string:
                    description: A string containing ascii math 
                    type: string 

        HttpCallback:
            required:
              - url
            properties:
                url:
                    type: string
                headers:
                    $ref: "#/components/schemas/HttpHeaderMap"

        HttpHeaderMap:
            type: object
            additionalProperties:
                type: string

        UnauthorizedError:
            description: API key is missing or invalid
            properties:
                message:
                    type: string
                    example: Forbidden


security:
  - ApiKeyAuth: [] 
