API Reference

Authentication

All API endpoints require a valid API key. Generate one from your account settings.

Pass the key in the Authorization header:

Authorization: Bearer hv_your_api_key_here

API keys have the format hv_ + 64 hex characters. Email verification is required before API keys work.

Credits

Hrvst is pay-per-use. You buy credits and spend them on jobs. Credits never expire.

New accounts start with 100 free credits. First 2 hrvst-agent unlocks are always free.

Errors

All errors follow the same shape:

{ "error": "description of what went wrong" }

Rate Limits

100 requests per minute per API key. Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1678456800

POST/api/jobs

Create and enqueue a new scraping job. Returns immediately — poll the job ID to check completion.

Request

curl -X POST https://hrvst.donostia.ai/api/jobs \
  -H "Authorization: Bearer hv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "scraperSlug": "google-maps",
    "name": "Restaurantes Madrid",
    "params": {
      "query": "restaurantes en Madrid",
      "limit": 20,
      "language": "es",
      "country": "ES"
    }
  }'

Body fields

Response — 201 Created

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

GET/api/jobs

List all jobs for the authenticated user, newest first.

Query params

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

GET/api/jobs/:id

Retrieve a single job. Use this to poll for completion.

# Poll until status is COMPLETED, FAILED, or CANCELLED
curl https://hrvst.donostia.ai/api/jobs/550e8400-... \
  -H "Authorization: Bearer hv_..."

Job status transitions: PENDING → PROCESSING → COMPLETED | FAILED | CANCELLED

DELETE/api/jobs/:id

Cancel and soft-delete a job. Returns {"status":"deleted"}.

POST/api/jobs/:id/unlock

Unlock full results for an hrvst-agent job. First 2 unlocks per account are free. Only works on COMPLETED jobs.

{ "resultsFullURL": "/jobs/550e8400-.../export?format=json" }

GET/api/scrapers

Returns all available scrapers with their slugs, credits, and output fields.

GET/api/user/me

Returns the authenticated user's profile and credit balance.

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

Scraper Reference