miso.ai User APIs API

openapi: 3.2.0
info:
  title: Miso User APIs API
  description: '# Overview

    Miso’s approach to personalization is to train machine learning Engines on three core data sets:


    1.'
  version: 1.1.4
servers:
- url: https://api.askmiso.com
tags:
- name: User APIs
  description: 'Miso’s User APIs let you upload, read, and delete User records that tell Miso about your site’s unique users and

    visitors.'
paths:
  /v1/users:
    post:
      tags:
      - User APIs
      summary: User Upload API
      description: 'Bulk API to insert User records. This API endpoint accepts POST requests with JSON data

        containing a list of User records wrapped in a dictionary.


        ```

        POST /v1/users

        ```


        ```json

        {

        "data": [user_1, user_2, user_3]

        }

        ```


        If a record with the same `user_id` already exists in the dataset, the existing record will

        be replaced (no partial update is allowed at this time). We recommend limiting your calls to

        around 100 records at a time to avoid memory issues or timeout risks.


        ### Schema validation


        This API validates the inserted records against the API schema. Any schema error will cause

        the whole request to fail (`status_code=422`), and none of the records will be inserted. As

        long as the request passes the schema validation, the API will return `status_code=200`, but

        you should still check if there is any error occurring with individual records.


        ```json

        {

        "errors": true,

        "data": [

        "data.0.user_id is invalid. The attribute was expected to be a `string`"

        ]

        }

        ```


        ## Response Format


        The API will return a JSON object with a `task_id` that can be used to retrieve.


        #### Example Successful Response


        ```json

        {

        "data": {

        "task_id": "{task_id}"

        }

        }

        ```


        To check the exact response body of this task_id, make a GET request to the following endpoint:


        ```

        GET /v1/users/_status/{task_id}

        ```


        Replace `{task_id}` with the task_id returned from the response.'
      operationId: user_write_api_v1_users_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBulkIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                'message:': Request timeout.
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                message: invalid api key.
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                message: Request is denied due to bot blocking. Please only access this API from a real browser or use Secret API Key instead.
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              example:
                errors: true
                message: None of the records are inserted, because at least one of them contain schema errors. Please see `data` field for details.
                data:
                - data.0.user_id is invalid. The attribute expected to be of type 'string', but 'array' is given.
                - data.0.created_at is invalid. The attribute should match 'date-time' format.
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                message: Something went wrong. Please contact miso product team.
      security:
      - Secret API Key: []
  /v1/users/{user_id}:
    parameters:
    - name: user_id
      in: path
      required: true
      schema:
        type: string
      description: The ID of the user.
    get:
      tags:
      - User APIs
      summary: User Read API
      description: 'This API endpoint retrieves the details of a specific user using their `user_id`.

        To fetch the user information, make a GET request to the following URL:


        **Notice**: Make sure the user_id is an urlencode string.


        ```

        GET /v1/users/{user_id}

        ```


        Replace `{user_id}` with the unique identifier of the user you wish to fetch.


        ## Response Format


        The API will return the user details in a JSON object if the given `user_id` is valid and

        exists in the system. The JSON object will include fields like `name`, `age`, `city`, `gender`

        , and other user information.


        ### Example Response


        Here''s an example of a successful API response for a user with the `user_id` "user123":


        ```json

        {

        "message": "success",

        "data": {

        "user_id": "user123",

        "name": "johndoe",

        // ... other user details

        }

        }

        ```


        If the provided `user_id` is invalid or does not exist in the system, the API will return an

        error response with a `status_code=404`.


        ### Example Error Response


        ```json

        {

        "message": "not found"

        }

        ```'
      operationId: user_read_api_v1_users__user_id__get
      parameters:
      - required: true
        schema:
          title: Userid
          maxLength: 512
          type: string
        name: userId
        in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserReadOut'
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                message: invalid api key.
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                message: Request is denied due to bot blocking. Please only access this API from a real browser or use Secret API Key instead.
        '404':
          description: User not Found
          content:
            application/json:
              example:
                message: not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                message: Something went wrong. Please contact miso product team.
      security:
      - Secret API Key: []
    delete:
      tags:
      - User APIs
      summary: User Delete API
      description: 'This API endpoint allows you to delete a specific user from the system using their `user_id`.


        **Notice**: Make sure the user_id is an urlencode string.


        To remove a user, make a DELETE request to:


        ```

        DELETE /v1/users/{user_id}

        ```


        Replace `{user_id}` with the unique identifier of the user you wish to delete.


        ## Response Format


        The API will return a JSON object with a `task_id` that can be used to retrieve.


        #### Example Error Response


        ```json

        {

        "message": "deleted",

        "data": {

        "task_id": "{task_id}"

        }

        }

        ```


        To check the exact response body of this task_id, make a GET request to the following endpoint:


        ```

        GET /v1/users/_status/{task_id}

        ```


        Replace `{task_id}` with the task_id returned from the response.'
      operationId: user_delete_api_v1_users__user_id__delete
      parameters:
      - required: true
        schema:
          title: User Id
          maxLength: 512
          type: string
        name: user_id
        in: path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                'message:': Request timeout.
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                message: invalid api key.
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                message: Request is denied due to bot blocking. Please only access this API from a real browser or use Secret API Key instead.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                message: Something went wrong. Please contact miso product team.
      security:
      - Secret API Key: []
  /v1/users/_delete:
    post:
      tags:
      - User APIs
      summary: User Bulk Delete API
      description: 'This API endpoint allows you to delete multiple users by providing their user_ids.


        To delete multiple users, make a POST request to the following URL:


        ```

        POST /v1/users/_delete

        ```


        The request body should contain a JSON object with an array of user_ids:


        ```json

        {

        "data": {

        "user_ids": [

        "product-1",

        "product-2",

        // ... more product_ids to delete

        ]

        }

        }

        ```


        ## Response Format


        The API will return a JSON object with a `message` and an array of `data`

        containing a `task_id` that can be used to get the status of the bulk deletion process.


        #### Example Successful Response


        ```json

        {

        "message": "deleted",

        "data": {

        "task_id": "{task_id}"

        }

        }

        ```


        To check the exact response body of this task_id, make a GET request to the following endpoint:


        ```

        GET /v1/users/_status/{task_id}

        ```


        Replace `{task_id}` with the task_id returned from the response.'
      operationId: user_bulk_delete_api_v1_users__delete_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBulkDeleteIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                'message:': Request timeout.
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                message: invalid api key.
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                message: Request is denied due to bot blocking. Please only access this API from a real browser or use Secret API Key instead.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                message: Something went wrong. Please contact miso product team.
      security:
      - Secret API Key: []
