# Add a custom audit area

POST

/projects/{projectId}/repositories/{repositoryId}/audit-areas

```js
const url = 'https://zkao.io/api/v1/projects/example/repositories/example/audit-areas';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","description":"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/audit-areas \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "description": "example" }'
```

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

Requires scope: `guidance:write`. An area is a name and a description, never a file list: a scan resolves it against the code at the commit it runs on. The `key` is derived from the name and disambiguated on collision.

## Authorizations

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

## Parameters

### Path Parameters

* **projectId**

  required

  string

* **repositoryId**

  required

  string

## Request Bodyrequired

application/json

object

* **name**

  required

  string

  <= 120 characters

* **description**

  What this part of the code does.

  string | null

  <= 500 characters

##### Examplegenerated

```json
{
  "name": "example",
  "description": "example"
}
```

## Responses

### 201

Created

application/json

object

* **area**

  required

  object

  * **key**

    required

    Stable slug, unique per repository. Pass it in `auditAreaKeys` when launching a scan.

    string

  * **name**

    required

    string

  * **description**

    required

    string | null

  * **source**

    required

    `discovered` was named by a scan’s map of the repository; `custom` was added through this API or the app.

    string

    Allowed values: discovered custom

  * **inLatestMap**

    required

    Whether the branch’s latest map still names this area.

    boolean

  * **files**

    required

    Files this area covers at that map. Null when the map does not name it.

    integer | null

  * **lines**

    required

    Lines this area covers at that map. Null when the map does not name it.

    integer | null

##### Example

```json
{
  "area": {
    "source": "discovered"
  }
}
```

### 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"
  }
}
```
