API Authentication

The Polimake API uses bearer token authentication in the Authorization header.

Status: preview contract. Self-serve API key management may vary depending on the rollout status of the public API.

Required Header

Authorization: Bearer YOUR_API_KEY

You must also send Content-Type: application/json on requests with a JSON body.

Content-Type: application/json

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": "fotografia de equipo en oficina",
    "top_k": 5
  }'

Example with JavaScript

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: "fotografia de equipo en oficina",
    top_k: 5,
  }),
});

if (!response.ok) {
  throw new Error(`Polimake API error: ${response.status}`);
}

const result = await response.json();

Example with Python

import os
import requests

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": "fotografia de equipo en oficina",
        "top_k": 5,
    },
    timeout=30,
)

response.raise_for_status()
result = response.json()

Security Recommendations

• Store the API key in environment variables or a secrets manager.
• Don't include keys in frontend apps, repositories, shared notebooks, or screenshots.
• Use separate keys per environment: development, staging, and production.
• Rotate keys if you suspect exposure.
• Limit permissions per project when scopes are available.

Common Errors

401 Unauthorized

The key is missing, malformed, or invalid.

{
  "error": {
    "type": "authentication_error",
    "message": "Missing or invalid API key"
  }
}

403 Forbidden

The key exists, but it doesn't have access to the requested project or resource.

{
  "error": {
    "type": "permission_error",
    "message": "The API key cannot access this project"
  }
}

Continue with Build: integrate Polimake.