Usage

This API uses the JSON API specification.

The specification allows for greater customization of the response and predictable behavior.

Request format

The specification allows the user to scope the response as they see fit for their application. For example, to fetch a specific program and only return the program code, the tagline on the brief, and whether or not it is a demo program:

api.bugcrowd.com/programs/PROGRAM_UUID?fields[program]=code&fields[program_brief]=tagline,demo&include=current_brief

Notice that the key for the fields object matches the resource name, but the value for the include parameter matches the relationship name.

All resources are uniquely referenced by type and id. The id will always be a uuid format string. To get the PROGRAM_UUID from the example above, you can use the /programs endpoint to index all the programs accessible by your user and each program resource will have a type and id property at the top level. That id property can be used to reference the individual program in api.bugcrowd.com/programs/PROGRAM_UUID

Response format

{
  "data": {
    "type": "RESOURCE_TYPE",
    "id": "RESOURCE_UUID",
    "attributes": { "attribute_name": "ATTRIBUTE_VALUE" },
    "relationships": {
      "many_relationship_name": {
        "data": [
          {
            "type": "RELATIONSHIP_RESOURCE_TYPE",
            "id": "RELATIONSHIP_RESOURCE_UUID_1"
          },
          {
            "type": "RELATIONSHIP_RESOURCE_TYPE",
            "id": "RELATIONSHIP_RESOURCE_UUID_2"
          }
        ],
        "links": {
          "related": {
            "href": "PATH_TO_RELATED_SET_OF_OBJECTS",
            "meta": { "count": 2, "total_hits": 2 }
          }
        }
      }
    }
  },
  "links": { "self": "PATH_TO_CURRENT_RESOURCE" },
  "included": [
    {
      "type": "RELATIONSHIP_RESOURCE_TYPE",
      "id": "RELATIONSHIP_RESOURCE_UUID_1",
      "attributes": { "attribute_name": "ATTRIBUTE_VALUE" },
      "relationships": { }
    },
    {
      "type": "RELATIONSHIP_RESOURCE_TYPE",
      "id": "RELATIONSHIP_RESOURCE_UUID_2",
      "attributes": { "attribute_name": "ATTRIBUTE_VALUE" },
      "relationships": { }
    }
  ]
}

In this case we have returned a single resource and included a ‘has many’ relationship. The relationships object on the root resource contains the relationship which can be correlated to the full resources in the included array. Every record can be uniquely identified by type and id. Links are provided for both pagination (on index endpoints) and navigating to related records.

Reference to JSON API document structure.

Use case examples

Here are some common workflows enabled through the API to get you started. The API can be used to provide custom connections to other services like a ticketing system or continuous integration systems. It is also commonly used to populate local data stores for internal dashboards or even used to handle assignment in conjunction with a tool like PagerDuty. Bellow are some request examples to illustrate some common use cases.

If you want to fetch all unblocked submissions that are assigned to you, in order of severity, and return proof of concept information with target name (10 at a time):

api.bugcrowd.com/submissions?filter[blocked_by]=none&filter[assignee]=me&fields[submission]=title,description,vrt_id,severity,target&fields[target]=name&include=target&sort=severity-asc&page[limit]=10&page[offset]=0

If you want to update the state of a submission based on internal events:

curl -X PATCH \
     --header "Accept: application/vnd.bugcrowd+json" \
     --header "Authorization: Token TOKEN_USERNAME:TOKEN_PASSWORD" \
     --data '{
       "data": {
         "type": "submission",
         "attributes": {
           "state": "unresolved"
         }
       }
     }' \
     'api.bugcrowd.com/submissions/SUBMISSION_UUID'

If you want to import target and scope data from all programs in certain organizations:

api.bugcrowd.com/programs?filter[organization_id]=ORGANIZATION_UUID_1,ORGANIZATION_UUID_2&include=current_brief.target_groups.targets,current_brief.target_groups.reward_range&fields[program]=code,current_brief&fields[program_brief]=target_groups&fields[target_group]=name,targets,reward_range&fields[target]=name

Common parameters

GET endpoints for both an index and a single resource share common query parameters that behave in the same way.

Both:

Index only:

Filtering

