Pentests

Get All Pentests

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.us.cobalt.io/pentests

URL Parameters

Parameter	Default	Description
asset	N/A	If specified, returns pentests scoped to this asset id. Example: https://api.us.cobalt.io/pentests?asset=as_GZgcehapJUNh6mjNuqsE4T or 404 if asset not found
cursor	N/A	Used for pagination. Example: https://api.us.cobalt.io/pentests?cursor=a1b2c3d4
limit	10	If specified, returns only a specified amount of pentests. Example: https://api.us.cobalt.io/pentests?limit=5
sort	N/A	If specified, returns pentests sorted by one of the chosen properties: start_date, or end_date. When defined, pentests are sorted in ascending order by the sort property. To sort in descending order, use a - before the sort property. Example: https://api.us.cobalt.io/pentests?sort=-start_date.
state	N/A	If specified, returns pentests that match state. See Response Fields below for example state values. Example: https://api.us.cobalt.io/pentests?state=new. Returns an empty list if no pentests match the state filter.
testing_type	N/A	If specified, returns pentests that match testing_type. See Response Fields below for example testing_type values. Example: https://api.us.cobalt.io/pentests?testing_type=agile. Returns an empty list if no pentests match the testing_type filter.
platform_tags_contains_all[]	N/A	If specified, returns pentests that contain all specified platform tags. This query parameter can be specified multiple times. Returns an empty list if no matches are found. Example: https://api.us.cobalt.io/pentests?platform_tags_contains_all[]=Kotlin&platform_tags_contains_all[]=AWS
start_date_lte	N/A	If specified, returns pentests where the start_date is less than or equal to the input date. Input format: YYYY-MM-DD. Returns an empty list if no pentests match the filter. Example: https://api.us.cobalt.io/pentests?start_date_lte=2021-04-16
start_date_gte	N/A	If specified, returns pentests where the start_date is greater than or equal to the input date. Input format: YYYY-MM-DD. Returns an empty list if no pentests match the filter. Example: https://api.us.cobalt.io/pentests?start_date_gte=2021-04-16
end_date_lte	N/A	If specified, returns pentests where the end_date is less than or equal to the input date. Input format: YYYY-MM-DD. Returns an empty list if no pentests match the filter. Example: https://api.us.cobalt.io/pentests?end_date_lte=2021-04-16
end_date_gte	N/A	If specified, returns pentests where the end_date is greater than or equal to the input date. Input format: YYYY-MM-DD. Returns an empty list if no pentests match the filter. Example: https://api.us.cobalt.io/pentests?end_date_gte=2021-04-16

Response Fields

Field	Description
id	A unique ID representing the pentest. Starts with pt_
title	The title of the returned pentest.
objectives	The objectives of the pentest, for example, “Coverage of OWASP Top 10”
asset_id	ID of the asset that the returned pentest belongs to
testing_type	Pentest testing type, where can be: agile or comprehensive
platform_tags	Tech stack of the target, for example, Java, Kotlin, Ruby, or AWS.
methodology	Pentest methodology. Web, API, Web+API, Mobile, External Network and so on.
targets	Targetted IP addresses, domains, services, and so on.
start_date	The starting date of the pentest. Format: Dec 11 2019
end_date	The ending date of the pentest. Format: Dec 11 2019
state	new, in_review, planned, cancelled, live, remediation, or closed
links.ui.url	A link to redirect an authorized user to this pentest in the Cobalt web application

curl -X GET "https://api.us.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",
      "testing_type": "agile",
      "platform_tags": [
        "rails",
        "ruby",
        "aws"
      ],
      "methodology": "web",
      "targets": [
        "https://cobalt.io",
        "192.168.1.1"
      ],
      "start_date": "Dec 11 2019",
      "end_date": "Dec 25 2019"
    },
    "links": {
      "ui": {
        "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
      }
    }
  }
}

:::info Remember - you can only request pentests scoped to the organization specified in the X-Org-Token header.

:::

---

Get a Pentest

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

HTTP Request

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

Response Fields

