PlanRadar Filters V2 API

openapi: 3.2.0
info:
  title: PlanRadar's API Documentation Approval Requests V2 Filters V2 API
  version: '2.0'
  description: "Welcome to PlanRadar's API documentation, here you can find all the details about our APIs as well as test them online.<br />\n        <h5>Rate Limits</h5>30 requests per minute per account, aggregated across all tokens.<br />\n        If the threshold is exceeded, a 5-minute cooldown is applied to the account, aggregated across all tokens.<br />\n        During the cooldown period, further requests may be rejected until the cooldown ends.<br />\n        In rare cases, an endpoint may have a different rate limit than the default. When that happens, the differing limit will be explicitly stated in the API documentation for that endpoint.<br />\n        <h5>Access Key</h5>In order to be able to access any API you have to create an access token.Therefore you have to follow these steps:-\n        <ul>\n          <li>Go to your profile page and click on Personal Access Tokens on the left side bar</li><li>Click on the 'Create Access Token' top right button in order to create a new access token.</li><li>Copy the created token and paste it into the field that pops up when you click on the 'Authorize' button </li><li>Note: you can copy the token only once.</li><li>Now you can easily access any API</li>\n        </ul>\n        <h5>V2 APIs</h5>We are currently working on upgrading all our APIs to v2, and we recommend that you use v2 APIs if it is available.\n        <p>V2 APIs are faster, robust and more flexible than v1 APIs</p>"
servers:
- url: /
tags:
- name: Filters V2
  description: Read and manage ticket filters
