NAV

Introduction

The Cobalt API gives you REST access to Organizations, Assets, Pentests, Findings, and Events.

API Versions

Authentication

Cobalt uses API tokens to allow access to various endpoints. You can create a new Cobalt API token from within your Cobalt profile.

Cobalt expects the API token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer YOUR-PERSONAL-API-TOKEN

Our Living Documentation and API Explorer are located in Swagger and built with the OpenAPI specification. To explore our API, complete the following steps:

Most API calls are scoped to a specific organization, with the X-Org-Token header. We include that header, as needed, in our API calls.

To see which organizations you belong to:

Organizations

Get All Organizations

curl -X GET "https://api.cobalt.io/orgs" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "or_Uevoq7MyoYsPT9NPc3conL",
        "name": "Acme Corp.",
        "token": "e9d6da*****************************0e8ad"
      },
      "links": {
        "ui": {
          "url": "https://api.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
        }
      }
    },
    {
      "resource": {
        "id": "or_SnUYXDBYd2qbaDSuNRNa5q",
        "name": "Lorem Corp.",
        "token": "f1d6da*****************************0e8ad"
      },
      "links": {
        "ui": {
          "url": "https://api.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
        }
      }
    }
  ],
  "pagination": {
    "next_page": "/orgs?cursor=a1b2c3d4",
    "prev_page": "/orgs?cursor=4d3c2b1a"
  }
}

This endpoint retrieves a list of organizations, i.e. orgs, that you belong to. Save the token field to be used in your X-Org-Token header in subsequent calls in querying for assets, findings, pentests and events that belong to that organization.

HTTP Request

GET https://api.cobalt.io/orgs

URL Parameters

ParameterDefaultDescription
cursorN/AUsed for pagination, e.g. https://api.cobalt.io/orgs?cursor=a1b2c3d4
limit10If specified, returns only a specified amount of organizations, e.g. https://api.cobalt.io/orgs?limit=5

Response Fields

FieldDescription
idA unique ID representing the organization. Starts with or_
nameThe name of the organization
tokenThe organization token you’ll need in subsequent calls
links.ui.urlA link to redirect an authorized user to this organization in the Cobalt web application

Assets

Get All Assets

curl -X GET "https://api.cobalt.io/assets" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "as_GZgcehapJUNh6mjNuqsE4T",
        "title": "Acme Corp. HR System",
        "description": "HR system of the Acme Corp. holding sensitive employee data",
        "asset_type": "web",
        "logo": "https://s3.amazonaws.com/acmecorp/uploads/attachment/file/12345/cat.jpeg?something=1",
        "attachments": [
          {
            "id": "at_LA5GcEL4HRitFGCHREqmzL",
            "file_name": "rainbow.jpeg",
            "download_url": "https://s3.amazonaws.com/acmecorp/uploads/attachment/file/12345/rainbow.jpeg?something=1"
          }
        ]
      },
      "links": {
        "ui": {
          "url": "https://api.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
        }
      }
    }
  ],
  "pagination": {
    "next_page": "/assets?cursor=a1b2c3d4",
    "prev_page": "/assets?cursor=4d3c2b1a"
  }
}

This endpoint retrieves a list of assets that belong to the organization specified in the X-Org-Token header.

HTTP Request

GET https://api.cobalt.io/assets

URL Parameters

ParameterDefaultDescription
cursorN/AUsed for pagination, e.g. https://api.cobalt.io/assets?cursor=a1b2c3d4
limit10If specified, returns only a specified amount of assets, e.g. https://api.cobalt.io/assets?limit=5

Response Fields

FieldDescription
idA unique ID representing the asset. Starts with as_
titleThe title of the asset; set by user creating the asset
descriptionA description of the asset; set by user creating the asset
asset_typeAn asset type, such as; api, cloud_config, external_network, internal_network, mobile, web, web_plus_api, web_plus_mobile
logoA link pointing the location of the uploaded asset logo
attachmentsA list of asset attachments. Attachment download URLs are pre-authorized and will expire after 10 minutes.
links.ui.urlA link to redirect an authorized user to this asset in the Cobalt web application

Get an Asset

curl -X GET "https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"

The above command returns JSON structured like this:

{
  "data": {
    "resource": {
      "id": "as_GZgcehapJUNh6mjNuqsE4T",
      "title": "Acme Corp. HR System",
      "description": "HR system of the Acme Corp. holding sensitive employee data",
      "asset_type": "web",
      "logo": "https://s3.amazonaws.com/acmecorp/uploads/attachment/file/12345/cat.jpeg?something=1",
      "attachments": [
        {
          "id": "at_LA5GcEL4HRitFGCHREqmzL",
          "file_name": "rainbow.jpeg",
          "download_url": "https://s3.amazonaws.com/acmecorp/uploads/attachment/file/12345/rainbow.jpeg?something=1"
        }
      ]
    },
    "links": {
      "ui": {
        "url": "https://api.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
      }
    }
  }
}

This endpoint retrieves a specific asset belonging to the organization specified in the X-Org-Token header.

HTTP Request

GET https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER

Response Fields

FieldDescription
idA unique ID representing the asset. Starts with as_
titleThe title of the asset; set by user creating the asset
descriptionA description of the asset; set by user creating the asset
asset_typeAn asset type, such as; api, cloud_config, external_network, internal_network, mobile, web, web_plus_api, web_plus_mobile
logoA link pointing the location of the uploaded asset logo
attachmentsA list of asset attachments (including the logo). Attachment download URLs are pre-authorized and will expire after 10 minutes.
links.ui.urlA link to redirect an authorized user to this asset in the Cobalt web application

Create an Asset

curl -X POST "https://api.cobalt.io/assets" \
  -H 'Accept: application/vnd.cobalt.v2+json' \
  -H 'Authorization: Bearer YOUR-PERSONAL-API-TOKEN' \
  -H 'Content-Type: application/vnd.cobalt.v2+json' \
  -H 'Idempotency-Key: A-UNIQUE-IDENTIFIER-TO-PREVENT-UNINTENTIONAL-DUPLICATION' \
  -H 'X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN' \
  --data '{
            "title": "Test Asset",
            "description": "Lorem ipsum",
            "asset_type": "web"
          }'

The above command returns no data and a 201 response code when successful. There will be a Location header pointing at the newly-created asset.

This endpoint creates a new asset belonging to the organization specified in the X-Org-Token header.

HTTP Request

POST https://api.cobalt.io/assets

Body

FieldDescription
titleThe title of the asset; set by user creating the asset
descriptionA description of the asset; set by user creating the asset
asset_typeapi, cloud_config, external_network, internal_network, mobile, web, web_plus_api, or web_plus_mobile

Response

On successful creation, a 201 response code will be returned. A response header, Location, will contain the URL within Cobalt’s API of the new asset.

Update an Asset

curl -X PUT 'https://api.cobalt.io/assets/AN-ASSET-IDENTIFIER' \
  -H 'Accept: application/vnd.cobalt.v2+json' \
  -H 'Authorization: Bearer YOUR-PERSONAL-API-TOKEN' \
  -H 'Content-Type: application/vnd.cobalt.v2+json' \
  -H 'X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN' \
  --data '{
            "title": "Updated title",
            "description": "Updated description",
            "asset_type": "web",
            "size": "m",
            "coverage": "standard"
          }'

The above command returns no data and a 204 response code when successful.

This endpoint updates an asset belonging to the organization specified in the X-Org-Token header.

HTTP Request

PUT https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER

Body

FieldDescription
titleThe title of the asset; set by user creating the asset
descriptionA description of the asset; set by user creating the asset
asset_typeOptions: api, cloud_config, external_network, internal_network, mobile, web, web_plus_api, web_plus_mobile
sizeOptions: xs (extra small), s (small), m (medium), l (large), xl (extra large)
coverageOptions: extra_light, light, standard, large, extra_large

Response

On a successful update, a 204 response code will be returned.

Delete an Asset

curl -X DELETE 'https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER' \
  -H 'Accept: application/vnd.cobalt.v2+json' \
  -H 'Authorization: Bearer YOUR-PERSONAL-API-TOKEN' \
  -H 'Content-Type: application/vnd.cobalt.v2+json' \
  -H 'X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN'

The above command returns no data and a 204 response code when successful.

This endpoint deletes an asset belonging to the organization specified in the header.

HTTP Request

DELETE https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER

Response

On successful deletion, a 204 response code will be returned.

Upload an Attachment

curl -X POST 'https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER/attachments' \
  -H 'Accept: application/vnd.cobalt.v2+json' \
  -H 'Authorization: Bearer YOUR-PERSONAL-API-TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -H 'Idempotency-Key: A-UNIQUE-IDENTIFIER-TO-PREVENT-UNINTENTIONAL-DUPLICATION' \
  -H 'X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN'
  --form 'attachment=@"/path/to/image.jpg"'