Field	Description
id	A unique ID representing the pentest. Starts with pt_
title	The title of the returned pentest.
objectives	The objectives of the pentest. for example “Coverage of OWASP Top 10”
asset_id	ID of the asset that the returned pentest belongs to
testing_type	Pentest testing type, where can be: agile or comprehensive
platform_tags	Tech stack of the target. for example java, kotlin, ruby, aws, and so on.
methodology	Pentest methodology. Web, API, Web+API, Mobile, External Network and so on.
targets	Targetted IP addresses, domains, services, and so on.
start_date	The starting date of the pentest. Format: Dec 11 2019
end_date	The ending date of the pentest. Format: Dec 11 2019
state	new, in_review, planned, cancelled, live, remediation, or closed
links.ui.url	A link to redirect an authorized user to this pentest in the Cobalt web application

curl -X GET "https://api.us.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",
      "testing_type": "agile",
      "platform_tags": [
        "rails",
        "ruby",
        "aws"
      ],
      "methodology": "web",
      "targets": [
        "https://cobalt.io",
        "192.168.1.1"
      ],
      "start_date": "Dec 11 2019",
      "end_date": "Dec 25 2019"
    },
    "links": {
      "ui": {
        "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
      }
    }
  }
}

:::info Remember - you can only request a pentest scoped to the organization specified in the X-Org-Token header.

:::

---

Get a Pentest Report

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:

• Whether or not the pentest report has been finalized.
• The role within the organization of the user who owns the API token.

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

HTTP Request

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

Response Fields

Field	Description
id	A unique ID representing the pentest. Starts with pt_.
title	Optional; if present, the title of the returned pentest.
state	One of live, remediation, or closed (reports can not be generated for pentests in other states).
asset	Optional; if present, an object representing the asset associated with this pentest.
asset.id	The unique ID representing the asset associated with this pentest. Starts with as_.
pentesters	Optional; if present, a list of the pentesters who performed this pentest.
report	Optional; if present, a summary of this pentest’s findings and recommendations.
findings	A 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 States section.
accepted_risks	Optional; if present, a list of the accepted risk findings. For details, refer to the Accepted Risk Response Fields section below.
links.ui.url	A link to redirect an authorized user to this pentest in the Cobalt web application.

Pentester Response Fields

Field	Description
username	The username of the pentester.
full_name	The full name of the pentester; can be null.

Report Response Fields

Field	Description
report_state	Optional; if present, one of new_state, draft, in_review, or final.
title	Optional; if present, the title of the pentest.
starts_at	Optional; if present, the date the pentest starts.
ends_at	Optional; if present, the date the pentest ends.
executive_summary	Optional; if present, a high-level overview of the pentest.
executive_analysis	Optional; if present, a high-level analysis of the pentest.
scope_of_work	Optional; if present, a description of the scope of work.
summary_of_findings	Optional; if present, a high-level summary of the findings.
summary_of_recommendations	Optional; if present, a high-level summary of the recommendations.

Accepted Risk Response Fields

Field	Description
finding_id	A unique ID representing the finding. Starts with vl_.
accepted_risk_reason	One of low_severity, mitigated_by_waf, mitigated_by_other, no_longer_relevant, third_party_dependencies, internal_dependencies, intended_functionality, or other.
state	The state of the finding.

Remember - you can only request the report for a pentest scoped to the organization specified in the X-Org-Token header.

---

Duplicate a Pentest

This endpoint creates a duplicate pentest based on the identifier provided. The pentest to be duplicated must exist and belong to the organization specified in the X-Org-Token header. Note there is no Request body required for this endpoint. Note that you cannot duplicate a pentest that is in Draft state. The new pentest will be in Draft state and will have the same brief as the pentest provided in the identifier.

HTTP Request

POST https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER-HERE/duplicate

Response

You get a 201 response code for a successful request. The Location response header contains the URL of the new pentest within the Cobalt API.

Field	Description
id	A unique ID representing the pentest. Starts with pt_
title	The title of the returned pentest.
objectives	The objectives of the pentest. for example “Coverage of OWASP Top 10”
asset_id	ID of the asset that the returned pentest belongs to
testing_type	Pentest testing type, where can be: agile or comprehensive
platform_tags	Tech stack of the target. for example java, kotlin, ruby, aws, and so on.
methodology	Pentest methodology. Web, API, Web+API, Mobile, External Network and so on.
targets	Targetted IP addresses, domains, services, and so on.
start_date	The starting date of the pentest. Format: Dec 11 2019
end_date	The ending date of the pentest. Format: Dec 11 2019
state	new, in_review, planned, cancelled, live, remediation, or closed
links.ui.url	A link to redirect an authorized user to this pentest in the Cobalt web application

