> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve Comment

Use this API to resolve one comment of a check, for a person (`by: "user"`) or an MCP client (`by: "mcp"`). The comment becomes Resolved and waits for the scan that verifies it (`pendingVerify: true`). Only a scan verifies: see [Statuses](https://velt.dev/docs/api-reference/rest-apis/v2/agents/checks/overview.md#statuses).

The resolve starts a verify rescan, which uses AI credits at the flat rescan rate. Resolves on one project within 15 seconds share one rescan per agent, so a fresh resolve answers `queued: true` with no run id yet.

Resolve is idempotent. Resolving a comment that already waits for its rescan answers `alreadyPending: true`, starts nothing and charges nothing. A comment a scan already verified is refused: [reopen](https://velt.dev/docs/api-reference/rest-apis/v2/agents/checks/comments/reopen.md) it first.

A [rejected](https://velt.dev/docs/api-reference/rest-apis/v2/agents/checks/comments/reject.md) comment takes the Resolved status and nothing else: no verify rescan, no charge, no `pendingVerify`. It answers `{ rescanExecutionId: null, queued: false, alreadyPending: false }` and stays rejected (`statusKind: "rejected"`), so it still counts nowhere.

The comment can be an agent comment, or a person's comment [attached](https://velt.dev/docs/api-reference/rest-apis/v2/agents/checks/comments/attach.md) to a check. An agent comment written before the checks engine, with no check, is Resolved and its agent scans its page once, charged like any one-page scan. A person's comment that is not attached to a check is refused.

# Endpoint

`POST https://api.velt.dev/v2/agents/checks/comments/resolve`

# Headers

**x-velt-api-key** `string` *required*

Your API key.

**x-velt-auth-token** `string` *required*

Your [Auth Token](https://velt.dev/docs/security/auth-tokens.md).

# Body

#### Params

**data** `object` *required*

**properties**

**organizationId** `string` *required*

1 to 512 characters. The organization of the project.

**documentId** `string` *required*

1 to 512 characters. The document of the project.

**annotationId** `string` *required*

The comment annotation id. 1 to 512 characters, no `/`, and not `.` or `..`.

**by** `string` *required*

Who resolves: `"user"` (a person) or `"mcp"` (an MCP client). Any other value is rejected.

**userId** `string` *required*

1 to 512 characters. Recorded as the person who resolved the comment.

**userName** `string`

At most 512 characters. The person's name, for the verify rescan's run.

**userEmail** `string`

At most 512 characters. The person's email, for the verify rescan's run.

The schema uses `.strict()`: unknown fields are rejected.

## **Example Requests**

```JSON theme={null}
{
  "data": {
    "organizationId": "org_acme",
    "documentId": "acme-marketing-site",
    "annotationId": "K7mQ2xR9vB4wLdT1sYpN",
    "by": "user",
    "userId": "user_jordan",
    "userName": "Jordan Lee",
    "userEmail": "jordan@example.com"
  }
}
```

# Response

#### Success Response (fresh resolve)

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Comment resolved",
    "data": {
      "rescanExecutionId": null,
      "queued": true,
      "alreadyPending": false
    }
  }
}
```

#### Success Response (already waiting)

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Comment resolved",
    "data": {
      "rescanExecutionId": "exec_4Wq7Zx2Np8",
      "queued": false,
      "alreadyPending": true
    }
  }
}
```

| Field | Type | Description |
| - | - | - |
| `data.rescanExecutionId` | string \| null | The verify rescan's execution id, once it has started. `null` while the resolve waits in its 15-second window. |
| `data.queued` | boolean | `true` when the comment waits for a rescan that has no run id yet. |
| `data.alreadyPending` | boolean | `true` when the comment already waited for its rescan: nothing new started. |

All three are `false` / `null` when no verify rescan is involved: the workspace has no store database, the comment has no check, or the rescan could not be queued. In the last case, the next scan of the comment's pages verifies or reopens it.

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "This comment was already verified by a scan",
    "status": "FAILED_PRECONDITION",
    "details": {
      "reason": "CHECKS_ALREADY_VERIFIED"
    }
  }
}
```

**Errors:**

* `INVALID_ARGUMENT` for a body outside the schema: a missing `annotationId`, `by` or `userId`, a `by` other than `"user"` or `"mcp"`, or an unknown field;
* `NOT_FOUND` with `CHECKS_COMMENT_NOT_FOUND` (no such comment in the project);
* `FAILED_PRECONDITION` with `CHECKS_ALREADY_VERIFIED` (a scan already verified the comment: reopen it first) or `CHECKS_NOT_AGENT_COMMENT` (a person's comment not attached to a check).

```js theme={null}
{
  "result": {
    "status": "success",
    "message": "Comment resolved",
    "data": {
      "rescanExecutionId": null,
      "queued": true,
      "alreadyPending": false
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.