NAV Navbar
shell

Getting Started

API Reference

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. It is compliant with the JSON API specification.

API tokens can be generated from your Program Settings if you are already using HackerOne Professional, Community, or Enterprise edition. Otherwise, you can contact sales to upgrade your program or create a test program to experiment with the API.

Changelog

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 10th, 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 29th, 2017: added endpoint to disable commenting / locking a report.

March 28th, 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 20th, 2017: added the me resource that enables the user to query the programs the API user is part of.

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

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

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

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

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

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

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

July 19th, 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 19th, 2016: fixed a bug where the time in a date filter was erroneously truncated.

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

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

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

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

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

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

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

Use cases

Get a list of new and triaged reports

  require 'httparty'

  basic_auth = {
    username: 'api_example_company',
    password: 'Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ=',
  }

  query = {
    filter: {
      program: ['john_doe_example_company'],
      state: ['new', 'triaged'],
    },
    sort: 'reports.last_program_activity_at',
  }

  HTTParty.get 'https://api.hackerone.com/v1/reports',
    query: query,
    basic_auth: basic_auth

A Ruby example to get a list of new and triaged reports. Requires 3rd party gem HTTParty to be installed.

The API is made for customers that have a need to access and interact with their HackerOne report data and be able to automate their workflows. Customers use this to generate dashboards, automatically escalate reports to their internal systems, assign users based on on-call personnel or when an internal ticket is resolved, interact with the reporters, and more. The public API provides a bi-directional channel to consume and interact with reports.

We have provided a code example on the right to show how easy it is to use. The code example fetches new and triaged reports, sorted by the last time someone from your program touched it.

Authentication

cURL example

  curl "https://api.hackerone.com/v1/reports/129329" \
    -u "api_example_company:Ke+2jinhe5jM87P95aAVOz7L3ZWrtSiERtyOkkh5tEQ="

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 program's API 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.

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.

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.