NAV
shell

Getting Started

API Endpoint

https://api.hackerone.com/

The HackerOne API can be used to query or update information about reports and your HackerOne program.

The API always returns a JSON response and implements REST to access resources. The API can only be accessed over HTTPS and is compliant with the JSON API specification.

API tokens can be generated from your Program Settings if you’re already using the HackerOne Professional, Community, or Enterprise edition. If you can’t generate an API token, you can contact sales to upgrade your program or create a test program to experiment with the API.

To get started with the HackerOne API:

  1. Generate an API Token.
  2. Go to Core Resources and choose the endpoint you want to pull information from.
  3. Copy the curl command for the endpoint.
  4. Paste the curl command in an editor.
  5. Edit the curl code with your own information.
  6. Paste the code into your terminal or the program you normally use to run the API call.

API sandbox

HackerOne offers a sandbox for customers to help test API functionality. To create a sandbox program, go here (make sure you're logged in to your HackerOne account. If you don't have an account yet, you can create one here). You can select any product edition, giving you access to almost all features HackerOne offers.

Authentication

cURL example

  curl "https://api.hackerone.com/v1/reports/129329" \
    -u "<YOUR_API_USERNAME>:<YOUR_API_TOKEN>"

Replace the example credentials in the example above with your own.

HTTP Basic authentication is used to authenticate to the API. As an Admin User you can generate and manage API Tokens from your organization's settings page. The API Token identifier and value are used as the username and password for basic authentication and must be sent in the Authorization header for every request.

If you set up an IP whitelist for your account and provide valid credentials, the server will respond with a 403 Forbidden response. If an invalid token is provided, the server will respond with a 401 Unauthorized response. See the error codes section for more information how these errors are returned.

Rate Limits

To ensure a pleasant platform experience for all our users, we have implemented several rate limits in our API. Customers who send too many requests may see an error show up with the status code: 429. We have the following rate limits in place:

Error Responses

Error Code Meaning Description
400 Bad Request Request does not conform with the specification. Please see the endpoint's documentation for further instructions.
401 Unauthorized The client sent a request without any form to identification. More information about this error can be found in the Authentication section.
403 Forbidden The API token does not grant the client access to perform this action. This can happen in case where the client requests a resource that belongs to another program or account.
404 Not Found The requested resource is not found. The client might be using outdated information to identify the resource.
406 Not Acceptable This error is returned when the client requests our API to respond in a format that we haven't implemented yet. The current version of the API only supports responses to be returned when the client requests application/javascript. The good news is that most clients do this by default, so you shouldn't see this error very often.
422 Unprocessable Entity The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
429 Too Many Requests The client sent too many requests, please review our rate limits to make sure you're not sending more requests than the limit indicates.
500 Internal Server Error This means that there's an error on our side. Our engineering team is notified of these errors, so we try to come up with a solution as soon as possible. If the error persists, please contact https://support.hackerone.com/
503 Service Unavailable Seems like our servers are offline. You can check our server status at www.hackeronestatus.com.

Versioning

URL structure

https://api.hackerone.com/{version}/{resource}

The entire API uses a global version. For every backwards-incompatible change, the version is bumped. There is no default version, so the requested version must be specified in the resource URL.

Introducing new attributes or resources are not considered backwards-incompatible and can be added to the latest stable version at any time.

Clients

There are open source API clients that are maintained by our customers and hackers. These libraries are welcoming contributions and can be found on GitHub.

Ruby: hackerone-client

Python: h1-python

Go: hackeroni

Erlang: h1.erl

Node.js: hackerone-client

Changelog

May 17, 2024: Added endpoint to Hai completion.

May 15, 2024: Added activity-report-vulnerability-information-updated object.

April 24, 2024: Added "organization" relationship to the program object.

March 1, 2024: Added "citizenship_verified" and "residency_verified" boolean fields to the allowed reporter object.

February 27, 2024: Added endpoint to get all CVE requests for programs. Added endpoint to create a CVE request for programs. Added endpoint to update CVEs for a report.

February 26, 2024: Added "rules_of_engagement_signed", "identity_verified" and "background_checked" boolean fields to the allowed reporter object.

February 8, 2024: Added "state" and "archived_at" fields to the asset object and enabled filtering assets by "state" and "archived" parameters.

