openapi: 3.0.3
info:
  title: Miralia.ai Analyses API v2
  contact:
    email: contact@miralia.ai
  description: >
    This is a sample of the Miralia.ai Documentation containing any necessary
    informations to post an

    analysis and get its result with the v2 API of Miralia.ai.


    # Authentication


    The Miralia.ai API is secured by a set of API Keys, and all your API
    requests must be made over

    HTTPS and must be authenticated with these API Keys.


    The API keys will be provided by Miralia.ai. You will have two values: the
    **"Secret Key"** and

    the **"App ID"**.

    - The **"App ID"** allows us to easily identify your integration, and is not
    sensitive
      information. You have to send it as a query parameter, with the name `appId`, so your URLs
      will end with something like `?appId=<YOUR_APP_ID>`.
    - The **"Secret Key"** is the real authorization token, and so is sensitive
    data. You just have
      to use it as the value of the `Authorization` HTTP header.

    # Getting started


    To use our API, you will need to create an analysis. Then, to retrieve the
    result, you can

    either do it the "push-based" way, with webhooks, or the "pull-based" way,
    with other HTTP REST

    calls.


    ## Create an analysis


    You will need to send your message with the

    [`/environment/{environmentId}/analyses`](#tag/Analyses/operation/createAnalysis)
    endpoint. The

    endpoint's documentation contains all details on how to send your message.


    ## Retrieve results with a webhook


    This is the preferred way of retrieving the result: we send the result as
    soon as possible, and

    we know when we delivered the result for sure.


    If you choose to integrate with this way, we will integrate the webhook in
    our configuration.

    When the analysis will be done, Miralia.ai will do a HTTP POST request to an
    URL you defined. You

    can also define a pair of header name and value that we will send alongside
    the request, to

    protect your endpoint.


    For more information on the webhook format, you will have more information
    on the

    [`/analysis/{analysisId}/result`](#tag/Analyses/operation/getAnalysisResult)
    endpoint.


    ## Retrieve results by HTTP REST call


    By using the the
    [`/analysis/{analysisId}/result`](#tag/Analyses/operation/getAnalysisResult)

    endpoint, you will have the same output you would have received by webhook.
  version: 2.0.0
servers:
  - url: https://api.console.miralia.ai
tags:
  - name: Analyses
    description: |
      Create and access ICv2 analyses.
paths:
  /environment/{environmentId}/analyses:
    post:
      operationId: createAnalysis
      tags:
        - Analyses
      summary: Create an analysis
      description: >
        Create an analysis in the environment provided in the path.


        ### The inputs of an analysis


        An analysis is composed of multiple inputs. For each input, you must
        specify:

        - the type of the input: is it the `BODY` (the main content)? An
        `ATTACHMENT` (a file)? Or
          another type for more information? (`TICKET_TOPIC` for example)
        - the content type of the input: is it a file or simply text.


        To specify the inputs, you have to build the `inputs` JSON array. Here
        is an example with

        all kinds of inputs:

        ```json5

        [
          {
            "type": "BODY",
            "contentType": "file",
            "file_key": "file_1"
          },
          // another possibility is to use a text input as the main content
          // but you should have only one BODY input
          {
            "type": "BODY",
            "contentType": "text",
            "text": "Main content to analyse",
            "name": "Main content" // This is optional, but recommended
          },
          // if you have attachments, you can specify them
          {
            "type": "ATTACHMENT",
            "contentType": "file",
            "file_key": "attachment_1"
          },
          {
            "type": "ATTACHMENT",
            "contentType": "file",
            "file_key": "attachment_2"
          },
          // if you have more information that golem must analyse.
          {
            "type": "TICKET_TOPIC",
            "contentType": "text",
            "text": "Ticket topic",
            "name": "TICKET_TOPIC" // This is optional, but recommended
          }
        ]

        ```


        This `inputs` array must be set in the `payload` field of the request.
        The request must be a

        `multipart/form-data` request, and `payload` is mandatory to describe
        the analysis. It

        contains a JSON object, with the `inputs` array, but also other fields,
        namely:

        - `metadata`: a JSON object containing the metadata of the analysis.
        Metadata are data you
          might want to keep around on your analysis, for example to match it back to something on
          your end when you receive the result by webhook.
          - the `inbox` metadata is special: if you have multiple "inboxes" for your messages, you
            should set this field to the inbox of the message. It will open a lot of features in the
            Miralia.ai console.
        - `name`: a string containing the name of the analysis. This is
        optional, and by default is
          set to the filename of the first `BODY` file. If that file has a non-descriptive name, you
          should set this field.
        - `manualFinalStatusUpdate`: a boolean indicating that the success or
        failure of the
          analysis must be confirmed by an external automation. If you're not sure if you need it,
          you don't need it.
        - `inputs`: the array of inputs described above.
      parameters:
        - name: environmentId
          in: path
          description: ID of the environment where the analysis must be created
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Content and settings for this analysis
        content:
          multipart/form-data:
            encoding:
              payload:
                contentType: application/json
            schema:
              example:
                file: ''
                metadata: null
                manualFinalStatusUpdate: false
                payload: >-
                  {"name": "custom-analysis-name", "inputs": [{"type": "BODY",
                  "contentType": "file", "file_key": "file1"}], "metadata":
                  {"inbox": "my_inbox_address@example.com"},
                  "manualFinalStatusUpdate": false}
              type: object
              additionalProperties:
                x-additionalPropertiesName: files
                type: string
                format: binary
                description: >
                  The files you want to upload. The name of the field in the
                  request payload (e.g., `file` or `file1`) must be specified in
                  the `inputs` field of the `payload` parameter.
              properties:
                file:
                  type: string
                  format: binary
                  example: ''
                manualFinalStatusUpdate:
                  type: boolean
                  example: false
                metadata:
                  type: object
                  description: >-
                    Metadata associated to the analysis. If you specify the
                    `inbox` metadata, tools will be available to work with
                    analysis coming from precises inboxes.
                  example: null
                payload:
                  type: string
                  example: >-
                    {"name": "custom-analysis-name", "inputs": [{"type": "BODY",
                    "contentType": "file", "file_key": "file1"}], "metadata":
                    {"inbox": "my_inbox_address@example.com"},
                    "manualFinalStatusUpdate": false}
                  description: >
                    A JSON Object encoded as a string which defines how to
                    create an API.

                    - `inputs` describes the inputs of the analysis. Usually,
                    you don't touch this.

                    - `name` allows overriding the name of the analysis. If not
                    defined, it will use the filename of the BODY file

                    - `metadata` defines the metadata associated to the
                    analysis. Useful for integration purposes. If you specify
                    the `inbox` metadata, tools will be available to work with
                    analyses coming from precises inboxes.
          application/json:
            schema:
              required:
                - text
              type: object
              properties:
                text:
                  type: string
                  example: I would like a coffee with two sugars
                manualFinalStatusUpdate:
                  type: boolean
                  example: false
      responses:
        '201':
          description: Analysis successfully created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 7f8e8725-221d-4128-bdb4-c655d0884ca8
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: number
                    example: 400
                  message:
                    type: string
                    example: Some input is not correct
  /analyses/{analysisId}/result:
    get:
      operationId: getAnalysisResult
      tags:
        - Analyses
      summary: Get the result of an an analysis
      description: >
        Get an analysis result according to a configured flow.


        The result can be overridden by integrations, but unless explicitly told
        so, the result will contain the same payload sent to any webhook.


        The payload is configured on Miralia.ai side. If the output misses some
        information you see here but is absent from the result, it might be a
        misconfiguration.
      parameters:
        - name: analysisId
          in: path
          description: ID of the analysis
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Analysis result queried
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/result'
              examples:
                In progress:
                  description: The analysis is still processing, the result is `null`
                  value:
                    status: IN_PROGRESS
                    result: null
                Finished:
                  description: >-
                    The analysis has finished, the result contains the same data
                    as the webhook payload.
                  value:
                    status: FINISHED
                    result:
                      filename: mail-0123456.eml
                      metadata: []
                      analysisId: 25e625ab-7d91-1234-8a4b-09f52c07ecb9
                      categories:
                        - Convocation
                      extractedData:
                        message:
                          date_rdv:
                            jour: '24'
                            mois: '05'
                            annee: '2025'
                          heure_rdv:
                            heure: '15'
                            minute: '00'
                          reference: '6754679'
                      attachmentsCategories:
                        file.txt:
                          - Autre
                        image.jpg:
                          - Facture
                Finished with a custom result:
                  description: >-
                    The analysis is finished but has a custom result due to some
                    integration
                  value:
                    status: FINISHED
                    result:
                      isJUID:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels: null
                      JUIDbirthdate:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels:
                            - null
                      nationality:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels:
                            - null
                      isStateDiploma:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels: null
                      diplomaDate:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels: null
                      diplomaNumber:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels: null
                      isSpeciality:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels: null
                      birthplace:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels: null
                      isDomicile:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels: null
                      address:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels: null
                      phoneNumber:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels: null
                      mail:
                        - values:
                            - NA
                          filename: null
                          page: null
                          labels: null
  /analyses/{analysisId}/feedback:
    parameters:
      - schema:
          type: string
        name: analysisId
        in: path
        required: true
    post:
      summary: Feedback
      operationId: post-analysis-analysisId-feedback
      responses:
        '204':
          description: No Content
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  $ref: '#/components/schemas/result'
      description: >-
        This route allows a user to send feedback on an analysis. It uses the
        same payload as `/analyses/{analysisId}/result` which the user will need
        to modify to submit the correction. You can use `feedbackURL` in the
        resul's payload to send a feedback on the analysis you queried. 
      tags:
        - Analyses
components:
  securitySchemes:
    Secret_Key:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        provided in the HTTP header `Authorization`, it should be kept
        confidential.
    App_ID:
      type: apiKey
      in: query
      name: appId
      description: >-
        provided in the URL as a query parameter `?appId=<id>`, meant  to
        publicly identify your account, it is not a sensitive information.
  schemas:
    result:
      title: result
      x-stoplight:
        id: mjfkwigrqlepa
      type: object
      properties:
        analysisId:
          type: string
          x-stoplight:
            id: l8arwpoqapxly
        filename:
          type: string
          x-stoplight:
            id: hnwv5614nwaw9
        metadata:
          type: object
          x-stoplight:
            id: xt6l7om5kz0c2
        categories:
          type: array
          x-stoplight:
            id: 3kmw9xoc2rfxs
          description: >-
            The list of categories found for this message. Unless explicitly
            told so, will always be either an empty array or an array with one
            entry.
          items:
            x-stoplight:
              id: kufsyrijjtifk
            type: string
        attachmentsCategories:
          type: object
          x-stoplight:
            id: ei9hj2y41ucap
          description: >-
            A key-value object where keys are attachments' names and values are
            there categories. The same rules applies as for the `categories`
            field.
        extractedData:
          type: object
          x-stoplight:
            id: trkwvvtsn9jlp
          description: >-
            The extracted data. Usually, will contain the `message` and
            `attachments` keys, but can contain a more specific format if
            needed.
          properties:
            message:
              type: object
              x-stoplight:
                id: m4xczi6gl4jxa
              description: The data extracted at the level of the message.
            attachments:
              type: object
              x-stoplight:
                id: vxygfr03wfo3c
              description: >-
                The data extracted at the level of the attachments. The key is
                the attachment name, the value is the extracted data.
        replyTemplate:
          type: string
          x-stoplight:
            id: hyq4xv59dj3r7
          description: The draft generated based on the analysis.
        feedbackURL:
          type: string
          x-stoplight:
            id: palzwnso4xxiy
          description: Use this URL to send feedback on the analysis
      description: Inside the "result" key
security:
  - Secret_Key: []
    App_ID: []
