Hugin · Jobs API

Endpoint Reference

17 endpoints for job search, trends, exports, alerts, billing, and account management. Base URL: https://api.vitkidata.com/api/v1

Authentication

Pass your API key in the X-Api-Key header on every authenticated request. Keys are provisioned after Stripe checkout and shown once only.

 curl "https://api.vitkidata.com/api/v1/jobs?q=python&remote=true" \
  -H "X-Api-Key: vtk_live_your_key_here"

Rate Limits

Limits are enforced per API key using a sliding window. Check RateLimit-Remaining in response headers.

Tier	Requests/min	Requests/month	Price
Starter	60	10,000	$49/mo
Pro	200	50,000	$149/mo
Enterprise	500	200,000	$499/mo

GET /v1/jobs Auth required

Search Jobs

Search and filter job postings. Returns paginated results with facets. Full-text search via PostgreSQL websearch syntax.

Parameters

Name	Type	Required	Description
`q`	string	No	Full-text search query (websearch syntax)
`source`	string	No	Comma-separated source filter (indeed, linkedin, glassdoor, etc.)
`location`	string	No	Partial match on location
`remote`	boolean	No	Filter remote jobs only
`remote_type`	string	No	full, hybrid, or onsite
`salary_min`	number	No	Minimum annual salary
`salary_max`	number	No	Maximum annual salary
`posted_after`	string	No	ISO 8601 date — only jobs posted after this date
`employment_type`	string	No	FULL_TIME, PART_TIME, CONTRACT, TEMPORARY, or INTERN
`ghost_score_max`	number	No	Max ghost score 0-100 (Pro/Enterprise only)
`cursor`	string	No	Base64 pagination cursor from previous response
`limit`	number	No	Results per page (1-100, default 20)

GET /v1/jobs/:id Auth required

Get Job Detail

Retrieve a single job by ID. Returns all fields including description, salary history, and status changes (Enterprise only for historical data).

Parameters

Name	Type	Required	Description
`id`	number	Yes	Job ID (positive integer)

GET /v1/filters Auth required

Get Available Filters

Returns all available filter values with counts. Use to populate filter dropdowns in your UI.

GET /v1/sources Auth required

Source Health

Returns per-source statistics: total jobs, last scrape time, success rate, and silent failure detection.

GET /v1/trends Pro+ Auth required

Trend Data

Time-series data for job posting volume, skills demand, salary distributions, and remote work ratios.

Parameters

Name	Type	Required	Description
`type`	string	Yes	volume, skills, salary, or remote
`skill`	string	No	Filter by skill name (type=skills only)
`role`	string	No	Filter by role (type=salary only)
`limit`	number	No	Data points to return (default 52 weekly, 12 monthly)

POST /v1/exports Pro+ Auth required

Create Export

Queue a CSV or JSON export of jobs matching your filters. Returns immediately with a job ID to poll.

Parameters

Name	Type	Required	Description
`format`	string	Yes	csv or json
`query`	string	No	FTS query to filter exported jobs
`filters`	object	No	Same filters as GET /v1/jobs

GET /v1/exports/:id Pro+ Auth required

Get Export Status

Check the status of an export job. When completed, includes a download URL.

Parameters

Name	Type	Required	Description
`id`	number	Yes	Export job ID

GET /v1/exports/:id/download Pro+ Auth required

Download Export

Download the completed export file. Returns CSV or JSON as a file stream.

Parameters

Name	Type	Required	Description
`id`	number	Yes	Export job ID

POST /v1/alerts Pro+ Auth required

Create Alert

Set up a webhook alert that fires when new jobs match your criteria. Returns a webhook secret for HMAC verification.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Alert name (1-100 characters)
`query`	string	No	FTS query to match against
`filters`	object	No	Same filters as GET /v1/jobs
`webhookUrl`	string	Yes	URL to POST matches to

GET /v1/alerts Pro+ Auth required

List Alerts

List all your webhook alerts with their configuration and last-triggered timestamps.

PATCH /v1/alerts/:id Pro+ Auth required

Update Alert

Update an alert's name, filters, webhook URL, or active status.

Parameters

Name	Type	Required	Description
`id`	number	Yes	Alert ID
`name`	string	No	New name
`query`	string	No	New FTS query
`filters`	object	No	New filters
`webhookUrl`	string	No	New webhook URL
`isActive`	boolean	No	Enable or disable

DELETE /v1/alerts/:id Pro+ Auth required

Delete Alert

Permanently delete an alert. Webhook deliveries stop immediately.