The above command returns no data and a 201 response code when successful. There will be a Location header pointing at the newly-created attachment.

This endpoint uploads a new attachment for an asset belonging to the organization specified in the X-Org-Token header.

HTTP Request

POST https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER/attachments

Body

Form fieldDescription
attachmentThe file to upload as an attachment.

File Requirements

Response

On successful upload, a 201 response code will be returned. A response header, Location, will contain the URL within Cobalt’s API of the new attachment which you can use only to DELETE the attachment.

Delete an Attachment

curl -X DELETE 'https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER/attachments/YOUR-ATTACHMENT-IDENTIFIER' \
  -H 'Accept: application/vnd.cobalt.v2+json' \
  -H 'Authorization: Bearer YOUR-PERSONAL-API-TOKEN' \
  -H 'X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN'

The above command returns no data and a 204 response code when successful.

This endpoint deletes an attachment from an asset belonging to the organization specified in the header.

HTTP Request

DELETE https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER/attachments/YOUR-ATTACHMENT-IDENTIFIER

You can obtain this URL from the Location response header of the create attachment endpoint, or build it by getting the attachment identifier from the response data of the GET /assets endpoint.

Response

On successful deletion, a 204 response code will be returned.

curl -X POST 'https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER/logo' \
  -H 'Accept: application/vnd.cobalt.v2+json' \
  -H 'Authorization: Bearer YOUR-PERSONAL-API-TOKEN' \
  -H 'Content-Type: multipart/form-data' \
  -H 'Idempotency-Key: A-UNIQUE-IDENTIFIER-TO-PREVENT-UNINTENTIONAL-UPLOADS' \
  -H 'X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN'
  --form 'attachment=@"/path/to/image.jpg"'

The above command returns no data and a 201 response code when successful.

This endpoint updates the logo for an asset belonging to the organization specified in the X-Org-Token header. This means the old logo is removed and replaced by the new logo.

HTTP Request

POST https://api.cobalt.io/assets/YOUR-ASSET-IDENTIFIER/logo

Body

Form fieldDescription
attachmentThe file to upload as a logo.

File Requirements

Response

On successful upload, a 201 response code will be returned.

Pentests

Get All Pentests

curl -X GET "https://api.cobalt.io/pentests" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "pt_JQJpAAMjyc8sVtXW2X2Aq5",
        "title": "HR System Security Test 2022-Q4",
        "objectives": "Coverage of OWASP top 10, ASVS and application logic.",
        "state": "new",
        "tag": "#PT5940",
        "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL",
        "platform_tags": [
          "rails",
          "ruby",
          "aws"
        ],
        "methodology": "web",
        "targets": [
          "https://example.com",
          "192.168.1.1"
        ],
        "start_date": "Dec 11 2019",
        "end_date": "Dec 25 2019"
      },
      "links": {
        "ui": {
          "url": "https://api.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
        }
      }
    }
  ],
  "pagination": {
    "next_page": "/pentests?cursor=a1b2c3d4",
    "prev_page": "/pentests?cursor=4d3c2b1a"
  }
}

This endpoint retrieves a list of all pentests that belong to the organization specified in the X-Org-Token header.

HTTP Request

GET https://api.cobalt.io/pentests

URL Parameters

ParameterDefaultDescription
assetN/AIf specified, returns pentests scoped to this asset id, e.g. https://api.cobalt.io/pentests?asset=as_GZgcehapJUNh6mjNuqsE4T
cursorN/AUsed for pagination, e.g. https://api.cobalt.io/pentests?cursor=a1b2c3d4
limit10If specified, returns only a specified amount of pentests, e.g. https://api.cobalt.io/pentests?limit=5

Response Fields

FieldDescription
idA unique ID representing the pentest. Starts with pt_
titleThe title of the returned pentest.
objectivesThe objectives of the pentest. E.g. “Coverage of OWASP Top 10”
asset_idID of the asset that the returned pentest belongs to
platform_tagsTech stack of the target. E.g. java, kotlin, ruby, aws, and so on.
methodologyPentest methodology. Web, API, Web+API, Mobile, External Network and so on.
targetsTargetted IP addresses, domains, services, and so on.
start_dateThe starting date of the pentest. Format: Dec 11 2019
end_dateThe ending date of the pentest. Format: Dec 11 2019
statenew, in_review, planned, cancelled, live, remediation, or closed
links.ui.urlA link to redirect an authorized user to this pentest in the Cobalt web application

Get a Pentest

curl -X GET "https://api.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"

The above command returns JSON structured like this:

