{
  "aid": "homerun.co:main-2.0.0",
  "name": "Homerun Public API",
  "type": "Index",
  "description": "# Introduction\n\nWelcome to the Homerun API! You can use our API to programmatically access your jobs and applicants in Homerun.\n\n\n## Authentication\n\nAll API endpoints require Bearer authentication. We'll reference this authentication method later in this document as `public-api-v2-key`. Example authentication header:\n\n```http\nAuthorization: Bearer <your secret API key>\n```\n\n## Authorization\n\nYour API key has scopes attached to it. Those scopes are used to authorize request to each endpoint. We recommend that you only assign scopes that you need to get the job done and nothing more.\n\nScopes can only be assigned once, when generating a new key on the [Integrations Page](https://app.homerun.co/settings/integrations) page in the Homerun App.\n\nPossible scopes include:\n\n* `vacancies:read`\n* `job-applications:read`\n* `job-applications:write`\n* `job-application-notes:read`\n* `job-application-notes:write`\n* `job-application-files:write`\n\nCheck endpoint documentation below to learn which scopes are required to make a specific request.\n\n## General security advice and fair use\n\nDon’t share your API key in publicly accessible places such as client-side code or services like Github. If you suspect unauthorized usage of your key, please delete it on the [Integrations Page](https://app.homerun.co/settings/integrations) in the Homerun App.\n\nWhen assigning scopes to your API keys, follow the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) and only grant the scopes that are absolutely necessary for your use-case. If you want to use our API in multiple workflows, consider generating separate keys with scopes tailored to the their specific needs, rather than re-using the same key.\n\nConsider periodically rotating your API keys. You can have up to 10 active API keys, so you can generate new ones to replace old ones without forcing downtime on your workflows.\n\nNote that keys can have an expiry date assigned to them. You can use it for keys that you know in advance you'll only need for a limited time.\n\nIf your workflow only involves fetching a list of vacancies, please consider using our [Job XML Feeds](https://help.homerun.co/en/articles/5013627-how-do-i-generate-an-xml-feed) feature instead.\n\nWe enforce a rate limit of 60 requests per minute to our API to ensure fair usage and limit abuse.\n\n## Pagination\n\nAll endpoints returning a list of objects are using configurable pagination mechanism. You can adjust the number of items per page (through `perPage` parameter). You can fetch more objects by incrementing the `page` query parameter. Pagination metadata is returned in a separate, top-level `meta` property, providing convenience links to following pages, current pagination state and a total number of objects.\n\nExample of a `meta` object:\n\n```json\n{\n    \"meta\": {\n        \"current_page\": 1,\n        \"from\": 1,\n        \"last_page\": 4,\n        \"links\": [\n            {\n                \"url\": null,\n                \"label\": \"&laquo; Previous\",\n                \"active\": false\n            },\n            {\n                \"url\": \"http://api.homerun.co/v2/job-applications?page=1\",\n                \"label\": \"1\",\n                \"active\": true\n            },\n            {\n                \"url\": \"http://api.homerun.co/v2/job-applications?page=2\",\n                \"label\": \"2\",\n                \"active\": false\n            },\n            {\n                \"url\": \"http://api.homerun.co/v2/job-applications?page=3\",\n                \"label\": \"3\",\n                \"active\": false\n            },\n            {\n                \"url\": \"http://api.homerun.co/v2/job-applications?page=4\",\n                \"label\": \"4\",\n                \"active\": false\n            },\n            {\n                \"url\": \"http://api.homerun.co/v2/job-applications?page=2\",\n                \"label\": \"Next &raquo;\",\n                \"active\": false\n            }\n        ],\n        \"path\": \"http://api.homerun.co/v2/job-applications\",\n        \"per_page\": 15,\n        \"to\": 15,\n        \"total\": 46\n    }\n}\n```\n\n## Changelog\n\n### 21.09.2023\n\n* `total_candidate_count` field from `Vacancy` schema is now an optional and can be added using `include[]=total_candidate_count`\n\n### 14.09.2023\n\n* `is_remote` field from `Vacancy` has been deprecated in favour of the new enum `location_type` field. `remote` is one of the values of the new field.\n",
  "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/homerun.co/main/2.0.0/apis.json",
  "tags": [
    "homerun.co",
    "main"
  ],
  "created": "2026-03-31",
  "modified": "2026-03-31",
  "specificationVersion": "0.19",
  "access": "3rd-Party",
  "maintainers": [
    {
      "FN": "Jentic",
      "X-github": "jentic",
      "url": "https://github.com/jentic"
    }
  ],
  "apis": [
    {
      "aid": "homerun.co:main-2.0.0",
      "name": "Homerun Public API",
      "description": "# Introduction\n\nWelcome to the Homerun API! You can use our API to programmatically access your jobs and applicants in Homerun.\n\n\n## Authentication\n\nAll API endpoints require Bearer authentication. We'll reference this authentication method later in this document as `public-api-v2-key`. Example authentication header:\n\n```http\nAuthorization: Bearer <your secret API key>\n```\n\n## Authorization\n\nYour API key has scopes attached to it. Those scopes are used to authorize request to each endpoint. We recommend that you only assign scopes that you need to get the job done and nothing more.\n\nScopes can only be assigned once, when generating a new key on the [Integrations Page](https://app.homerun.co/settings/integrations) page in the Homerun App.\n\nPossible scopes include:\n\n* `vacancies:read`\n* `job-applications:read`\n* `job-applications:write`\n* `job-application-notes:read`\n* `job-application-notes:write`\n* `job-application-files:write`\n\nCheck endpoint documentation below to learn which scopes are required to make a specific request.\n\n## General security advice and fair use\n\nDon’t share your API key in publicly accessible places such as client-side code or services like Github. If you suspect unauthorized usage of your key, please delete it on the [Integrations Page](https://app.homerun.co/settings/integrations) in the Homerun App.\n\nWhen assigning scopes to your API keys, follow the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) and only grant the scopes that are absolutely necessary for your use-case. If you want to use our API in multiple workflows, consider generating separate keys with scopes tailored to the their specific needs, rather than re-using the same key.\n\nConsider periodically rotating your API keys. You can have up to 10 active API keys, so you can generate new ones to replace old ones without forcing downtime on your workflows.\n\nNote that keys can have an expiry date assigned to them. You can use it for keys that you know in advance you'll only need for a limited time.\n\nIf your workflow only involves fetching a list of vacancies, please consider using our [Job XML Feeds](https://help.homerun.co/en/articles/5013627-how-do-i-generate-an-xml-feed) feature instead.\n\nWe enforce a rate limit of 60 requests per minute to our API to ensure fair usage and limit abuse.\n\n## Pagination\n\nAll endpoints returning a list of objects are using configurable pagination mechanism. You can adjust the number of items per page (through `perPage` parameter). You can fetch more objects by incrementing the `page` query parameter. Pagination metadata is returned in a separate, top-level `meta` property, providing convenience links to following pages, current pagination state and a total number of objects.\n\nExample of a `meta` object:\n\n```json\n{\n    \"meta\": {\n        \"current_page\": 1,\n        \"from\": 1,\n        \"last_page\": 4,\n        \"links\": [\n            {\n                \"url\": null,\n                \"label\": \"&laquo; Previous\",\n                \"active\": false\n            },\n            {\n                \"url\": \"http://api.homerun.co/v2/job-applications?page=1\",\n                \"label\": \"1\",\n                \"active\": true\n            },\n            {\n                \"url\": \"http://api.homerun.co/v2/job-applications?page=2\",\n                \"label\": \"2\",\n                \"active\": false\n            },\n            {\n                \"url\": \"http://api.homerun.co/v2/job-applications?page=3\",\n                \"label\": \"3\",\n                \"active\": false\n            },\n            {\n                \"url\": \"http://api.homerun.co/v2/job-applications?page=4\",\n                \"label\": \"4\",\n                \"active\": false\n            },\n            {\n                \"url\": \"http://api.homerun.co/v2/job-applications?page=2\",\n                \"label\": \"Next &raquo;\",\n                \"active\": false\n            }\n        ],\n        \"path\": \"http://api.homerun.co/v2/job-applications\",\n        \"per_page\": 15,\n        \"to\": 15,\n        \"total\": 46\n    }\n}\n```\n\n## Changelog\n\n### 21.09.2023\n\n* `total_candidate_count` field from `Vacancy` schema is now an optional and can be added using `include[]=total_candidate_count`\n\n### 14.09.2023\n\n* `is_remote` field from `Vacancy` has been deprecated in favour of the new enum `location_type` field. `remote` is one of the values of the new field.\n",
      "image": "img/logo.svg",
      "baseURL": "https://api.homerun.co/v2",
      "humanURL": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/homerun.co/main/2.0.0",
      "version": "2.0.0",
      "tags": [
        "homerun.co",
        "main"
      ],
      "properties": [
        {
          "type": "OpenAPI",
          "name": "OpenAPI definition",
          "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/homerun.co/main/2.0.0/openapi.json",
          "mediaType": "application/openapi+json"
        },
        {
          "type": "GitHubRepo",
          "url": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/homerun.co/main/2.0.0"
        }
      ]
    }
  ]
}