curl -X GET "https://api.us.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.",
        "executive_analysis": "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.us.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
      }
    }
  }
}

:::info Remember - you can only duplicate a pentest within the organization specified in the X-Org-Token header.

:::

---

Duplicate a Pentest

This endpoint creates a duplicate pentest based on the identifier provided. The pentest to be duplicated must exist and belong to the organization specified in the X-Org-Token header. Note there is no Request body required for this endpoint. Note that you cannot duplicate a pentest that is in Draft state. The new pentest will be in Draft state and will have the same brief as the pentest provided in the identifier.

HTTP Request

POST https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER-HERE/duplicate

Response

You get a 201 response code for a successful request. The Location response header contains the URL of the new pentest within the Cobalt API.

Field	Description
id	A unique ID representing the pentest. Starts with pt_
title	The title of the returned pentest.
objectives	The objectives of the pentest. for example “Coverage of OWASP Top 10”
asset_id	ID of the asset that the returned pentest belongs to
testing_type	Pentest testing type, where can be: agile or comprehensive
platform_tags	Tech stack of the target. for example java, kotlin, ruby, aws, and so on.
methodology	Pentest methodology. Web, API, Web+API, Mobile, External Network and so on.
targets	Targetted IP addresses, domains, services, and so on.
start_date	The starting date of the pentest. Format: Dec 11 2019
end_date	The ending date of the pentest. Format: Dec 11 2019
state	new, in_review, planned, cancelled, live, remediation, or closed
links.ui.url	A link to redirect an authorized user to this pentest in the Cobalt web application

curl -X POST "https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER/duplicate" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Content-Type: application/vnd.cobalt.v2+json" \
  -H "Idempotency-Key: A-UNIQUE-IDENTIFIER-TO-PREVENT-UNINTENTIONAL-DUPLICATION" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"

The above command returns the new duplicate pentest and a 201 response code when successful. There will be a Location header pointing at the newly created pentest.

{
  "data": {
    "resource": {
      "id": "pt_MsZGgJW55dJZxAs2AgXAF5",
      "title": "[COPY] foobar - September 2023",
      "objectives": "",
      "state": "new",
      "tag": "#PT83653",
      "asset_id": "as_7PFxAamzsqDNixMcQoR723",
      "platform_tags": [
        "rails"
      ],
      "methodology": "web",
      "targets": [
        "127.0.0.1"
      ],
      "start_date": null,
      "end_date": null,
      "testing_type": "agile"
    },
    "links": {
      "ui": {
        "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoiUEVOVEVTVCIsIm9yZ1NsdWciOiJna3VobnMtdGVzdC1vcmciLCJwZW50ZXN0VGFnIjoiY29weS1mb29iYXItc2VwdGVtYmVyLTIwMjMtcHQ4MzY1MyIsImZpbmRpbmdJZCI6IiIsImFzc2V0VGFnIjoiIn0="
      }
    }
  }
}

---

Create a Pentest

This endpoint creates a new pentest from the information provided. The pentest will belong to the organization specified in the X-Org-Token header. The pentest will be in the Draft state.

HTTP Request

POST https://api.us.cobalt.io/pentests

Body

Field	Description
asset_id	The ID of the asset being pentested; this asset must exist and belong to the organization specified in the X-Org-Token header.
title	The title of the pentest.
description	A description of the pentest.
technology_stack	A comma separated list of technologies in use; for example, “Ruby, Go, C#”
instructions	Optional; if present, instructions for the pentesters.
additional_requests	Optional; if present, special requests or instructions for the pentesters.
test_credentials	Optional; if present, credentials to be used by the pentesters.
test_credentials_option	Optional; if present, additional information about the credentials. Must be one of the following: provided, distributed, not_required
targets	Optional; if present, the URLs, endpoints, etc. being targeted by the pentest. A comma separated list; "1.1.1.1, https://cobalt.io"
testing_type	Optional; If present, this will be the type of the pentest. Must be one of the following: agile, comprehensive. Default: comprehensive
scoping	Optional; if present, information about the size of the pentest. For details, refer to the Scoping Body Fields section below.