{
  "data": {
    "resource": {
      "id": "pt_JQJpAAMjyc8sVtXW2X2Aq5",
      "title": "HR System Security Test 2022-Q4",
      "objectives": "Coverage of OWASP top 10, ASVS and application logic.",
      "state": "new",
      "tag": "#PT5940",
      "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL",
      "platform_tags": [
        "rails",
        "ruby",
        "aws"
      ],
      "methodology": "web",
      "targets": [
        "https://example.com",
        "192.168.1.1"
      ],
      "start_date": "Dec 11 2019",
      "end_date": "Dec 25 2019"
    },
    "links": {
      "ui": {
        "url": "https://api.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
      }
    }
  }
}

This endpoint retrieves a specific pentest that belongs to the organization specified in the X-Org-Token header.

HTTP Request

GET https://api.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER-HERE

Response Fields

FieldDescription
idA unique ID representing the pentest. Starts with pt_
titleThe title of the returned pentest.
objectivesThe objectives of the pentest. E.g. “Coverage of OWASP Top 10”
asset_idID of the asset that the returned pentest belongs to
platform_tagsTech stack of the target. E.g. java, kotlin, ruby, aws, and so on.
methodologyPentest methodology. Web, API, Web+API, Mobile, External Network and so on.
targetsTargetted IP addresses, domains, services, and so on.
start_dateThe starting date of the pentest. Format: Dec 11 2019
end_dateThe ending date of the pentest. Format: Dec 11 2019
statenew, in_review, planned, cancelled, live, remediation, or closed
links.ui.urlA link to redirect an authorized user to this pentest in the Cobalt web application

Get a Pentest Report

curl -X GET "https://api.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER/report" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"

The above command returns JSON structured like this:

{
  "data": {
    "resource": {
      "id": "pt_JQJpAAMjyc8sVtXW2X2Aq5",
      "title": "Pentest Title",
      "state": "live",
      "asset": {
        "id": "as_4L4ZjKgfzP7VBwUmqCZmmL",
      },
      "pentesters": [
        {
          "username": "user1",
          "full_name": "User One"
        },
        {
          "username": "user2",
          "full_name": null
        }
      ],
      "report": {
        "report_state": "final",
        "title": "Pentest Title",
        "starts_at": "2022-06-09",
        "ends_at": "2022-06-13",
        "executive_summary": "A pentest.",
        "scope_of_work": "Everything.",
        "summary_of_findings": "Some findings were found.",
        "summary_of_recommendations": "Fix some things."
      },
      "findings": {
        "severity": {
          "informational": [
            {
              "id": "vl_3sP2RCWWUajc3oRXmbQ4j2",
            },
            {
              "id": "vl_3sP2RCWWUajc3oRXmbQ4j3",
            }
          ],
          "low": [
            {
              "id": "vl_3sP2RCWWUajc3oRXmbQ4j4",
            }
          ],
          "medium": [],
          "high": [
            {
              "id": "vl_3sP2RCWWUajc3oRXmbQ4j5",
            }
          ],
          "critical": []
        },
        "state": {
          "new": [],
          "triaging": [
            {
              "id": "vl_3sP2RCWWUajc3oRXmbQ4j5",
            }
          ],
          "invalid": [
            {
              "id": "vl_3sP2RCWWUajc3oRXmbQ4j3",
            }
          ],
          "duplicate": [],
          "out_of_scope": [
            {
              "id": "vl_3sP2RCWWUajc3oRXmbQ4j2",
            }
          ],
          "need_fix": [],
          "wont_fix": [],
          "check_fix": [],
          "valid_fix": []
        }
      },
      "accepted_risks": [
        {
          "finding_id": "vl_VuLnerabiLityVuLnerab4",
          "accepted_risk_reason": "internal_dependencies",
          "state": "wont_fix"
        }
      ]
    },
    "links": {
      "ui": {
        "url": "https://api.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
      }
    }
  }
}

This endpoint retrieves the report for a specific pentest that belongs to the organization specified in the X-Org-Token header. The pentest must be in one of the states live, remediation, or closed.

Note that being able to view a pentest does not equal the ability to view a pentest report. Pentest report visibility depends on a number of factors:

If this endpoint returns a 404 but the underlying pentest is viewable, it’s likely a permissions issue.

HTTP Request

GET https://api.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER-HERE/report

Response Fields