February 2, 2024: Added "inbox_ids" filter field to the Get All Reports endpoint.

February 1, 2024: Added "submitted_at" field to the reports endpoint and enabled filtering by "submitted_at_gt" and "submitted_at_lt" parameters.

January 25, 2024: Added "cvss_vector_string" field to the severity object.

January 9, 2024: Enabled filtering assets by ID greater than the specified ID.

January 4, 2024: Added "old_severity" and "new_severity" relationships to the activity-report-severity-updated object.

December 6, 2023: Added aiModel asset type.

December 4, 2023: Adjusted rate limiting for reports to be more lenient.

November 28, 2023: Added "last_sign_in_at" attribute to the organization member object.

October 17, 2023: Added endpoint to get all inboxes for organizations. Added inboxes relationship to report. Added endpoint to update inboxes for a report.

October 12, 2023: Implemented more strict rate limiting for reports

October 5, 2023: Added collaborators relationship to report.

July 19, 2023: Added endpoint to get allowed reporters of a private program.

July 19, 2023: Added endpoint to get activities of allowed reporter of a private program.

July 19, 2023: Deprecated "Get whitelisted reporters of a private program" endpoint and get activities of whitelisted reporter of a private program endpoints. Use get allowed reporters of a private program and get activities of allowed reporter of a private program instead.

July 11, 2023: Added sorting by report_id, created_at, updated_at fields on query activities endpoint.

July 5, 2023: Added endpoint to get whitelisted reporters of a private program.

July 5, 2023: Added endpoint to get activities of whitelisted reporter of a private program.

May 2, 2023: Added the attribute email to organization-member object.

February 13, 2023: Added endpoint to get all programs for organizations.

February 9, 2023: Added endpoint to get all eligibility settings in an organization.

February 9, 2023: Added endpoint to get an eligibility settings in an organization.

February 7, 2023: Added endpoint to create a group for an organizations.

February 6, 2023: Added endpoint to get a member in an organization.

February 6, 2023: Added endpoint to update a group from an organizations.

February 3, 2023: Added endpoint to get a group in an organization.

February 1, 2023: Added endpoint to list pending invitations in an organization.

January 31, 2023: Added endpoint to update a member for an organizations.

January 31, 2023: Added endpoint to delete a member for an organizations.

January 25, 2023: Added error 422 to error responses.

January 25, 2023: Added endpoint to create an invitation to an organizations.

January 25, 2023: Added endpoint to get all groups for organizations.

January 24, 2023: Added endpoint to get all members for organizations.

January 6, 2023: Added endpoint to add an asset to scope for assets.

January 6, 2023: Added endpoint to add an archive asset scopes for assets.

January 6, 2023: Added endpoint to update an asset for assets.

January 6, 2023: Added endpoint to archive assets for assets.

December 12, 2022: Updated valid key parameter values for analytics.

November 9, 2022: Added endpoint to get analytics data for analytics.

September 6, 2022: Added endpoint to get your organizations for organizations.

July 20, 2022: Added endpoint to create an asset for assets.

July 20, 2022: Added endpoint to get all assets for assets.

July 20, 2022: Added endpoint to get an asset for assets.

July 20, 2022: Added endpoint to get all asset tags for assets.

July 20, 2022: Added endpoint to retrieve an assets import for assets.

July 20, 2022: Added endpoint to import assets with CSV file for assets.

October 12, 2021: Added endpoint to upload attachments for state changes.

September 30, 2021: Added endpoint to upload attachments for comments.

November 9, 2020: Added automated and custom remediation guidance attributes to the report object.

November 3, 2020: Added rate limits for read and write operations to ensure platform stability.

October 26, 2020: Added endpoint to request a retest for a report.

October 9, 2020: Added endpoint to get an activity by ID.

August 17, 2020: Added report attributes that track how long it took to respond, triage, reward, and resolve a report. Additionally, the report object now also contains when it expects any of those actions to happen.

February 7, 2020: Added endpoint to add report participants.

January 9, 2020: Added endpoint to transfer reports between related programs

November 20, 2019: Added program management permission requirement to the get awarded swag endpoint.

October 31, 2019: Added endpoint to upload attachments to program policy.

October 30, 2019: Enabled filtering reports by hacker disclosure request. Added attribute to report for timestamp when the reporter agreed for disclosure.