Scoping Body Fields

If scoping data is provided, it must match the type of the asset being pentested. For example, if the asset being pentested is of type API, the API-related scoping fields should be filled in.

Field	Description
api.num_of_endpoints	The number of API endpoints to be pentested.
api.num_of_roles	The number of roles to be pentested per API endpoint.
cloud_config.num_of_services	The number of cloud services to be pentested.
cloud_config.num_of_accounts	The number of roles to be pentested per cloud service.
mobile.num_of_views	The number of mobile app views to be pentested.
mobile.num_of_roles	The number of roles to be pentested per mobile app view.
mobile.num_of_operating_systems	The number of operating systems to be pentested per mobile app.
network.num_of_ips	The number of network IP addresses to be pentested.
web.num_of_pages	The number of web pages to be pentested.
web.num_of_roles	The number of roles to be pentested per web page.

Response

You get a 201 response code for a successful request. The Location response header contains the URL of the new pentest within the Cobalt API.

Field	Description
id	A unique ID representing the pentest. Starts with pt_
title	The title of the returned pentest.
objectives	The objectives of the pentest. for example “Coverage of OWASP Top 10”
asset_id	ID of the asset that the returned pentest belongs to
testing_type	Pentest testing type, where can be: agile or comprehensive
platform_tags	Tech stack of the target. for example java, kotlin, ruby, aws, and so on.
methodology	Pentest methodology. Web, API, Web+API, Mobile, External Network and so on.
targets	Targetted IP addresses, domains, services, and so on.
start_date	The starting date of the pentest. Format: Dec 11 2019
end_date	The ending date of the pentest. Format: Dec 11 2019
state	new, in_review, planned, cancelled, live, remediation, or closed
links.ui.url	A link to redirect an authorized user to this pentest in the Cobalt web application

curl -X POST "https://api.us.cobalt.io/pentests" \
  -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 '{
            "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL",
            "title": "Pentest Title",
            "description": "Pentest description.",
            "technology_stack": "ruby,golang,rails,kotlin",
            "instructions": "The pentest target is the v1 endpoints",
            "additional_requests": "Do not test webhook endpoints.",
            "test_credentials": "Account: foobar, password: foobar",
            "test_credentials_option": "provided",
            "targets": "1.1.1.1,https://google.com",
            "testing_type": "comprehensive",
            "scoping": {
              "api": {
                "num_of_endpoints": 1,
                "num_of_roles": 1
              }
            }
          }'

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

  "data": {
    "resource": {
      "id": "pt_G8kBTQUR3Nrmv3mWzYvzxT",
      "title": "Pentest Title",
      "objectives": "",
      "state": "new",
      "tag": "#PT83597",
      "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL",
      "platform_tags": [
        "ruby",
        "golang",
        "rails",
        "kotlin"
      ],
      "methodology": "api",
      "targets": [
        "1.1.1.1",
        "https://google.com"
      ],
      "start_date": null,
      "end_date": null,
      "testing_type": "comprehensive"
    },
    "links": {
      "ui": {
        "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoiUEVOVEVTVCIsIm9yZ1NsdWciOiJna3VobnMtdGVzdC1vcmciLCJwZW50ZXN0VGFnIjoicGVudGVzdC10aXRsZS1wdDgzNTk3IiwiZmluZGluZ0lkIjoiIiwiYXNzZXRUYWciOiIifQ=="
      }
    }
  }
}

:::info Remember - you can only create a pentest within the organization specified in the X-Org-Token header.

:::

---

Update a Pentest

This endpoint updates a pentest from the information provided.

HTTP Request

PUT https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER

Body

Field	Description
asset_id	The ID of the asset being pentested; this asset must exist and belong to the organization specified in the X-Org-Token header.
title	The title of the pentest.
description	A description of the pentest.
technology_stack	A description of the technology stacks in use; for example, C# or Ruby on Rails.
instructions	Optional; if present, instructions for the pentesters.
additional_requests	Optional; if present, special requests or instructions for the pentesters.
test_credentials	Optional; if present, credentials to be used by the pentesters.
test_credentials_option	Optional; if present, additional information about the credentials.
targets	Optional; if present, the URLs, endpoints, etc being targeted by the pentest.
testing_type	Optional; If present, this will be the new type of the pentest. Must be one of the following: agile, comprehensive.
scoping	Optional; if present, information about the size of the pentest. For details, refer to the Scoping Body Fields section below.