FieldDescription
idA unique ID representing the pentest. Starts with pt_.
titleThe title of the returned pentest.
stateOne of live, remediation, or closed (reports can not be generated for pentests in other states).
asset.idThe unique ID representing the asset associated with this pentest. Starts with as_.
pentestersA list of the pentesters who performed this pentest.
reportA summary of this pentest’s findings and recommendations.
findingsA list of the findings broken down by both severity and state. severity is not a required field so some findings may appear in the state section but not in severity. For a list of the valid severity keys, refer to the table in the Calculations section. For a list of valid state keys refer to the State section.
accepted_risksA list of the findings that have been accepted as risks. For details, refer to the Accepted Risk Response Fields section below.
links.ui.urlA link to redirect an authorized user to this pentest in the Cobalt web application.

Pentester Response Fields

FieldDescription
usernameThe username of the pentester.
full_nameThe full name of the pentester; can be null.

Report Response Fields

FieldDescription
report_stateOne of new_state, draft, in_review, or final.
titleThe title of the pentest.
starts_atThe date the pentest starts.
ends_atThe date the pentest ends.
executive_summaryA high-level overview of the pentest.
scope_of_workA description of the scope of work.
summary_of_findingsA high-level summary of the findings.
summary_of_recommendationsA high-level summary of the recommendations.

Accepted Risk Response Fields

FieldDescription
finding_idA unique ID representing the finding. Starts with vl_.
accepted_risk_reasonOne of low_severity, mitigated_by_waf, mitigated_by_other, no_longer_relevant, third_party_dependencies, internal_dependencies, intended_functionality, or other.
stateThe state of the finding.

Findings

Get All Findings

curl -X GET "https://api.cobalt.io/findings" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "vl_3sP2RCWWUajc3oRXmbQ4j9",
        "tag": "#PT3334_37",
        "title": "XSS vulnerability",
        "description": "Cross-Site Scripting (XSS) attacks are a type of injection, in which malicious scripts...",
        "type_category": "Cross-Site Scripting (XSS)",
        "labels": [
          {
            "name": "Your label"
          }
        ],
        "impact": 5,
        "likelihood": 4,
        "severity": "high",
        "affected_targets": [
          "https://example.com",
          "192.168.1.1"
        ],
        "proof_of_concept": "Here you can see...",
        "suggested_fix": "Ensure this...",
        "pentest_id": "pt_PEtv4dqnwGV2efZhLw3BM5",
        "asset_id": "as_HcChCMueiPQQgvckmZtRSd",
        "log": [
          {
            "action": "created",
            "timestamp": "2021-04-01T15:13:24.322Z"
          },
          {
            "action": "likelihood_changed",
            "value": 4,
            "timestamp": "2021-04-01T15:14:05.856Z"
          },
          {
            "action": "impact_changed",
            "value": 5,
            "timestamp": "2021-04-01T15:14:05.856Z"
          },
          {
            "action": "state_changed",
            "value": "need_fix",
            "timestamp": "2021-04-01T15:14:06.757Z"
          },
          {
            "action": "state_changed",
            "value": "check_fix",
            "timestamp": "2021-04-01T15:14:57.845Z"
          }
        ],
        "state": "check_fix",
        "attachments": [
          {
            "id": "at_LA5GcEL4HRitFGCHREqmzL",
            "file_name": "rainbow.jpeg",
            "download_url": "https://s3.amazonaws.com/acmecorp/uploads/attachment/file/12345/rainbow.jpeg?something=1"
          }
        ]
      },
      "links": {
        "ui": {
          "url": "https://api.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
        }
      }
    }
  ],
  "pagination": {
    "next_page": "/findings?cursor=a1b2c3d4",
    "prev_page": "/findings?cursor=4d3c2b1a"
  }
}

This endpoint retrieves a list of all pentest findings that belong to the organization specified in the X-Org-Token header, filterable by pentest_id or asset_id. The log array presents a history of each finding and corresponding timestamp.

Calculations

We follow the standard risk model described by OWASP, where:

Risk = Impact * Likelihood

Cobalt Risk Input Fields:

Cobalt Risk Classification (severity, a.k.a. criticality):

CategoryScoreDescription
critical25Includes vulnerabilities that require immediate attention.
high16-24Impacts the security of your application/platform/hardware, including supported systems. Includes high probability vulnerabilities with a high business impact.
medium5-15Includes vulnerabilities that are: medium risk, medium impact; low risk, high impact; high risk, low impact.
low2-4Specifies common vulnerabilities with minimal impact.
informational1Notes vulnerabilities of minimal risk to your business.

HTTP Request

GET https://api.cobalt.io/findings

