openapi: 3.0.2
info:
  title: Lists
  version: ''
  description: >-
    Lists APIs provided by Fraud Prevention are used to organize recommendations
    into categories and manage them.
servers:
  - url: https://api.sbx.transmitsecurity.io/risk/v1
    description: Sandbox environment
  - url: https://api.transmitsecurity.io/risk/v1
    description: Production environment (US)
  - url: https://api.eu.transmitsecurity.io/risk/v1
    description: Production environment (EU)
  - url: https://api.ca.transmitsecurity.io/risk/v1
    description: Production environment (CA)
  - url: https://api.au.transmitsecurity.io/risk/v1
    description: Production environment (AU)
paths:
  /lists:
    post:
      summary: Create list
      description: Creates a new recommendation list.
      operationId: createList
      security:
        - risk_access_token: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/list_api_request'
      responses:
        '201':
          $ref: '#/components/responses/list_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '409':
          $ref: '#/components/responses/collision'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
    get:
      summary: Get all lists
      description: >-
        Retrieves all lists of the tenant. To return lists that include a
        specific recommendation, add `item_id`  to the query.
      operationId: getLists
      security:
        - risk_access_token: []
      parameters:
        - name: item_id
          required: false
          in: query
          description: ID of the list item.
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/lists_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
  /lists/{list_id}:
    get:
      summary: Get list
      description: Retrieves a specific list by its ID.
      operationId: getList
      security:
        - risk_access_token: []
      parameters:
        - name: list_id
          description: ID of the recommendation list.
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/list_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
    put:
      operationId: updateList
      summary: Update list
      description: Updates a specific list. Currently, you can update a list name.
      parameters:
        - name: list_id
          description: ID of the recommendation list.
          required: true
          in: path
          schema:
            type: string
        - name: list_name
          description: The list title.
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/list_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '409':
          $ref: '#/components/responses/collision'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
    delete:
      operationId: removeList
      summary: Delete list
      description: Removes a recommendation list by its ID.
      parameters:
        - name: list_id
          description: ID of the recommendation list.
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/message_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
  /lists/{list_id}/items:
    post:
      operationId: addItems
      summary: Add to list
      description: Adds recommendations to the specific list.
      parameters:
        - name: list_id
          description: ID of the recommendation list.
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/list_items_api_request'
      responses:
        '201':
          $ref: '#/components/responses/list_items_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '409':
          $ref: '#/components/responses/collision'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
  /lists/{list_id}/items/{item_id}:
    delete:
      operationId: removeItem
      summary: Remove item from list
      description: Removes a specific item from the list.
      parameters:
        - name: list_id
          description: ID of the recommendation list.
          required: true
          in: path
          schema:
            type: string
        - name: item_id
          description: ID of the item to be removed.
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/message_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/rate_limit_reached'
        '500':
          $ref: '#/components/responses/internal_error'
components:
  schemas:
    list_type:
      type: string
      description: The type of recommendation list.
      enum:
        - action_id
    list_api_request:
      type: object
      properties:
        list_name:
          type: string
          description: The list title.
        list_type:
          $ref: '#/components/schemas/list_type'
        creator:
          type: string
          description: The list owner.
      required:
        - list_name
        - list_type
        - creator
    list_items_api_request:
      type: object
      properties:
        item_ids:
          type: array
          items:
            type: string
            description: ID of the list item.
      required:
        - item_ids
    list_items_metadata_api_response:
      type: object
      properties:
        item_id:
          type: string
          description: ID of the list item.
        item_created_timestamp:
          format: date-time
          type: string
          description: The timestamp when the item was added to the list.
      required:
        - item_id
        - item_created_timestamp
    list_api_response:
      type: object
      properties:
        list_name:
          type: string
          description: The list title.
        tenant_id:
          type: string
          description: ID of the tenant.
        list_type:
          $ref: '#/components/schemas/list_type'
        creator:
          type: string
          description: The list owner.
        list_id:
          type: string
          description: ID of the recommendation list.
        items:
          type: array
          items:
            $ref: '#/components/schemas/list_items_metadata_api_response'
        created_date:
          format: date-time
          type: string
          description: The timestamp when the list was created.
        updated_date:
          format: date-time
          type: string
          description: The timestamp when the list was updated.
      required:
        - list_name
        - tenant_id
        - list_type
        - creator
        - list_id
        - items
        - created_date
        - updated_date
    list_items_api_response:
      type: object
      properties:
        list_id:
          type: string
          description: ID of the recommendation list.
        tenant_id:
          type: string
          description: ID of the tenant.
        added_date:
          format: date-time
          type: string
          description: The timestamp the items were added.
        items:
          type: array
          items:
            $ref: '#/components/schemas/list_items_metadata_api_response'
      required:
        - list_id
        - tenant_id
        - added_date
        - items
  responses:
    list_response:
      description: List
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/list_api_response'
    lists_response:
      description: Matching lists
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/list_api_response'
    list_items_response:
      description: List contents
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/list_items_api_response'
    message_response:
      description: Success
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
            required:
              - message
    unauthorized:
      description: Invalid authentication
    not_found:
      description: Not found
    forbidden:
      description: Invalid authorization (e.g, unauthorized resource)
    rate_limit_reached:
      description: Rate limit reached
    internal_error:
      description: Internal error
    collision:
      description: Unique field collision
    bad_request:
      description: Bad request
  securitySchemes:
    risk_access_token:
      type: http
      scheme: bearer
      description: >-
        An access token generated by the [token
        endpoint](/openapi/token.openapi/other/getaccesstoken), which should
        target the following resource: `https://risk.identity.security`
      bearerFormat: JWT