components:
  schemas:
    UserBulkDeleteIn:
      title: UserBulkDeleteIn
      required:
      - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/UserIdList'
    CreateResponse:
      title: CreateResponse
      required:
      - message
      - data
      type: object
      properties:
        message:
          title: Message
          type: string
          description: Human-readable message
          example: success
        data:
          $ref: '#/components/schemas/TaskId'
    UserReadOut:
      title: UserReadOut
      required:
      - message
      - data
      type: object
      properties:
        message:
          title: Message
          type: string
          description: Human-readable message
          example: success
        data:
          $ref: '#/components/schemas/UserRecord'
    TaskId:
      title: TaskId
      required:
      - task_id
      type: object
      properties:
        task_id:
          title: Task Id
          type: string
    DeleteResponse:
      title: DeleteResponse
      required:
      - message
      - data
      type: object
      properties:
        message:
          title: Message
          type: string
          description: Human-readable message
          example: success
        data:
          $ref: '#/components/schemas/TaskId'
    UserRecord:
      title: UserRecord
      required:
      - user_id
      type: object
      properties:
        user_id:
          title: User Id
          maxLength: 512
          minLength: 1
          type: string
          description: "\nUnique identifier for a user who has signed in. `user_id` can be in any format (e.g. users' email, internal user\nUUID or serial ID). The only restriction is that the first character must not be an underline `_`. Miso will use \nthis id to cross-reference your User records with your Interaction records.\n"
          example: user_1234
        created_at:
          title: Created At
          anyOf:
          - type: string
            format: date-time
          - type: string
            format: date
          description: "\nThe date the user’s account was created as an ISO-8601 date or datetime string. \n"
        updated_at:
          title: Updated At
          anyOf:
          - type: string
            format: date-time
          - type: string
            format: date
          description: "\nThe date the user’s account was updated as an ISO-8601 date or datetime string. \n"
        name:
          title: Name
          type: string
          description: The user's full name.
          example: John Doe
        profile_image:
          title: Profile Image
          maxLength: 65536
          minLength: 1
          type: string
          description: URL to the profile image of the user.
          format: uri
        age:
          title: Age
          type: integer
          description: Age of the user. We will internally convert it to year of birth.
          example: 33
        gender:
          title: Gender
          type: string
          description: The user's gender.
          example: M
        city:
          title: City
          type: string
          description: City or zipcode the user is based in.
          example: Mountain View
        state:
          title: State
          type: string
          description: State the user is based in.
          example: California
        country:
          title: Country
          type: string
          description: Country the user is based in.
          example: US
        group_id:
          title: Group Id
          type: string
          description: "\nGroup or Account ID from your CRM. This is useful in B2B scenarios. For example, you can use `group_id` to \nassociate a user with their company or account. We will use this information to infer the user's interests and \nfine-tune their personalization and search results. For example, users from the same group might have similar \ninterests on the site, and we can improve their user experience accordingly\n"
          example: Northwind Corp
        description:
          title: Description
          type: string
          description: "\nText description of the user. This can be the user's own bio or the internal notes about the user. If available,\nMiso will analyze this description to better profile a user.  \n"
          example: Engineer from Northwind Corp
        custom_attributes:
          title: Custom Attributes
          type: object
          additionalProperties:
            anyOf:
            - type: boolean
            - type: integer
            - type: number
            - type: string
            - type: array
              items:
                type: number
            - type: array
              items:
                type: string
            - type: array
              items:
                type: object
                additionalProperties:
                  anyOf:
                  - type: string
                  - type: number
                  - type: integer
                  - type: boolean
          description: "\nDictionary of custom attributes about the user. As with the [Product API](#operation/content_write_api_v1_products_post\n), you can specify attributes specific to your business in a `{\"KEY\" : VALUE}` format, where `KEY` must be a string, and\n `VALUE` can be:\n* a `string` or `an array of strings`\n* a `number` or `an array of numbers`\n* an `array of objects`\n* a `bool`\n* `null` \n\n* Example:\n```\n{\n    \"custom_attributes\": {\n        \"acquisition_channel\": \"Facebook Campaign 2020\",\n        \"declared_interests\": [\"Drama\", \"Romance\"]\n    }\n}\n```\nThese custom attributes types must be consistent across all User records in your data set. \nRecords with inconsistent types will fail to be inserted.\n"
          example:
            acquisition_channel: Facebook Campaign 2020
            declared_interests:
            - Drama
            - Romance
      additionalProperties: false
    UserIdList:
      title: UserIdList
      required:
      - user_ids
      type: object
      properties:
        user_ids:
          title: User Ids
          type: array
          items:
            type: string
    UserBulkIn:
      title: UserBulkIn
      required:
      - data
      type: object
      properties:
        data:
          title: Data
          type: array
          items:
            $ref: '#/components/schemas/UserRecord'
    ValidationError:
      title: ValidationError
      required:
      - loc
      - msg
      - type
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            type: string
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
    HTTPValidationError:
      title: HTTPValidationError
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
  securitySchemes:
    Secret_API_Key:
      type: apiKey
      description: "\nYour secret API key is used to access every Miso API endpoint. You should secure this key and only use it on a backend \nserver. Never leave this key in your client-side JavaScript code. If the private key is compromised, you can revoke it \nin [Dojo](https://dojo.askmiso.com/docs/api-browser) and get a new one.\n\nSpecify your secret key in the `api_key` query parameter. For example:\n```\nPOST /v1/users?api_key=039c501ac8dfcac91c6f05601cee876e1cc07e17\n```\n\n"
      in: query
      name: api_key
    Publishable_API_Key:
      type: apiKey
      description: "\nYour publishable API key is used to call Miso's APIs from your front-end code. It can be used to stream interactions from the browser using Miso's Interactions Upload API or to access read-only search and recommendation results for a given user. When using the publishable API key, the requested user_id will need to be hashed to maintain the necessary security compliance. \n\nSpecify your publishable key in the `api_key` query parameter. For example:\n```\nPOST /v1/interactions?api_key=039c501ac8dfcac91c6f05601cee876e1cc07e17\n```\n"
      in: query
      name: api_key
x-tagGroups:
- name: Data APIs
  tags:
  - Interaction APIs
  - Product / Content APIs
  - User APIs
- name: Engine APIs
  tags:
  - Search APIs
  - Ask APIs
  - Bulk API
  - User Recommendations
  - Product Recommendations
- name: Experiment APIs
  tags:
  - Experiment APIs
- name: Q&A APIs
  tags:
  - Q&A APIs