Each index endpoint may have its own set of filter parameters that look like: filter[FILTER_NAME]=VALUE. Sometimes the filter is limited to a single value (such as integer), but in other cases it may allow a comma separated string of values (such as Array of integers). This will be indicated in the schema of the specific parameter.

The assignee filter on the /submissions endpoint can contain an array of emails or reserved words such as me or none. For example, the following query would return submissions that are unassigned, or assigned to either me or jane.doe@company.com:

api.bugcrowd.com/submissions?filter[assignee]=me,none,jane.doe@company.com

The duplicate filter on the /submissions endpoint only accepts a single boolean value. For example, the following query would return only submissions that are not duplicates:

api.bugcrowd.com/submissions?filter[duplicate]=false

To return both duplicates and non-duplicates do not include the duplicate filter.

Reference to JSON API filtering.

Date ranges

Some filter parameters such as the submitted filter on the /submissions endpoint allow filtering within a range of dates or timestamps. The syntax uses the from. and to. prefixes and allows passing multiple parameters to the filter separated by a comma or distinct filters separated by an &.

For example:

api.bugcrowd.com/submissions?filter[submitted]=from.2021-02-28,to.2021-03-01

Date range filters also support selecting specific dates by removing the from. and to. prefixes.

api.bugcrowd.com/submissions?filter[submitted]=2021-02-28,2021-03-01

Open ended ranges and timestamps are also supported. For example, to fetch all submissions submitted one second or more after midnight January 1, 2021.

api.bugcrowd.com/submissions?filter[submitted]=from.2021-01-01T00:00:01Z

Warning: Combining these in ways that don’t make sense (like having 2 from. or mixing ranges with specific dates) will likely return unexpected results

Sorting

Each index endpoint may also define a sort parameter with specific values that may be used. Often the sort parameter will also allow a comma separated string of values to sort by multiple criteria.

For example, to fetch all accessible submissions sorted primarily by severity ascending, and secondarily by submitted_at timestamp descending:

api.bugcrowd.com/submissions?sort=severity-asc,submitted-desc

Reference to JSON API sorting. Currently there is a deviation from the spec in naming the inverted sort parameters. This may be updated to use - instead of asc/desc in a future version.

Pagination

Pagination is controlled by 2 parameters: page[limit] and page[offset]

The limit controls the number of records returned (default: 25). The offset controls the number of records to offset the current collection.

For example, to fetch all submissions 10 at a time:

api.bugcrowd.com/submissions?page[limit]=10&page[offset]=0

Increasing the page[offset] parameter by the page[limit] parameter will get the next set of records.

Example: page[offset] = page[offset] + page[limit] (or in this case 10)

Reference to JSON API pagination.

For index endpoints links are provided in the root object of the response to follow for next and previous pages. We do not currently provide first and last links, but we will add them in a future version.

{
  "links": {
    "self": "/submissions?fields[submission]=vrt_id&page[limit]=25&page[offset]=25",
    "next": "/submissions?fields[submission]=vrt_id&page[limit]=25&page[offset]=50",
    "previous": "/submissions?fields[submission]=vrt_id&page[limit]=25&page[offset]=0"
  }
}

Limitations

Limited number of records returned

The maximum number of root records that can be returned is 100, so the range of values allowed for the page[limit] parameter is 0-100, where 0 would return no records.

For the records included from relationships, the maximum returned records will be 100 per relationship. There is no way to paginate included relationships in the same request. Resources that have a root endpoint and the correct filter for the relationship can be fetched and paginated from the root endpoint for that resource. If the relationship is not complete, there will be a discrepancy between the count and total_hits.

Example:

{
  "links": {
    "related": {
      "href": "/targets?filter[target_group_id]=TARGET_GROUP_ID",
      "meta": { "count": 100, "total_hits": 503 }
    }
  }
}

The href property can be used to access the rest of the relationship if that endpoint has been implemented.

An example of an included relationship that can be fetched from the root resource endpoint is the current_brief.target_groups.targets relationship on the /programs endpoint. If there are more than 100 targets in a group you can use the /targets endpoint with the filter[target_group_id] parameter. From the /programs endpoint the relationship on the target_group will look like the response above and the href in the relationship links can be paginated like normal: /targets?filter[target_group_id]=ID_FROM_TARGET_GROUP_RELATIONSHIP&page[limit]=100&page[offset]=200"

