✨ add model search API

Author: ianardee

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## v5.0.0-beta2 - 2026-05-20
 ### ¡Breaking Changes!
 * :recycle: put error parsing in its own package
+* :sparkles: add model search API
 
 
 ## v5.0.0-beta1 - 2026-05-06

src/main/java/com/mindee/v2/MindeeClient.java

@@ -10,6 +10,7 @@
 import com.mindee.v2.parsing.CommonResponse;
 import com.mindee.v2.parsing.JobResponse;
 import com.mindee.v2.parsing.error.ErrorResponse;
+import com.mindee.v2.parsing.search.SearchResponse;
 import com.mindee.v2.product.extraction.ExtractionResponse;
 import java.io.IOException;
 
@@ -172,6 +173,36 @@ public <TResponse extends CommonResponse> TResponse enqueueAndGetResult(
     return pollAndFetch(responseClass, job, pollingOptions);
   }
 
+  /**
+   * Return all models.
+   *
+   * @return an instance of {@link SearchResponse}
+   */
+  public SearchResponse searchModels() {
+    return searchModels(null, null);
+  }
+
+  /**
+   * Search for models by name.
+   *
+   * @param modelName name of the model to search for
+   * @return an instance of {@link SearchResponse}
+   */
+  public SearchResponse searchModels(String modelName) {
+    return searchModels(modelName, null);
+  }
+
+  /**
+   * Search for models by name and type.
+   *
+   * @param modelName name of the model to search for
+   * @param modelType type of the model to search for
+   * @return an instance of {@link SearchResponse}
+   */
+  public SearchResponse searchModels(String modelName, String modelType) {
+    return mindeeApi.reqGetSearchModels(modelName, modelType);
+  }
+
   /**
    * Common logic for polling an asynchronous job for local & url files.
    *

src/main/java/com/mindee/v2/http/MindeeApiV2.java

@@ -8,6 +8,7 @@
 import com.mindee.v2.parsing.CommonResponse;
 import com.mindee.v2.parsing.JobResponse;
 import com.mindee.v2.parsing.error.ErrorResponse;
+import com.mindee.v2.parsing.search.SearchResponse;
 import java.io.IOException;
 
 /**
@@ -48,11 +49,19 @@ public abstract JobResponse reqPostEnqueue(
    *
    * @param inferenceId ID of the inference to poll.
    */
-  abstract public <TResponse extends CommonResponse> TResponse reqGetResult(
+  public abstract <TResponse extends CommonResponse> TResponse reqGetResult(
       Class<TResponse> responseClass,
       String inferenceId
   );
 
+  /**
+   * Retrieves a list of models.
+   *
+   * @param modelName search term for model name
+   * @param modelType search term for model type
+   */
+  public abstract SearchResponse reqGetSearchModels(String modelName, String modelType);
+
   /**
    * Creates an "unknown error" response from an HTTP status code.
    */

src/main/java/com/mindee/v2/http/MindeeHttpApiV2.java

@@ -10,12 +10,14 @@
 import com.mindee.v2.parsing.CommonResponse;
 import com.mindee.v2.parsing.JobResponse;
 import com.mindee.v2.parsing.error.ErrorResponse;
+import com.mindee.v2.parsing.search.SearchResponse;
 import java.io.IOException;
 import java.net.URISyntaxException;
 import java.nio.charset.StandardCharsets;
 import lombok.Builder;
 import org.apache.hc.client5.http.classic.methods.HttpGet;
 import org.apache.hc.client5.http.classic.methods.HttpPost;
+import org.apache.hc.client5.http.classic.methods.HttpUriRequestBase;
 import org.apache.hc.client5.http.config.RequestConfig;
 import org.apache.hc.client5.http.entity.mime.HttpMultipartMode;
 import org.apache.hc.client5.http.entity.mime.MultipartEntityBuilder;
@@ -82,7 +84,7 @@ public JobResponse reqPostEnqueue(LocalInputSource inputSource, BaseParameters o
         inputSource.getFilename()
       );
     post.setEntity(options.buildHttpBody(builder).build());
-    return executeEnqueue(post);
+    return executeAPIRequest(post, JobResponse.class);
   }
 
   /**
@@ -103,33 +105,7 @@ public JobResponse reqPostEnqueue(URLInputSource inputSource, BaseParameters opt
     builder.setMode(HttpMultipartMode.EXTENDED);
     builder.addTextBody("url", inputSource.getUrl().toString());
     post.setEntity(options.buildHttpBody(builder).build());
-    return executeEnqueue(post);
-  }
-
-  /**
-   * Executes an enqueue action, common to URL & local inputs.
-   *
-   * @param post HTTP Post object.
-   * @return a valid job response.
-   */
-  private JobResponse executeEnqueue(HttpPost post) {
-    try (var httpClient = httpClientBuilder.build()) {
-      return httpClient.execute(post, response -> {
-        var responseEntity = response.getEntity();
-        var statusCode = response.getCode();
-        if (isInvalidStatusCode(statusCode)) {
-          throw getHttpError(response);
-        }
-        try {
-          var raw = EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8);
-          return deserializeOrThrow(raw, JobResponse.class, response.getCode());
-        } finally {
-          EntityUtils.consumeQuietly(responseEntity);
-        }
-      });
-    } catch (IOException err) {
-      throw new MindeeException(err.getMessage(), err);
-    }
+    return executeAPIRequest(post, JobResponse.class);
   }
 
   @Override