URL Parameters

ParameterDefaultDescription
cursorN/AUsed for pagination, e.g. https://api.cobalt.io/findings?cursor=a1b2c3d4
limit10If specified, returns only a specified amount of findings, e.g. https://api.cobalt.io/findings?limit=5
pentestN/AIf specified, returns findings scoped to this pentest id, e.g. https://api.cobalt.io/findings?pentest=pt_PEtv4dqnwGV2efZhLw3BM5
assetN/AIf specified, returns findings scoped to this asset id, e.g. https://api.cobalt.io/findings?asset=as_HcChCMueiPQQgvckmZtRSd

Response Fields

FieldEnum Types
logcreated, impact_changed, likelihood_changed, state_changed
severitynull, low, medium, high (aka criticality. will be null if likelihood/impact have not yet been set by the pentester)
statenew, triaging, need_fix, wont_fix, valid_fix, check_fix, invalid, carried_over
type_categoryXSS, SQLi, … (about 30 more via the Cobalt Taxonomy)
attachmentsA list of finding attachments. Attachment download URLs are pre-authorized and will expire after 10 minutes.
links.ui.urlA link to redirect an authorized user to this finding in the Cobalt web application

State

Get a Finding

curl -X GET "https://api.cobalt.io/findings/YOUR-FINDING-IDENTIFIER" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"

The above command returns JSON structured like this:

{
  "resource": {
    "id": "vl_3sP2RCWWUajc3oRXmbQ4j9",
    "tag": "#PT5940",
    "title": "XSS vulnerability",
    "description": "Cross-Site Scripting (XSS) attacks are a type of injection, in which malicious scripts...",
    "type_category": "Cross-Site Scripting (XSS)",
    "labels": [
      {
        "name": "Your label"
      }
    ],
    "impact": 5,
    "likelihood": 4,
    "severity": "high",
    "affected_targets": [
      "https://example.com",
      "192.168.1.1"
    ],
    "proof_of_concept": "Here you can see...",
    "suggested_fix": "Ensure this...",
    "pentest_id": "pt_PEtv4dqnwGV2efZhLw3BM5",
    "asset_id": "as_HcChCMueiPQQgvckmZtRSd",
    "log": [
      {
        "action": "created",
        "timestamp": "2021-09-22T18:43:01.677Z"
      }
    ],
    "state": "new",
    "attachments": [
      {
        "id": "at_LA5GcEL4HRitFGCHREqmzL",
        "file_name": "rainbow.jpeg",
        "download_url": "https://s3.amazonaws.com/acmecorp/uploads/attachment/file/12345/rainbow.jpeg?something=1"
      }
    ]
  },
  "links": {
    "ui": {
      "url": "https://api.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
    }
  }
}

This endpoint retrieves a specific finding that belong to the organization specified in the X-Org-Token header.

HTTP Request

GET https://api.cobalt.io/findings/YOUR-FINDING-IDENTIFIER

Response Fields

FieldEnum Types
logcreated, impact_changed, likelihood_changed, state_changed
severitynull, low, medium, high (aka criticality. will be null if likelihood/impact have not yet been set by the pentester)
statenew, triaging, need_fix, wont_fix, valid_fix, check_fix, invalid, carried_over
type_categoryXSS, SQLi, … (about 30 more via the Cobalt Taxonomy)
attachmentsA list of finding attachments. Attachment download URLs are pre-authorized and will expire after 10 minutes.
urlThe links.ui.url will redirect an authorized user to this finding in the Cobalt platform

State

View Available Finding States

curl -X GET "https://api.cobalt.io/findings/YOUR-FINDING-ID/possible_states" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"

The above command returns JSON structured like this:

{
  "resource": {
    "current_state": "invalid",
    "possible_states": [
      "triaging",
      "need_fix",
      "duplicate",
      "out_of_scope"
    ]
  }
}

This endpoint retrieves the current state of a finding as well as possible next states.

HTTP Request

GET https://api.cobalt.io/findings/YOUR-FINDING-ID/possible_states

URL Parameters

ParameterDescription
YOUR-FINDING-IDA unique ID representing the organization. Starts with vl_

Response Fields

FieldDescription
current_stateThe current state of the finding.
possible_statesA list of states that the finding can be transitioned to.

States

Update Finding State

curl -X PATCH "https://api.cobalt.io/findings/YOUR-FINDING-ID" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" \
  -d '{"state":"triaging"}'

If successful, this command returns 204.

This endpoint updates the current state of a finding.

HTTP Request