Parameters

Name	Type	Required	Description
`id`	number	Yes	Alert ID

POST /v1/checkout/create

Create Checkout

Generate a Stripe checkout URL for a subscription. No auth required — this is how new customers sign up.

Parameters

Name	Type	Required	Description
`email`	string	Yes	Customer email address
`tier`	string	Yes	starter, pro, or enterprise

GET /v1/checkout/success

Get API Key

After checkout completes, retrieve the provisioned API key. The key is shown once only.

Parameters

Name	Type	Required	Description
`session_id`	string	Yes	Stripe checkout session ID

GET /v1/account Auth required

Account Info

Returns your email, tier, subscription status, trial end date, and rate limits.

GET /v1/account/usage Auth required

Usage Stats

Returns current month API usage, remaining quota, and billing period.

POST /v1/billing/portal Auth required

Billing Portal

Generate a Stripe Customer Portal URL to manage subscription, payment method, and invoices.

Example: Search Jobs

Request

 curl "https://api.vitkidata.com/api/v1/jobs?q=software+engineer&location=Austin&remote=true&salary_min=100000&limit=2" \
  -H "X-Api-Key: vtk_live_your_key_here"

Response

 {
  "data": [
    {
      "id": 4521,
      "source": "indeed",
      "sourceUrl": "https://indeed.com/viewjob?jk=abc123",
      "title": "Senior Software Engineer",
      "titleNormalized": "senior software engineer",
      "seniorityLevel": "Senior",
      "company": "Acme Corp",
      "companyNormalized": "acme corp",
      "location": "Austin, TX",
      "isRemote": true,
      "remoteType": "full",
      "salaryMin": 140000,
      "salaryMax": 180000,
      "salaryCurrency": "USD",
      "salaryPeriod": "yearly",
      "employmentType": "FULL_TIME",
      "skillsNormalized": ["python", "aws", "kubernetes", "postgresql"],
      "datePosted": "2026-05-14T00:00:00.000Z",
      "dateScraped": "2026-05-15T08:30:00.000Z",
      "ghostScore": 12
    }
  ],
  "meta": {
    "timestamp": "2026-05-17T10:00:00.000Z",
    "cursor": "eyJwb3N0ZWRfYXQiOiIyMDI2LTA1LTE0IiwiaWQiOjQ1MjF9",
    "hasMore": true,
    "total": 284,
    "facets": {
      "source": { "indeed": 120, "linkedin": 89, "glassdoor": 75 },
      "remoteType": { "full": 180, "hybrid": 64, "onsite": 40 },
      "employmentType": { "FULL_TIME": 250, "CONTRACT": 34 }
    }
  }
}

Example: Create Webhook Alert

Request

 curl -X POST "https://api.vitkidata.com/api/v1/alerts" \
  -H "X-Api-Key: vtk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Remote Python $150K+","query":"python","filters":{"remote":true,"salary_min":150000},"webhookUrl":"https://example.com/hooks/jobs"}'

Response

 {
  "data": {
    "id": 17,
    "name": "Remote Python $150K+",
    "query": "python",
    "filters": { "remote": true, "salary_min": 150000 },
    "webhookUrl": "https://example.com/hooks/jobs",
    "webhookSecret": "whsec_abc123...store_this_securely",
    "isActive": true,
    "lastTriggeredAt": null,
    "createdAt": "2026-05-17T10:05:00.000Z"
  },
  "meta": { "timestamp": "2026-05-17T10:05:00.000Z" }
}

Example: Account Usage

 curl "https://api.vitkidata.com/api/v1/account/usage" \
  -H "X-Api-Key: vtk_live_your_key_here"

 {
  "data": {
    "tier": "pro",
    "rateLimitPerMinute": 200,
    "rateLimitPerMonth": 50000,
    "currentMonthUsage": 8420,
    "currentMonthRemaining": 41580,
    "billingPeriod": "2026-05"
  },
  "meta": { "timestamp": "2026-05-17T10:00:00.000Z" }
}

Error Responses

All errors return a consistent shape with an error code and human-readable message.

 {
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Monthly quota exhausted. Upgrade your plan or wait for the next billing period."
  }
}

Status	Code	Meaning
400	VALIDATION_ERROR	Invalid parameters
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Feature not available on your tier
404	NOT_FOUND	Resource does not exist
429	RATE_LIMIT_EXCEEDED	Per-minute or per-month limit hit
500	INTERNAL_ERROR	Server error (reported to Sentry)

Get an API key → Back to docs