API Reference

Quick Start

Extrae datos en 4 pasos:

curl -X POST https://hrvst.donostia.ai/api/jobs \
  -H "Authorization: Bearer hv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "scraperSlug": "google-maps",
    "name": "Cafes Barcelona",
    "params": {
      "query": "cafes in Barcelona",
      "limit": 20,
      "language": "en",
      "country": "ES"
    }
  }'

import requests

API_KEY = "hv_your_api_key"
BASE_URL = "https://hrvst.donostia.ai"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(f"{BASE_URL}/api/jobs", headers=headers, json={
    "scraperSlug": "google-maps",
    "name": "Cafes Barcelona",
    "params": {
        "query": "cafes in Barcelona",
        "limit": 20,
        "language": "en",
        "country": "ES",
    }
})
job = resp.json()
job_id = job["id"]
print(f"Job created: {job_id}")

const API_KEY = "hv_your_api_key";
const BASE_URL = "https://hrvst.donostia.ai";
const headers = { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" };

const resp = await fetch(`${BASE_URL}/api/jobs`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    scraperSlug: "google-maps",
    name: "Cafes Barcelona",
    params: { query: "cafes in Barcelona", limit: 20, language: "en", country: "ES" }
  })
});
const job = await resp.json();
console.log("Job created:", job.id);

# Repeat until status != PENDING and != PROCESSING
curl https://hrvst.donostia.ai/api/jobs/JOB_ID \
  -H "Authorization: Bearer hv_your_api_key"

import time

def wait_for_job(job_id, timeout=300):
    terminal = {"COMPLETED", "FAILED", "CANCELLED"}
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{BASE_URL}/api/jobs/{job_id}", headers=headers)
        job = r.json()
        if job["status"] in terminal:
            return job
        time.sleep(3)
    raise TimeoutError("Job did not finish in time")

job = wait_for_job(job_id)
print(f"Status: {job['status']}, Records: {len(job.get('results') or [])}")

async function waitForJob(jobId, timeoutMs = 300_000) {
  const terminal = new Set(["COMPLETED", "FAILED", "CANCELLED"]);
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const r = await fetch(`${BASE_URL}/api/jobs/${jobId}`, { headers });
    const job = await r.json();
    if (terminal.has(job.status)) return job;
    await new Promise(res => setTimeout(res, 3000));
  }
  throw new Error("Job timeout");
}

const finished = await waitForJob(job.id);
console.log("Records:", finished.results?.length ?? 0);

# CSV
curl "https://hrvst.donostia.ai/jobs/JOB_ID/export?format=csv" \
  -H "Authorization: Bearer hv_your_api_key" -o results.csv

# JSON
curl "https://hrvst.donostia.ai/jobs/JOB_ID/export?format=json" \
  -H "Authorization: Bearer hv_your_api_key" -o results.json

Authentication

Todos los endpoints requieren una API key válida. Genera una desde tu cuenta.

Envía la clave en el header Authorization:

Authorization: Bearer hv_your_api_key_here

Las API keys tienen el formato hv_ + 64 caracteres hex. Requieren verificación de email para funcionar.

Créditos

Hrvst es de pago por uso. Compras créditos y los gastas en trabajos. Los créditos no caducan.

Las cuentas nuevas reciben 100 créditos gratis. Los primeros 2 desbloqueos de hrvst-agent son siempre gratuitos.

Los créditos se descuentan cuando el trabajo completa, no al crearlo. Los trabajos fallidos no consumen créditos.

Errores

Todos los errores tienen el mismo formato:

{ "error": "error description" }

Rate Limits

Los límites se aplican por usuario autenticado (sesión o API key).

Cuando se supera el límite de trabajos la API devuelve 429 Too Many Requests con el mensaje "Job limit exceeded. Maximum 50 jobs per hour."

POST/api/jobs

Crea y encola un nuevo trabajo de scraping. Responde inmediatamente — consulta el ID del trabajo para ver el progreso.

Campos del body

Respuesta — 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "user-id",
  "scraperSlug": "google-maps",
  "status": "PENDING",
  "params": { "query": "cafes in Barcelona", "limit": 20 },
  "results": null,
  "creditsUsed": 0,
  "error": null,
  "createdAt": "2026-03-14T10:30:45Z",
  "updatedAt": "2026-03-14T10:30:45Z",
  "completedAt": null,
  "unlockCost": 0,
  "unlockedAt": null,
  "freeUnlock": false
}

GET/api/jobs

Lista todos los trabajos del usuario autenticado, del más reciente al más antiguo.

Query params

{
  "jobs": [ ...job objects... ],
  "total": 42,
  "page": 1,
  "limit": 20,
  "total_returned": 20
}

GET/api/jobs/:id

Recupera un trabajo concreto. Usa este endpoint para hacer polling hasta que finalice.

curl https://hrvst.donostia.ai/api/jobs/550e8400-... \
  -H "Authorization: Bearer hv_your_api_key"

Transición de estado: PENDING → PROCESSING → COMPLETED | FAILED | CANCELLED

Para hrvst-agent: el campo resultsPreview contiene 5 registros enmascarados. Llama a POST /api/jobs/:id/unlock para obtener resultsFull.

DELETE/api/jobs/:id

Cancela y elimina un trabajo. Los trabajos en curso se marcan como cancelados antes de eliminarse.

{ "status": "deleted" }

GET/jobs/:id/export

Descarga los resultados de un trabajo completado como CSV o JSON. Solo funciona con trabajos en estado COMPLETED.

Query params

# Download as CSV
curl "https://hrvst.donostia.ai/jobs/JOB_ID/export?format=csv" \
  -H "Authorization: Bearer hv_your_api_key" \
  -o results.csv

# Download as JSON
curl "https://hrvst.donostia.ai/jobs/JOB_ID/export?format=json" \
  -H "Authorization: Bearer hv_your_api_key" \
  -o results.json

POST/api/jobs/:id/unlock

Desbloquea los resultados completos de un trabajo hrvst-agent. Los primeros 2 desbloqueos por cuenta son gratuitos. Solo funciona con trabajos COMPLETED.

curl -X POST https://hrvst.donostia.ai/api/jobs/JOB_ID/unlock \
  -H "Authorization: Bearer hv_your_api_key"

# Response
{ "resultsFullURL": "/jobs/JOB_ID/export?format=json" }

Después de desbloquear, el campo resultsFull en GET /api/jobs/:id contiene los datos completos sin enmascarar.

GET/api/scrapers

Devuelve todos los scrapers disponibles con sus slugs, créditos y campos de salida.

curl https://hrvst.donostia.ai/api/scrapers \
  -H "Authorization: Bearer hv_your_api_key"

GET/api/user/me

Devuelve el perfil y saldo de créditos del usuario autenticado.

{
  "id": "user-id",
  "email": "you@email.com",
  "name": "Your Name",
  "credits": 500,
  "freeSearchesUsed": 1
}