PATCH https://api.cobalt.io/findings/YOUR-FINDING-ID

URL Parameters

ParameterDescription
YOUR-FINDING-IDA unique ID representing the organization. Starts with vl_

Body

FieldDescription
stateThe desired next state of the finding. Should be one of the possible states.

Events

Get All Events

curl -X GET "https://api.cobalt.io/events" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "ac_Y35JcpGoakrjUSVjtVpXyH",
        "action": "comment_created",
        "subject": {
          "id": "ac_Y35JcpGoakrjUSVjtVpXyH",
          "type": "comment"
        },
        "timestamp": "2022-05-03T01:34:21.587Z"
      }
    },
    {
      "resource": {
        "id": "ac_Y35JcpGoakrjUSVjtVpXyP",
        "action": "pentest_deleted",
        "subject": {
          "id": "ac_Y35JcpGoakrjUSVjtVpXyP",
          "type": "program"
        },
        "timestamp": "2022-05-03T01:34:21.587Z"
      }
    },
    {
      "resource": {
        "id": "ac_Y35JcpGoakrjUSVjtVpXyX",
        "action": "finding_created",
        "subject": {
          "id": "ac_Y35JcpGoakrjUSVjtVpXyX",
          "type": "vulnerability"
        },
        "timestamp": "2022-05-03T01:34:21.587Z"
      }
    }
  ],
  "pagination": {
    "next_page": "/events?cursor=a1b2c3d4",
    "prev_page": "/events?cursor=4d3c2b1a"
  }
}

This endpoint retrieves a list of all events for your account.

HTTP Request

GET https://api.cobalt.io/events

URL Parameters

ParameterDefaultDescription
cursorN/AUsed for pagination, e.g. https://api.cobalt.io/events?cursor=a1b2c3d4
limit10If specified, returns only a specified amount of events, e.g. https://api.cobalt.io/events?limit=5

Tokens

Get All Tokens

curl -X GET "https://api.cobalt.io/tokens" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "api_Dge3LsHMjtX8SGEk4a8nux",
        "last_characters": "9qy7",
        "name": "Lorem ipsum",
        "expire_at": null
      }
    }
  ],
  "pagination": {
    "next_page": null,
    "prev_page": null
  }
}

This endpoint retrieves a list of all tokens that belong to you.

HTTP Request

GET https://api.cobalt.io/tokens

URL Parameters

ParameterDefaultDescription
cursorN/AUsed for pagination, e.g. https://api.cobalt.io/tokens?cursor=a1b2c3d4
limit10If specified, returns only a specified amount of tokens, e.g. https://api.cobalt.io/tokens?limit=5

Response Fields

FieldDescription
idA unique ID representing the token. Starts with api_
nameName of the API token
last_charactersLast four characters of your token, so that you can recognize tokens even if they have the same name
expire_atnull (not currently implemented)

Refresh Token

curl -X POST "https://api.cobalt.io/tokens/YOUR-TOKEN-ID/refresh" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "Idempotency-Key: A-UNIQUE-IDENTIFIER-TO-PREVENT-UNINTENTIONAL-DUPLICATION"

The above command returns JSON structured like this:

{
  "resource": {
    "id": "api_Dge3LsHMjtX8SGEk4a8nux",
    "secret": "YOUR-NEW-PERSONAL-API-TOKEN",
    "name": "Lorem ipsum",
    "expire_at": null
  }
}

You can revoke an existing token and issue a new one with the same name by making a POST request to the token refresh endpoint.

Process:

If you’ve forgotten your token, you can always re-authenticate in the Cobalt web app. Go to your profile, revoke the old token you’ve forgotten, and generate a new token.

HTTP Request

POST https://api.cobalt.io/tokens/YOUR-TOKEN-ID/refresh

Response Fields

FieldDescription
idA unique ID representing the new token. Starts with api_
secretYour new personal API token. Keep it safe and don’t share with anyone
nameName of your API token
expire_atnull (not currently implemented)

Pagination

Pagination can be used if the number of resources for a request exceeds the value of the limit query parameter of the request. If the next_page and/or prev_page values in the response are non-null there are additional resources. To paginate append the next_page or prev_page value to the base API URL.

For example, if the next_page value in a response is /resource?cursor=a1b2c3d4 you can send the following request for the next page.

GET https://api.cobalt.io/resource?cursor=a1b2c3d4

Idempotency

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create an asset does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one asset is created.

To perform an idempotent request, provide an additional Idempotency-Key: <key> header to the request. The header name Mutation-Check is also supported for backwards compatibility with previous versions of the API.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

