Search API

The Search API lets you find creative resources using natural language. It's designed for internal DAMs, CRMs, CMSs, intranets, copilots, and agents that need to retrieve the right resource without navigating folders.

Status: preview contract. The final endpoint and field names may change before general availability.

Endpoint

POST /v1/media/search

Request

{
  "project_id": "brand-assets",
  "query": "presentacion para cliente de energia renovable",
  "top_k": 10,
  "mime_types": ["application/pdf", "application/vnd.ms-powerpoint"],
  "filters": {
    "has_logo": true
  }
}

Parameters

Field	Type	Required	Description
project_id	string	Yes	Project to search in.
query	string	Yes	Natural language query.
top_k	number	No	Maximum number of results. Defaults to 10.
mime_types	string[]	No	Limits results by MIME type.
filters	object	No	Structured filters available depending on the project.

Example with curl

curl https://api.polimake.com/v1/media/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "brand-assets",
    "query": "presentacion para cliente de energia renovable",
    "top_k": 10,
    "mime_types": ["application/pdf", "application/vnd.ms-powerpoint"]
  }'

Example with JavaScript

async function searchPolimakeMedia(query) {
  const response = await fetch("https://api.polimake.com/v1/media/search", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.POLIMAKE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      project_id: "brand-assets",
      query,
      top_k: 10,
    }),
  });

  if (!response.ok) {
    const error = await response.json().catch(() => null);
    throw new Error(error?.error?.message || `Polimake API error: ${response.status}`);
  }

  return response.json();
}

Example with Python

import os
import requests

def search_polimake_media(query: str):
    response = requests.post(
        "https://api.polimake.com/v1/media/search",
        headers={
            "Authorization": f"Bearer {os.environ['POLIMAKE_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "project_id": "brand-assets",
            "query": query,
            "top_k": 10,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Response

{
  "object": "search_result",
  "query": "presentacion para cliente de energia renovable",
  "items": [
    {
      "id": "media_01HX9R8K4Q2Z4T",
      "object": "media_object",
      "score": 0.92,
      "project_id": "brand-assets",
      "filename": "deck-renovables-q2.pdf",
      "mime_type": "application/pdf",
      "urls": {
        "preview": "https://cdn.polimake.com/previews/media_01HX9R8K4Q2Z4T.webp"
      },
      "ai": {
        "description": "Presentacion comercial sobre energia renovable con graficos trimestrales.",
        "tags": ["energia renovable", "presentacion", "ventas", "graficos"]
      }
    }
  ]
}

Best Practices

• Send complete queries, not just keywords.
• Use mime_types when you know you're looking for documents, images, or videos.
• Use a low top_k for fast interfaces and increase it for offline processes.
• Show ai.description to the user to explain why a result appears.
• Store the media object's id, not the temporary preview URL.

Continue with [Build: integrate Polimake](/docs/developers/01-overview).