{ "openapi": "3.1.0", "info": { "title": "Hopin Public API", "version": "1.0.0", "summary": "Read-only access to Hopin's fresher and entry-level job listings in India.", "description": "The public, unauthenticated surface of Hopin (hopinjobs.com): fresher and entry-level job listings across India, internships, the filter vocabulary those listings use, campus events, and an openly licensed aggregate hiring dataset.\n\nEverything described here is a `GET`, needs no API key or OAuth flow, and returns JSON with `Access-Control-Allow-Origin: *`. There is no public write surface, no webhook and no event subscription.\n\nCollection operations return the whole filtered collection in a single response rather than a page at a time, so an agent that needs every fresher job in a city makes one request instead of walking a cursor. Filter server-side with the query parameters rather than fetching everything and discarding most of it.\n\nRate limit: 300 requests per 60-second window per client. Every response carries the IETF `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy` header fields, so read the remaining budget off the response instead of counting requests locally.\n\nNarrative documentation with worked examples: https://hopinjobs.com/api", "termsOfService": "https://hopinjobs.com/terms", "contact": { "name": "Hopin support", "email": "help@hopinjobs.com", "url": "https://hopinjobs.com/contact" }, "license": { "name": "CC-BY-4.0 (aggregate hiring dataset only)", "identifier": "CC-BY-4.0" } }, "externalDocs": { "description": "Hopin developer and AI agent documentation", "url": "https://hopinjobs.com/docs" }, "servers": [ { "url": "https://api.hopinjobs.com", "description": "Production API" } ], "tags": [ { "name": "jobs", "description": "Full-time and entry-level job listings." }, { "name": "internships", "description": "Internship listings." }, { "name": "reference", "description": "Filter vocabulary, events and service health." }, { "name": "open-data", "description": "Aggregate hiring data published under CC-BY-4.0." } ], "paths": { "/api/health": { "get": { "operationId": "getHealth", "summary": "Check that the Hopin API is reachable", "description": "Liveness check. Returns a small JSON object when the API is serving traffic. Call it once before a batch of requests rather than treating a failed listing call as an outage.", "tags": [ "reference" ], "security": [], "responses": { "200": { "description": "The API is up.", "content": { "application/json": { "schema": { "type": "object", "description": "Service liveness.", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "`ok` when the API is serving." }, "message": { "type": "string", "description": "Human-readable detail." } } }, "example": { "status": "ok", "message": "Hopin Backend API is running" } } }, "headers": { "RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer", "examples": [ 300 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window. Read this rather than counting locally.", "schema": { "type": "integer", "examples": [ 299 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "RateLimit-Policy": { "description": "The advertised policy in IETF structured-field form.", "schema": { "type": "string", "examples": [ "300;w=60" ] } } } }, "429": { "description": "Rate limit exceeded. Honour `Retry-After` before retrying.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before the next request.", "schema": { "type": "integer" } } } } } } }, "/api/jobs": { "get": { "operationId": "listJobs", "summary": "List fresher and entry-level jobs in India", "description": "Returns every job listing matching the supplied filters in a single response, newest first. This is the bulk read: there is no pagination, so one call retrieves the whole filtered collection.\n\nSet `is_unofficial=true` to get hidden roles — openings sourced from a recruiter's own feed rather than syndicated to a job board. Every listing has passed a scam and authenticity check before it appears here.\n\nUse `getFilters` to discover the exact values `industry`, `location`, `work_type` and `role_type` accept; they are matched exactly, not fuzzily.", "tags": [ "jobs" ], "security": [], "parameters": [ { "name": "is_unofficial", "in": "query", "required": false, "description": "`true` returns hidden roles: openings sourced from a recruiter's own feed rather than a job board. Default `false`.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, { "name": "is_on_campus", "in": "query", "required": false, "description": "Restrict to on-campus (`true`) or off-campus (`false`) listings. Ignored when `is_unofficial=true`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "industry", "in": "query", "required": false, "description": "Exact match on an industry value from `getFilters`, for example `Technology`.", "schema": { "type": "string", "examples": [ "Technology" ] } }, { "name": "location", "in": "query", "required": false, "description": "Exact match on a location value from `getFilters`, for example `Bangalore, India`.", "schema": { "type": "string", "examples": [ "Bangalore, India" ] } }, { "name": "work_type", "in": "query", "required": false, "description": "Where the role is performed.", "schema": { "type": "string", "enum": [ "On-site", "Remote", "Hybrid" ] } }, { "name": "role_type", "in": "query", "required": false, "description": "Exact match on a role value from `getFilters`, for example `Software Engineer`.", "schema": { "type": "string", "examples": [ "Software Engineer" ] } } ], "responses": { "200": { "description": "The complete set of jobs matching the filters. An empty `jobs` array means nothing matched, not an error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobs" ], "properties": { "jobs": { "type": "array", "description": "Every matching job listing.", "items": { "type": "object", "description": "One fresher or entry-level job listing in India.", "required": [ "id", "company", "title" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable identifier for this listing." }, "company": { "type": "string", "description": "Hiring company." }, "title": { "type": "string", "description": "Role title as posted." }, "description": { "type": [ "string", "null" ], "description": "Role description as posted." }, "logo": { "type": [ "string", "null" ], "format": "uri", "description": "Company logo. The curated company logo wins over the per-listing one." }, "location": { "type": [ "string", "null" ], "description": "Where the role is based, for example `Bangalore, India`." }, "work_type": { "type": [ "string", "null" ], "description": "`On-site`, `Remote` or `Hybrid`." }, "industry": { "type": [ "string", "null" ], "description": "Industry the role sits in." }, "role_type": { "type": [ "string", "null" ], "description": "Role family, for example `Software Engineer`." }, "ctc_amount": { "type": [ "string", "null" ], "description": "Human-readable pay band, sometimes marked estimated. A display string, not a number." }, "ctc_description": { "type": [ "string", "null" ], "description": "Free-text note about compensation." }, "salary": { "type": [ "string", "null" ], "description": "Legacy salary field; prefer `ctc_amount`." }, "start_date": { "type": [ "string", "null" ], "description": "When the role starts, as posted." }, "deadline": { "type": [ "string", "null" ], "description": "Application deadline, when the source states one." }, "deadline_display": { "type": [ "string", "null" ], "description": "Human-readable deadline hint." }, "posted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the listing was posted." }, "posted_days": { "type": [ "integer", "null" ], "description": "Whole days since `posted_at`, computed at request time." }, "is_on_campus": { "type": [ "boolean", "null" ], "description": "Whether this is an on-campus opportunity." }, "is_active": { "type": [ "boolean", "null" ], "description": "Whether the listing is still open." }, "job_type": { "type": [ "string", "null" ], "description": "`job` for this collection." }, "match_score": { "type": [ "integer", "null" ], "description": "Fit score out of 100. Without a user profile this is the listing's default score, not a personalised one." }, "prestige_tier": { "type": [ "integer", "null" ], "description": "Company prestige weighting used for ordering." } } } } } }, "example": { "jobs": [ { "id": "e4841672-3717-4959-ac26-d9fa5fca7673", "company": "Infosys", "title": "Business Roles", "description": "Information Technology / Business Roles", "location": "Remote, India", "work_type": "On-site", "industry": "Information Technology", "role_type": "Business Roles", "ctc_amount": "₹3.5-7 LPA (Estimated)", "posted_at": "2026-08-21T03:52:44", "posted_days": 1, "is_on_campus": false, "is_active": true, "job_type": "job" } ] } } }, "headers": { "RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer", "examples": [ 300 ] } }, "RateLimit-Remaining": { "description": "Requests left in the current window. Read this rather than counting locally.", "schema": { "type": "integer", "examples": [ 299 ] } }, "RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "RateLimit-Policy": { "description": "The advertised policy in IETF structured-field form.", "schema": { "type": "string", "examples": [ "300;w=60" ] } } } }, "429": { "description": "Rate limit exceeded. Honour `Retry-After` before retrying.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before the next request.", "schema": { "type": "integer" } } } }, "500": { "description": "The failure is server-side; the request is worth retrying.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } }, "example": { "error": "Failed to fetch jobs" } } } } } } }, "/api/jobs/{id}": { "get": { "operationId": "getJob", "summary": "Get one job by id", "description": "Returns a single job listing by its UUID. Ids come from `listJobs`; they are stable for the life of the listing.", "tags": [ "jobs" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The job's UUID, as returned by `listJobs`.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The job.", "content": { "application/json": { "schema": { "type": "object", "required": [ "job" ], "properties": { "job": { "type": "object", "description": "One fresher or entry-level job listing in India.", "required": [ "id", "company", "title" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable identifier for this listing." }, "company": { "type": "string", "description": "Hiring company." }, "title": { "type": "string", "description": "Role title as posted." }, "description": { "type": [ "string", "null" ], "description": "Role description as posted." }, "logo": { "type": [ "string", "null" ], "format": "uri", "description": "Company logo. The curated company logo wins over the per-listing one." }, "location": { "type": [ "string", "null" ], "description": "Where the role is based, for example `Bangalore, India`." }, "work_type": { "type": [ "string", "null" ], "description": "`On-site`, `Remote` or `Hybrid`." }, "industry": { "type": [ "string", "null" ], "description": "Industry the role sits in." }, "role_type": { "type": [ "string", "null" ], "description": "Role family, for example `Software Engineer`." }, "ctc_amount": { "type": [ "string", "null" ], "description": "Human-readable pay band, sometimes marked estimated. A display string, not a number." }, "ctc_description": { "type": [ "string", "null" ], "description": "Free-text note about compensation." }, "salary": { "type": [ "string", "null" ], "description": "Legacy salary field; prefer `ctc_amount`." }, "start_date": { "type": [ "string", "null" ], "description": "When the role starts, as posted." }, "deadline": { "type": [ "string", "null" ], "description": "Application deadline, when the source states one." }, "deadline_display": { "type": [ "string", "null" ], "description": "Human-readable deadline hint." }, "posted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the listing was posted." }, "posted_days": { "type": [ "integer", "null" ], "description": "Whole days since `posted_at`, computed at request time." }, "is_on_campus": { "type": [ "boolean", "null" ], "description": "Whether this is an on-campus opportunity." }, "is_active": { "type": [ "boolean", "null" ], "description": "Whether the listing is still open." }, "job_type": { "type": [ "string", "null" ], "description": "`job` for this collection." }, "match_score": { "type": [ "integer", "null" ], "description": "Fit score out of 100. Without a user profile this is the listing's default score, not a personalised one." }, "prestige_tier": { "type": [ "integer", "null" ], "description": "Company prestige weighting used for ordering." } } } } } } } }, "404": { "description": "No job exists with that id.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } }, "example": { "error": "Job not found" } } } }, "429": { "description": "Rate limit exceeded. Honour `Retry-After` before retrying.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before the next request.", "schema": { "type": "integer" } } } } } } }, "/api/internships": { "get": { "operationId": "listInternships", "summary": "List internships in India", "description": "Returns every internship matching the supplied filters in a single response, newest first. Same filter vocabulary as `listJobs`; each item carries `stipend` in place of `ctc_amount`.", "tags": [ "internships" ], "security": [], "parameters": [ { "name": "is_unofficial", "in": "query", "required": false, "description": "`true` returns hidden roles: openings sourced from a recruiter's own feed rather than a job board. Default `false`.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, { "name": "is_on_campus", "in": "query", "required": false, "description": "Restrict to on-campus (`true`) or off-campus (`false`) listings. Ignored when `is_unofficial=true`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "industry", "in": "query", "required": false, "description": "Exact match on an industry value from `getFilters`, for example `Technology`.", "schema": { "type": "string", "examples": [ "Technology" ] } }, { "name": "location", "in": "query", "required": false, "description": "Exact match on a location value from `getFilters`, for example `Bangalore, India`.", "schema": { "type": "string", "examples": [ "Bangalore, India" ] } }, { "name": "work_type", "in": "query", "required": false, "description": "Where the role is performed.", "schema": { "type": "string", "enum": [ "On-site", "Remote", "Hybrid" ] } }, { "name": "role_type", "in": "query", "required": false, "description": "Exact match on a role value from `getFilters`, for example `Software Engineer`.", "schema": { "type": "string", "examples": [ "Software Engineer" ] } } ], "responses": { "200": { "description": "The complete set of internships matching the filters.", "content": { "application/json": { "schema": { "type": "object", "required": [ "internships" ], "properties": { "internships": { "type": "array", "description": "Every matching internship listing.", "items": { "type": "object", "description": "One internship listing in India. Same shape as `Job` with `stipend` in place of `ctc_amount`.", "required": [ "id", "company", "title" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable identifier for this listing." }, "company": { "type": "string", "description": "Hiring company." }, "title": { "type": "string", "description": "Role title as posted." }, "description": { "type": [ "string", "null" ], "description": "Role description as posted." }, "logo": { "type": [ "string", "null" ], "format": "uri", "description": "Company logo." }, "location": { "type": [ "string", "null" ], "description": "Where the internship is based." }, "work_type": { "type": [ "string", "null" ], "description": "`On-site`, `Remote` or `Hybrid`." }, "industry": { "type": [ "string", "null" ], "description": "Industry the internship sits in." }, "role_type": { "type": [ "string", "null" ], "description": "Role family." }, "stipend": { "type": [ "string", "null" ], "description": "Human-readable monthly stipend band, sometimes marked estimated." }, "duration": { "type": [ "string", "null" ], "description": "How long the internship runs." }, "posted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the listing was posted." }, "posted_days": { "type": [ "integer", "null" ], "description": "Whole days since `posted_at`." }, "is_on_campus": { "type": [ "boolean", "null" ], "description": "Whether this is an on-campus opportunity." }, "is_active": { "type": [ "boolean", "null" ], "description": "Whether the listing is still open." }, "job_type": { "type": [ "string", "null" ], "description": "`internship` for this collection." } } } } } } } } }, "429": { "description": "Rate limit exceeded. Honour `Retry-After` before retrying.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before the next request.", "schema": { "type": "integer" } } } }, "500": { "description": "The failure is server-side; the request is worth retrying.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } }, "example": { "error": "Failed to fetch jobs" } } } } } } }, "/api/internships/{id}": { "get": { "operationId": "getInternship", "summary": "Get one internship by id", "description": "Returns a single internship listing by its UUID. Ids come from `listInternships`.", "tags": [ "internships" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The internship's UUID, as returned by `listInternships`.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The internship.", "content": { "application/json": { "schema": { "type": "object", "required": [ "internship" ], "properties": { "internship": { "type": "object", "description": "One internship listing in India. Same shape as `Job` with `stipend` in place of `ctc_amount`.", "required": [ "id", "company", "title" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable identifier for this listing." }, "company": { "type": "string", "description": "Hiring company." }, "title": { "type": "string", "description": "Role title as posted." }, "description": { "type": [ "string", "null" ], "description": "Role description as posted." }, "logo": { "type": [ "string", "null" ], "format": "uri", "description": "Company logo." }, "location": { "type": [ "string", "null" ], "description": "Where the internship is based." }, "work_type": { "type": [ "string", "null" ], "description": "`On-site`, `Remote` or `Hybrid`." }, "industry": { "type": [ "string", "null" ], "description": "Industry the internship sits in." }, "role_type": { "type": [ "string", "null" ], "description": "Role family." }, "stipend": { "type": [ "string", "null" ], "description": "Human-readable monthly stipend band, sometimes marked estimated." }, "duration": { "type": [ "string", "null" ], "description": "How long the internship runs." }, "posted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the listing was posted." }, "posted_days": { "type": [ "integer", "null" ], "description": "Whole days since `posted_at`." }, "is_on_campus": { "type": [ "boolean", "null" ], "description": "Whether this is an on-campus opportunity." }, "is_active": { "type": [ "boolean", "null" ], "description": "Whether the listing is still open." }, "job_type": { "type": [ "string", "null" ], "description": "`internship` for this collection." } } } } } } } }, "404": { "description": "No internship exists with that id.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } }, "example": { "error": "Internship not found" } } } }, "429": { "description": "Rate limit exceeded. Honour `Retry-After` before retrying.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before the next request.", "schema": { "type": "integer" } } } } } } }, "/api/filters": { "get": { "operationId": "getFilters", "summary": "Get the allowed values for every listing filter", "description": "Returns the filter vocabulary the listing endpoints accept, grouped by type: `industry`, `location`, `pay_range`, `role` and `work_type`. Send `filter_value` to the listing endpoints and show `display_label` to a person.\n\nCall this before filtering. The listing endpoints match these values exactly, so a guessed string returns an empty collection rather than an error.", "tags": [ "reference" ], "security": [], "responses": { "200": { "description": "The filter vocabulary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "filters" ], "properties": { "filters": { "type": "object", "description": "Filter options keyed by filter type.", "additionalProperties": { "type": "array", "items": { "type": "object", "description": "One allowed value for a listing filter.", "required": [ "filter_type", "filter_value" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier for this option." }, "filter_type": { "type": "string", "description": "Which filter this option belongs to, for example `work_type`." }, "filter_value": { "type": "string", "description": "The value to send to a listing endpoint." }, "display_label": { "type": "string", "description": "The label to show a person." }, "sort_order": { "type": [ "integer", "null" ], "description": "Display order within the group." }, "is_active": { "type": [ "boolean", "null" ], "description": "Whether the option is currently offered." } } } } } } }, "example": { "filters": { "work_type": [ { "id": "9b1f0e2a-0000-0000-0000-000000000000", "filter_type": "work_type", "filter_value": "Remote", "display_label": "Remote", "sort_order": 2, "is_active": true } ] } } } } }, "429": { "description": "Rate limit exceeded. Honour `Retry-After` before retrying.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before the next request.", "schema": { "type": "integer" } } } } } } }, "/api/events": { "get": { "operationId": "listEvents", "summary": "List campus and career events", "description": "Returns the campus and career events Hopin tracks — workshops, drives and information sessions — with their date, time, venue and whether they run online.", "tags": [ "reference" ], "security": [], "responses": { "200": { "description": "The events.", "content": { "application/json": { "schema": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "type": "object", "description": "A campus or career event.", "required": [ "id", "title" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier for this event." }, "title": { "type": "string", "description": "Event name." }, "company": { "type": [ "string", "null" ], "description": "Company running the event." }, "description": { "type": [ "string", "null" ], "description": "What the event covers." }, "event_type": { "type": [ "string", "null" ], "description": "Kind of event, for example `Workshop`." }, "event_date": { "type": [ "string", "null" ], "format": "date", "description": "Date the event runs." }, "event_time": { "type": [ "string", "null" ], "description": "Start time as published." }, "location": { "type": [ "string", "null" ], "description": "Venue." }, "is_online": { "type": [ "boolean", "null" ], "description": "Whether the event runs online." }, "max_attendees": { "type": [ "integer", "null" ], "description": "Capacity, when published." }, "current_attendees": { "type": [ "integer", "null" ], "description": "Registrations so far." }, "is_active": { "type": [ "boolean", "null" ], "description": "Whether the event is still listed." } } } } } } } } }, "429": { "description": "Rate limit exceeded. Honour `Retry-After` before retrying.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before the next request.", "schema": { "type": "integer" } } } } } } }, "/reports/fresher-hiring-india.json": { "servers": [ { "url": "https://hopinjobs.com", "description": "Website origin. The aggregate dataset is a static file, not an API call, so it is cacheable and citable." } ], "get": { "operationId": "getFresherHiringDataset", "summary": "Download the India fresher hiring dataset", "description": "The whole aggregate dataset in one request: live listing count, listings added in the last seven days, internship and remote share, median posting age, and the leading cities, roles and companies.\n\nRebuilt daily from Hopin's own listing corpus and stamped with `updatedAt`. Licensed CC-BY-4.0 — quote it freely, including in an AI answer, with attribution to Hopin and a link to hopinjobs.com. Cite the `updatedAt` value alongside any figure, because the numbers move every day.", "tags": [ "open-data" ], "security": [], "responses": { "200": { "description": "The dataset.", "content": { "application/json": { "schema": { "type": "object", "description": "Aggregate India fresher hiring data, rebuilt daily and licensed CC-BY-4.0.", "required": [ "updatedAt", "totals" ], "properties": { "updatedAt": { "type": "string", "format": "date-time", "description": "When this snapshot was built. Cite it alongside any figure taken from the dataset." }, "totals": { "type": "object", "description": "Headline figures for the snapshot.", "properties": { "liveListings": { "type": "integer", "description": "Live fresher and entry-level listings across India." }, "newLast7Days": { "type": "integer", "description": "Listings added in the last seven days." }, "internshipSharePct": { "type": "number", "description": "Percentage of live listings that are internships." }, "remoteSharePct": { "type": "number", "description": "Percentage of live listings that are remote." }, "medianPostingAgeDays": { "type": "number", "description": "Median age of a live listing, in days." } } }, "topCities": { "type": "array", "description": "Cities with the most live listings, most first.", "items": { "type": "object", "description": "One counted bucket in the hiring dataset.", "required": [ "count" ], "properties": { "city": { "type": "string", "description": "City slug, on city buckets." }, "role": { "type": "string", "description": "Role slug, on role buckets." }, "company": { "type": "string", "description": "Company name, on company buckets." }, "label": { "type": "string", "description": "Human-readable label for the bucket." }, "count": { "type": "integer", "description": "Live listings in this bucket." } } } }, "topRoles": { "type": "array", "description": "Role families with the most live listings, most first.", "items": { "type": "object", "description": "One counted bucket in the hiring dataset.", "required": [ "count" ], "properties": { "city": { "type": "string", "description": "City slug, on city buckets." }, "role": { "type": "string", "description": "Role slug, on role buckets." }, "company": { "type": "string", "description": "Company name, on company buckets." }, "label": { "type": "string", "description": "Human-readable label for the bucket." }, "count": { "type": "integer", "description": "Live listings in this bucket." } } } }, "topCompanies": { "type": "array", "description": "Companies with the most live listings, most first.", "items": { "type": "object", "description": "One counted bucket in the hiring dataset.", "required": [ "count" ], "properties": { "city": { "type": "string", "description": "City slug, on city buckets." }, "role": { "type": "string", "description": "Role slug, on role buckets." }, "company": { "type": "string", "description": "Company name, on company buckets." }, "label": { "type": "string", "description": "Human-readable label for the bucket." }, "count": { "type": "integer", "description": "Live listings in this bucket." } } } } } } } } }, "404": { "description": "The snapshot is temporarily unavailable. The file is rebuilt daily and is served from a CDN, so a miss is transient; retry rather than treating it as gone." } } } } }, "components": { "securitySchemes": {}, "headers": { "RateLimitLimit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer", "examples": [ 300 ] } }, "RateLimitRemaining": { "description": "Requests left in the current window. Read this rather than counting locally.", "schema": { "type": "integer", "examples": [ 299 ] } }, "RateLimitReset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer", "examples": [ 60 ] } }, "RateLimitPolicy": { "description": "The advertised policy in IETF structured-field form.", "schema": { "type": "string", "examples": [ "300;w=60" ] } } }, "parameters": { "IsUnofficial": { "name": "is_unofficial", "in": "query", "required": false, "description": "`true` returns hidden roles: openings sourced from a recruiter's own feed rather than a job board. Default `false`.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, "IsOnCampus": { "name": "is_on_campus", "in": "query", "required": false, "description": "Restrict to on-campus (`true`) or off-campus (`false`) listings. Ignored when `is_unofficial=true`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, "Industry": { "name": "industry", "in": "query", "required": false, "description": "Exact match on an industry value from `getFilters`, for example `Technology`.", "schema": { "type": "string", "examples": [ "Technology" ] } }, "Location": { "name": "location", "in": "query", "required": false, "description": "Exact match on a location value from `getFilters`, for example `Bangalore, India`.", "schema": { "type": "string", "examples": [ "Bangalore, India" ] } }, "WorkType": { "name": "work_type", "in": "query", "required": false, "description": "Where the role is performed.", "schema": { "type": "string", "enum": [ "On-site", "Remote", "Hybrid" ] } }, "RoleType": { "name": "role_type", "in": "query", "required": false, "description": "Exact match on a role value from `getFilters`, for example `Software Engineer`.", "schema": { "type": "string", "examples": [ "Software Engineer" ] } }, "JobId": { "name": "id", "in": "path", "required": true, "description": "The job's UUID, as returned by `listJobs`.", "schema": { "type": "string", "format": "uuid" } }, "InternshipId": { "name": "id", "in": "path", "required": true, "description": "The internship's UUID, as returned by `listInternships`.", "schema": { "type": "string", "format": "uuid" } }, "Ids": { "name": "ids", "in": "query", "required": false, "description": "Bulk read: a comma-separated list of job UUIDs, at most 100 per request. Returns those jobs in a single response instead of one `getJob` call each — the difference between one round trip and fifty when acting on a set of ids. When `ids` is present every other filter is ignored. An id that no longer exists is simply absent from the array rather than an error, so a partially stale set still returns everything still live. A non-UUID entry, or more than 100 of them, returns `400` without touching the database.", "schema": { "type": "string", "examples": [ "e4841672-3717-4959-ac26-d9fa5fca7673,9f2c1d84-55aa-4b31-8c0e-7d4a1b2e3f56" ] } } }, "responses": { "RateLimited": { "description": "Rate limit exceeded. Honour `Retry-After` before retrying.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before the next request.", "schema": { "type": "integer" } } } }, "ServerError": { "description": "The failure is server-side; the request is worth retrying.", "content": { "application/json": { "schema": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } }, "example": { "error": "Failed to fetch jobs" } } } } }, "schemas": { "Health": { "type": "object", "description": "Service liveness.", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "`ok` when the API is serving." }, "message": { "type": "string", "description": "Human-readable detail." } } }, "Error": { "type": "object", "description": "Every failure is returned as JSON, never as an HTML error page.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong." } } }, "Job": { "type": "object", "description": "One fresher or entry-level job listing in India.", "required": [ "id", "company", "title" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable identifier for this listing." }, "company": { "type": "string", "description": "Hiring company." }, "title": { "type": "string", "description": "Role title as posted." }, "description": { "type": [ "string", "null" ], "description": "Role description as posted." }, "logo": { "type": [ "string", "null" ], "format": "uri", "description": "Company logo. The curated company logo wins over the per-listing one." }, "location": { "type": [ "string", "null" ], "description": "Where the role is based, for example `Bangalore, India`." }, "work_type": { "type": [ "string", "null" ], "description": "`On-site`, `Remote` or `Hybrid`." }, "industry": { "type": [ "string", "null" ], "description": "Industry the role sits in." }, "role_type": { "type": [ "string", "null" ], "description": "Role family, for example `Software Engineer`." }, "ctc_amount": { "type": [ "string", "null" ], "description": "Human-readable pay band, sometimes marked estimated. A display string, not a number." }, "ctc_description": { "type": [ "string", "null" ], "description": "Free-text note about compensation." }, "salary": { "type": [ "string", "null" ], "description": "Legacy salary field; prefer `ctc_amount`." }, "start_date": { "type": [ "string", "null" ], "description": "When the role starts, as posted." }, "deadline": { "type": [ "string", "null" ], "description": "Application deadline, when the source states one." }, "deadline_display": { "type": [ "string", "null" ], "description": "Human-readable deadline hint." }, "posted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the listing was posted." }, "posted_days": { "type": [ "integer", "null" ], "description": "Whole days since `posted_at`, computed at request time." }, "is_on_campus": { "type": [ "boolean", "null" ], "description": "Whether this is an on-campus opportunity." }, "is_active": { "type": [ "boolean", "null" ], "description": "Whether the listing is still open." }, "job_type": { "type": [ "string", "null" ], "description": "`job` for this collection." }, "match_score": { "type": [ "integer", "null" ], "description": "Fit score out of 100. Without a user profile this is the listing's default score, not a personalised one." }, "prestige_tier": { "type": [ "integer", "null" ], "description": "Company prestige weighting used for ordering." } } }, "Internship": { "type": "object", "description": "One internship listing in India. Same shape as `Job` with `stipend` in place of `ctc_amount`.", "required": [ "id", "company", "title" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable identifier for this listing." }, "company": { "type": "string", "description": "Hiring company." }, "title": { "type": "string", "description": "Role title as posted." }, "description": { "type": [ "string", "null" ], "description": "Role description as posted." }, "logo": { "type": [ "string", "null" ], "format": "uri", "description": "Company logo." }, "location": { "type": [ "string", "null" ], "description": "Where the internship is based." }, "work_type": { "type": [ "string", "null" ], "description": "`On-site`, `Remote` or `Hybrid`." }, "industry": { "type": [ "string", "null" ], "description": "Industry the internship sits in." }, "role_type": { "type": [ "string", "null" ], "description": "Role family." }, "stipend": { "type": [ "string", "null" ], "description": "Human-readable monthly stipend band, sometimes marked estimated." }, "duration": { "type": [ "string", "null" ], "description": "How long the internship runs." }, "posted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the listing was posted." }, "posted_days": { "type": [ "integer", "null" ], "description": "Whole days since `posted_at`." }, "is_on_campus": { "type": [ "boolean", "null" ], "description": "Whether this is an on-campus opportunity." }, "is_active": { "type": [ "boolean", "null" ], "description": "Whether the listing is still open." }, "job_type": { "type": [ "string", "null" ], "description": "`internship` for this collection." } } }, "FilterOption": { "type": "object", "description": "One allowed value for a listing filter.", "required": [ "filter_type", "filter_value" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier for this option." }, "filter_type": { "type": "string", "description": "Which filter this option belongs to, for example `work_type`." }, "filter_value": { "type": "string", "description": "The value to send to a listing endpoint." }, "display_label": { "type": "string", "description": "The label to show a person." }, "sort_order": { "type": [ "integer", "null" ], "description": "Display order within the group." }, "is_active": { "type": [ "boolean", "null" ], "description": "Whether the option is currently offered." } } }, "Event": { "type": "object", "description": "A campus or career event.", "required": [ "id", "title" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Identifier for this event." }, "title": { "type": "string", "description": "Event name." }, "company": { "type": [ "string", "null" ], "description": "Company running the event." }, "description": { "type": [ "string", "null" ], "description": "What the event covers." }, "event_type": { "type": [ "string", "null" ], "description": "Kind of event, for example `Workshop`." }, "event_date": { "type": [ "string", "null" ], "format": "date", "description": "Date the event runs." }, "event_time": { "type": [ "string", "null" ], "description": "Start time as published." }, "location": { "type": [ "string", "null" ], "description": "Venue." }, "is_online": { "type": [ "boolean", "null" ], "description": "Whether the event runs online." }, "max_attendees": { "type": [ "integer", "null" ], "description": "Capacity, when published." }, "current_attendees": { "type": [ "integer", "null" ], "description": "Registrations so far." }, "is_active": { "type": [ "boolean", "null" ], "description": "Whether the event is still listed." } } }, "HiringDataset": { "type": "object", "description": "Aggregate India fresher hiring data, rebuilt daily and licensed CC-BY-4.0.", "required": [ "updatedAt", "totals" ], "properties": { "updatedAt": { "type": "string", "format": "date-time", "description": "When this snapshot was built. Cite it alongside any figure taken from the dataset." }, "totals": { "type": "object", "description": "Headline figures for the snapshot.", "properties": { "liveListings": { "type": "integer", "description": "Live fresher and entry-level listings across India." }, "newLast7Days": { "type": "integer", "description": "Listings added in the last seven days." }, "internshipSharePct": { "type": "number", "description": "Percentage of live listings that are internships." }, "remoteSharePct": { "type": "number", "description": "Percentage of live listings that are remote." }, "medianPostingAgeDays": { "type": "number", "description": "Median age of a live listing, in days." } } }, "topCities": { "type": "array", "description": "Cities with the most live listings, most first.", "items": { "type": "object", "description": "One counted bucket in the hiring dataset.", "required": [ "count" ], "properties": { "city": { "type": "string", "description": "City slug, on city buckets." }, "role": { "type": "string", "description": "Role slug, on role buckets." }, "company": { "type": "string", "description": "Company name, on company buckets." }, "label": { "type": "string", "description": "Human-readable label for the bucket." }, "count": { "type": "integer", "description": "Live listings in this bucket." } } } }, "topRoles": { "type": "array", "description": "Role families with the most live listings, most first.", "items": { "type": "object", "description": "One counted bucket in the hiring dataset.", "required": [ "count" ], "properties": { "city": { "type": "string", "description": "City slug, on city buckets." }, "role": { "type": "string", "description": "Role slug, on role buckets." }, "company": { "type": "string", "description": "Company name, on company buckets." }, "label": { "type": "string", "description": "Human-readable label for the bucket." }, "count": { "type": "integer", "description": "Live listings in this bucket." } } } }, "topCompanies": { "type": "array", "description": "Companies with the most live listings, most first.", "items": { "type": "object", "description": "One counted bucket in the hiring dataset.", "required": [ "count" ], "properties": { "city": { "type": "string", "description": "City slug, on city buckets." }, "role": { "type": "string", "description": "Role slug, on role buckets." }, "company": { "type": "string", "description": "Company name, on company buckets." }, "label": { "type": "string", "description": "Human-readable label for the bucket." }, "count": { "type": "integer", "description": "Live listings in this bucket." } } } } } }, "DatasetBucket": { "type": "object", "description": "One counted bucket in the hiring dataset.", "required": [ "count" ], "properties": { "city": { "type": "string", "description": "City slug, on city buckets." }, "role": { "type": "string", "description": "Role slug, on role buckets." }, "company": { "type": "string", "description": "Company name, on company buckets." }, "label": { "type": "string", "description": "Human-readable label for the bucket." }, "count": { "type": "integer", "description": "Live listings in this bucket." } } } } }, "security": [] }