@@ -138,31 +114,10 @@ public JobResponse reqGetJob(String jobId) {
     var url = this.mindeeSettings.getBaseUrl() + "/jobs/" + jobId;
     var get = new HttpGet(url);
 
-    if (this.mindeeSettings.getApiKey().isPresent()) {
-      get.setHeader(HttpHeaders.AUTHORIZATION, this.mindeeSettings.getApiKey().get());
-    }
-    get.setHeader(HttpHeaders.USER_AGENT, getUserAgent());
     var noRedirect = RequestConfig.custom().setRedirectsEnabled(false).build();
     get.setConfig(noRedirect);
 
-    try (var httpClient = httpClientBuilder.build()) {
-      return httpClient.execute(get, response -> {
-        var responseEntity = response.getEntity();
-        var statusCode = response.getCode();
-        if (isInvalidStatusCode(statusCode)) {
-          throw getHttpError(response);
-        }
-        try {
-          var raw = EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8);
-
-          return deserializeOrThrow(raw, JobResponse.class, response.getCode());
-        } finally {
-          EntityUtils.consumeQuietly(responseEntity);
-        }
-      });
-    } catch (IOException err) {
-      throw new MindeeException(err.getMessage(), err);
-    }
+    return this.executeAPIRequest(get, JobResponse.class);
   }
 
   @Override
@@ -179,25 +134,54 @@ public <TResponse extends CommonResponse> TResponse reqGetResult(
         inferenceId
       );
     var get = new HttpGet(url);
+    return executeAPIRequest(get, responseClass);
+  }
 