Scoping Body Fields

If scoping data is provided, it must match the type of the asset being pentested. For example, if the asset being pentested is of type API, the API-related scoping fields should be filled in.

Field	Description
api.num_of_endpoints	The number of API endpoints to be pentested.
api.num_of_roles	The number of roles to be pentested per API endpoint.
cloud_config.num_of_services	The number of cloud services to be pentested.
cloud_config.num_of_accounts	The number of roles to be pentested per cloud service.
mobile.num_of_views	The number of mobile app views to be pentested.
mobile.num_of_roles	The number of roles to be pentested per mobile app view.
mobile.num_of_operating_systems	The number of operating systems to be pentested per mobile app.
network.num_of_ips	The number of network IP addresses to be pentested.
web.num_of_pages	The number of web pages to be pentested.
web.num_of_roles	The number of roles to be pentested per web page.

Response

On success, a 200 response code will be returned.

Field	Description
id	A unique ID representing the pentest. Starts with pt_
title	The title of the returned pentest.
objectives	The objectives of the pentest. for example “Coverage of OWASP Top 10”
asset_id	ID of the asset that the returned pentest belongs to
testing_type	Pentest testing type, where can be: agile or comprehensive
platform_tags	Tech stack of the target. for example java, kotlin, ruby, aws, and so on.
methodology	Pentest methodology. Web, API, Web+API, Mobile, External Network and so on.
targets	Targetted IP addresses, domains, services, and so on.
start_date	The starting date of the pentest. Format: Dec 11 2019
end_date	The ending date of the pentest. Format: Dec 11 2019
state	new, in_review, planned, cancelled, live, remediation, or closed
links.ui.url	A link to redirect an authorized user to this pentest in the Cobalt web application

curl -X PUT "https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER" \
  -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 '{
            "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL",
            "title": "Pentest Title",
            "description": "Pentest description.",
            "technology_stack": "ruby,golang,rails,kotlin",
            "instructions": "The pentest target is the v1 endpoints",
            "additional_requests": "Do not test webhook endpoints.",
            "test_credentials": "Account: foobar, password: foobar",
            "test_credentials_option": "provided",
            "targets": "1.1.1.1,https://google.com",
            "testing_type": "comprehensive",
            "scoping": {
              "api": {
                "num_of_endpoints": 1,
                "num_of_roles": 1
              }
            }
          }'

The above command returns the updated pentest and a 204 response code when successful.

{
  "data": {
    "resource": {
      "id": "pt_8T215LptHHFKhdRENjm8Ka",
      "title": "Pentest Title",
      "objectives": "Pentest description.",
      "state": "new",
      "tag": "#PT83652",
      "asset_id": "as_4L4ZjKgfzP7VBwUmqCZmmL",
      "platform_tags": [
        "ruby",
        "golang",
        "rails",
        "kotlin"
      ],
      "methodology": "api",
      "targets": [
        "1.1.1.1",
        "https://google.com"
      ],
      "start_date": null,
      "end_date": null,
      "testing_type": "comprehensive"
    },
    "links": {
      "ui": {
        "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoiUEVOVEVTVCIsIm9yZ1NsdWciOiJna3VobnMtdGVzdC1vcmciLCJwZW50ZXN0VGFnIjoicGVudGVzdC10aXRsZS1wdDgzNjUyIiwiZmluZGluZ0lkIjoiIiwiYXNzZXRUYWciOiIifQ=="
      }
    }
  }
}

:::info Remember - you can only update a pentest within the organization specified in the X-Org-Token header.

:::

---

Delete a Pentest

This endpoint deletes a pentest belonging to the organization specified in the header. Note that you can only delete a pentest when it is in draft or review state.

HTTP Request

DELETE https://api.us.cobalt.io/pentests/YOUR-PENTEST-IDENTIFIER

Response

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

curl -X DELETE 'https://api.us.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 no data and a 204 response code when successful.

Remember - you can only delete a pentest within the organization specified in the X-Org-Token header.