All POST requests optionally accept idempotency keys. Idempotency keys expire after 5 minutes.

Errors

The Cobalt API uses the following error codes:

Error CodeMeaning
400Bad Request – Your request is not good
401Unauthorized – Your API token is wrong
403Forbidden – You don’t have access to this
404Not Found – The specified request could not be found
405Method Not Allowed – You tried to access Cobalt data with an invalid method
406Not Acceptable – You requested a format that isn’t json
409Conflict – You attempted to create a resource with the same Idempotency-Key header as a recent request.
410Gone – The requested endpoint has been removed from Cobalt servers
418I’m a teapot
422Unprocessable Entity – The content and syntax are correctly formed, but something else is off.
429Too Many Requests – You’re making requests too often! Slow down!
500Internal Server Error – We had a problem with our server. Try again later.
503Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Changelog

New Endpoints

In the v2 release, we’ve published some additional endpoints to extend the capabilities of Cobalt API. Please refer to the following endpoints for more details:

Identifier Changes

In Cobalt API v2, we’ve focused on standardizing and extending identifiers for all endpoints. As a result, either the structure or the length of some identifiers has changed. You can see a side-by-side comparison of v1 and v2 with some sample identifiers below:

EndpointResponse fieldv1 (example)v2 (example)
organizationsidor_A2bb4FEor_Uevoq7MyoYsPT9NPc3conL
organizationstokenABCDEFGHJ12345678901ASDFGHJKLQWERTYUM1234567890ABCDEFGH1234567891234
assetsidas_rvZRC5Yas_GZgcehapJUNh6mjNuqsE4T
assetsattachments.tokenatt_yYXZodAat_LA5GcEL4HRitFGCHREqmzL
pentestsidpt_rVShby8pt_JQJpAAMjyc8sVtXW2X2Aq5
findingsidvu_ZzZuekbvl_3sP2RCWWUajc3oRXmbQ4j9
findingspentest_idpt_9Ig1234pt_PEtv4dqnwGV2efZhLw3BM5
findingsasset_idas_cwrsqsLas_HcChCMueiPQQgvckmZtRSd
eventsid277603ac_Y35JcpGoakrjUSVjtVpXyH
eventssubject.id277603ac_Y35JcpGoakrjUSVjtVpXyH

For the majority of endpoints, the only change is the length of the identifier. However, there are some prefix and type changes too. For example, the identifier prefix of the findings endpoint has changed from vu to vl. Similarly, the attachments.token prefix has changed from att to at.

We aren’t expecting any of these to be breaking changes for the majority of our customers, but, if you have any validations in place, concerning prefixes or the length of strings, please update them accordingly.

Please note - the token attribute of the organizations endpoint now returns a different string in v2. This value is also known as “organization token” all over the API docs, and is used as the value of X-Org-Token header when calling endpoints.

Renamed Response Attributes

The token attribute of the attachments object in v1 of assets endpoint was renamed to id in v2.

{
  // v1
  "attachments": [
    {
      "token": "att_yYXZodA"
    }
  ],

  // v2
  "attachments": [
    {
      "id": "at_LA5GcEL4HRitFGCHREqmzL"
    }
  ]
}

New Response Attributes

The response from listing findings and getting a single finding now includes an attachments attribute that shows files attached to a finding. Finding attachments can be programmatically downloaded using this information. Click here for more information.

Request Headers

Headerv1v2Description
Acceptapplication/vnd.cobalt.v1+jsonapplication/vnd.cobalt.v2+jsonMust be present in the request
Content-TypeN/Aapplication/vnd.cobalt.v2+jsonRequired for POST/PUT/DELETE HTTP methods
Idempotency-KeyN/ARefer to idempotencySuggested for POST requests

In v1, the Cobalt API was read-only, and in v2 we’ve added different endpoints where you can create, update or delete resources.

With these additions in place, two new headers came into place; Content-Type and Idempotency-Key. The Idempotency-Key is explained in the idempotency section.

Pagination Defaults

In v1, some endpoints had 10, and some others had 1000 as their pagination default value. In this release, we’ve updated the default pagination values of all endpoints to 10. Two endpoints were affected by this change:

Endpointv1 (default)v2 (default)
pentests100010
findings100010

Subscription

If you want to receive our API updates you can subscribe to our mailing list. We will be sending you a newsletter containing changes and improvements in our API once a month. You can also unsubscribe anytime you want. Your e-mail address won’t be shared with any other organization.