Maximum Offset

Currently the maximum value for the page[offset] parameter is 9900. We may explore additional options for increasing this in future versions.

There is a workaround if you wish to get all submissions for example. You can filter them into smaller groups (date ranges work well generically) then paginate through the group until the end as long as it is less than 10k total records in the filtered group.

Sparse fieldsets

The fields[RESOURCE_NAME] parameter is used to limit the data returned in the response to only what is desired. The value for the parameter is a comma separated string that can contain any attribute or relationship on the given resource. When limiting attributes the size of the response is reduced. When reducing the relationships returned the server-side performance is also improved due to not needing to load the other resources.

For example to fetch a list of program names without loading the related brief or submissions use:

api.bugcrowd.com/programs?fields[program]=name

Or to load the program and its brief, but not the submissions use:

api.bugcrowd.com/programs?fields[program]=name,current_brief

Not including the fields parameter at all defaults to returning all fields, which sometimes can be excessive.

See how to scope fields on included resources below.

Reference to JSON API sparse fieldsets.

Including additional resources

Each GET endpoint may define a list of values that can be used for the include parameter. Relationships used in the include parameter will be returned as a flat array of resources under the included key in the root object of the response.

When using the include parameter, it is often best to also use the fields parameter to scope the attributes and relationships of the included resource like so:

api.bugcrowd.com/submissions?include=program&fields[submission]=title,program&fields[program]=name

The above request would return the program type and id under the relationships of the submission, and the rest of the program resource under the included array in the root object of the response. Since all resources are unique by type and id they can be correlated between the relationships and the included array.

Reference to JSON API includes.

Nested resources

Sometimes the include parameter will also define values separated by a dot (.) that represent nested relationships that can be included in the response.

For example, on the /programs, an acceptable value for the include parameter is current_brief.target_groups.reward_range. The current_brief relationship is on the program resource and corresponds to a program_brief resource. A program_brief resource has a relationship called target_groups that is a list of target_group resources. Each target_group has a relationship that is a single reward_range.

To use these relationships from the /programs endpoint, you could add the dot notation value to the include parameter and make sure to return the relationships necessary to correlate the objects in the included array.

api.bugcrowd.com/programs?include=current_brief.target_groups.reward_range&fields[program]=current_brief&fields[program_brief]=target_groups&fields[target_group]=reward_range&fields[reward_range]=p1_max_cents

Response

{
  "data": [
    {
      "type": "program",
      "id": "RANDOM_UUID",
      "attributes": {},
      "relationships": {
        "current_brief": {
          "data": {
            "type": "program_brief",
            "id": "RANDOM_UUID"
          },
          "links": {
            "related": "(NOT IMPLEMENTED)"
          }
        }
      }
    }
  ],
  "included": [
    {
      "type": "program_brief",
      "id": "RANDOM_UUID",
      "attributes": {},
      "relationships": {
        "target_groups": {
          "data": [
            {
              "type": "target_group",
              "id": "RANDOM_UUID"
            }
          ],
          "links": {
            "related": {
              "href": "(NOT IMPLEMENTED)",
              "meta": { "count": 1, "total_hits": 1 }
            }
          }
        }
      }
    },
    {
      "type": "target_group",
      "id": "RANDOM_UUID",
      "attributes": {},
      "relationships": {
        "reward_range": {
          "data": {
            "type": "reward_range",
            "id": "RANDOM_UUID"
          },
          "links": {
            "related": "(NOT IMPLEMENTED)"
          }
        }
      }
    },
    {
      "type": "reward_range",
      "id": "RANDOM_UUID",
      "attributes": {
        "p1_max_cents": 10000
      }
    }
  ],
  "links": {
    "self": "api.bugcrowd.com/programs?include=current_brief.target_groups.reward_range&fields[program]=current_brief&fields[program_brief]=target_groups&fields[target_group]=reward_range&fields[reward_range]=p1_max_cents"
  }
}

Reference to JSON API compound document.

Visit bugcrowd.com