# File a vulnerability report against a repository

POST

/projects/{projectId}/repositories/{repositoryId}/reports

```js
const url = 'https://zkao.io/api/v1/projects/example/repositories/example/reports';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"title":"example","body":"example","claimedSeverity":"CRITICAL","reporter":{"name":"example","email":"example","githubLogin":"example"}}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```sh
curl --request POST \
  --url https://zkao.io/api/v1/projects/example/repositories/example/reports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "example", "body": "example", "claimedSeverity": "CRITICAL", "reporter": { "name": "example", "email": "example", "githubLogin": "example" } }'
```

* Production`zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/reports`
* Staging`staging.zkao.io/api/v1/projects/{projectId}/repositories/{repositoryId}/reports`

Requires scope: `reports:write`. Files a report into this project’s security programme for an active repository belonging to the project. GitHub private-report intake setup and repository admin access are not required. The report arrives as prose and is read and split into claims by the same step as an imported GitHub report.

Returns with `intakeState: PENDING`. `investigateReport` refuses a report until that reaches `COMPLETE`, so poll `/projects/{projectId}/reports` before asking for an investigation.

Idempotent on content: the same title and body against the same repository name the same report, so a retried call returns the original with `200` rather than filing a second copy.

Free. The reading that follows is charged to the project, and the investigation is charged when someone asks for it.

## Authorizations

* **[bearerAuth](https://docs.zkao.io/api/#bearerauth)**

## Parameters

### Path Parameters

* **projectId**

  required

  string

* **repositoryId**

  required

  string

## Request Bodyrequired

application/json

object

* **title**

  required

  One line naming the flaw.

  string

  <= 500 characters

* **body**

  required

  What the flaw is, how to reach it, and what it costs. Prose: this is read and split into claims, so write it for a reader rather than as fields. Anything past the limit would be stored and never read.

  string

  <= 80000 characters

* **claimedSeverity**

  What the reporter claims, which is not an assessment. It decides how closely the report is read, so an inflated claim costs the programme more.

  string | null

  Allowed values: CRITICAL HIGH MEDIUM LOW INFO

* **reporter**

  Who found it, all self-asserted. Used for attribution on the advisory, never for authorization.

  object

  * **name**

    string | null

  * **email**

    string | null

  * **githubLogin**

    string | null

## Responses

### 200

Already filed, by an identical earlier call

application/json

object

* **publicId**

  required

  The identifier `investigateReport` takes.

  string

* **intakeState**

  required

  Always PENDING here. The report is queued to be read and split into claims, and an investigation waits for COMPLETE.

  string

##### Examplegenerated

```json
{
  "publicId": "example",
  "intakeState": "example"
}
```

### 201

Filed

application/json

object

* **publicId**

  required

  The identifier `investigateReport` takes.

  string

* **intakeState**

  required

  Always PENDING here. The report is queued to be read and split into claims, and an investigation waits for COMPLETE.

  string

##### Examplegenerated

```json
{
  "publicId": "example",
  "intakeState": "example"
}
```

### 400

Invalid request

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 401

Missing, malformed, expired, or revoked token

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 403

The token lacks the required scope

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 404

Resource not in this token’s project or repo allowlist

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 409

A compare-and-set (`expectedContent`) missed: the guidance changed since it was read. Re-read the current guidance and retry.

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

### 429

Rate limited. Either the token’s spend limit for the current period is reached (on launch), or the token is sending too many requests. Wait the number of seconds in the `Retry-After` header before retrying.

application/json

object

* **error**

  required

  object

  * **code**

    required

    string

    Allowed values: unauthorized forbidden not_found bad_request conflict insufficient_credits budget_below_minimum repository_initializing diff_base_required diff_base_not_allowed diff_base_invalid diff_empty rate_limited internal

  * **message**

    required

    string

  * **minimumCredits**

    Budget_below_minimum only: the least the launch could have reserved, in credits. A diff scan’s first scan of a repository also builds its overview, so its minimum is higher.

    integer

##### Example

```json
{
  "error": {
    "code": "unauthorized"
  }
}
```

#### Headers

* **Retry-After**

  integer

  Seconds to wait before retrying.