October 28, 2019: Added groups attribute to member object.

October 25, 2019: Added endpoint for redacting reports.

October 24, 2019: Added endpoint for cancelling the report disclosure request.

October 18, 2019: Added attribute for requesting report disclosure to show the disclosure timestamp.

October 15, 2019: Added endpoint for requesting report disclosure.

October 11, 2019: Added endpoint for showing program policy and its attachments.

October 10, 2019: Added endpoint for fetching bounty suggestions.

October 10, 2019: Added endpoint to fetch all program swag.

October 9, 2019: Added endpoint for filtering reports by keywords.

October 9, 2019: Enabled filtering reports by severities.

October 8, 2019: Added endpoint for updating report structured scope.

October 7, 2019: Added endpoint for getting program's balance.

October 7, 2019: Added endpoint for fetching program payment transactions.

October 7, 2019: Added endpoint for fetching program thanks items.

October 3, 2019: Enabled filtering reports by weaknesses.

September 26, 2019: Added endpoint for marking swag as sent.

September 25, 2019: Made title, vulnerability information, impact, and source parameters required for the report create endpoint.

September 5, 2019: Added endpoint to mark a report as ineligible for bounty.

August 29, 2019: Added endpoint for updating program policy.

August 23, 2019: Added endpoint for updating report weakness.

Aug 22, 2019: Added endpoint to create reports.

August 21, 2019: Added endpoint for fetching program weaknesses.

June 26, 2019: Added a severity parameter to create a program bounty, it will set the severity for the created report.

June 25, 2019: Made the recipient parameter optional to create a program bounty and added the claim link to the response.

May 23, 2019: Added filter attribute to include/exclude hacker published reports.

May 15, 2019: Added endpoint to read Audit Log for a Program.

April 24, 2019: Expose Custom Field Attributes on a Program and added endpoint for updating Custom Field Values on a Report.

February 19, 2019: Added endpoint for creating/updating severities on reports.

February 4, 2019: Enabled filtering reports by assignee emails.

December 4, 2018: Added endpoints for fetching, creating, updating, and archiving structured scopes.

November 26, 2018: Added activities endpoint.

November 8, 2018: Enabled filtering reports by assignees.

August 20, 2018: Added attribute to report to show CVE IDs.

July 6, 2018: Added endpoint for fetching specific data of a user.

August 29, 2017: added endpoint for fetching common responses of a program.

August 28, 2017: added endpoints for awarding bounties, suggesting bounties, and for awarding swag.

May 10, 2017: added last_public_activity_at in favor of last_activity_at. The new attribute can be used in filtering and exposes the date of the last public activity. The last_activity_at attribute will now return the date of the last activity, both public and internal.

March 29, 2017: added endpoint to disable commenting / locking a report.

March 28, 2017: added the reports resource that enables the user to update the title of reports that are received by teams the API user is part of.

February 20, 2017: added the me resource that enables the user to query the programs the API user is part of.

January 26, 2017: added ability to filter reports based on user usernames. Added endpoint to retrieve a list of users that participated in a program.

November 23, 2016: added ability to set a page size when querying reports.

November 2, 2016: added ability to change the state of a report object and added ability to post internal and public comments.

October 5, 2016: added severity relationship to report object.

September 23, 2016: added endpoint to query more information about a program.

September 21, 2016: added ability to assign users and groups to a report.

August 24, 2016: added reputation, signal, and impact metrics of a report's reporter.

July 19, 2016: removed inlining if a report in the bug cloned activity to avoid a denial of service vulnerability when the original report references the cloned report.

July 19, 2016: fixed a bug where the time in a date filter was erroneously truncated.

July 18, 2016: added activity objects for hacker mediation requests and vulnerability types updates.

June 1, 2016: the endpoint for querying reports now returns descriptive errors in case an invalid filter value is given.

May 23, 2016: added last_activity_at attribute to the report object and as a filter for querying reports.

May 23, 2016: removed inlined duplicate report object from activities relationship when a single report is fetched.

May 6, 2016: introduced endpoint to query multiple reports.

April 14, 2016: introduced endpoint to query a single report.

Feedback

We strive to build the best API possible to help you fulfill your API use cases. If you have any questions or feedback, feel free to reach out to us at feedback@hackerone.com.