+  @Override
+  public SearchResponse reqGetSearchModels(String modelName, String modelType) {
+    URIBuilder url;
+    try {
+      url = new URIBuilder(this.mindeeSettings.getBaseUrl() + "/search/models");
+    } catch (URISyntaxException e) {
+      throw new RuntimeException(e);
+    }
+    if (modelName != null) {
+      url.addParameter("name", modelName);
+    }
+    if (modelType != null) {
+      url.addParameter("type", modelType);
+    }
+    var get = new HttpGet(url.toString());
+    return executeAPIRequest(get, SearchResponse.class);
+  }
+
+  /**
+   * Executes an enqueue action, common to URL & local inputs.
+   *
+   * @param apiRequest HTTP request object.
+   * @return a valid job response.
+   */
+  private <TResponse extends CommonResponse> TResponse executeAPIRequest(
+      HttpUriRequestBase apiRequest,
+      Class<TResponse> responseClass
+  ) {
     if (this.mindeeSettings.getApiKey().isPresent()) {
-      get.setHeader(HttpHeaders.AUTHORIZATION, this.mindeeSettings.getApiKey().get());
+      apiRequest.setHeader(HttpHeaders.AUTHORIZATION, this.mindeeSettings.getApiKey().get());
     }
-    get.setHeader(HttpHeaders.USER_AGENT, getUserAgent());
+    apiRequest.setHeader(HttpHeaders.USER_AGENT, getUserAgent());
 
     try (var httpClient = httpClientBuilder.build()) {
-
-      return httpClient.execute(get, response -> {
-        var entity = response.getEntity();
-        var status = response.getCode();
+      return httpClient.execute(apiRequest, response -> {
+        var responseEntity = response.getEntity();
+        var statusCode = response.getCode();
+        if (isInvalidStatusCode(statusCode)) {
+          throw getHttpError(response);
+        }
         try {
-          if (isInvalidStatusCode(status)) {
-            throw getHttpError(response);
-          }
-          var raw = EntityUtils.toString(entity, StandardCharsets.UTF_8);
-          return deserializeOrThrow(raw, responseClass, status);
+          var raw = EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8);
+          return deserializeOrThrow(raw, responseClass, response.getCode());
         } finally {
-          EntityUtils.consumeQuietly(entity);
+          EntityUtils.consumeQuietly(responseEntity);
         }
       });
     } catch (IOException err) {
@@ -235,11 +219,6 @@ private HttpPost buildHttpPost(String url) {
     catch (URISyntaxException err) {
       return new HttpPost("invalid URI");
     }
-
-    if (this.mindeeSettings.getApiKey().isPresent()) {
-      post.setHeader(HttpHeaders.AUTHORIZATION, this.mindeeSettings.getApiKey().get());
-    }
-    post.setHeader(HttpHeaders.USER_AGENT, getUserAgent());
     return post;
   }
 

src/main/java/com/mindee/v2/parsing/search/ModelWebhook.java

@@ -0,0 +1,37 @@
+package com.mindee.v2.parsing.search;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AllArgsConstructor;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+/**
+ * Model webhook info.
+ */
+@Getter
+@EqualsAndHashCode
+@JsonIgnoreProperties(ignoreUnknown = true)
+@AllArgsConstructor
+@NoArgsConstructor
+public class ModelWebhook {
+  /**
+   * ID of the webhook.
+   */
+  @JsonProperty("id")
+  private String id;
+
+  /**
+   * Name of the webhook.
+   */
+  @JsonProperty("name")
+  private String name;
+
+  /**
+   * URL of the webhook.
+   */
+  @JsonProperty("url")
+  private String url;
+
+}

src/main/java/com/mindee/v2/parsing/search/PaginationMetadata.java

@@ -0,0 +1,57 @@
+package com.mindee.v2.parsing.search;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.StringJoiner;
+import lombok.AllArgsConstructor;
+import lombok.EqualsAndHashCode;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+/**
+ * PaginationMetadata data associated with model search.
+ */
+@Getter
+@EqualsAndHashCode
+@JsonIgnoreProperties(ignoreUnknown = true)
+@AllArgsConstructor
+@NoArgsConstructor
+public class PaginationMetadata {
+
+  /**
+   * Number of items per page.
+   */
+  @JsonProperty("per_page")
+  private int perPage;
+
+  /**
+   * 1-indexed page number.
+   */
+  @JsonProperty("page")
+  private int page;
+
+  /**
+   * Total items.
+   */
+  @JsonProperty("total_items")
+  private int totalItems;
+
+  /**
+   * Total number of pages.
+   */
+  @JsonProperty("total_pages")
+  private int totalPages;
+
+  /**
+   * String representation of the pagination metadata.
+   */
+  @Override
+  public String toString() {
+    var joiner = new StringJoiner("\n");
+    joiner.add(":Per Page: " + perPage);
+    joiner.add(":Page: " + page);
+    joiner.add(":Total Items: " + totalItems);
+    joiner.add(":Total Pages: " + totalPages);
+    return joiner.toString();
+  }
+}