> ## 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 (the next scan of the comment's pages then 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.