paths:
  /api/v2/{customer_id}/projects/{project_id}/filters:
    get:
      summary: Returns all filters of a project
      tags:
      - Filters V2
      description: This API returns all filters of the logged in costumer.
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: last_sync_date
        in: query
        description: is a Unix Timestamp. If it is set, only filters that were created after that timestamp will be returned
        schema:
          type: string
      - name: pagesize
        in: query
        description: sets the number of filters that should be returned per page <br> Maximum is 500, default is 100
        schema:
          type: string
      - name: page
        in: query
        description: sets the number of pages for the returned filters
        schema:
          type: string
      - name: search
        in: query
        description: keyword, based on which the roles will be filtered
        schema:
          type: string
      - name: load_all
        in: query
        description: sets whether or not all filters should be loaded
        schema:
          type: boolean
      responses:
        '404':
          description: Filters Not Found
    post:
      summary: Creates new filter
      tags:
      - Filters V2
      security:
      - apiKey: []
      description: 'This API is used for creating a new filter. <br />The filters object contains all the filter data. Each filter is an array that consists of the attributes "predicate" and "value". The default field-keys of the filters object are "sequential-id", "subject", "status-id", "priority-id", "assigned-to-id", "author-id", "created-at", "updated-at", "updated-by-id", "due-date", "progress", "component-id", "company". If a filter is a custom created one its field key will be generated and look similar to the following example. <b>Example:</b> "tf37e04757dabbca63" <br /><b>Available Predicates</b>: "eq" (=), "starts-with", "ends-with", "like", "not_like", "ge"(>=), "le"(<=), "neq"(!=), "between", "has", "has-not", "in", "not-in". Values are either strings or integers, arrays are used if the predicate is: "in" or "not-in". When using "author-id", "updated-by-id", "assigned-to-id" you can set the value to 0 if you want to get NULL values. <br />The following example creates a filter that displays all tickets of which the id aka sequential-id is >= 3. <b> Filter Example:</b> <br /> { "data": { "attributes": { "name": "filter_ticketid_greater_than_2", "visibility": 3, "visibile_for_projects": true, "filters": { "sequential-id": [ { "predicate": "ge", "value": "3" } ] } } } }'
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Filters not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      $ref: '#/components/schemas/Filter'
  /api/v2/{customer_id}/projects/{project_id}/filters/check_name_duplication:
    post:
      summary: Checks for filter name duplication
      tags:
      - Filters V2
      security:
      - apiKey: []
      description: This API is used for checking if the name of a filter already exists.
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Filter Not Found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      type: object
                      properties:
                        name:
                          type: string
                          description: name of the filter that should be checked
  /api/v2/{customer_id}/projects/{project_id}/filters/{id}:
    get:
      summary: Returns specific filter
      tags:
      - Filters V2
      description: This API returns a specific filter based on its id.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Filter Not Found
    delete:
      summary: Deletes specific filter
      tags:
      - Filters V2
      description: This API is used for deleting a specific filter based on its id.
      security:
      - apiKey: []
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Filter Not Found
    put:
      summary: Updates specific filter
      tags:
      - Filters V2
      security:
      - apiKey: []
      description: 'This API is used for updating a specific filter based on its id. <br />The filters object contains all the filter data. Each filter is an array that consists of the attributes "predicate" and "value". The default field-keys of the filters object are "sequential-id", "subject", "status-id", "priority-id", "assigned-to-id", "author-id", "created-at", "updated-at", "updated-by-id", "due-date", "progress", "component-id", "company". If a filter is a custom created one its field key will be generated and look similar to the following example. <b>Example:</b> "tf37e04757dabbca63" <br /><b>Available Predicates</b>: "eq" (=), "starts-with", "ends-with", "like", "not_like", "ge"(>=), "le"(<=), "neq"(!=), "between", "has", "has-not", "in", "not-in". Values are either strings or integers, arrays are used if the predicate is: "in" or "not-in". When using "author-id", "updated-by-id", "assigned-to-id" you can set the value to 0 if you want to get NULL values. <br />The following example creates a filter that displays all tickets of which the id aka sequential-id is >= 3. <b> Filter Example:</b> <br /> { "data": { "attributes": { "name": "filter_ticketid_greater_than_2", "visibility": 3, "visibile_for_projects": true, "filters": { "sequential-id": [ { "predicate": "ge", "value": "3" } ] } } } }'
      parameters:
      - name: customer_id
        in: path
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: id of the filter that should be updated
        required: true
        schema:
          type: string
      responses:
        '404':
          description: Filter Not Found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      $ref: '#/components/schemas/Filter'
  /api/v2/{customer_id}/projects/{project_id}/filters/filterable_fields:
    get:
      summary: List available filterable fields for a given type
      tags:
      - Filters V2
      security:
      - apiKey: []
      description: Returns all available filter fields for a given entity type (e.g., tickets, dms, approval-requests). Each field includes its ID, name, type, predicates, and display options.
      parameters:
      - name: customer_id
        in: path
        description: ID of the customer
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        description: ID of the project
        required: true
        schema:
          type: string
      - name: type
        in: query
        description: Type of entity to get filterable fields for
        schema:
          type: string
          enum:
          - tickets
          - dms
          - ticket-attachments
          - groups
          - approval-requests
      responses:
        '400':
          description: Invalid Parameters
  /api/v2/{customer_id}/projects/{project_id}/filters/list_options:
    get:
      summary: List available options for a specific field
      tags:
      - Filters V2
      security:
      - apiKey: []
      description: This API returns all options for a specific field based on its id.
      parameters:
      - name: customer_id
        in: path
        description: ID of the customer
        required: true
        schema:
          type: string
      - name: project_id
        in: path
        description: ID of the project
        required: true
        schema:
          type: string
      - name: field_id
        in: query
        description: Field ID for which options are listed (e.g., "ticket.status-id", "ticket.approval-status")
        schema:
          type: string
      - name: type
        in: query
        description: Type of filter (e.g., tickets, dms, approval-requests)
        schema:
          type: string
      - name: selected_ids
        in: query
        schema:
          type: array
          items:
            type: string
        description: Array of selected option IDs
      - name: search
        in: query
        description: Search term to filter options
        schema:
          type: string
      responses:
        '404':
          description: Field Not Found
components:
  schemas:
    Filter:
      type: object
      properties:
        name:
          type: string
          example: filtername
          description: name of the filter - has to be unique
        visibility:
          type: integer
          example: 1
          description: 'sets to whom the filter that is being created is visible <br /> 1 = visible to all users, 2 = only visible to in-house users, 3 = only visible to the logged in customer '
        visibile_for_projects:
          type: boolean
          description: set to true if the filter for all projects otherwise it should be false.
        filters:
          type: object
          description: contains the data of the filter
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-PlanRadar-API-Key
      in: header
externalDocs:
  description: Find out more about our development portal
  url: https://www.planradar.com/knowledge-base-overview/