From 5786301cc18ddcc25c1a2581143adcba99ea8942 Mon Sep 17 00:00:00 2001 From: raghul-velt Date: Fri, 15 May 2026 12:42:26 +0530 Subject: [PATCH 1/7] Add agent documentation and API references - Introduced new sections for "Agents" in the documentation, including an overview and setup guide. - Added API references for creating, updating, deleting, and extracting agents. - Included analytics and execution details for agents, enhancing the overall API documentation. - Structured the content to improve clarity and usability for developers working with AI agents. --- ai/agents/overview.mdx | 167 +++++++++++ ai/agents/setup.mdx | 188 ++++++++++++ .../rest-apis/v2/agents/analytics/get.mdx | 225 ++++++++++++++ .../rest-apis/v2/agents/config/resolve.mdx | 126 ++++++++ api-reference/rest-apis/v2/agents/create.mdx | 264 +++++++++++++++++ api-reference/rest-apis/v2/agents/delete.mdx | 93 ++++++ .../rest-apis/v2/agents/execution/get.mdx | 276 ++++++++++++++++++ .../rest-apis/v2/agents/execution/run.mdx | 198 +++++++++++++ api-reference/rest-apis/v2/agents/extract.mdx | 138 +++++++++ api-reference/rest-apis/v2/agents/get.mdx | 239 +++++++++++++++ .../rest-apis/v2/agents/groups/add-agents.mdx | 127 ++++++++ .../rest-apis/v2/agents/groups/create.mdx | 151 ++++++++++ .../rest-apis/v2/agents/groups/delete.mdx | 93 ++++++ .../rest-apis/v2/agents/groups/get.mdx | 108 +++++++ .../rest-apis/v2/agents/groups/list.mdx | 109 +++++++ .../v2/agents/groups/remove-agents.mdx | 126 ++++++++ .../rest-apis/v2/agents/groups/update.mdx | 133 +++++++++ .../rest-apis/v2/agents/prompt/enhance.mdx | 160 ++++++++++ .../rest-apis/v2/agents/prompt/refine.mdx | 132 +++++++++ .../rest-apis/v2/agents/prompt/validate.mdx | 156 ++++++++++ api-reference/rest-apis/v2/agents/update.mdx | 131 +++++++++ .../rest-apis/v2/agents/version/update.mdx | 173 +++++++++++ .../rest-apis/v2/agents/versions/list.mdx | 135 +++++++++ .../rest-apis/v2/agents/versions/restore.mdx | 95 ++++++ docs.json | 59 ++++ 25 files changed, 3802 insertions(+) create mode 100644 ai/agents/overview.mdx create mode 100644 ai/agents/setup.mdx create mode 100644 api-reference/rest-apis/v2/agents/analytics/get.mdx create mode 100644 api-reference/rest-apis/v2/agents/config/resolve.mdx create mode 100644 api-reference/rest-apis/v2/agents/create.mdx create mode 100644 api-reference/rest-apis/v2/agents/delete.mdx create mode 100644 api-reference/rest-apis/v2/agents/execution/get.mdx create mode 100644 api-reference/rest-apis/v2/agents/execution/run.mdx create mode 100644 api-reference/rest-apis/v2/agents/extract.mdx create mode 100644 api-reference/rest-apis/v2/agents/get.mdx create mode 100644 api-reference/rest-apis/v2/agents/groups/add-agents.mdx create mode 100644 api-reference/rest-apis/v2/agents/groups/create.mdx create mode 100644 api-reference/rest-apis/v2/agents/groups/delete.mdx create mode 100644 api-reference/rest-apis/v2/agents/groups/get.mdx create mode 100644 api-reference/rest-apis/v2/agents/groups/list.mdx create mode 100644 api-reference/rest-apis/v2/agents/groups/remove-agents.mdx create mode 100644 api-reference/rest-apis/v2/agents/groups/update.mdx create mode 100644 api-reference/rest-apis/v2/agents/prompt/enhance.mdx create mode 100644 api-reference/rest-apis/v2/agents/prompt/refine.mdx create mode 100644 api-reference/rest-apis/v2/agents/prompt/validate.mdx create mode 100644 api-reference/rest-apis/v2/agents/update.mdx create mode 100644 api-reference/rest-apis/v2/agents/version/update.mdx create mode 100644 api-reference/rest-apis/v2/agents/versions/list.mdx create mode 100644 api-reference/rest-apis/v2/agents/versions/restore.mdx diff --git a/ai/agents/overview.mdx b/ai/agents/overview.mdx new file mode 100644 index 000000000..fd01eef5a --- /dev/null +++ b/ai/agents/overview.mdx @@ -0,0 +1,167 @@ +--- +title: "Agents" +sidebarTitle: "Overview" +description: "Run AI agents that analyze web pages, surface findings, and create comment annotations — without writing the analysis pipeline yourself." +--- + +## What are Agents? + +Agents are AI-driven QA tools that analyze a web page (or set of pages) and surface findings as comment annotations. You configure what an agent looks for; the platform handles context gathering, LLM invocation, post-processing, deduplication, and annotation creation. + +Build any check you want — brand consistency, accessibility, SEO, broken links, spelling, custom domain rules — by writing a prompt and selecting a few configuration options. No need to run your own browser pool, prompt your own model, or wire up annotation creation. + +You define an **agent configuration** once, then call **Run Execution** with a URL. Results are persisted as a versioned execution document plus per-URL findings, and annotations are automatically posted to the document via the Comments API. + +## What you get + +- **Built-in and custom agents.** Use ready-made agents (spell check, broken links, grammar, PII detection, profanity, sensitive-data) or define your own custom agents from a prompt. + +- **Pluggable context gathering.** Stack one or more strategies — page text, screenshots, HTML, CSS, links, accessibility tree, computed styles, robots.txt, sitemap, Lighthouse — and the engine extracts everything in parallel. + +- **Versioned configurations.** Every behavioral edit creates a new version. In-flight executions stay pinned to the version they started on. One-click restore rolls back the most recent change. + +- **Async execution with polling.** `Run Execution` returns an `executionId` immediately and dispatches a Cloud Task. Poll `Get Execution` until `status !== "running"`. + +- **Cross-page execution.** Set `crossPageExecute: true` and the engine crawls the seed URL, processes up to `maxUrlsToProcess` pages, and aggregates findings across the site. + +- **Match-and-merge dedup.** Re-running an agent against the same document only creates new annotations for new findings; pre-existing matches are skipped, and resolved findings are auto-resolved. + +- **Token usage analytics.** Per-agent, per-model, per-month token consumption tracked automatically in Firestore and exposed via the Analytics endpoint. + +- **Agent groups.** Organize related agents into named groups (e.g. "Brand QA") and filter list responses by group. + +## Use cases + + + + A custom agent verifies brand colors, typography, and logo placement across your marketing pages. Re-run on every deploy. + + + + Spell-check, broken-links, and accessibility agents run in parallel before a release. Findings appear as comment annotations on the staging document. + + + + PII detection and profanity filter agents flag sensitive content on user-generated pages. Pair with Approval Engine for human review. + + + + Run a brand consistency agent in `crossPageExecute: true` mode against a marketing site. The crawler discovers internal links, then the agent checks each one. + + + + Describe a check in plain English (e.g. "every CTA must use the primary brand color"). The Validate Prompt endpoint expands it into a structured QA task you can ship as an agent. + + + + Trigger an agent execution from an Approval Engine workflow node. The engine handles parking the workflow on the agent's findings. + + + +## How it works + +1. **Define the agent.** Call [Create Agent](/api-reference/rest-apis/v2/agents/create) with a name, instructions, and a configuration block (context gathering strategies, execution strategy, post-processing options). The engine creates version 1 in the agent's versions subcollection. +2. **Run an execution.** Call [Run Execution](/api-reference/rest-apis/v2/agents/execution/run) with `agentId` and `url`. The engine creates an execution document, dispatches a Cloud Task, and returns an `executionId`. +3. **The pipeline runs.** Context gathering → LLM execution → post-processing (guardrails, match-and-merge, annotation creation, analytics) → response shaping. Every phase is bounded by `phaseTimeoutMs`. +4. **Poll for results.** Call [Get Execution](/api-reference/rest-apis/v2/agents/execution/get) until `status !== "running"`. Set `includeResults: true` to fetch per-URL findings. +5. **Findings appear as annotations.** When `postProcess.annotations.enabled` is true (default), each finding becomes a comment annotation on the document referenced by `organizationId` / `documentId`. + +## Mental model + +### Agent + +An **agent** is a reusable QA configuration. Each agent has an identity (`name`, `description`, `enabled`) plus a behavioral configuration (instructions, context gathering, execution, post-processing). Identity edits update the root document; behavioral edits create a new version. + +### Execution + +An **execution** is one run of an agent against a seed URL. It pins the agent's `version` at dispatch time, so in-flight runs are immune to mid-run config changes. + +**Lifecycle:** + +``` +running → passed | failed | error | skipped +``` + +### Finding + +A **finding** is one issue the agent surfaced on one URL. Findings carry severity, category, target text, suggestion, HTML selector, and confidence. Findings below the guardrails confidence floor are suppressed unless explicitly disabled. + +### Pipeline phases + +Each agent run executes 5 sequential phases: + +| Phase | What happens | +| ----------------- | ---------------------------------------------------------------------------------- | +| `validate` | Zod check on payload + input requirements + variable keys | +| `extract` | All configured context gathering strategies run (cached by tenant + content hash) | +| `execute` | LLM call (or registered service); results normalized to a finding array | +| `postProcess` | Guardrails → match-and-merge → annotation creation → analytics | +| `structureResponse` | Final response assembly with optional response adapter | + +## Built-in agents + +| Agent ID | Description | Internal | +| ------------------- | ---------------------------------------------------- | -------- | +| `spell-check` | Spelling and typo detection | no | +| `grammar-check` | Grammar checking | no | +| `broken-links` | Broken link validation | no | +| `pii-detection` | PII (personal info) detection | no | +| `profanity-filter` | Profanity detection | no | +| `sensitive-data` | Sensitive data detection | no | +| `screenshot` | Page screenshot capture | yes | +| `crawler` | Site crawling | yes | + +Internal agents (`metadata.internal: true`) power the execution pipeline and are excluded from list responses. + +## Context gathering strategies + +Stack one or more strategies in the order you want them to run. Strategy results are cached by tenant + content hash, so re-running the same agent against the same page is cheap. + +| Strategy | What it returns | +| ------------------------- | -------------------------------------------------------------- | +| `web-page-text` | Visible text extracted via Puppeteer | +| `web-page-screenshot` | Full-page screenshot as image | +| `web-page-html` | Cleaned HTML content | +| `web-page-css` | Cleaned CSS content from stylesheets | +| `web-page-links` | All hyperlinks on the page | +| `web-page-accessibility` | Accessibility tree (ARIA roles, landmarks, headings) | +| `computed-styles` | Computed CSS for every element | +| `robots-txt` | Fetched `robots.txt` | +| `sitemap-data` | Discovered and parsed XML sitemaps | +| `lighthouse` | Google Lighthouse audit (perf / a11y / SEO) | +| `none` | No context gathering (for service-only agents) | + +## Execution strategies + +| Strategy | Purpose | +| ------------------ | ------------------------------------------------------------- | +| `ai` | LLM-driven analysis (default) | +| `service` | Delegate to a registered built-in service (`serviceId` required) | +| `service+ai` | Service context gathering + AI analysis | +| `stagehand-agent` | Autonomous browser agent via Stagehand AI | + +## Scope + +| Field | Bound to | +| ---------------- | ---------------------------------------------------------- | +| `apiKey` | Workspace-wide (default; agents are per-workspace) | +| `organizationId` | Annotations created on the named organization | +| `documentId` | Annotations created on the named document | + +`organizationId` and `documentId` on Run Execution control where annotations land. They are not required for the agent to execute. + +## Async execution + +Run Execution returns immediately with `{ executionId }` and dispatches a Cloud Task. The engine processes the URL(s) asynchronously and writes results to Firestore. Poll Get Execution to track progress. + +## Get started + + + + Create an agent, run it against a URL, and read the findings end-to-end. + + + + All endpoints organized into Agents, Execution, Versioning, Prompt Tools, Analytics, and Groups. + + diff --git a/ai/agents/setup.mdx b/ai/agents/setup.mdx new file mode 100644 index 000000000..4be31c1aa --- /dev/null +++ b/ai/agents/setup.mdx @@ -0,0 +1,188 @@ +--- +title: "Setup" +description: "Build an agent end to end: create, run, poll, and inspect findings." +--- + +This guide walks through the five steps to get an agent running and surfacing findings as comment annotations. Each step links to the full API reference for request and response details. + +## Step 1: (Optional) Refine your prompt + +If you have a one-line QA instruction and you're not sure it's specific enough to ship, run it through the prompt tools first. + +**Check completeness:** [Enhance Prompt](/api-reference/rest-apis/v2/agents/prompt/enhance) returns either "your prompt is sufficient" or a specific clarification request (with suggested options for the user to pick from). + +**Expand into a structured task:** [Validate Prompt](/api-reference/rest-apis/v2/agents/prompt/validate) takes a simple instruction and expands it into a comprehensive QA task with an analysis prompt, response descriptions, demo examples, and tool requirements. + +**Iterate on demo failures:** [Refine Prompt](/api-reference/rest-apis/v2/agents/prompt/refine) takes an existing analysis prompt and a list of demo failures (with feedback) and produces a refined prompt. + +**Resolve optimal config:** [Resolve Config](/api-reference/rest-apis/v2/agents/config/resolve) takes raw + processed instructions and recommends extraction strategies + execution strategy. + +These tools are optional. Skip straight to Step 2 if you already know what your agent should do. + +## Step 2: Create the agent + +Call [Create Agent](/api-reference/rest-apis/v2/agents/create) with a name, instructions, and a configuration block. + +The minimum viable agent is `name` + `instructions` + `contextGathering.strategies`: + +```JSON +{ + "data": { + "name": "Brand Color Checker", + "instructions": "Verify all CTAs use the primary brand color #1A73E8.", + "contextGathering": { + "strategies": ["web-page-text", "web-page-screenshot"] + } + } +} +``` + +The engine creates the agent's main document and writes version 1 to its versions subcollection. The response returns `{ agentId }`. + +For a complete walkthrough of every config block (`execution`, `response`, `postProcess`, `input`, `scope`, `setup`, `metadata`), see the [Create Agent](/api-reference/rest-apis/v2/agents/create) reference. + + + Built-in agents (`spell-check`, `broken-links`, etc.) are pre-registered for every workspace. You don't need to create them — skip straight to Step 3 with one of the [built-in agent IDs](/ai/agents/overview#built-in-agents). + + +## Step 3: Run an execution + +Call [Run Execution](/api-reference/rest-apis/v2/agents/execution/run) with `agentId` and `url`. Pass `organizationId` and `documentId` if you want findings to land as annotations on a specific document. + +```JSON +{ + "data": { + "agentId": "abc123def456", + "url": "https://example.com/pricing", + "organizationId": "org_001", + "documentId": "doc_001", + "ranBy": { + "userId": "user_123", + "name": "Jane Doe", + "email": "jane@example.com" + } + } +} +``` + +The response returns immediately with `{ executionId }`. The engine creates an execution document, dispatches a Cloud Task, and starts processing asynchronously. + +**Cross-page execution:** Set `crossPageExecute: true` and the engine crawls the seed URL and processes up to `maxUrlsToProcess` pages (default 50). + +**Workflow trigger:** Set `trigger: "workflow"` and pass `workflowExecutionId` when running an agent as part of an Approval Engine workflow node. + +## Step 4: Poll for results + +Call [Get Execution](/api-reference/rest-apis/v2/agents/execution/get) with the `executionId` returned from Step 3. Poll until `execution.status !== "running"`. + +```JSON +{ + "data": { + "executionId": "exec_1711900000000_abc123def456" + } +} +``` + +Terminal statuses: + +| Status | Meaning | +| ----------- | ------------------------------------------------------------------ | +| `passed` | Execution completed successfully | +| `failed` | Execution completed with failures | +| `error` | Unrecoverable error (see `execution.error.code` and `retryable`) | +| `skipped` | Execution was skipped (precondition unmet) | + +When the execution completes, `resultsSummary` contains aggregate counts: + +```JSON +{ + "totalFindings": 7, + "totalAnnotationsCreated": 5, + "urlsProcessed": 12, + "urlsWithFindings": 5, + "matchResult": { + "created": 5, + "skipped": 2, + "resolved": 1 + } +} +``` + +`matchResult` is populated when `postProcess.matchAndMerge.enabled` is true (the default). It tells you how many findings were new (`created`), already existed as annotations (`skipped`), or were resolved because the previous finding is no longer detected (`resolved`). + +## Step 5: Fetch per-URL findings + +Set `includeResults: true` on Get Execution to fetch the full findings array per URL: + +```JSON +{ + "data": { + "executionId": "exec_1711900000000_abc123def456", + "includeResults": true + } +} +``` + +The response includes a `results` array alongside `execution`. Each entry has the URL, its findings, and per-URL counts: + +```JSON +{ + "results": [ + { + "url": "https://example.com/pricing", + "urlHash": "a1b2c3d4e5f6", + "findings": [ + { + "id": "finding-1", + "title": "CTA uses non-brand color", + "description": "The 'Buy now' button uses #FF5722 instead of #1A73E8", + "severity": "high", + "category": "color", + "targetText": "Buy now", + "suggestion": "Change background-color to #1A73E8", + "htmlSelector": "a.cta-primary", + "isPageLevel": false, + "issueType": "brand-color", + "confidence": 95 + } + ], + "findingCount": 1, + "annotationsCreated": 1, + "processedAt": 1711900050000 + } + ] +} +``` + +Findings are also written to the document as comment annotations (when `postProcess.annotations.enabled` is true and `organizationId` + `documentId` were provided on dispatch). Authors of these annotations are flagged with the system `AGENT_USER`. + +## Iterating on the agent + +Behavioral edits create a new version. Identity edits do not. + +- **Edit identity (`name`, `description`, `enabled`):** [Update Agent](/api-reference/rest-apis/v2/agents/update). No new version; the root doc is updated in place. +- **Edit behavior (`instructions`, `contextGathering`, `execution`, `postProcess`, `input`, `scope`, `setup`):** [Update Agent Version](/api-reference/rest-apis/v2/agents/version/update). Creates version `N+1` and bumps the agent's `version` pointer. In-flight executions stay pinned to whatever version they started on. +- **List versions:** [List Versions](/api-reference/rest-apis/v2/agents/versions/list). Each version contains the full behavioral snapshot. +- **Roll back the most recent change:** [Restore Version](/api-reference/rest-apis/v2/agents/versions/restore). Single-step undo; call repeatedly to walk backward. Cannot go below version 1. + +## Organizing agents + +Use [Agent Groups](/api-reference/rest-apis/v2/agents/groups/create) to bundle related agents together (e.g. "Brand QA"). Agents stay independent documents — groups just store an `agentIds` array. An agent can belong to multiple groups; deleting an agent removes it from every group automatically. + +When listing agents with [Get Agent(s)](/api-reference/rest-apis/v2/agents/get), pass `groupId` to filter to a single group's members. + +## Track usage + +[Get Agent Analytics](/api-reference/rest-apis/v2/agents/analytics/get) returns per-agent, per-model, per-month token consumption plus execution counts. Filter by `agentId`, `year`, `month`, or `model`. + +## Next steps + + + + All endpoints organized into Agents, Execution, Versioning, Prompt Tools, Analytics, and Groups, with full request and response schemas. + + + + What agents are, the 5-phase pipeline, built-in vs custom agents, and the full enum vocabulary. + + diff --git a/api-reference/rest-apis/v2/agents/analytics/get.mdx b/api-reference/rest-apis/v2/agents/analytics/get.mdx new file mode 100644 index 000000000..a3a0f983d --- /dev/null +++ b/api-reference/rest-apis/v2/agents/analytics/get.mdx @@ -0,0 +1,225 @@ +--- +title: "Get Agent Analytics" +api: "POST https://api.velt.dev/v2/agents/analytics/get" +--- + +Use this API to fetch AI token usage analytics and execution counts. Token usage is tracked per workspace, per agent, per model, and per request, with breakdowns by `allTime`, `yearly`, `monthly`, and `byModel`. + +Filters narrow what is returned but do not change the response shape — empty buckets simply contain zeros. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/analytics/get` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. Agent ID. Omit for aggregate analytics across all agents. + + + + 4-digit year string (e.g. `"2026"`). Regex `^\d{4}$`. + + + + Two-digit month string (e.g. `"01"` to `"12"`). Regex `^(0[1-9]|1[0-2])$`. + + + + Filter by model identifier (e.g. `"gemini-3-flash-preview"`). + + + + +## **Example Requests** + +#### 1. Aggregate analytics for the workspace + +```JSON +{ + "data": {} +} +``` + +#### 2. Single agent analytics + +```JSON +{ + "data": { + "agentId": "abc123def456" + } +} +``` + +#### 3. Filtered by year and month + +```JSON +{ + "data": { + "agentId": "abc123def456", + "year": "2026", + "month": "03" + } +} +``` + +#### 4. Filtered by model + +```JSON +{ + "data": { + "model": "gemini-3-flash-preview" + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Analytics fetched successfully", + "data": { + "analytics": { + "tokenUsage": { + "allTime": { + "requestCount": 1250, + "promptTokens": 2500000, + "completionTokens": 750000, + "thoughtsTokens": 50000, + "totalTokens": 3300000 + }, + "yearly": { + "2026": { + "claude_claude-sonnet-4-6": { + "requestCount": 350, + "promptTokens": 700000, + "completionTokens": 210000, + "thoughtsTokens": 20000, + "totalTokens": 930000 + }, + "gemini_gemini-3-flash-preview": { + "requestCount": 500, + "promptTokens": 1000000, + "completionTokens": 300000, + "thoughtsTokens": 10000, + "totalTokens": 1310000 + } + } + }, + "monthly": { + "03": { + "claude_claude-sonnet-4-6": { + "requestCount": 120, + "promptTokens": 240000, + "completionTokens": 72000, + "thoughtsTokens": 5000, + "totalTokens": 317000 + } + } + }, + "byModel": { + "claude_claude-sonnet-4-6": { + "requestCount": 500, + "promptTokens": 1000000, + "completionTokens": 300000, + "thoughtsTokens": 50000, + "totalTokens": 1350000 + }, + "gemini_gemini-3-flash-preview": { + "requestCount": 750, + "promptTokens": 1500000, + "completionTokens": 450000, + "thoughtsTokens": 0, + "totalTokens": 1950000 + } + } + }, + "executionCounts": { + "abc123def456": { "executionCount": 45, "lastExecutedAt": 1711900000000 }, + "spell-check": { "executionCount": 142, "lastExecutedAt": 1711900000000 }, + "broken-links": { "executionCount": 210, "lastExecutedAt": 1711800000000 } + } + } + } + } +} +``` + +#### `TokenUsageSummary` fields (repeated in every breakdown) + +| Field | Type | Description | +| ------------------ | ------ | ---------------------------------------------------------- | +| `requestCount` | number | Total LLM API requests | +| `promptTokens` | number | Total input tokens consumed | +| `completionTokens` | number | Total output tokens generated | +| `thoughtsTokens` | number | Thinking/reasoning tokens (model-dependent; 0 for Gemini) | +| `totalTokens` | number | Total tokens consumed | + +#### `tokenUsage` breakdown keys + +| Key | Type | Description | +| --------- | --------------------------------------------- | ---------------------------------------------------------------------------- | +| `allTime` | `TokenUsageSummary` | Aggregate across all time | +| `yearly` | `Record>` | Keyed by 4-digit year, then by sanitised model key | +| `monthly` | `Record>` | Keyed by `"01"`-`"12"`, then by sanitised model key | +| `byModel` | `Record` | Cross-year aggregate, keyed by sanitised model (e.g. `"claude_claude-sonnet-4-6"`) | + +#### `executionCounts` map + +| Field | Type | Description | +| ---------------- | --------------- | ------------------------------------------ | +| `executionCount` | number | Total executions for this agent | +| `lastExecutedAt` | number \| null | Epoch ms of last execution. `null` if never. | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + +**Errors:** `INVALID_ARGUMENT` (invalid `year` or `month` format). + + +```js +{ + "result": { + "status": "success", + "message": "Analytics fetched successfully", + "data": { + "analytics": { + "tokenUsage": { + "allTime": { "requestCount": 0, "promptTokens": 0, "completionTokens": 0, "thoughtsTokens": 0, "totalTokens": 0 }, + "yearly": {}, + "monthly": {}, + "byModel": {} + }, + "executionCounts": {} + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/config/resolve.mdx b/api-reference/rest-apis/v2/agents/config/resolve.mdx new file mode 100644 index 000000000..e4d252ba9 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/config/resolve.mdx @@ -0,0 +1,126 @@ +--- +title: "Resolve Config" +api: "POST https://api.velt.dev/v2/agents/config/resolve" +--- + +Use this API to resolve optimal extraction strategies and execution strategy for an agent based on its instructions. The engine analyzes the (optional `rawInstructions` plus the processed `instructions`) and returns: + +- A recommended set of `contextGathering.strategies` +- A recommended `executionStrategy` (`ai`, `service`, `service+ai`, or `stagehand-agent`) +- Reasoning for each recommendation + +Use this as a starting point when creating a new agent — the response can be passed straight into [Create Agent](/api-reference/rest-apis/v2/agents/create) under the `contextGathering` and `execution` blocks. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/config/resolve` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. The processed/enhanced agent instructions. + + + + Verbatim user prompt. When provided, the resolver also uses it to detect navigation/interaction intent (e.g. "click the menu, then check…") and may recommend `stagehand-agent` execution. + + + + LLM provider override: `"gemini"` or `"claude"`. + + + + +## **Example Requests** + +#### 1. Resolve a static analysis agent + +```JSON +{ + "data": { + "instructions": "Verify all CTAs use the primary brand color #1A73E8 and the heading font 'Inter'." + } +} +``` + +#### 2. Resolve an interactive agent + +```JSON +{ + "data": { + "rawInstructions": "Open the navigation menu, click 'Pricing', and check that the page title contains 'Pricing'.", + "instructions": "Open the navigation menu, click the Pricing link, and verify the resulting page title contains 'Pricing'." + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Config resolved successfully", + "data": { + "resolvedConfig": { + "extraction_strategies": ["web-page-text", "web-page-screenshot", "web-page-html"], + "execution_strategy": "ai", + "reasoning": "The instructions describe a static visual + textual check (brand colors and fonts). Screenshots support color verification; HTML supports font detection. AI execution is sufficient — no service delegation needed." + } + } + } +} +``` + +| Field | Type | Description | +| ---------------------------------------------- | -------- | ------------------------------------------------------------------------ | +| `data.resolvedConfig.extraction_strategies` | string[] | Recommended `contextGathering.strategies` values. | +| `data.resolvedConfig.execution_strategy` | string | Recommended `execution.executionStrategy` value. | +| `data.resolvedConfig.reasoning` | string | Explanation for the recommendations. | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + +**Errors:** `INVALID_ARGUMENT` (missing or empty `instructions`). + + +```js +{ + "result": { + "status": "success", + "message": "Config resolved successfully", + "data": { + "resolvedConfig": { + "extraction_strategies": ["web-page-text"], + "execution_strategy": "ai", + "reasoning": "..." + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/create.mdx b/api-reference/rest-apis/v2/agents/create.mdx new file mode 100644 index 000000000..1cfe374ee --- /dev/null +++ b/api-reference/rest-apis/v2/agents/create.mdx @@ -0,0 +1,264 @@ +--- +title: "Create Agent" +api: "POST https://api.velt.dev/v2/agents/create" +--- + +Use this API to create a new custom agent configuration. The engine stores the agent in Firestore and writes version 1 to the agent's versions subcollection. The schema uses `.passthrough()`, so any additional behavioral fields are forwarded to the service layer. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/create` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. Agent display name. + + + + Human-readable description of what the agent does. + + + + Original user-provided instructions (before enhancement). + + + + Processed/enhanced instructions used by the AI execution. + + + + Whether the agent is active. Defaults to `true`. + + + + Arbitrary metadata (e.g. `{ "type": "qa", "category": "brand" }`). + + + + Context gathering configuration. + + | Field | Type | Required | Description | + | ----------------- | -------- | -------- | ---------------------------------------------------------------------------------------- | + | `strategies` | string[] | no | Min 1 if provided. See [context gathering strategies](/ai/agents/overview#context-gathering-strategies). | + | `strategyOptions` | object | no | Per-strategy option overrides, keyed by strategy name. | + + + + Execution configuration. + + | Field | Type | Required | Description | + | ---------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------- | + | `executionStrategy` | string | no | `"ai"` (default), `"service"`, `"service+ai"`, or `"stagehand-agent"`. | + | `serviceId` | string | no | Required when `executionStrategy` is `"service"` or `"service+ai"`. Values: `"broken-links"`, `"crawler"`, `"screenshot"`. | + | `responseDescriptions` | object | no | Per-field descriptions guiding AI response shaping ([see below](#response-descriptions)). | + | `strategyOptions` | object | no | Per-strategy option overrides. | + | `knowledge` | object | no | Knowledge integration: `{ sourceIds?: string[], useMemory?: boolean, maxChunks?: number }`. `maxChunks` range 1-50. | + + + + Response formatting configuration. + + | Field | Type | Required | Description | + | ------------------ | ------- | -------- | ------------------------------------------------------------------------------------ | + | `useAiFormatting` | boolean | no | Whether to use AI for response formatting. | + | `formattingPrompt` | string | no | Custom prompt for AI formatting. | + | `responseAdapter` | string | no | Adapter name: `"broken-links-response"`, `"crawler-response"`, `"screenshot-response"`. | + + + + Post-processing pipeline configuration. All stages default to **enabled** when omitted or when `enabled` is not explicitly `false`. + + | Field | Type | Required | Description | + | ------------------ | -------- | -------- | ------------------------------------------------------------------------------------ | + | `guardrails` | object | no | `{ enabled?: boolean }` — confidence-based filtering. Findings below 50% are suppressed. | + | `matchAndMerge` | object | no | `{ enabled?: boolean }` — deduplication against previous execution findings. | + | `pinResolution` | object | no | `{ enabled?: boolean }` — anchor pin resolution for visual annotations. | + | `annotations` | object | no | `{ enabled?: boolean, strategy?: string }` — strategy: `"findings"`, `"word-level"`, `"page-level"`, `"none"`. | + | `analytics` | object | no | `{ enabled?: boolean }` — analytics event tracking. | + | `customProcessors` | string[] | no | Custom post-processor names. | + + + + Input declaration configuration. + + | Field | Type | Required | Description | + | ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------- | + | `variableKeys` | string[] | no | Variable names the agent expects in the payload. | + | `userContextFields` | object[] | no | User-context field definitions (`{ id, title, type, required?, defaultValue? }`). | + | `inputRequirements` | object | no | `{ requires?: string[], requiresOneOf?: string[] }`. | + + Each `userContextFields[]` entry: `id` (min 1), `title` (min 1), `type` (`"string"` / `"number"` / `"boolean"`), optional `required` (boolean), optional `defaultValue`. + + + + Scope and targeting configuration. + + | Field | Type | Required | Description | + | --------------------- | -------- | -------- | -------------------------------------------------------------------------- | + | `pageScope` | string[] | no | URL glob patterns the agent runs on. | + | `pageScopeExclude` | string[] | no | URL glob patterns to exclude. | + | `contentTypes` | string[] | no | Content types the agent handles. | + | `crossPage` | object | no | Cross-page execution config (`enabled`, `targetProperty`, `pageDiscovery`, optional `pages[]`, `sourceOfTruthKnowledgeSourceId`). | + + + + Tooling metadata for the setup assistant and checklist-to-agent converter. Not consumed by the agent pipeline at runtime. + + Fields: `setupSamples[]`, `checklistOrigin`. + + + + +#### Response Descriptions + +All fields are optional strings that instruct the AI on how to populate each finding field: + +| Field | Description | +| -------------- | ---------------------------------------------------------------------------- | +| `summary` | Summary text of the overall analysis. | +| `title` | Short title of the finding. | +| `description` | Detailed description of the finding. | +| `severity` | Severity level. Values: `critical`, `high`, `medium`, `low`, `info`. | +| `targetText` | The exact text on the page this finding refers to. | +| `suggestion` | Suggested fix or recommendation. | +| `isPageLevel` | `true` for visual/layout findings; `false` when targetText is real DOM text. | +| `htmlSelector` | CSS selector of the DOM element. | +| `issueType` | Issue type for match-and-merge keying (short, lowercase, hyphenated). | +| `confidence` | Confidence score from 0 to 100. | +| `findingType` | Finding type classification. | + +## **Example Requests** + +#### 1. Minimal agent + +```JSON +{ + "data": { + "name": "Simple Content Checker", + "instructions": "Check for broken images and missing alt text on the page.", + "contextGathering": { + "strategies": ["web-page-html"] + } + } +} +``` + +#### 2. Full custom agent with cross-page execution + +```JSON +{ + "data": { + "name": "Brand Consistency Checker", + "description": "Validates brand colors, logos, and typography across pages", + "rawInstructions": "Check that all headings use the brand font 'Inter'. Verify the primary color #1A73E8 is used for CTAs.", + "instructions": "Check that all headings use the brand font 'Inter'. Verify the primary color #1A73E8 is used for CTAs.", + "enabled": true, + "metadata": { "type": "qa", "category": "brand" }, + "contextGathering": { + "strategies": ["web-page-screenshot", "web-page-text", "web-page-html"], + "strategyOptions": { + "web-page-screenshot": { "scrollBeforeCapture": true } + } + }, + "execution": { + "executionStrategy": "ai", + "responseDescriptions": { + "title": "Short name for the brand inconsistency", + "severity": "One of: critical, high, medium, low", + "suggestion": "Specific CSS or design fix", + "issueType": "One of: brand-color, brand-font, brand-logo" + }, + "knowledge": { + "sourceIds": ["ks_brand_guidelines_v2"], + "useMemory": true, + "maxChunks": 10 + } + }, + "postProcess": { + "guardrails": { "enabled": true }, + "matchAndMerge": { "enabled": true }, + "annotations": { "enabled": true, "strategy": "findings" }, + "analytics": { "enabled": true } + }, + "input": { + "inputRequirements": { "requires": ["url"] }, + "userContextFields": [ + { "id": "brand_color", "title": "Primary brand color?", "type": "string", "required": true }, + { "id": "brand_font", "title": "Heading font family?", "type": "string" } + ] + }, + "scope": { + "pageScope": ["https://example.com/*"], + "pageScopeExclude": ["https://example.com/admin/*"], + "crossPage": { + "enabled": true, + "targetProperty": "brandConsistency", + "pageDiscovery": "auto", + "sourceOfTruthKnowledgeSourceId": "ks_brand_guidelines_v2" + } + } + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agent created successfully", + "data": { + "agentId": "abc123def456" + } + } +} +``` + +| Field | Type | Description | +| ---------------- | ------ | -------------------------------------- | +| `data.agentId` | string | Firestore document ID of the new agent | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + +**Errors:** `INVALID_ARGUMENT` (Zod validation failure — e.g. missing `name`, missing `apiKey`, invalid `userContextFields.type`) / `RESOURCE_EXHAUSTED` (workspace already has the maximum number of custom agents). + + +```js +{ + "result": { + "status": "success", + "message": "Agent created successfully", + "data": { + "agentId": "abc123def456" + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/delete.mdx b/api-reference/rest-apis/v2/agents/delete.mdx new file mode 100644 index 000000000..a6dab7f66 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/delete.mdx @@ -0,0 +1,93 @@ +--- +title: "Delete Agent" +api: "POST https://api.velt.dev/v2/agents/delete" +--- + +Use this API to delete a custom agent configuration and all its versions. + +**Group cleanup:** Before the agent document and its versions subcollection are recursively deleted, the `agentId` is removed from the `agentIds` array of every agent group it belongs to. A cleanup failure aborts the delete and leaves the agent intact, so the call can safely be retried. Groups themselves are never deleted as part of agent deletion, even when they become empty. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/delete` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. Agent ID to delete. + + + + +## **Example Requests** + +#### Delete a custom agent + +```JSON +{ + "data": { + "agentId": "abc123def456" + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agent deleted successfully", + "data": { + "agentId": "abc123def456" + } + } +} +``` + +| Field | Type | Description | +| --------------- | ------ | ---------------------------- | +| `data.agentId` | string | The ID of the deleted agent | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "NOT_FOUND" + } +} +``` + +**Errors:** `NOT_FOUND` (agent does not exist). + + +```js +{ + "result": { + "status": "success", + "message": "Agent deleted successfully", + "data": { + "agentId": "abc123def456" + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/execution/get.mdx b/api-reference/rest-apis/v2/agents/execution/get.mdx new file mode 100644 index 000000000..9ae4e8c3b --- /dev/null +++ b/api-reference/rest-apis/v2/agents/execution/get.mdx @@ -0,0 +1,276 @@ +--- +title: "Get Execution" +api: "POST https://api.velt.dev/v2/agents/execution/get" +--- + +Use this API to fetch an execution document by ID. This is the polling endpoint — call it after [Run Execution](/api-reference/rest-apis/v2/agents/execution/run) and poll until `execution.status !== "running"`. + +Set `includeResults: true` to also fetch the per-URL findings subcollection. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/execution/get` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. Execution ID returned from [Run Execution](/api-reference/rest-apis/v2/agents/execution/run). + + + + Include the full per-URL findings subcollection. Default: `false`. + + + + +## **Example Requests** + +#### 1. Poll status only + +```JSON +{ + "data": { + "executionId": "exec_1711900000000_abc123def456" + } +} +``` + +#### 2. Fetch with full results + +```JSON +{ + "data": { + "executionId": "exec_1711900000000_abc123def456", + "includeResults": true + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Execution fetched successfully", + "data": { + "execution": { + "id": "exec_1711900000000_abc123def456", + "agentId": "abc123def456", + "agentName": "Brand Consistency Checker", + "agentVersion": 3, + "metadata": { + "apiKey": "ak_xxx", + "organizationId": "server_org_001", + "clientOrganizationId": "org_001", + "documentId": "server_doc_001", + "clientDocumentId": "doc_001" + }, + "config": { + "seedUrl": "https://example.com", + "crossPageExecute": true, + "maxUrlsToProcess": 25, + "crawlerConfig": { "maxPages": 100, "timeout": 300000, "maxDepth": 0 } + }, + "status": "passed", + "startedAt": 1711900000000, + "completedAt": 1711900150000, + "durationMs": 150000, + "trigger": "standalone", + "workflowExecutionId": null, + "previousExecutionId": null, + "ranBy": { "userId": "user_123", "name": "Jane Doe", "email": "jane@example.com" }, + "resultsSummary": { + "totalFindings": 7, + "totalAnnotationsCreated": 5, + "urlsProcessed": 12, + "urlsWithFindings": 5, + "issuesCreated": 7, + "summary": "Found 7 issues across 12 pages. 5 annotations created, 2 matched existing annotations.", + "matchResult": { "created": 5, "skipped": 2, "resolved": 1 } + }, + "crawlerResults": { "status": "completed", "totalUrlsFound": 12, "duration": 45000, "pagesVisited": 12 }, + "llmModel": "claude/claude-sonnet-4-6", + "tokenUsage": { + "promptTokens": 12500, + "completionTokens": 3200, + "thoughtsTokens": 0, + "totalTokens": 15700 + }, + "knowledgeRetrieved": true, + "knowledgeCached": false, + "degraded": false + } + } + } +} +``` + +#### Execution document fields + +| Field | Type | Description | +| ---------------------------------------- | ------------------- | ----------------------------------------------------------------- | +| `id` | string | Execution ID | +| `agentId` | string | Agent that was executed | +| `agentName` | string | Denormalized agent display name | +| `agentVersion` | number | Agent config version pinned at dispatch time | +| `metadata.apiKey` | string | Workspace API key | +| `metadata.organizationId` | string | Server-namespaced organization ID | +| `metadata.clientOrganizationId` | string | Client-provided organization ID | +| `metadata.documentId` | string | Server-namespaced document ID | +| `metadata.clientDocumentId` | string | Client-provided document ID | +| `config.seedUrl` | string | The seed URL provided by the user | +| `config.crossPageExecute` | boolean | Whether cross-page mode was used | +| `config.maxUrlsToProcess` | number | Max URLs limit | +| `config.crawlerConfig` | object \| undefined | Crawler config (only when `crossPageExecute: true`) | +| `status` | string | `"running"`, `"passed"`, `"failed"`, `"error"`, `"skipped"` | +| `startedAt` | number | Epoch ms | +| `completedAt` | number \| null | Epoch ms when completed; null while running | +| `durationMs` | number \| null | Total duration in ms | +| `error` | object \| undefined | Populated on `error` or `failed` status | +| `error.code` | string | One of `TIMEOUT`, `LLM_ERROR`, `LLM_RATE_LIMITED`, `MALFORMED_RESPONSE`, `CRAWLER_ERROR`, `EXTRACTION_ERROR`, `POST_PROCESS_ERROR`, `INTERNAL` | +| `error.message` | string | Human-readable error description | +| `error.retryable` | boolean | Whether this error can be retried | +| `error.advisoryComment` | string \| undefined | Advisory comment text posted to the document | +| `error.occurredAt` | number | Epoch ms | +| `trigger` | string | `"standalone"` or `"workflow"` | +| `workflowExecutionId` | string \| undefined | Parent workflow execution ID (workflow-triggered runs) | +| `previousExecutionId` | string \| undefined | Previous execution ID (for match-and-merge reruns) | +| `ranBy.userId` | string | User ID | +| `ranBy.name` | string | Display name | +| `ranBy.email` | string | Email | +| `resultsSummary.totalFindings` | number | Total findings (after guardrails filtering) | +| `resultsSummary.totalAnnotationsCreated` | number | Annotations created (after match-and-merge dedup) | +| `resultsSummary.urlsProcessed` | number | URLs processed | +| `resultsSummary.urlsWithFindings` | number | URLs that had at least one finding | +| `resultsSummary.matchResult` | object \| undefined | `{ created, skipped, resolved }` — match-and-merge outcome | +| `crawlerResults` | object \| undefined | Only populated when `crossPageExecute: true` | +| `llmModel` | string \| undefined | LLM model used (e.g. `"claude/claude-sonnet-4-6"`) | +| `tokenUsage` | object | `{ promptTokens, completionTokens, thoughtsTokens, totalTokens }` | +| `knowledgeRetrieved` | boolean \| undefined | Whether knowledge was retrieved from Memory | +| `knowledgeCached` | boolean \| undefined | Whether knowledge retrieval was served from cache | +| `degraded` | boolean \| undefined | Whether the agent ran in degraded mode | + +#### Success Response (with results — `includeResults: true`) + +```JSON +{ + "result": { + "status": "success", + "message": "Execution fetched successfully", + "data": { + "execution": { "...same as above..." }, + "results": [ + { + "url": "https://example.com", + "urlHash": "a1b2c3d4e5f6", + "findings": [ + { + "id": "finding-1", + "title": "Heading uses wrong font", + "description": "The h1 element uses 'Arial' instead of brand font 'Inter'", + "severity": "high", + "category": "typography", + "targetText": "Welcome to Example", + "occurrence": 1, + "sourceUrl": "https://example.com", + "suggestion": "Change font-family to 'Inter' for the h1 element", + "htmlSelector": "h1.hero-title", + "htmlXpath": "/html/body/main/section[1]/h1", + "isPageLevel": false, + "issueType": "brand-font", + "confidence": 92 + } + ], + "findingCount": 1, + "annotationsCreated": 1, + "processedAt": 1711900050000 + } + ] + } + } +} +``` + +#### Per-URL result fields + +| Field | Type | Description | +| -------------------- | -------- | -------------------------------------------------- | +| `url` | string | The URL analyzed | +| `urlHash` | string | MD5 hash of the URL (Firestore doc ID) | +| `findings` | object[] | Array of `AgentFinding` objects | +| `findingCount` | number | Number of findings for this URL | +| `annotationsCreated` | number | Annotations created for this URL | +| `processedAt` | number | Epoch ms when this URL was processed | + +#### Finding fields (`AgentFinding`) + +| Field | Type | Required | Description | +| -------------- | -------- | -------- | -------------------------------------------------------------------------- | +| `id` | string | yes | Unique finding ID (e.g. `"finding-1"`) | +| `title` | string | yes | Short title | +| `description` | string | yes | Detailed description | +| `severity` | string | yes | `critical`, `high`, `medium`, `low`, `info` | +| `category` | string | no | Grouping tag (e.g. `accessibility`, `seo`, `content`, `layout`) | +| `targetText` | string | yes | Exact DOM text. Empty string for image/non-text findings | +| `occurrence` | number | no | 1-based occurrence index of `targetText` on the page | +| `sourceUrl` | string | no | URL where the finding was detected | +| `suggestion` | string | no | Suggested fix | +| `htmlSelector` | string | yes | CSS selector of the DOM element | +| `htmlXpath` | string | yes | XPath of the DOM element | +| `htmlSnippet` | string | no | Surrounding HTML snippet for context | +| `isPageLevel` | boolean | yes | `true` for visual/layout findings; `false` when targetText matches DOM text | +| `issueType` | string | no | Match-and-merge key (e.g. `"casing"`, `"pii"`, `"spelling"`) | +| `confidence` | number | no | 0-100. Findings below 50 may be suppressed by guardrails | +| `commentId` | string | no | Comment annotation ID populated after annotation creation | +| `source` | string | no | `"instructions"` or `"knowledge"` | +| `metadata` | object | no | Additional finding-specific metadata | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "NOT_FOUND" + } +} +``` + +**Errors:** `NOT_FOUND` (execution or store database not found) / `INVALID_ARGUMENT` (missing or empty `executionId`). + + +```js +{ + "result": { + "status": "success", + "message": "Execution fetched successfully", + "data": { + "execution": { + "id": "exec_1711900000000_abc123def456", + "status": "running", + "startedAt": 1711900000000, + "completedAt": null, + "durationMs": null + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/execution/run.mdx b/api-reference/rest-apis/v2/agents/execution/run.mdx new file mode 100644 index 000000000..da2670e2f --- /dev/null +++ b/api-reference/rest-apis/v2/agents/execution/run.mdx @@ -0,0 +1,198 @@ +--- +title: "Run Execution" +api: "POST https://api.velt.dev/v2/agents/execution/run" +--- + +Use this API to start an asynchronous agent execution. The engine creates an execution document in Firestore and dispatches a Cloud Task for processing. The response returns immediately with the `executionId` — poll [Get Execution](/api-reference/rest-apis/v2/agents/execution/get) to track progress and fetch findings. + +The `apiKey` is injected from request headers. Pass `organizationId` and `documentId` at the top level of the body if you want findings to land as comment annotations on a specific document. Cross-page execution is controlled via the `crossPageExecute` boolean — no separate endpoint. + +The schema uses `.passthrough()` so any additional fields are forwarded. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/execution/run` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. Agent ID to execute. + + + + Valid URL. The seed URL to process. + + + + When true, the engine crawls the seed URL and processes up to `maxUrlsToProcess` pages. Default: `false`. + + + + Max URLs to process when `crossPageExecute: true`. Positive integer. Default: 50. + + + + Client organization ID. Required for findings to be persisted as comment annotations. + + + + Client document ID. Required for findings to be persisted as comment annotations. + + + + `"standalone"` (default) or `"workflow"`. Use `"workflow"` when running an agent as part of an Approval Engine workflow node. + + + + Parent workflow execution ID. Pair with `trigger: "workflow"`. + + + + User who triggered the execution. + + | Field | Type | Required | Description | + | -------- | ------ | --------------- | ----------------- | + | `userId` | string | yes (if ranBy) | User ID | + | `name` | string | no | Display name. Default: `""`. | + | `email` | string | no | Email. Default: `""`. | + + + + Runtime values for the agent's `userContextFields`. Keys must match the field IDs declared in the agent's `input.userContextFields`. + + + + +## **Example Requests** + +#### 1. Single page execution + +```JSON +{ + "data": { + "agentId": "abc123def456", + "url": "https://example.com/pricing", + "organizationId": "org_001", + "documentId": "doc_001", + "ranBy": { + "userId": "user_123", + "name": "Jane Doe", + "email": "jane@example.com" + } + } +} +``` + +#### 2. Cross-page execution with user context + +```JSON +{ + "data": { + "agentId": "abc123def456", + "url": "https://example.com", + "crossPageExecute": true, + "maxUrlsToProcess": 25, + "organizationId": "org_001", + "documentId": "doc_001", + "trigger": "standalone", + "userContext": { + "brand_color": "#1A73E8", + "brand_font": "Inter", + "check_images": true + }, + "ranBy": { + "userId": "user_123", + "name": "Jane Doe", + "email": "jane@example.com" + } + } +} +``` + +#### 3. Workflow-triggered execution + +```JSON +{ + "data": { + "agentId": "abc123def456", + "url": "https://example.com", + "trigger": "workflow", + "workflowExecutionId": "wf_exec_789", + "organizationId": "org_001", + "documentId": "doc_001", + "ranBy": { "userId": "user_123" } + } +} +``` + +#### 4. Minimal request + +```JSON +{ + "data": { + "agentId": "abc123def456", + "url": "https://example.com" + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agent execution created successfully", + "data": { + "executionId": "exec_1711900000000_abc123def456" + } + } +} +``` + +| Field | Type | Description | +| -------------------- | ------ | ---------------------------------------------------------- | +| `data.executionId` | string | Unique execution ID. Use to poll via [Get Execution](/api-reference/rest-apis/v2/agents/execution/get). | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + +**Errors:** `INVALID_ARGUMENT` (invalid URL, missing required fields, invalid `trigger`) / `NOT_FOUND` (agent does not exist) / `FAILED_PRECONDITION` (agent is disabled, store database not found, or active execution already exists for this document). + + +```js +{ + "result": { + "status": "success", + "message": "Agent execution created successfully", + "data": { + "executionId": "exec_1711900000000_abc123def456" + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/extract.mdx b/api-reference/rest-apis/v2/agents/extract.mdx new file mode 100644 index 000000000..c850d8a6f --- /dev/null +++ b/api-reference/rest-apis/v2/agents/extract.mdx @@ -0,0 +1,138 @@ +--- +title: "Extract Agents from File" +api: "POST https://api.velt.dev/v2/agents/extract" +--- + +Use this API to extract agent definitions from an uploaded file. The file is parsed by an LLM and the response returns a list of structured agent configurations that can be passed straight into [Create Agent](/api-reference/rest-apis/v2/agents/create). + +Useful for migrating an existing QA checklist (CSV / Excel / PDF / plain text) into agents in bulk. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/extract` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. Base64-encoded file content. + + + + Min 1 char. MIME type of the uploaded file (e.g. `"text/csv"`, `"application/pdf"`, `"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"`). + + + + LLM provider override: `"gemini"` or `"claude"`. + + + + +## **Example Requests** + +#### 1. Extract from a CSV checklist + +```JSON +{ + "data": { + "fileBase64": "QWdlbnQgTmFtZSxEZXNjcmlwdGlvbixJbnN0cnVjdGlvbnMK...", + "mimeType": "text/csv" + } +} +``` + +#### 2. Extract from a PDF checklist + +```JSON +{ + "data": { + "fileBase64": "JVBERi0xLjcKJeLjz9MK...", + "mimeType": "application/pdf" + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agents extracted successfully", + "data": { + "extractionResult": { + "agents": [ + { + "name": "Brand Color Check", + "description": "Verify all CTAs use the primary brand color", + "instructions": "Check that every element uses the primary brand color #1A73E8.", + "contextGathering": { "strategies": ["web-page-html", "web-page-screenshot"] }, + "execution": { "executionStrategy": "ai" } + }, + { + "name": "Heading Font Check", + "description": "Verify all headings use the brand font", + "instructions": "Check that every

,

, and

element uses font-family 'Inter'.", + "contextGathering": { "strategies": ["web-page-html"] }, + "execution": { "executionStrategy": "ai" } + } + ], + "summary": "Extracted 2 agents from CSV file", + "skipped": [] + } + } + } +} +``` + +| Field | Type | Description | +| -------------------------------------- | -------- | -------------------------------------------------------------------------- | +| `data.extractionResult.agents` | object[] | Array of extracted agent configurations ready for [Create Agent](/api-reference/rest-apis/v2/agents/create). | +| `data.extractionResult.summary` | string | Human-readable summary of the extraction. | +| `data.extractionResult.skipped` | object[] | Rows the engine could not turn into agents (with the reason for each). | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + +**Errors:** `INVALID_ARGUMENT` (missing or empty `fileBase64` / `mimeType`, or unsupported MIME type). + + +```js +{ + "result": { + "status": "success", + "message": "Agents extracted successfully", + "data": { + "extractionResult": { + "agents": [], + "summary": "Extracted 0 agents", + "skipped": [] + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/get.mdx b/api-reference/rest-apis/v2/agents/get.mdx new file mode 100644 index 000000000..335144f11 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/get.mdx @@ -0,0 +1,239 @@ +--- +title: "Get Agent(s)" +api: "POST https://api.velt.dev/v2/agents/get" +--- + +Use this API to fetch a single agent or list agents in your workspace. The endpoint behaves differently based on the provided fields: + +- **`agentId` provided:** returns a single agent. For custom agents, the response merges identity + behavioral fields from the version subcollection. For built-in agents, only sanitized public fields are returned. +- **`agentId` omitted:** returns a list of agents with identity-only fields. Optionally filter by `filter` (default vs custom) and/or `groupId` (members of an agent group). + +Built-in agents flagged `metadata.internal: true` (e.g. `crawler`, `screenshot`) are excluded from list responses but can still be fetched individually. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/get` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. Agent ID. When provided, returns a single agent. When omitted, returns a list. + + + + `"defaultOnly"` (built-in only) or `"customOnly"` (user-created only). Ignored when `agentId` is provided. + + + + Min 1 char. Agent group id. When provided (and `agentId` omitted), returns only agents that are members of the group, ordered by the group's `agentIds` array. Compatible with `filter`. Unknown group ids return `NOT_FOUND`. + + + + +## **Example Requests** + +#### 1. Get a single custom agent + +```JSON +{ + "data": { + "agentId": "abc123def456" + } +} +``` + +#### 2. Get a single built-in agent + +```JSON +{ + "data": { + "agentId": "spell-check" + } +} +``` + +#### 3. List all agents (no filter) + +```JSON +{ + "data": {} +} +``` + +#### 4. List only custom agents + +```JSON +{ + "data": { + "filter": "customOnly" + } +} +``` + +#### 5. List agents in a group + +```JSON +{ + "data": { + "groupId": "grp_brand_qa" + } +} +``` + +# Response + +#### Success Response (single custom agent) + +```JSON +{ + "result": { + "status": "success", + "message": "Agent fetched successfully", + "data": { + "agent": { + "id": "abc123def456", + "name": "Brand Consistency Checker", + "description": "Validates brand colors and typography", + "enabled": true, + "version": 3, + "managedBy": "customer", + "rawInstructions": "Check that all headings use the brand font 'Inter'...", + "instructions": "Check that all headings use the brand font 'Inter'...", + "contextGathering": { + "strategies": ["web-page-text", "web-page-screenshot"] + }, + "execution": { + "executionStrategy": "ai", + "responseDescriptions": { "title": "Short name for the brand inconsistency" }, + "knowledge": { "sourceIds": ["ks_brand_guidelines_v2"], "useMemory": true } + }, + "response": { "useAiFormatting": false }, + "postProcess": { + "guardrails": { "enabled": true }, + "matchAndMerge": { "enabled": true }, + "annotations": { "enabled": true, "strategy": "findings" } + }, + "input": { + "inputRequirements": { "requires": ["url"] }, + "userContextFields": [ + { "id": "brand_color", "title": "Primary brand color?", "type": "string", "required": true } + ] + }, + "scope": { + "pageScope": ["https://example.com/*"], + "crossPage": { "enabled": true, "targetProperty": "brandConsistency", "pageDiscovery": "auto" } + }, + "metadata": { "type": "qa", "category": "brand" }, + "executionCount": 5, + "lastExecutedAt": 1711900000000 + } + } + } +} +``` + +#### Success Response (single built-in agent — sanitized) + +Built-in agents return only public fields. Internal implementation fields (`instructions`, `contextGathering`, `execution`, `postProcess`, `response`, `payloadSchema`, `supportedVariables`) are stripped. + +```JSON +{ + "result": { + "status": "success", + "message": "Agent fetched successfully", + "data": { + "agent": { + "id": "spell-check", + "name": "Spell Check", + "description": "Finds spelling mistakes and typos in page content using AI analysis", + "enabled": true, + "managedBy": "velt", + "metadata": { "type": "system", "category": "quality" }, + "system": true, + "inputRequirements": { "requires": ["url"] }, + "userContextFields": [], + "executionCount": 142, + "lastExecutedAt": 1711900000000 + } + } + } +} +``` + +#### Success Response (list) + +```JSON +{ + "result": { + "status": "success", + "message": "Agents fetched successfully", + "data": { + "agents": [ + { + "id": "spell-check", + "name": "Spell Check", + "description": "Finds spelling mistakes and typos", + "system": true, + "enabled": true, + "managedBy": "velt", + "metadata": { "type": "system", "category": "quality" }, + "executionCount": 142, + "lastExecutedAt": 1711900000000 + }, + { + "id": "abc123def456", + "name": "Brand Consistency Checker", + "description": "Validates brand colors and typography", + "enabled": true, + "managedBy": "customer", + "version": 3, + "metadata": { "type": "qa", "category": "brand" }, + "executionCount": 5, + "lastExecutedAt": 1711900000000 + } + ] + } + } +} +``` + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "NOT_FOUND" + } +} +``` + +**Errors:** `NOT_FOUND` (agent or group not found) / `INVALID_ARGUMENT` (invalid `filter` value). + + +```js +{ + "result": { + "status": "success", + "message": "Agents fetched successfully", + "data": { + "agents": [] + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/groups/add-agents.mdx b/api-reference/rest-apis/v2/agents/groups/add-agents.mdx new file mode 100644 index 000000000..d9b5355f9 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/groups/add-agents.mdx @@ -0,0 +1,127 @@ +--- +title: "Add Agents to Group" +api: "POST https://api.velt.dev/v2/agents/groups/add-agents" +--- + +Use this API to add one or more agents to an existing group. The operation is **idempotent** — adding an id that is already a member is a silent success (no duplicate appended, no error). + +The post-add membership size is enforced atomically inside a Firestore transaction at `MAX_AGENTS_PER_GROUP = 100`. Built-in agent ids are accepted without a Firestore lookup; custom agent ids are validated in a single batched read before the transaction. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/groups/add-agents` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Trimmed, non-empty. Agent group id. + + + + Non-empty. Each id must be min 1 char. Capped at `MAX_AGENTS_PER_GROUP`. + + + + +## **Example Requests** + +#### 1. Add a single custom agent + +```JSON +{ + "data": { + "groupId": "grp_9f3ac2", + "agentIds": ["abc123def456"] + } +} +``` + +#### 2. Add multiple agents (mix of custom and built-in) + +```JSON +{ + "data": { + "groupId": "grp_9f3ac2", + "agentIds": ["abc123def456", "spell-check", "broken-links"] + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agents added to group successfully", + "data": { + "group": { + "id": "grp_9f3ac2", + "name": "Brand QA", + "agentIds": ["abc123def456", "spell-check", "broken-links"], + "metadata": { "apiKey": "ak_xxx" }, + "createdAt": 1711900000000, + "updatedAt": 1711950000000 + } + } + } +} +``` + +| Field | Type | Description | +| ------------- | ------ | -------------------------- | +| `data.group` | object | The updated group document | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "RESOURCE_EXHAUSTED" + } +} +``` + +**Errors:** + +- `NOT_FOUND` — group does not exist, OR any provided custom `agentId` does not exist +- `RESOURCE_EXHAUSTED` — resulting group size would exceed `MAX_AGENTS_PER_GROUP` +- `INVALID_ARGUMENT` — empty `agentIds` array, or any id is empty + + +```js +{ + "result": { + "status": "success", + "message": "Agents added to group successfully", + "data": { + "group": { + "id": "grp_9f3ac2", + "name": "Brand QA", + "agentIds": ["abc123def456"], + "metadata": { "apiKey": "ak_xxx" }, + "createdAt": 1711900000000, + "updatedAt": 1711950000000 + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/groups/create.mdx b/api-reference/rest-apis/v2/agents/groups/create.mdx new file mode 100644 index 000000000..049c630da --- /dev/null +++ b/api-reference/rest-apis/v2/agents/groups/create.mdx @@ -0,0 +1,151 @@ +--- +title: "Create Agent Group" +api: "POST https://api.velt.dev/v2/agents/groups/create" +--- + +Use this API to create an agent group. Groups are lightweight named collections that reference existing agents via an `agentIds` array — agents themselves remain independent documents and can belong to multiple groups. + +`metadata` is an **optional, free-form** object — mirroring the agent create contract. The workspace `apiKey` is merged into `metadata.apiKey` server-side. **`metadata` is immutable after creation** — there is no way to modify it via [Update Group](/api-reference/rest-apis/v2/agents/groups/update). If you need document or organization context on a group, embed it inside `metadata` on create. + +The schema uses `.strict()` so unknown top-level fields are rejected with a clear validation error. + +**Limits:** + +- Workspace cap: `MAX_GROUPS_PER_API_KEY = 50` (enforced via Firestore `count()` on create) +- Per-group cap: `MAX_AGENTS_PER_GROUP = 100` (enforced inside a Firestore transaction) + +# Endpoint + +`POST https://api.velt.dev/v2/agents/groups/create` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Trimmed, non-empty. Capped at `MAX_GROUP_NAME_LENGTH`. + + + + Trimmed. Capped at `MAX_GROUP_DESCRIPTION_LENGTH`. + + + + Initial members. Each id must be min 1 char. Capped at `MAX_AGENTS_PER_GROUP`. Built-in agent ids are accepted without a Firestore lookup; custom agent ids are validated in a single batched read. Unknown ids return `NOT_FOUND`. + + + + Free-form metadata. Persisted verbatim; the workspace `apiKey` is merged in as `metadata.apiKey`. Immutable after creation. + + + + +## **Example Requests** + +#### 1. Minimal group + +```JSON +{ + "data": { + "name": "Brand QA" + } +} +``` + +#### 2. Full group with members and metadata + +```JSON +{ + "data": { + "name": "Brand QA", + "description": "All brand-quality agents", + "agentIds": ["abc123def456", "spell-check"], + "metadata": { + "organizationId": "server_org_001", + "documentId": "server_doc_001", + "clientOrganizationId": "org_001", + "clientDocumentId": "doc_001" + } + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agent group created successfully", + "data": { + "group": { + "id": "grp_9f3ac2", + "name": "Brand QA", + "description": "All brand-quality agents", + "agentIds": ["abc123def456", "spell-check"], + "metadata": { + "apiKey": "ak_xxx", + "organizationId": "server_org_001", + "documentId": "server_doc_001", + "clientOrganizationId": "org_001", + "clientDocumentId": "doc_001" + }, + "createdAt": 1711900000000, + "updatedAt": 1711900000000 + } + } + } +} +``` + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "RESOURCE_EXHAUSTED" + } +} +``` + +**Errors:** + +- `INVALID_ARGUMENT` — Zod validation failure (missing `name`, unknown top-level field, etc.) +- `RESOURCE_EXHAUSTED` — workspace already has `MAX_GROUPS_PER_API_KEY` groups, OR initial `agentIds` exceeds `MAX_AGENTS_PER_GROUP` +- `NOT_FOUND` — one of the initial `agentIds` does not exist + + +```js +{ + "result": { + "status": "success", + "message": "Agent group created successfully", + "data": { + "group": { + "id": "grp_9f3ac2", + "name": "Brand QA", + "agentIds": [], + "metadata": { "apiKey": "ak_xxx" }, + "createdAt": 1711900000000, + "updatedAt": 1711900000000 + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/groups/delete.mdx b/api-reference/rest-apis/v2/agents/groups/delete.mdx new file mode 100644 index 000000000..7acfc0368 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/groups/delete.mdx @@ -0,0 +1,93 @@ +--- +title: "Delete Agent Group" +api: "POST https://api.velt.dev/v2/agents/groups/delete" +--- + +Use this API to delete an agent group document. **The agents referenced by the group are not affected** — they remain intact in the workspace's custom agent collection. + +To delete a custom agent (and have it removed from every group), use [Delete Agent](/api-reference/rest-apis/v2/agents/delete). + +# Endpoint + +`POST https://api.velt.dev/v2/agents/groups/delete` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Trimmed, non-empty. Agent group id. + + + + +## **Example Requests** + +#### Delete a group + +```JSON +{ + "data": { + "groupId": "grp_9f3ac2" + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agent group deleted successfully", + "data": { + "groupId": "grp_9f3ac2" + } + } +} +``` + +| Field | Type | Description | +| --------------- | ------ | --------------------------------- | +| `data.groupId` | string | The ID of the deleted group | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "NOT_FOUND" + } +} +``` + +**Errors:** `NOT_FOUND` (group does not exist). + + +```js +{ + "result": { + "status": "success", + "message": "Agent group deleted successfully", + "data": { + "groupId": "grp_9f3ac2" + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/groups/get.mdx b/api-reference/rest-apis/v2/agents/groups/get.mdx new file mode 100644 index 000000000..985dae438 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/groups/get.mdx @@ -0,0 +1,108 @@ +--- +title: "Get Agent Group" +api: "POST https://api.velt.dev/v2/agents/groups/get" +--- + +Use this API to fetch a single agent group by id. Returns the full group document including the complete `agentIds` array. + +For a paginated overview of all groups in the workspace (returns `agentCount` instead of `agentIds`), use [List Groups](/api-reference/rest-apis/v2/agents/groups/list). + +# Endpoint + +`POST https://api.velt.dev/v2/agents/groups/get` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Trimmed, non-empty. Agent group id. + + + + +## **Example Requests** + +#### Get a group + +```JSON +{ + "data": { + "groupId": "grp_9f3ac2" + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agent group fetched successfully", + "data": { + "group": { + "id": "grp_9f3ac2", + "name": "Brand QA", + "description": "All brand-quality agents", + "agentIds": ["abc123def456", "spell-check"], + "metadata": { + "apiKey": "ak_xxx", + "organizationId": "server_org_001", + "documentId": "server_doc_001" + }, + "createdAt": 1711900000000, + "updatedAt": 1711900000000 + } + } + } +} +``` + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "NOT_FOUND" + } +} +``` + +**Errors:** `NOT_FOUND` (group does not exist) / `INVALID_ARGUMENT` (missing or empty `groupId`). + + +```js +{ + "result": { + "status": "success", + "message": "Agent group fetched successfully", + "data": { + "group": { + "id": "grp_9f3ac2", + "name": "Brand QA", + "agentIds": [], + "metadata": { "apiKey": "ak_xxx" }, + "createdAt": 1711900000000, + "updatedAt": 1711900000000 + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/groups/list.mdx b/api-reference/rest-apis/v2/agents/groups/list.mdx new file mode 100644 index 000000000..58aee7a51 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/groups/list.mdx @@ -0,0 +1,109 @@ +--- +title: "List Agent Groups" +api: "POST https://api.velt.dev/v2/agents/groups/list" +--- + +Use this API to list all agent groups in the workspace. Returns `IAgentGroupSummary[]` — the full `agentIds` array is intentionally **stripped** from each row and replaced with an `agentCount` field, so list payloads stay O(1) per group regardless of group size. + +To fetch the complete `agentIds` array for a specific group, call [Get Group](/api-reference/rest-apis/v2/agents/groups/get). + +# Endpoint + +`POST https://api.velt.dev/v2/agents/groups/list` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + Empty object — only the `apiKey` (injected from headers) is required. + + +## **Example Requests** + +#### List all groups + +```JSON +{ + "data": {} +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agent groups fetched successfully", + "data": { + "groups": [ + { + "id": "grp_9f3ac2", + "name": "Brand QA", + "description": "All brand-quality agents", + "agentCount": 12, + "metadata": { + "apiKey": "ak_xxx", + "organizationId": "server_org_001", + "documentId": "server_doc_001" + }, + "createdAt": 1711900000000, + "updatedAt": 1711900000000 + }, + { + "id": "grp_a72bc1", + "name": "Accessibility Suite", + "agentCount": 4, + "metadata": { "apiKey": "ak_xxx" }, + "createdAt": 1711800000000, + "updatedAt": 1711800000000 + } + ] + } + } +} +``` + +| Field | Type | Description | +| --------------- | -------- | --------------------------------------------- | +| `data.groups` | object[] | Array of group summary documents | + +Each summary contains `id`, `name`, `description?`, `agentCount`, `metadata`, `createdAt`, `updatedAt`. The full `agentIds` array is omitted; fetch it via [Get Group](/api-reference/rest-apis/v2/agents/groups/get). + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "Agent groups fetched successfully", + "data": { + "groups": [] + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/groups/remove-agents.mdx b/api-reference/rest-apis/v2/agents/groups/remove-agents.mdx new file mode 100644 index 000000000..dc50645a1 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/groups/remove-agents.mdx @@ -0,0 +1,126 @@ +--- +title: "Remove Agents from Group" +api: "POST https://api.velt.dev/v2/agents/groups/remove-agents" +--- + +Use this API to remove one or more agents from a group. The operation is **idempotent** — removing an id that is not a member is a silent success. + +The agents themselves are **not deleted** — only their membership in this group is removed. To delete a custom agent (and have it removed from every group), use [Delete Agent](/api-reference/rest-apis/v2/agents/delete). + +# Endpoint + +`POST https://api.velt.dev/v2/agents/groups/remove-agents` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Trimmed, non-empty. Agent group id. + + + + Non-empty. Each id must be min 1 char. + + + + +## **Example Requests** + +#### 1. Remove a single agent + +```JSON +{ + "data": { + "groupId": "grp_9f3ac2", + "agentIds": ["abc123def456"] + } +} +``` + +#### 2. Remove multiple agents + +```JSON +{ + "data": { + "groupId": "grp_9f3ac2", + "agentIds": ["abc123def456", "spell-check"] + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agents removed from group successfully", + "data": { + "group": { + "id": "grp_9f3ac2", + "name": "Brand QA", + "agentIds": ["broken-links"], + "metadata": { "apiKey": "ak_xxx" }, + "createdAt": 1711900000000, + "updatedAt": 1711950000000 + } + } + } +} +``` + +| Field | Type | Description | +| ------------- | ------ | -------------------------- | +| `data.group` | object | The updated group document | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "NOT_FOUND" + } +} +``` + +**Errors:** + +- `NOT_FOUND` — group does not exist +- `INVALID_ARGUMENT` — empty `agentIds` array, or any id is empty + + +```js +{ + "result": { + "status": "success", + "message": "Agents removed from group successfully", + "data": { + "group": { + "id": "grp_9f3ac2", + "name": "Brand QA", + "agentIds": [], + "metadata": { "apiKey": "ak_xxx" }, + "createdAt": 1711900000000, + "updatedAt": 1711950000000 + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/groups/update.mdx b/api-reference/rest-apis/v2/agents/groups/update.mdx new file mode 100644 index 000000000..0e1e662bb --- /dev/null +++ b/api-reference/rest-apis/v2/agents/groups/update.mdx @@ -0,0 +1,133 @@ +--- +title: "Update Agent Group" +api: "POST https://api.velt.dev/v2/agents/groups/update" +--- + +Use this API to update a group's `name` and/or `description`. **Membership and metadata cannot be changed via this endpoint:** + +- For membership changes, use [Add Agents to Group](/api-reference/rest-apis/v2/agents/groups/add-agents) and [Remove Agents from Group](/api-reference/rest-apis/v2/agents/groups/remove-agents). +- `metadata` is **immutable** after creation — set it on [Create Group](/api-reference/rest-apis/v2/agents/groups/create). + +The schema uses `.strict()` so any unknown field (including `agentIds` and `metadata`) is rejected with a clear validation error. At least one of `name` or `description` must be provided — empty updates are rejected. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/groups/update` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Trimmed, non-empty. Agent group id. + + + + Trimmed, non-empty. Capped at `MAX_GROUP_NAME_LENGTH`. + + + + Trimmed. Capped at `MAX_GROUP_DESCRIPTION_LENGTH`. + + + + +At least one of `name` or `description` is required. + +## **Example Requests** + +#### 1. Rename a group + +```JSON +{ + "data": { + "groupId": "grp_9f3ac2", + "name": "Brand & Visual QA" + } +} +``` + +#### 2. Update name and description + +```JSON +{ + "data": { + "groupId": "grp_9f3ac2", + "name": "Brand & Visual QA", + "description": "Brand consistency, color, typography, and layout agents" + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agent group updated successfully", + "data": { + "group": { + "id": "grp_9f3ac2", + "name": "Brand & Visual QA", + "description": "Brand consistency, color, typography, and layout agents", + "agentIds": ["abc123def456", "spell-check"], + "metadata": { "apiKey": "ak_xxx" }, + "createdAt": 1711900000000, + "updatedAt": 1711950000000 + } + } + } +} +``` + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + +**Errors:** + +- `NOT_FOUND` — group does not exist +- `INVALID_ARGUMENT` — neither `name` nor `description` provided, or unknown field sent (e.g. `agentIds`, `metadata`) + + +```js +{ + "result": { + "status": "success", + "message": "Agent group updated successfully", + "data": { + "group": { + "id": "grp_9f3ac2", + "name": "Brand & Visual QA", + "agentIds": [], + "metadata": { "apiKey": "ak_xxx" }, + "createdAt": 1711900000000, + "updatedAt": 1711950000000 + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/prompt/enhance.mdx b/api-reference/rest-apis/v2/agents/prompt/enhance.mdx new file mode 100644 index 000000000..13813d835 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/prompt/enhance.mdx @@ -0,0 +1,160 @@ +--- +title: "Enhance Prompt" +api: "POST https://api.velt.dev/v2/agents/prompt/enhance" +--- + +Use this API to validate whether a prompt has enough detail for agent execution. Returns either a "sufficient" signal or a specific clarification request with suggested options. + +This endpoint **does not modify the prompt** — it only checks completeness. Use it as a guardrail before letting a user save an underspecified agent. To expand a simple instruction into a structured QA task, use [Validate Prompt](/api-reference/rest-apis/v2/agents/prompt/validate). + +# Endpoint + +`POST https://api.velt.dev/v2/agents/prompt/enhance` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. The user's raw prompt to validate. + + + + LLM provider override: `"gemini"` or `"claude"`. + + + + Optional `userContextFields` declarations the user has already added to the agent. The enhancer takes them into account when judging completeness. + + Each entry: `{ id, title, type, example?, defaultValue? }`. `type` is `"string"`, `"number"`, or `"boolean"`. + + + + +## **Example Requests** + +#### 1. Check completeness of a vague prompt + +```JSON +{ + "data": { + "prompt": "Check that the page uses our brand colors" + } +} +``` + +#### 2. Check completeness with a provider override + +```JSON +{ + "data": { + "prompt": "Verify all CTAs use the correct color", + "provider": "claude" + } +} +``` + +#### 3. Check completeness with declared user-context fields + +```JSON +{ + "data": { + "prompt": "Check that the page uses {{brand_color}} on all buttons", + "userContextFields": [ + { "id": "brand_color", "title": "Primary brand color", "type": "string", "example": "#1A73E8" } + ] + } +} +``` + +# Response + +#### Success Response (prompt is sufficient) + +When the prompt contains enough information, `requirement` is `null`: + +```JSON +{ + "result": { + "status": "success", + "message": "Prompt enhanced successfully", + "data": { + "enhancedPrompt": { + "requirement": null + } + } + } +} +``` + +#### Success Response (needs clarification) + +When the prompt needs more detail: + +```JSON +{ + "result": { + "status": "success", + "message": "Prompt enhanced successfully", + "data": { + "enhancedPrompt": { + "requirement": "Please specify which brand colors to verify", + "context": "We need the exact hex values or color names to check accurately", + "suggestion": [ + "check primary brand color #1A73E8 only", + "check all brand palette colors" + ], + "suggestion_type": "single-select" + } + } + } +} +``` + +| Field | Type | Present When | Description | +| ----------------- | -------------- | -------------------- | ------------------------------------------------------------ | +| `requirement` | string \| null | always | `null` if sufficient; clarification question if not | +| `context` | string | needs clarification | Why the clarification is needed | +| `suggestion` | string[] | needs clarification | Suggested options for the user to choose from | +| `suggestion_type` | string | needs clarification | `"boolean"`, `"single-select"`, `"multi-select"`, or `"info"` | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + +**Errors:** `INVALID_ARGUMENT` (missing or empty `prompt`). + + +```js +{ + "result": { + "status": "success", + "message": "Prompt enhanced successfully", + "data": { + "enhancedPrompt": { + "requirement": null + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/prompt/refine.mdx b/api-reference/rest-apis/v2/agents/prompt/refine.mdx new file mode 100644 index 000000000..697eb48f4 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/prompt/refine.mdx @@ -0,0 +1,132 @@ +--- +title: "Refine Prompt" +api: "POST https://api.velt.dev/v2/agents/prompt/refine" +--- + +Use this API to refine an existing analysis prompt based on feedback from demo runs. You provide the current prompt and a list of demos with the user's feedback on what went wrong; the engine returns a refined analysis prompt and updated response descriptions. + +This is the iteration step in the prompt-design loop: run [Validate Prompt](/api-reference/rest-apis/v2/agents/prompt/validate) to expand a simple instruction, run the demos against the resulting prompt, then refine when the demos don't pass. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/prompt/refine` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. The current analysis prompt to refine. Typically the `analysis_prompt` returned by [Validate Prompt](/api-reference/rest-apis/v2/agents/prompt/validate). + + + + Min 1 entry. Demo feedback items. + + Each entry: + + | Field | Type | Required | Description | + | -------------- | ------ | -------- | ----------------------------------------------------------------- | + | `demoId` | string | yes | Min 1 char. Stable demo identifier. | + | `demoTitle` | string | yes | Min 1 char. Human-readable demo title. | + | `demoHtml` | string | yes | Min 1 char. HTML content the demo was run against. | + | `demoExpected` | string | yes | Min 1 char. The expected outcome for this demo. | + | `feedback` | string | yes | Min 1 char. Free-form feedback explaining what was wrong. | + + + + LLM provider override: `"gemini"` or `"claude"`. + + + + +## **Example Requests** + +#### Refine after a missed detection + +```JSON +{ + "data": { + "analysisPrompt": "## Objective\nIdentify all broken links on the page.\n\n## Detection Logic\nCheck HTTP status codes for non-2xx responses.", + "demoFeedback": [ + { + "demoId": "demo-1", + "demoTitle": "Mailto link with malformed address", + "demoHtml": "Email us", + "demoExpected": "detected", + "feedback": "The agent missed this — malformed mailto links should also count as broken links, not just non-2xx HTTP responses." + } + ] + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Prompt refined successfully", + "data": { + "refinerResult": { + "analysis_prompt": "## Objective\nIdentify all broken or non-functional hyperlinks on the page, including malformed mailto and tel links.\n\n## Detection Logic\nFor http(s) URLs, check HTTP status codes for non-2xx responses. For mailto links, validate the email address format. For tel links, validate the phone number format.", + "response_descriptions": { + "title": "Brief description of the broken link", + "severity": "critical for 5xx, high for 4xx and malformed mailto/tel, medium for timeouts, low for redirects", + "targetText": "The anchor text of the broken link", + "suggestion": "The correct URL, email address, or phone number" + } + } + } + } +} +``` + +| Field | Type | Description | +| ------------------------------------------ | ------ | ------------------------------------------------------ | +| `data.refinerResult.analysis_prompt` | string | The refined analysis prompt. | +| `data.refinerResult.response_descriptions` | object | Updated per-field descriptions for AI response shaping. | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + +**Errors:** `INVALID_ARGUMENT` (missing required fields, empty `demoFeedback` array, or any demo entry missing required fields). + + +```js +{ + "result": { + "status": "success", + "message": "Prompt refined successfully", + "data": { + "refinerResult": { + "analysis_prompt": "## Objective\n...\n\n## Detection Logic\n...", + "response_descriptions": {} + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/prompt/validate.mdx b/api-reference/rest-apis/v2/agents/prompt/validate.mdx new file mode 100644 index 000000000..48fa8d6db --- /dev/null +++ b/api-reference/rest-apis/v2/agents/prompt/validate.mdx @@ -0,0 +1,156 @@ +--- +title: "Validate Prompt" +api: "POST https://api.velt.dev/v2/agents/prompt/validate" +--- + +Use this API to expand a simple instruction into a structured QA task. The response includes: + +- An analysis prompt (markdown-formatted) with objective, scope, detection logic, and output format +- Per-field response descriptions for AI response shaping +- Demo test cases organized by detection dimension +- Tool requirements +- Suggested required runtime inputs + +This is the transformation step that turns a one-line instruction into a comprehensive QA task definition you can persist as an agent. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/prompt/validate` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. The user's simple instruction to expand. + + + + LLM provider override: `"gemini"` or `"claude"`. + + + + Optional `userContextFields` declarations the user has already added. The validator considers them when generating the analysis prompt and demos. + + Each entry: `{ id, title, type, example?, defaultValue? }`. `type` is `"string"`, `"number"`, or `"boolean"`. + + + + +## **Example Requests** + +#### 1. Expand a broken-links instruction + +```JSON +{ + "data": { + "prompt": "Make sure there are no broken links on the page" + } +} +``` + +#### 2. Expand an accessibility instruction + +```JSON +{ + "data": { + "prompt": "Check all images have alt text and all form inputs have labels" + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Prompt validated successfully", + "data": { + "validationResult": { + "analysis_prompt": "## Objective\nIdentify all broken or non-functional hyperlinks on the page\n\n## Scope\nAll anchor elements () and embedded resource URLs\n\n## Detection Logic\nHTTP HEAD/GET validation of link targets, checking for non-2xx status codes\n\n## Output Format\nList of broken links with source element, target URL, and HTTP status", + "requires_tool": "TOOL_TEXT_EXTRACTOR", + "response_descriptions": { + "title": "Brief description of the broken link", + "severity": "critical for 5xx errors, high for 4xx, medium for timeouts, low for redirects", + "targetText": "The anchor text of the broken link", + "suggestion": "The correct URL or action to fix the broken link", + "issueType": "broken-link" + }, + "demos": { + "detection_dimensions": ["Link targets", "HTTP status codes", "Redirect chains"], + "cases": [ + { + "id": "demo-1", + "title": "Broken link to documentation", + "tier": "obvious_match", + "dimension_tested": "HTTP status codes: 404", + "html": "API Reference", + "expected": "detected", + "reason": "Link returns 404 Not Found" + } + ] + }, + "suggested_required_inputs": [] + } + } + } +} +``` + +#### Validation result fields + +| Field | Type | Description | +| --------------------------- | -------- | ---------------------------------------------------------------------------------------- | +| `analysis_prompt` | string | Markdown-formatted QA analysis prompt (objective, scope, detection logic, output format) | +| `requires_tool` | string | `"TOOL_TEXT_EXTRACTOR"` or `"NONE"` | +| `response_descriptions` | object | Per-field descriptions for AI response shaping | +| `demos` | object | Demo test cases with `detection_dimensions[]` and tiered `cases[]` | +| `suggested_required_inputs` | object[] | Runtime-dependent fields the user must provide at execution time | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + +**Errors:** `INVALID_ARGUMENT` (missing or empty `prompt`). + + +```js +{ + "result": { + "status": "success", + "message": "Prompt validated successfully", + "data": { + "validationResult": { + "analysis_prompt": "## Objective\n...\n\n## Scope\n...", + "requires_tool": "NONE", + "response_descriptions": {}, + "demos": { "detection_dimensions": [], "cases": [] }, + "suggested_required_inputs": [] + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/update.mdx b/api-reference/rest-apis/v2/agents/update.mdx new file mode 100644 index 000000000..27a1c8dd3 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/update.mdx @@ -0,0 +1,131 @@ +--- +title: "Update Agent (Identity)" +api: "POST https://api.velt.dev/v2/agents/update" +--- + +Use this API to update identity fields (`name`, `description`, `enabled`) on the root agent document. **No new version is created.** Use [Update Agent Version](/api-reference/rest-apis/v2/agents/version/update) for behavioral edits. + +Works for both custom and built-in agents, but built-in agents only support updating `enabled`. Server-managed fields (`id`, `apiKey`, `managedBy`, `metadata`, `version`, `createdAt`, `updatedAt`) cannot be set through this endpoint. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/update` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. Agent ID to update (custom or built-in). + + + + Min 1 char. New display name. Not allowed for built-in agents. + + + + New human-readable description. Not allowed for built-in agents. + + + + Whether the agent is active. + + + + +At least one of `name`, `description`, or `enabled` should be provided. + +## **Example Requests** + +#### 1. Rename a custom agent + +```JSON +{ + "data": { + "agentId": "abc123def456", + "name": "Updated Brand Checker", + "description": "Now also checks footer typography" + } +} +``` + +#### 2. Disable an agent + +```JSON +{ + "data": { + "agentId": "abc123def456", + "enabled": false + } +} +``` + +#### 3. Enable a built-in agent + +```JSON +{ + "data": { + "agentId": "spell-check", + "enabled": true + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agent updated successfully", + "data": { + "agentId": "abc123def456" + } + } +} +``` + +| Field | Type | Description | +| --------------- | ------ | --------------------------- | +| `data.agentId` | string | The ID of the updated agent | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + +**Errors:** `INVALID_ARGUMENT` (sending `name` or `description` for a built-in agent — only `enabled` is allowed) / `NOT_FOUND` (agent does not exist). + + +```js +{ + "result": { + "status": "success", + "message": "Agent updated successfully", + "data": { + "agentId": "abc123def456" + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/version/update.mdx b/api-reference/rest-apis/v2/agents/version/update.mdx new file mode 100644 index 000000000..8ac32b04f --- /dev/null +++ b/api-reference/rest-apis/v2/agents/version/update.mdx @@ -0,0 +1,173 @@ +--- +title: "Update Agent Version (Behavioral)" +api: "POST https://api.velt.dev/v2/agents/version/update" +--- + +Use this API to update behavioral/version fields on a custom agent. Creates a new version `N+1` in the versions subcollection, updates the `version` pointer on the root document, and bumps `updatedAt`. + +In-flight executions stay pinned to whatever version they started on — the update only affects future executions. + +The schema uses `.passthrough()` so additional behavioral fields are forwarded. Deep validation happens in the service layer via `updateCustomAgentConfigSchema`. + +**Custom agents only.** Use [Update Agent](/api-reference/rest-apis/v2/agents/update) for identity edits on built-in agents. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/version/update` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. Custom agent ID. + + + + Original user-provided instructions. + + + + Processed/enhanced instructions. + + + + Per-phase timeout in milliseconds (positive integer). + + + + Context gathering config. Same shape as [Create Agent](/api-reference/rest-apis/v2/agents/create#param-contextgathering). + + + + Execution config. Same shape as [Create Agent](/api-reference/rest-apis/v2/agents/create#param-execution). + + + + Response formatting config. Same shape as [Create Agent](/api-reference/rest-apis/v2/agents/create#param-response). + + + + Post-processing pipeline config. Same shape as [Create Agent](/api-reference/rest-apis/v2/agents/create#param-postprocess). + + + + Input declaration config. Same shape as [Create Agent](/api-reference/rest-apis/v2/agents/create#param-input). + + + + Scope and targeting config. Same shape as [Create Agent](/api-reference/rest-apis/v2/agents/create#param-scope). + + + + Setup assistant metadata. Same shape as [Create Agent](/api-reference/rest-apis/v2/agents/create#param-setup). + + + + +## **Example Requests** + +#### 1. Update instructions and post-processing + +```JSON +{ + "data": { + "agentId": "abc123def456", + "instructions": "Check headings use 'Inter' font. Verify #1A73E8 on all CTAs and links.", + "postProcess": { + "guardrails": { "enabled": true }, + "matchAndMerge": { "enabled": true } + } + } +} +``` + +#### 2. Update context gathering strategies + +```JSON +{ + "data": { + "agentId": "abc123def456", + "contextGathering": { + "strategies": ["web-page-text", "web-page-html", "web-page-screenshot"] + } + } +} +``` + +#### 3. Enable cross-page execution + +```JSON +{ + "data": { + "agentId": "abc123def456", + "scope": { + "crossPage": { + "enabled": true, + "targetProperty": "brandConsistency", + "pageDiscovery": "manual", + "pages": ["https://example.com", "https://example.com/about"] + } + } + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Agent version created successfully", + "data": { + "version": 4 + } + } +} +``` + +| Field | Type | Description | +| --------------- | ------ | ------------------------------------ | +| `data.version` | number | New version number after the update | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "INVALID_ARGUMENT" + } +} +``` + +**Errors:** `NOT_FOUND` (agent does not exist) / `INVALID_ARGUMENT` (validation failure or attempting to update a built-in agent's behavior). + + +```js +{ + "result": { + "status": "success", + "message": "Agent version created successfully", + "data": { + "version": 4 + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/versions/list.mdx b/api-reference/rest-apis/v2/agents/versions/list.mdx new file mode 100644 index 000000000..37f30994c --- /dev/null +++ b/api-reference/rest-apis/v2/agents/versions/list.mdx @@ -0,0 +1,135 @@ +--- +title: "List Agent Versions" +api: "POST https://api.velt.dev/v2/agents/versions/list" +--- + +Use this API to fetch the version history for a custom agent. A new version is automatically created on every behavioral update via [Update Agent Version](/api-reference/rest-apis/v2/agents/version/update). Versions are ordered descending (newest first) and contain the full behavioral snapshot at that point in time. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/versions/list` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. Agent ID. + + + + +## **Example Requests** + +#### List versions for an agent + +```JSON +{ + "data": { + "agentId": "abc123def456" + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Versions listed successfully", + "data": { + "versions": [ + { + "id": "3", + "version": 3, + "createdAt": 1711900000000, + "name": "Brand Consistency Checker", + "description": "Validates brand colors, logos, and typography across pages", + "instructions": "Check headings use 'Inter' font. Verify #1A73E8 on all CTAs and links. Check footer uses 'Inter' for body text.", + "contextGathering": { + "strategies": ["web-page-text", "web-page-screenshot", "web-page-html"] + }, + "execution": { + "executionStrategy": "ai", + "responseDescriptions": { + "title": "Short name for the brand inconsistency", + "severity": "One of: critical, high, medium, low, info" + } + }, + "postProcess": { + "guardrails": { "enabled": true }, + "matchAndMerge": { "enabled": true } + } + }, + { + "id": "2", + "version": 2, + "createdAt": 1711800000000, + "name": "Brand Consistency Checker", + "description": "Validates brand colors and typography", + "instructions": "Check headings use 'Inter' font. Verify #1A73E8 on all CTAs and links.", + "contextGathering": { "strategies": ["web-page-text", "web-page-screenshot"] }, + "execution": { "executionStrategy": "ai" }, + "postProcess": { "guardrails": { "enabled": true } } + }, + { + "id": "1", + "version": 1, + "createdAt": 1711700000000, + "name": "Brand Consistency Checker", + "instructions": "Check headings use Inter font...", + "contextGathering": { "strategies": ["web-page-text"] } + } + ] + } + } +} +``` + +| Field | Type | Description | +| ---------------- | -------- | ------------------------------------------------ | +| `data.versions` | object[] | Version snapshots ordered descending by version | + +Each entry contains the full behavioral snapshot of the agent at that version. + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "NOT_FOUND" + } +} +``` + +**Errors:** `NOT_FOUND` (agent or store database not found). + + +```js +{ + "result": { + "status": "success", + "message": "Versions listed successfully", + "data": { + "versions": [] + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/agents/versions/restore.mdx b/api-reference/rest-apis/v2/agents/versions/restore.mdx new file mode 100644 index 000000000..27657fef1 --- /dev/null +++ b/api-reference/rest-apis/v2/agents/versions/restore.mdx @@ -0,0 +1,95 @@ +--- +title: "Restore Agent Version" +api: "POST https://api.velt.dev/v2/agents/versions/restore" +--- + +Use this API to roll back an agent one version step. The current version `N` is deleted from the versions subcollection and the main document's `version` pointer is decremented to `N-1`. + +This is a single-step undo. Call it repeatedly to walk backward through version history. The operation cannot go below version 1 — the agent must always have at least one version on file. + +There is no target-version parameter. The operation always undoes the most recent change. + +# Endpoint + +`POST https://api.velt.dev/v2/agents/versions/restore` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Min 1 char. Agent ID. + + + + +## **Example Requests** + +#### Restore an agent's previous version + +```JSON +{ + "data": { + "agentId": "abc123def456" + } +} +``` + +# Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Version restored successfully", + "data": { + "version": 2 + } + } +} +``` + +| Field | Type | Description | +| --------------- | ------ | -------------------------------------------- | +| `data.version` | number | The version the agent was restored to (`N-1`) | + +#### Failure Response + +```JSON +{ + "error": { + "message": "ERROR_MESSAGE", + "status": "FAILED_PRECONDITION" + } +} +``` + +**Errors:** `NOT_FOUND` (agent does not exist) / `FAILED_PRECONDITION` (already at version 1; cannot go below). + + +```js +{ + "result": { + "status": "success", + "message": "Version restored successfully", + "data": { + "version": 2 + } + } +} +``` + diff --git a/docs.json b/docs.json index 5f2cf37be..b4fbe09f9 100644 --- a/docs.json +++ b/docs.json @@ -277,6 +277,13 @@ "ai/rewriter/customize-behavior" ] }, + { + "group": "Agents", + "pages": [ + "ai/agents/overview", + "ai/agents/setup" + ] + }, { "group": "Approval Engine", "pages": [ @@ -765,6 +772,58 @@ "api-reference/rest-apis/v2/rewriter/ask-ai" ] }, + { + "group": "Agents", + "pages": [ + "api-reference/rest-apis/v2/agents/create", + "api-reference/rest-apis/v2/agents/get", + "api-reference/rest-apis/v2/agents/update", + "api-reference/rest-apis/v2/agents/delete", + "api-reference/rest-apis/v2/agents/extract", + { + "group": "Execution", + "pages": [ + "api-reference/rest-apis/v2/agents/execution/run", + "api-reference/rest-apis/v2/agents/execution/get" + ] + }, + { + "group": "Versions", + "pages": [ + "api-reference/rest-apis/v2/agents/versions/list", + "api-reference/rest-apis/v2/agents/versions/restore", + "api-reference/rest-apis/v2/agents/version/update" + ] + }, + { + "group": "Prompt Tools", + "pages": [ + "api-reference/rest-apis/v2/agents/prompt/enhance", + "api-reference/rest-apis/v2/agents/prompt/validate", + "api-reference/rest-apis/v2/agents/prompt/refine", + "api-reference/rest-apis/v2/agents/config/resolve" + ] + }, + { + "group": "Groups", + "pages": [ + "api-reference/rest-apis/v2/agents/groups/create", + "api-reference/rest-apis/v2/agents/groups/get", + "api-reference/rest-apis/v2/agents/groups/list", + "api-reference/rest-apis/v2/agents/groups/update", + "api-reference/rest-apis/v2/agents/groups/delete", + "api-reference/rest-apis/v2/agents/groups/add-agents", + "api-reference/rest-apis/v2/agents/groups/remove-agents" + ] + }, + { + "group": "Analytics", + "pages": [ + "api-reference/rest-apis/v2/agents/analytics/get" + ] + } + ] + }, { "group": "Approval Engine", "pages": [ From 9d996eeba63cf8f66884f275e6dbb4ecea09f6a0 Mon Sep 17 00:00:00 2001 From: raghul-velt Date: Thu, 4 Jun 2026 15:33:46 +0530 Subject: [PATCH 2/7] docs: add new API endpoints for activity, notification, and permission provider configurations - Introduced `activityconfig-get` and `activityconfig-update` for managing activity logs. - Added `notificationconfig-get` and `notificationconfig-update` for in-app notification settings. - Implemented `permissionproviderconfig-get` and `permissionproviderconfig-update` for permission provider configurations. - Updated existing API documentation to reflect changes and new endpoints. --- ...etadata-get.mdx => activityconfig-get.mdx} | 32 ++--- .../v2/workspace/activityconfig-update.mdx | 100 +++++++++++++ .../rest-apis/v2/workspace/apikey-copy.mdx | 134 ++++++++++++++++++ .../rest-apis/v2/workspace/apikey-create.mdx | 12 +- .../rest-apis/v2/workspace/apikey-update.mdx | 6 +- .../v2/workspace/apikeyconfig-get.mdx | 109 ++++++++++++++ .../v2/workspace/apikeyconfig-update.mdx | 131 +++++++++++++++++ .../rest-apis/v2/workspace/apikeys-get.mdx | 6 +- .../v2/workspace/authtoken-reset.mdx | 6 +- .../rest-apis/v2/workspace/authtokens-get.mdx | 6 +- api-reference/rest-apis/v2/workspace/get.mdx | 6 +- .../v2/workspace/notificationconfig-get.mdx | 99 +++++++++++++ .../workspace/notificationconfig-update.mdx | 117 +++++++++++++++ .../permissionproviderconfig-get.mdx | 85 +++++++++++ .../permissionproviderconfig-update.mdx | 98 +++++++++++++ .../v2/workspace/webhookconfig-get.mdx | 4 + .../v2/workspace/webhookconfig-update.mdx | 4 + docs.json | 30 +++- 18 files changed, 949 insertions(+), 36 deletions(-) rename api-reference/rest-apis/v2/workspace/{apikeymetadata-get.mdx => activityconfig-get.mdx} (59%) create mode 100644 api-reference/rest-apis/v2/workspace/activityconfig-update.mdx create mode 100644 api-reference/rest-apis/v2/workspace/apikey-copy.mdx create mode 100644 api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx create mode 100644 api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx create mode 100644 api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx create mode 100644 api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx create mode 100644 api-reference/rest-apis/v2/workspace/permissionproviderconfig-get.mdx create mode 100644 api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx diff --git a/api-reference/rest-apis/v2/workspace/apikeymetadata-get.mdx b/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx similarity index 59% rename from api-reference/rest-apis/v2/workspace/apikeymetadata-get.mdx rename to api-reference/rest-apis/v2/workspace/activityconfig-get.mdx index 1cbc6d08a..dda7b77c9 100644 --- a/api-reference/rest-apis/v2/workspace/apikeymetadata-get.mdx +++ b/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx @@ -1,9 +1,9 @@ --- -title: "Get API Key Metadata" -api: "POST https://api.velt.dev/v2/workspace/apikeymetadata/get" +title: "Get Activity Config" +api: "POST https://api.velt.dev/v2/workspace/activityconfig/get" --- -Use this API to retrieve metadata associated with a workspace API key. +Use this API to retrieve the current activity logs configuration for a workspace. This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. @@ -11,7 +11,7 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut # Endpoint -`POST https://api.velt.dev/v2/workspace/apikeymetadata/get` +`POST https://api.velt.dev/v2/workspace/activityconfig/get` # Headers @@ -43,13 +43,13 @@ This endpoint does not require a request body. { "result": { "status": "success", - "message": "API key metadata retrieved successfully.", + "message": "Activity logs configuration retrieved successfully.", "data": { - "defaultDocumentAccessType": "public", - "planInfo": { - "type": "sdk test" - }, - "ownerEmail": "owner@example.com" + "activityServiceConfig": { + "isEnabled": false, + "immutable": false, + "triggers": { "comment": { } } + } } } } @@ -71,13 +71,13 @@ This endpoint does not require a request body. { "result": { "status": "success", - "message": "API key metadata retrieved successfully.", + "message": "Activity logs configuration retrieved successfully.", "data": { - "defaultDocumentAccessType": "public", - "planInfo": { - "type": "sdk test" - }, - "ownerEmail": "owner@example.com" + "activityServiceConfig": { + "isEnabled": false, + "immutable": false, + "triggers": { "comment": { } } + } } } } diff --git a/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx b/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx new file mode 100644 index 000000000..54b81129b --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx @@ -0,0 +1,100 @@ +--- +title: "Update Activity Config" +api: "POST https://api.velt.dev/v2/workspace/activityconfig/update" +--- + +Use this API to update the activity logs configuration for a workspace. The `activityServiceConfig` object must contain at least one sub-field. The config is deep-merged with the existing value, so omitted sub-fields are preserved (including `enabledTime` when you omit it). + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/activityconfig/update` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Activity service configuration object. Must contain at least one sub-field. + + + Whether activity logging is enabled. + + + Timestamp (ms) when activity logging was enabled. Preserved when omitted. + + + Whether activity logs are immutable. + + + Event triggers that produce activity logs. Supports the `comment` trigger group — a map of event-type string to a boolean to enable (`true`) or disable (`false`) that trigger. See [Webhooks](/webhooks/advanced) for the full list of event types. + + + + + + +# Example Request + +```JSON +{ + "data": { + "activityServiceConfig": { + "isEnabled": true, + "immutable": false + } + } +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Activity logs configuration updated successfully." + } +} +``` + +#### Failure Response + +##### If activityServiceConfig has no sub-fields + +```JSON +{ + "error": { + "status": "INVALID_ARGUMENT", + "message": "At least one field must be provided for update" + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "Activity logs configuration updated successfully." + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/apikey-copy.mdx b/api-reference/rest-apis/v2/workspace/apikey-copy.mdx new file mode 100644 index 000000000..66ca3456b --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/apikey-copy.mdx @@ -0,0 +1,134 @@ +--- +title: "Copy API Key" +api: "POST https://api.velt.dev/v2/workspace/apikey/copy" +--- + +Use this API to copy the entire configuration from one API key into another. Both the source and (if it already exists) the target API key must belong to the authenticated workspace. If the target does not exist, a new API key document is created with the provided target ID; if it exists and belongs to the same workspace, it is overwritten. + + +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/apikey/copy` + +# Headers + + + Your Workspace ID. + + + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. + + +# Body + +#### Params + + + + + The API key ID to copy data from. Must belong to the authenticated workspace. + + + The API key ID to copy data into. Created if it doesn't exist; overwritten if it exists and belongs to the same workspace. + + + + +# Example Request + +```JSON +{ + "data": { + "sourceApiKey": "velt_api_key_source", + "targetApiKey": "velt_api_key_target" + } +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "API key copied successfully.", + "data": { + "sourceApiKey": "velt_api_key_source", + "targetApiKey": "velt_api_key_target", + "created": true + } + } +} +``` + + +`created` is `true` when the target API key document was newly created, and `false` when an existing document was overwritten. + + +#### Failure Response + +##### If either field is empty + +```JSON +{ + "error": { + "status": "INVALID_ARGUMENT", + "message": "API key ID is required" + } +} +``` + +##### If `sourceApiKey` and `targetApiKey` are the same + +```JSON +{ + "error": { + "status": "INVALID_ARGUMENT", + "message": "sourceApiKey and targetApiKey must be different" + } +} +``` + +##### If the source API key does not exist + +```JSON +{ + "error": { + "status": "NOT_FOUND", + "message": "Source API key not found: velt_api_key_source" + } +} +``` + +##### If the source (or existing target) belongs to a different workspace + +```JSON +{ + "error": { + "status": "PERMISSION_DENIED", + "message": "Source API key does not belong to the authenticated workspace" + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "API key copied successfully.", + "data": { + "sourceApiKey": "velt_api_key_source", + "targetApiKey": "velt_api_key_target", + "created": true + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/apikey-create.mdx b/api-reference/rest-apis/v2/workspace/apikey-create.mdx index 5268d4a0f..0144c81fd 100644 --- a/api-reference/rest-apis/v2/workspace/apikey-create.mdx +++ b/api-reference/rest-apis/v2/workspace/apikey-create.mdx @@ -6,9 +6,13 @@ api: "POST https://api.velt.dev/v2/workspace/apikey/create" Use this API to create a new API key for a workspace. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. + +This API currently supports creating **`testing`** API keys only. + + # Endpoint `POST https://api.velt.dev/v2/workspace/apikey/create` @@ -19,8 +23,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your Workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body @@ -33,7 +37,7 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Email address of the API key owner. - API key type. Accepted values: `"testing"` or `"production"`. + API key type. Currently only `"testing"` is supported. Whether to create an auth token along with the API key. Recommended: `true`. diff --git a/api-reference/rest-apis/v2/workspace/apikey-update.mdx b/api-reference/rest-apis/v2/workspace/apikey-update.mdx index 0c57de38e..84c1b0da8 100644 --- a/api-reference/rest-apis/v2/workspace/apikey-update.mdx +++ b/api-reference/rest-apis/v2/workspace/apikey-update.mdx @@ -6,7 +6,7 @@ api: "POST https://api.velt.dev/v2/workspace/apikey/update" Use this API to update the name of an existing API key. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. # Endpoint @@ -19,8 +19,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your Workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body diff --git a/api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx b/api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx new file mode 100644 index 000000000..ab365a366 --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx @@ -0,0 +1,109 @@ +--- +title: "Get API Key Config" +api: "POST https://api.velt.dev/v2/workspace/apikeyconfig/get" +--- + +Use this API to retrieve the app configuration for a workspace API key: owner email, plan info, default document access type, the private-comments flag, the JWT / auto-org-user toggles, and the configured AI model keys (masked). + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + + +The legacy path `POST https://api.velt.dev/v2/workspace/apikeymetadata/get` is still supported and routes to this same endpoint. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/apikeyconfig/get` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +This endpoint does not require a request body. + +# Example Request + +```JSON +{ + "data": {} +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "API key metadata retrieved successfully.", + "data": { + "ownerEmail": "owner@example.com", + "planInfo": { + "type": "sdk test" + }, + "defaultDocumentAccessType": "public", + "isPrivateCommentsEnabled": false, + "requireJwtToken": false, + "requireAutoOrgUser": false, + "aiModelsConfig": { + "openai": { + "displayText": "sk-...XyZ" + } + } + } + } +} +``` + + +`aiModelsConfig` is a map of `provider -> { displayText }` and is **masked** — the raw or encrypted AI model key is never returned. It is absent when no AI keys are configured. `defaultDocumentAccessType` is one of `public`, `restricted`, or `organizationPrivate` (defaults to `public`). + + +#### Failure Response + +```JSON +{ + "error": { + "status": "PERMISSION_DENIED", + "message": "Invalid API key." + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "API key metadata retrieved successfully.", + "data": { + "ownerEmail": "owner@example.com", + "planInfo": { + "type": "sdk test" + }, + "defaultDocumentAccessType": "public", + "isPrivateCommentsEnabled": false, + "requireJwtToken": false, + "requireAutoOrgUser": false, + "aiModelsConfig": { + "openai": { + "displayText": "sk-...XyZ" + } + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx b/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx new file mode 100644 index 000000000..73dab13e3 --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx @@ -0,0 +1,131 @@ +--- +title: "Update API Key Config" +api: "POST https://api.velt.dev/v2/workspace/apikeyconfig/update" +--- + +Use this API to update the app configuration for a workspace API key. Every field is optional, but **at least one** must be provided. Unknown fields are rejected. All writes are field-merge only — no fields are removed. + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + + +The legacy path `POST https://api.velt.dev/v2/workspace/apikeymetadata/update` is still supported and routes to this same endpoint. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/apikeyconfig/update` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + At least one of the following fields must be provided. + + + Enable (`true`) or disable (`false`) private comments for this API key. + + + When `true`, the SDK requires a signed JWT to authenticate. + + + When `true`, users are auto-added to the organization on first access. + + + Workspace-default document access type. One of `public`, `restricted`, or `organizationPrivate`. + + + AI model provider key. The raw key is encrypted at rest and is never returned in any response. + + + AI provider. One of `openai`, `anthropic`, or `gemini`. + + + The provider API key to store (encrypted). + + + + + + +# Example Request + +```JSON +{ + "data": { + "requireJwtToken": true, + "defaultDocumentAccessType": "restricted" + } +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "API key configuration updated successfully.", + "data": { + "updatedFields": [ + "requireJwtToken", + "defaultDocumentAccessType" + ], + "noop": false, + "requireJwtToken": true, + "defaultDocumentAccessType": "restricted" + } + } +} +``` + + +The response echoes the post-write values for the fields you provided. For `aiModelApiKey`, only `{ provider }` is echoed — the key value is never returned. When `enablePrivateComments` is the only field and its value already matches the current value, the request is a no-op and returns `{ "enablePrivateComments": , "noop": true }`. + + +#### Failure Response + +##### If no field is provided, or an unknown field is sent + +```JSON +{ + "error": { + "status": "INVALID_ARGUMENT", + "message": "At least one field must be provided for update" + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "API key configuration updated successfully.", + "data": { + "updatedFields": [ + "requireJwtToken", + "defaultDocumentAccessType" + ], + "noop": false, + "requireJwtToken": true, + "defaultDocumentAccessType": "restricted" + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/apikeys-get.mdx b/api-reference/rest-apis/v2/workspace/apikeys-get.mdx index 29ed3bdd0..84c69044a 100644 --- a/api-reference/rest-apis/v2/workspace/apikeys-get.mdx +++ b/api-reference/rest-apis/v2/workspace/apikeys-get.mdx @@ -6,7 +6,7 @@ api: "POST https://api.velt.dev/v2/workspace/apikeys/get" Use this API to retrieve a list of API keys for a workspace. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. # Endpoint @@ -19,8 +19,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your Workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body diff --git a/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx b/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx index 221c6e739..6f3645e5f 100644 --- a/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx +++ b/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx @@ -6,7 +6,7 @@ api: "POST https://api.velt.dev/v2/workspace/authtoken/reset" Use this API to reset the auth token for a specific API key. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. # Endpoint @@ -19,8 +19,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your Workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body diff --git a/api-reference/rest-apis/v2/workspace/authtokens-get.mdx b/api-reference/rest-apis/v2/workspace/authtokens-get.mdx index 81a207476..968a8c715 100644 --- a/api-reference/rest-apis/v2/workspace/authtokens-get.mdx +++ b/api-reference/rest-apis/v2/workspace/authtokens-get.mdx @@ -6,7 +6,7 @@ api: "POST https://api.velt.dev/v2/workspace/authtokens/get" Use this API to retrieve all auth tokens associated with a specific API key. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. # Endpoint @@ -19,8 +19,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your Workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body diff --git a/api-reference/rest-apis/v2/workspace/get.mdx b/api-reference/rest-apis/v2/workspace/get.mdx index 4d88d63ae..59af274ad 100644 --- a/api-reference/rest-apis/v2/workspace/get.mdx +++ b/api-reference/rest-apis/v2/workspace/get.mdx @@ -6,7 +6,7 @@ api: "POST https://api.velt.dev/v2/workspace/get" Use this API to retrieve details of an existing Velt workspace. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. # Endpoint @@ -19,8 +19,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body diff --git a/api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx b/api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx new file mode 100644 index 000000000..3f378296f --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx @@ -0,0 +1,99 @@ +--- +title: "Get Notification Config" +api: "POST https://api.velt.dev/v2/workspace/notificationconfig/get" +--- + +Use this API to retrieve the current in-app notification service configuration for a workspace. + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/notificationconfig/get` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +This endpoint does not require a request body. + +# Example Request + +```JSON +{ + "data": {} +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Notification configuration retrieved successfully.", + "data": { + "useNotificationService": false, + "notificationServiceConfig": { + "triggers": { "comment": { }, "huddle": { } }, + "delayConfig": { + "isEnabled": false, + "delaySeconds": 10 + }, + "batchConfig": { + "document": { "isEnabled": false, "batchWindowSeconds": 10, "maxActivities": 2 }, + "user": { "isEnabled": false, "batchWindowSeconds": 10, "maxActivities": 2 } + } + } + } + } +} +``` + +#### Failure Response + +```JSON +{ + "error": { + "status": "PERMISSION_DENIED", + "message": "Invalid API key." + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "Notification configuration retrieved successfully.", + "data": { + "useNotificationService": false, + "notificationServiceConfig": { + "triggers": { "comment": { }, "huddle": { } }, + "delayConfig": { + "isEnabled": false, + "delaySeconds": 10 + }, + "batchConfig": { + "document": { "isEnabled": false, "batchWindowSeconds": 10, "maxActivities": 2 }, + "user": { "isEnabled": false, "batchWindowSeconds": 10, "maxActivities": 2 } + } + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx b/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx new file mode 100644 index 000000000..c6056d469 --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx @@ -0,0 +1,117 @@ +--- +title: "Update Notification Config" +api: "POST https://api.velt.dev/v2/workspace/notificationconfig/update" +--- + +Use this API to update the in-app notification service configuration for a workspace. At least one of `useNotificationService` or `notificationServiceConfig` must be provided. The config is deep-merged with the existing value, so omitted sub-fields are preserved. + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/notificationconfig/update` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Whether to enable the in-app notification service. + + + Notification service configuration object. + + + Event triggers that activate in-app notifications. Supports `comment` and `huddle` trigger groups. Each is a map of event-type string to a boolean to enable (`true`) or disable (`false`) that trigger. See [Webhooks](/webhooks/advanced) for the full list of event types. + + + Notification delay settings. + + + Whether delayed notifications are enabled. + + + Delay before sending a notification, in seconds. + + + + + Notification batching settings, with independent `document` and `user` configs. + + + Per-document batching. `{ isEnabled?: boolean, batchWindowSeconds?: number, maxActivities?: number }`. + + + Per-user batching. `{ isEnabled?: boolean, batchWindowSeconds?: number, maxActivities?: number }`. + + + + + + + + +# Example Request + +```JSON +{ + "data": { + "useNotificationService": true, + "notificationServiceConfig": { + "delayConfig": { + "isEnabled": true, + "delaySeconds": 30 + } + } + } +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Notification configuration updated successfully." + } +} +``` + +#### Failure Response + +```JSON +{ + "error": { + "status": "INVALID_ARGUMENT", + "message": "At least one of useNotificationService or notificationServiceConfig must be provided" + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "Notification configuration updated successfully." + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/permissionproviderconfig-get.mdx b/api-reference/rest-apis/v2/workspace/permissionproviderconfig-get.mdx new file mode 100644 index 000000000..41ee0f636 --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/permissionproviderconfig-get.mdx @@ -0,0 +1,85 @@ +--- +title: "Get Permission Provider Config" +api: "POST https://api.velt.dev/v2/workspace/permissionproviderconfig/get" +--- + +Use this API to retrieve the current permission provider configuration for a workspace. + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/permissionproviderconfig/get` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +This endpoint does not require a request body. + +# Example Request + +```JSON +{ + "data": {} +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Permission provider configuration retrieved successfully.", + "data": { + "usePermissionProvider": false, + "permissionProviderConfig": { + "permissionProviderUrl": "", + "authToken": "" + } + } + } +} +``` + +#### Failure Response + +```JSON +{ + "error": { + "status": "PERMISSION_DENIED", + "message": "Invalid API key." + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "Permission provider configuration retrieved successfully.", + "data": { + "usePermissionProvider": false, + "permissionProviderConfig": { + "permissionProviderUrl": "", + "authToken": "" + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx b/api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx new file mode 100644 index 000000000..4d08e15ad --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx @@ -0,0 +1,98 @@ +--- +title: "Update Permission Provider Config" +api: "POST https://api.velt.dev/v2/workspace/permissionproviderconfig/update" +--- + +Use this API to update the permission provider configuration for a workspace. At least one of `usePermissionProvider` or `permissionProviderConfig` must be provided. The config is merged with the existing value, so e.g. the `authToken` is preserved when only the URL changes. + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/permissionproviderconfig/update` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Whether to enable the permission provider. + + + Permission provider configuration object. + + + Provider URL. Must be an empty string (to clear the value) or a valid `http`/`https` URL. Any other value is rejected. + + + Auth token sent to the permission provider. + + + + + + +# Example Request + +```JSON +{ + "data": { + "usePermissionProvider": true, + "permissionProviderConfig": { + "permissionProviderUrl": "https://example.com/permissions", + "authToken": "provider_auth_token_here" + } + } +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Permission provider configuration updated successfully." + } +} +``` + +#### Failure Response + +##### If permissionProviderUrl is not empty and not a valid http(s) URL + +```JSON +{ + "error": { + "status": "INVALID_ARGUMENT", + "message": "Please enter a valid URL" + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "Permission provider configuration updated successfully." + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/webhookconfig-get.mdx b/api-reference/rest-apis/v2/workspace/webhookconfig-get.mdx index 0318b63d7..34f201bc9 100644 --- a/api-reference/rest-apis/v2/workspace/webhookconfig-get.mdx +++ b/api-reference/rest-apis/v2/workspace/webhookconfig-get.mdx @@ -9,6 +9,10 @@ Use this API to retrieve the current webhook service configuration for a workspa This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + +Currently only supported for Basic Webhooks. + + # Endpoint `POST https://api.velt.dev/v2/workspace/webhookconfig/get` diff --git a/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx b/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx index e4166d54b..e34c9c3ba 100644 --- a/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx @@ -9,6 +9,10 @@ Use this API to update the webhook service configuration for a workspace. At lea This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + +Currently only supported for Basic Webhooks. + + # Endpoint `POST https://api.velt.dev/v2/workspace/webhookconfig/update` diff --git a/docs.json b/docs.json index 76d9acabf..0cf605971 100644 --- a/docs.json +++ b/docs.json @@ -879,7 +879,14 @@ "api-reference/rest-apis/v2/workspace/apikey-create", "api-reference/rest-apis/v2/workspace/apikeys-get", "api-reference/rest-apis/v2/workspace/apikey-update", - "api-reference/rest-apis/v2/workspace/apikeymetadata-get" + "api-reference/rest-apis/v2/workspace/apikey-copy" + ] + }, + { + "group": "API Key Configuration", + "pages": [ + "api-reference/rest-apis/v2/workspace/apikeyconfig-get", + "api-reference/rest-apis/v2/workspace/apikeyconfig-update" ] }, { @@ -910,6 +917,27 @@ "api-reference/rest-apis/v2/workspace/webhookconfig-get", "api-reference/rest-apis/v2/workspace/webhookconfig-update" ] + }, + { + "group": "Activity Configuration", + "pages": [ + "api-reference/rest-apis/v2/workspace/activityconfig-get", + "api-reference/rest-apis/v2/workspace/activityconfig-update" + ] + }, + { + "group": "Notification Configuration", + "pages": [ + "api-reference/rest-apis/v2/workspace/notificationconfig-get", + "api-reference/rest-apis/v2/workspace/notificationconfig-update" + ] + }, + { + "group": "Permission Provider Configuration", + "pages": [ + "api-reference/rest-apis/v2/workspace/permissionproviderconfig-get", + "api-reference/rest-apis/v2/workspace/permissionproviderconfig-update" + ] } ] } From e6726568a285f2ab29e49746d41786d20b27360f Mon Sep 17 00:00:00 2001 From: raghul-velt Date: Thu, 4 Jun 2026 18:00:33 +0530 Subject: [PATCH 3/7] docs: enhance comment annotations and agent configurations in API documentation - Added new parameters for adding comment annotations, including `createOrganization`, `createDocument`, and `agent` block for agent-authored comments. - Updated the `get-comment-annotations-v2` endpoint to include filters for agent annotations and added detailed response structure for agent-related data. - Enhanced the `add-comments` endpoint to support agent replies with a structured `agent` object. - Included default behavior notes for activity logs, email service, notification service, permission provider, and webhook configurations in their respective documentation. - Improved clarity and completeness of existing API documentation. --- .../add-comment-annotations.mdx | 211 ++++++++++++++++++ .../get-comment-annotations-v2.mdx | 66 +++++- .../comments/add-comments.mdx | 103 +++++++++ .../v2/workspace/activityconfig-get.mdx | 4 + .../v2/workspace/activityconfig-update.mdx | 4 + .../v2/workspace/apikeyconfig-update.mdx | 39 ++-- .../v2/workspace/emailconfig-update.mdx | 4 + .../v2/workspace/notificationconfig-get.mdx | 4 + .../workspace/notificationconfig-update.mdx | 39 +++- .../permissionproviderconfig-update.mdx | 4 + .../v2/workspace/webhookconfig-update.mdx | 4 + 11 files changed, 458 insertions(+), 24 deletions(-) diff --git a/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx b/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx index 74af7e1db..e7f357eef 100644 --- a/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx @@ -36,6 +36,14 @@ Use this API to add comment annotations to a document within an organization. Document ID + + If set to true, a new organization will be created (if it doesn't exist) before the annotation is added. + + + + If set to true, a new document will be created (if it doesn't exist) before the annotation is added. + + When enabled, verifies the user has access to the document before creating comment annotations. This ensures annotations respect document access permissions configured via Access Control or Permission Provider. @@ -150,6 +158,71 @@ Use this API to add comment annotations to a document within an organization. + + + Marks this comment as agent-authored (an agent finding or an agent reply). V2 only. When set, the server stamps `sourceType: "agent"` on the comment. When set on the root comment (`commentData[0]`), the server also generates the annotation-level agent block and stamps `sourceType: "agent"` on the annotation. Discriminated on `agentSource`. + + + Origin of the agent. Must be one of: `velt` or `external`. + + + Agent ID. Required when `agentSource` is `velt` (a built-in agent like `spell-check`, or a custom agent ID that is verified server-side). Optional and opaque (never validated) when `agentSource` is `external`. + + + Execution / run ID for this agent invocation. + + + Display name for the agent. Used only when `agentSource` is `external` (for `velt` agents the name is resolved server-side). + + + Page URL associated with the finding. + + + Finding details produced by the agent. Additional custom fields are preserved. + + + Short finding title. + + + Finding description. + + + Severity of the finding. Must be one of: `critical`, `high`, `medium`, `low`, or `info`. + + + Unique identifier for the finding. + + + Type of finding. Must be one of: `text`, `pin`, or `page`. + + + Custom issue classification. + + + Confidence score for the finding. Integer between 0 and 100. + + + Suggested change in plain text. + + + Suggested fix for the finding. + + + Relevant HTML snippet for the finding. + + + CSS/HTML selector pointing to the finding location. + + + Provenance of the rule that triggered the finding. Must be one of: `instructions` or `knowledge`. + + + Knowledge section that triggered the finding. + + + + + @@ -223,6 +296,36 @@ Use this API to add comment annotations to a document within an organization. + + + Annotation kind. Must be one of: `comment` or `suggestion`. This is the source of truth for the suggestion classification; agent-produced findings should set `suggestion`. Defaults to `comment` when omitted. + + + + Caller-driven comment classification. Must be one of: `manual` or `chart`. Defaults to `manual` when omitted. + + + The legacy value `commentType: "suggestion"` is still accepted and preserved for backward compatibility, but it no longer drives the suggestion classification. Use the annotation-level `type: "suggestion"` field instead. + + + + + Controls who can see the annotation. Discriminated on `type`. When omitted, the annotation defaults to `public`. + + + Visibility type. Must be one of: `public`, `organizationPrivate`, or `restricted`. + - `public`: Visible to everyone. + - `organizationPrivate`: Visible only to users in the specified organization. Requires `organizationId`. + - `restricted`: Visible only to the specified users (private comment). Requires `userIds`. + + + Organization ID whose users can see the annotation. Required when `type` is `organizationPrivate`. + + + User IDs allowed to see the annotation. Required (non-empty) when `type` is `restricted`. + + + @@ -393,6 +496,114 @@ When `verifyUserPermissions` is enabled, the API verifies the user has access to } ``` +#### Add an agent suggestion (finding) + +Set `type: "suggestion"` and attach an `agent` block to the root comment (`commentData[0]`). The server generates the annotation-level agent block and stamps `sourceType: "agent"`. + +```JSON +{ + "data": { + "organizationId": "acme-corp", + "documentId": "design-mockup-v2", + "commentAnnotations": [ + { + "type": "suggestion", + "commentData": [ + { + "commentText": "Heading has a spelling mistake: 'Welcom' should be 'Welcome'.", + "from": { + "userId": "spell-check", + "name": "Spell Check Agent" + }, + "agent": { + "agentSource": "velt", + "agentId": "spell-check", + "executionId": "exec_123", + "url": "https://example.com/design-mockup-v2", + "reason": { + "title": "Spelling error", + "description": "The word 'Welcom' is misspelled.", + "severity": "low", + "findingType": "text", + "confidence": 98, + "suggestedFix": "Welcome", + "source": "instructions" + } + } + } + ] + } + ] + } +} +``` + +To attach a finding from an agent run through your own framework, use `agentSource: "external"` and supply your own `agentName` (and optionally `agentId` / `executionId`): + +```JSON +{ + "data": { + "organizationId": "acme-corp", + "documentId": "design-mockup-v2", + "commentAnnotations": [ + { + "type": "suggestion", + "commentData": [ + { + "commentText": "This button has insufficient color contrast.", + "from": { + "userId": "a11y-bot" + }, + "agent": { + "agentSource": "external", + "agentName": "Accessibility Bot", + "agentId": "a11y-bot", + "reason": { + "title": "Low color contrast", + "description": "Contrast ratio is 2.1:1, below the 4.5:1 WCAG AA threshold.", + "severity": "high", + "findingType": "pin" + } + } + } + ] + } + ] + } +} +``` + +#### Add a private (restricted) comment annotation + +Use `visibility` to limit who can see the annotation. + +```JSON +{ + "data": { + "organizationId": "acme-corp", + "documentId": "design-mockup-v2", + "commentAnnotations": [ + { + "visibility": { + "type": "restricted", + "userIds": ["user_sarah_chen", "user_john_smith"] + }, + "commentData": [ + { + "commentText": "Internal note: don't ship this section yet.", + "from": { + "userId": "user_john_smith", + "name": "John Smith", + "email": "john.smith@acme-corp.com" + } + } + ] + } + ] + } +} +``` + # Response #### Success Response diff --git a/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx b/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx index 844940725..d1bf2ff09 100644 --- a/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx @@ -65,9 +65,49 @@ Prior to using this API, you must: Array of User IDs. Limit: Only 30 IDs can be passed at a time. - {/* - Order of results based on `lastUpdated` timestamp. Options: `asc` or `desc`. Default: `desc`. - */} + + Array of User IDs. Filters annotations that mention (tag) any of these users. + + + + Filter annotations resolved by the given user ID. + + + + Filter to agent annotations created by the given agent ID. + + + + Filter to agent annotations from the given agent execution / run ID. + + + + Filter to agent annotations of the given agent type. Must be one of: `built-in`, `custom`, or `external`. + + + + Filter to agent annotations from the given source. Must be one of: `velt` or `external`. + + + + When true, returns only fresh (unaccepted) agent suggestions. + + + + When true, returns all agent annotations regardless of status. + + + + Raw agent-field token filter (advanced). Prefer the friendly agent filters above. + + + + Only one agent filter (`agentId`, `executionId`, `agentType`, `agentSource`, `agentSuggestions`, `agentComments`, or `agentFields`) may be supplied per request. + + + + Order of results based on `lastUpdated` timestamp. Must be one of: `asc` or `desc`. Default: `desc`. + Status IDs of the annotations to filter on. @@ -243,6 +283,19 @@ Prior to using this API, you must: ``` +#### 10. Get agent annotations by organizationId, documentId, and agentId + +```JSON +{ + "data": { + "organizationId": "yourOrganizationId", + "documentId": "yourDocumentId", + "agentId": "spell-check" + } +} +``` + +Agent annotations in the response carry `type: "suggestion"`, `sourceType: "agent"`, and an `agent` block (see Response Field Notes below). # Response @@ -252,7 +305,12 @@ Prior to using this API, you must: - `reactionAnnotations`: Array of full reaction annotation objects attached to a comment. Each reaction includes the `icon`, `fromUsers` (the users who reacted), `location`, `locationId`, `commentAnnotationId`, `context`, `type`, `annotationId`, and `lastUpdated`. - `viewedBy`: This field is not currently returned by this endpoint. - `createdAt` and `lastUpdated`: Timestamps are returned in milliseconds since epoch for annotations and reactions, and in ISO 8601 format for comments. -- `context.access` / `context.accessFields`: Access control metadata for the annotation (e.g. `{ "default": "velt" }`). +- `type`: Annotation kind, either `comment` (a regular collaboration comment) or `suggestion` (an agent-produced finding). +- `sourceType`: How the annotation/comment was created. `rest-api` for annotations created via this REST API, or `agent` for agent-authored annotations and comments. +- `agent`: Present on agent-authored annotations and comments. Contains `agentId`, `agentType` (`built-in` / `custom` / `external`), `agentSource` (`velt` / `external`), `executionId`, `agentName`, `url`, and the `reason` finding object (`title`, `description`, `severity`, `findingType`, etc.). The annotation-level `agent` block additionally carries `agentFields` (the filter tokens used by the agent GET filters); the per-comment `agent` block omits `agentFields`. +- `suggestion`: Lifecycle object present only when `type` is `suggestion`, e.g. `{ "status": "pending" }`. `status` is one of `pending`, `accepted`, or `rejected`. +- `visibilityConfig`: Visibility of the annotation, e.g. `{ "type": "public" }`. `type` is one of `public`, `organizationPrivate`, or `restricted`. +- `context.access` / `context.accessFields`: Access control metadata for the annotation (e.g. `{ "default": "velt" }`). When `visibility` is set on creation, the resolved access tokens appear in `context.accessFields`. - `hasDraftComments`: Boolean indicating whether the annotation has any draft comments. diff --git a/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx b/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx index 1ffe9b203..1cef87f59 100644 --- a/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx @@ -148,6 +148,71 @@ Use this API to add comments within a specific CommentAnnotation. + + Marks this comment as an agent-authored reply. V2 only. When set, the server stamps `sourceType: "agent"` on the comment. Discriminated on `agentSource`. + + + Origin of the agent. Must be one of: `velt` or `external`. + + + Agent ID. Required when `agentSource` is `velt` (a built-in agent like `spell-check`, or a custom agent ID that is verified server-side). Optional and opaque (never validated) when `agentSource` is `external`. + + + Execution / run ID for this agent invocation. + + + Display name for the agent. Used only when `agentSource` is `external` (for `velt` agents the name is resolved server-side). + + + Page URL associated with the finding. + + + Finding details produced by the agent. Additional custom fields are preserved. + + + Short finding title. + + + Finding description. + + + Severity of the finding. Must be one of: `critical`, `high`, `medium`, `low`, or `info`. + + + Unique identifier for the finding. + + + Type of finding. Must be one of: `text`, `pin`, or `page`. + + + Custom issue classification. + + + Confidence score for the finding. Integer between 0 and 100. + + + Suggested change in plain text. + + + Suggested fix for the finding. + + + Relevant HTML snippet for the finding. + + + CSS/HTML selector pointing to the finding location. + + + Provenance of the rule that triggered the finding. Must be one of: `instructions` or `knowledge`. + + + Knowledge section that triggered the finding. + + + + + + @@ -156,6 +221,10 @@ Use this API to add comments within a specific CommentAnnotation. ## **Example Requests** + +This endpoint adds comments (including agent replies) to an existing CommentAnnotation. Annotation-level fields such as `type` (`comment` / `suggestion`) and `visibility` are set when the annotation is created or updated via the [Add Comment Annotations](/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations) and Update Comment Annotations APIs — they are not accepted on this endpoint. + + #### 1. Add comment in a CommentAnnotation by organizationId, documentId, and annotationId ```JSON @@ -245,6 +314,40 @@ When `verifyUserPermissions` is enabled, the API verifies the user has access to } ``` +#### 4. Add an agent reply + +Attach an `agent` block to mark the comment as agent-authored. The server stamps `sourceType: "agent"` on the comment. + +```JSON +{ + "data": { + "organizationId": "yourOrganizationId", + "documentId": "yourDocumentId", + "annotationId": "yourAnnotationId", + "commentData": [ + { + "commentText": "I fixed the spelling. Please re-review.", + "from": { + "userId": "spell-check", + "name": "Spell Check Agent" + }, + "agent": { + "agentSource": "velt", + "agentId": "spell-check", + "executionId": "exec_124", + "reason": { + "title": "Spelling corrected", + "description": "Updated 'Welcom' to 'Welcome'.", + "severity": "info", + "findingType": "text" + } + } + } + ] + } +} +``` + # Response #### Success Response diff --git a/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx b/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx index dda7b77c9..fd725f77b 100644 --- a/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx +++ b/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx @@ -37,6 +37,10 @@ This endpoint does not require a request body. # Example Response + +If a workspace has never configured activity logs, `activityServiceConfig` defaults to `{ "isEnabled": false }` (default-disabled). + + #### Success Response ```JSON diff --git a/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx b/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx index 54b81129b..48ff4b124 100644 --- a/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx @@ -9,6 +9,10 @@ Use this API to update the activity logs configuration for a workspace. The `act This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + +**Defaults on first enable.** If you enable activity logs (`activityServiceConfig.isEnabled: true`) and no `activityServiceConfig` exists yet, defaults are seeded automatically: the standard `comment` triggers are turned on, `immutable` is set to `true`, and `enabledTime` is stamped with the current timestamp when you don't provide one. Any values you send in the same request (including `immutable: false` or your own `enabledTime`) are merged on top of these defaults. + + # Endpoint `POST https://api.velt.dev/v2/workspace/activityconfig/update` diff --git a/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx b/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx index 73dab13e3..509fc6e46 100644 --- a/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx @@ -46,9 +46,9 @@ The legacy path `POST https://api.velt.dev/v2/workspace/apikeymetadata/update` i Workspace-default document access type. One of `public`, `restricted`, or `organizationPrivate`. - - AI model provider key. The raw key is encrypted at rest and is never returned in any response. - + + Array of AI model provider keys — pass multiple entries to update several providers in one call. Each raw key is encrypted at rest and is never returned in any response. Must contain at least one entry. + AI provider. One of `openai`, `anthropic`, or `gemini`. @@ -66,7 +66,12 @@ The legacy path `POST https://api.velt.dev/v2/workspace/apikeymetadata/update` i { "data": { "requireJwtToken": true, - "defaultDocumentAccessType": "restricted" + "defaultDocumentAccessType": "restricted", + "aiModelApiKey": [ + { "provider": "openai", "customerApiKey": "sk-openai-..." }, + { "provider": "anthropic", "customerApiKey": "sk-ant-..." }, + { "provider": "gemini", "customerApiKey": "AIza..." } + ] } } ``` @@ -81,20 +86,20 @@ The legacy path `POST https://api.velt.dev/v2/workspace/apikeymetadata/update` i "status": "success", "message": "API key configuration updated successfully.", "data": { - "updatedFields": [ - "requireJwtToken", - "defaultDocumentAccessType" - ], - "noop": false, "requireJwtToken": true, - "defaultDocumentAccessType": "restricted" + "defaultDocumentAccessType": "restricted", + "aiModelsConfig": { + "openai": { "displayText": "sk-open...xxxxxxxxxxxxxxxxxxxxxxx" }, + "anthropic": { "displayText": "sk-ant-...xxxxxxxxxxxxxxxxxxxxx" }, + "gemini": { "displayText": "AIza...xxxxxxxxxxxxxxxxxxxxxxxxx" } + } } } } ``` -The response echoes the post-write values for the fields you provided. For `aiModelApiKey`, only `{ provider }` is echoed — the key value is never returned. When `enablePrivateComments` is the only field and its value already matches the current value, the request is a no-op and returns `{ "enablePrivateComments": , "noop": true }`. +The response echoes the post-write values for the fields you provided. For `aiModelApiKey`, the keys come back masked under `aiModelsConfig` as a map of `provider -> { displayText }` (the same shape as [Get API Key Config](/api-reference/rest-apis/v2/workspace/apikeyconfig-get)) — the raw key value is never returned. When `enablePrivateComments` is the only field and its value already matches the current value, the write is skipped internally and the response is simply `{ "enablePrivateComments": }`. #### Failure Response @@ -117,13 +122,13 @@ The response echoes the post-write values for the fields you provided. For `aiMo "status": "success", "message": "API key configuration updated successfully.", "data": { - "updatedFields": [ - "requireJwtToken", - "defaultDocumentAccessType" - ], - "noop": false, "requireJwtToken": true, - "defaultDocumentAccessType": "restricted" + "defaultDocumentAccessType": "restricted", + "aiModelsConfig": { + "openai": { "displayText": "sk-open...xxxxxxxxxxxxxxxxxxxxxxx" }, + "anthropic": { "displayText": "sk-ant-...xxxxxxxxxxxxxxxxxxxxx" }, + "gemini": { "displayText": "AIza...xxxxxxxxxxxxxxxxxxxxxxxxx" } + } } } } diff --git a/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx b/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx index 75ade3105..cbf9fbb7b 100644 --- a/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx @@ -9,6 +9,10 @@ Use this API to update the email service configuration for a workspace. At least This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + +**Defaults on first enable.** If you enable the service — either with `useEmailService: true` or by sending `emailServiceConfig.type: "custom"` — and no `emailServiceConfig` exists yet, defaults are seeded automatically: the service is marked as a custom provider (`type: "custom"`), the standard `comment` triggers and all `huddle` triggers are turned on, and `useEmailService` is set to `true`. Any `emailServiceConfig` values you send in the same request are merged on top of these defaults. + + # Endpoint `POST https://api.velt.dev/v2/workspace/emailconfig/update` diff --git a/api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx b/api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx index 3f378296f..762cb568c 100644 --- a/api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx +++ b/api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx @@ -9,6 +9,10 @@ Use this API to retrieve the current in-app notification service configuration f This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + +The numeric `delayConfig` / `batchConfig` fields returned here are constrained to these ranges when set via [Update Notification Config](/api-reference/rest-apis/v2/workspace/notificationconfig-update): `delaySeconds` `10`–`15552000` (6 months), `batchWindowSeconds` `10`–`604800` (1 week), `maxActivities` `2`–`50`. + + # Endpoint `POST https://api.velt.dev/v2/workspace/notificationconfig/get` diff --git a/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx b/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx index c6056d469..fbc5bf615 100644 --- a/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx @@ -9,6 +9,17 @@ Use this API to update the in-app notification service configuration for a works This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + +The numeric delay/batching fields must be integers within these ranges, otherwise the request is rejected with `INVALID_ARGUMENT`: +- `delayConfig.delaySeconds`: `10`–`15552000` (10 seconds to 6 months) +- `batchConfig.document.batchWindowSeconds` / `batchConfig.user.batchWindowSeconds`: `10`–`604800` (10 seconds to 1 week) +- `batchConfig.document.maxActivities` / `batchConfig.user.maxActivities`: `2`–`50` + + + +**Defaults on first enable.** If you enable the service (`useNotificationService: true`) and no `notificationServiceConfig` exists yet, a default set of triggers is seeded automatically: the standard `comment` triggers and all `huddle` triggers are turned on. Delay and batching stay off — no `delayConfig` or `batchConfig` is written. Any `notificationServiceConfig` values you send in the same request are merged on top of these defaults. + + # Endpoint `POST https://api.velt.dev/v2/workspace/notificationconfig/update` @@ -45,7 +56,7 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut Whether delayed notifications are enabled. - Delay before sending a notification, in seconds. + Delay before sending a notification, in seconds. Must be an integer between `10` and `15552000` (10 seconds to 6 months). @@ -53,10 +64,32 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut Notification batching settings, with independent `document` and `user` configs. - Per-document batching. `{ isEnabled?: boolean, batchWindowSeconds?: number, maxActivities?: number }`. + Per-document batching. + + + Whether document-level batching is enabled. + + + Time window to group document-level notifications, in seconds. Must be an integer between `10` and `604800` (10 seconds to 1 week). + + + Flush the batch once this many activities accumulate. Must be an integer between `2` and `50`. + + - Per-user batching. `{ isEnabled?: boolean, batchWindowSeconds?: number, maxActivities?: number }`. + Per-user batching. + + + Whether user-level batching is enabled. + + + Time window to group user-level notifications, in seconds. Must be an integer between `10` and `604800` (10 seconds to 1 week). + + + Flush the batch once this many activities accumulate. Must be an integer between `2` and `50`. + + diff --git a/api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx b/api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx index 4d08e15ad..3e9da9e70 100644 --- a/api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx @@ -9,6 +9,10 @@ Use this API to update the permission provider configuration for a workspace. At This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + +**Defaults on first enable.** If you enable the provider (`usePermissionProvider: true`) and no `permissionProviderConfig` exists yet, an empty config is seeded (`permissionProviderUrl` and `authToken` set to empty strings) and returned in the response `data`. Any `permissionProviderConfig` values you send in the same request are merged on top. + + # Endpoint `POST https://api.velt.dev/v2/workspace/permissionproviderconfig/update` diff --git a/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx b/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx index e34c9c3ba..9192c5af8 100644 --- a/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx @@ -13,6 +13,10 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut Currently only supported for Basic Webhooks. + +**Defaults on first enable.** If you enable the service (`useWebhookService: true`) and no `webhookServiceConfig` exists yet, defaults are seeded automatically: all `comment` triggers and all `huddle` triggers are turned on, the `crdt` and `recorder` triggers are off, and `enableDataProtection` is `false`. Any `webhookServiceConfig` values you send in the same request are merged on top of these defaults. + + # Endpoint `POST https://api.velt.dev/v2/workspace/webhookconfig/update` From 00d5f15812bc06ab79192035ad5a7482bd919a48 Mon Sep 17 00:00:00 2001 From: raghul-velt Date: Thu, 4 Jun 2026 19:22:26 +0530 Subject: [PATCH 4/7] docs: update comment annotations and webhook configurations in API documentation - Clarified the structure of agent annotations in the `get-comment-annotations-v2` response, specifying the location of the `agent` block. - Added details about opt-in triggers for suggestion accept/reject events in the `activityconfig-update` and `webhookconfig-update` documentation. - Enhanced clarity regarding default settings for webhook configurations and activity log triggers. --- .../comment-annotations/get-comment-annotations-v2.mdx | 4 ++-- .../rest-apis/v2/workspace/activityconfig-update.mdx | 2 +- .../rest-apis/v2/workspace/webhookconfig-update.mdx | 8 +++++++- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx b/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx index d1bf2ff09..a54cc033e 100644 --- a/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx @@ -295,7 +295,7 @@ Prior to using this API, you must: } ``` -Agent annotations in the response carry `type: "suggestion"`, `sourceType: "agent"`, and an `agent` block (see Response Field Notes below). +Agent annotations in the response carry `type: "suggestion"` and `sourceType: "agent"` at the annotation root, and the `agent` block on the agent-authored comment (`comments[].agent`) — there is no annotation-root `agent` object in the response (see Response Field Notes below). # Response @@ -307,7 +307,7 @@ Agent annotations in the response carry `type: "suggestion"`, `sourceType: "agen - `createdAt` and `lastUpdated`: Timestamps are returned in milliseconds since epoch for annotations and reactions, and in ISO 8601 format for comments. - `type`: Annotation kind, either `comment` (a regular collaboration comment) or `suggestion` (an agent-produced finding). - `sourceType`: How the annotation/comment was created. `rest-api` for annotations created via this REST API, or `agent` for agent-authored annotations and comments. -- `agent`: Present on agent-authored annotations and comments. Contains `agentId`, `agentType` (`built-in` / `custom` / `external`), `agentSource` (`velt` / `external`), `executionId`, `agentName`, `url`, and the `reason` finding object (`title`, `description`, `severity`, `findingType`, etc.). The annotation-level `agent` block additionally carries `agentFields` (the filter tokens used by the agent GET filters); the per-comment `agent` block omits `agentFields`. +- `agent`: Present only on agent-authored **comments** (`comments[].agent`) — the response does not include an `agent` object at the annotation root. Contains `agentId`, `agentType` (`built-in` / `custom` / `external`), `agentSource` (`velt` / `external`), `executionId`, `agentName`, `url`, and the `reason` finding object (`title`, `description`, `severity`, `findingType`, etc.). The internal `agentFields` filter tokens are not returned. - `suggestion`: Lifecycle object present only when `type` is `suggestion`, e.g. `{ "status": "pending" }`. `status` is one of `pending`, `accepted`, or `rejected`. - `visibilityConfig`: Visibility of the annotation, e.g. `{ "type": "public" }`. `type` is one of `public`, `organizationPrivate`, or `restricted`. - `context.access` / `context.accessFields`: Access control metadata for the annotation (e.g. `{ "default": "velt" }`). When `visibility` is set on creation, the resolved access tokens appear in `context.accessFields`. diff --git a/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx b/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx index 48ff4b124..a2c75c741 100644 --- a/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx @@ -46,7 +46,7 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut Whether activity logs are immutable. - Event triggers that produce activity logs. Supports the `comment` trigger group — a map of event-type string to a boolean to enable (`true`) or disable (`false`) that trigger. See [Webhooks](/webhooks/advanced) for the full list of event types. + Event triggers that produce activity logs. Supports the `comment` trigger group — a map of event-type string to a boolean to enable (`true`) or disable (`false`) that trigger. See [Webhooks](/webhooks/advanced) for the full list of event types. The `comment_annotation.suggestion_accept` / `comment_annotation.suggestion_reject` triggers are opt-in (disabled by default) — enable them explicitly to log suggestion accept/reject events. diff --git a/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx b/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx index 9192c5af8..2877d4bc9 100644 --- a/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx @@ -14,7 +14,7 @@ Currently only supported for Basic Webhooks. -**Defaults on first enable.** If you enable the service (`useWebhookService: true`) and no `webhookServiceConfig` exists yet, defaults are seeded automatically: all `comment` triggers and all `huddle` triggers are turned on, the `crdt` and `recorder` triggers are off, and `enableDataProtection` is `false`. Any `webhookServiceConfig` values you send in the same request are merged on top of these defaults. +**Defaults on first enable.** If you enable the service (`useWebhookService: true`) and no `webhookServiceConfig` exists yet, defaults are seeded automatically: the standard `comment` triggers and all `huddle` triggers are turned on, the `crdt` and `recorder` triggers are off, and `enableDataProtection` is `false`. The opt-in `suggestion_accept` / `suggestion_reject` comment triggers stay off until you enable them explicitly. Any `webhookServiceConfig` values you send in the same request are merged on top of these defaults. # Endpoint @@ -85,6 +85,12 @@ Currently only supported for Basic Webhooks. Trigger when a thread's priority changes. + + Trigger when a suggestion is accepted. Opt-in: disabled by default, enable it explicitly to receive this event. + + + Trigger when a suggestion is rejected. Opt-in: disabled by default, enable it explicitly to receive this event. + Trigger when a reaction is added to a comment. From 866eca0402679d538c5abeed49982457f4be97f3 Mon Sep 17 00:00:00 2001 From: raghul-velt Date: Thu, 4 Jun 2026 20:51:50 +0530 Subject: [PATCH 5/7] docs: clarify agent annotations structure in get-comment-annotations-v2 response - Updated the description of agent annotations to specify the presence of the `agent` block at both the annotation root and within agent-authored comments. - Clarified that the internal `agentFields` filter tokens are omitted from both `agent` blocks in the response. --- .../get-comment-annotations-v2.mdx | 4 +- .../rest-apis/v2/workspace/apikey-copy.mdx | 134 ------------------ docs.json | 3 +- 3 files changed, 3 insertions(+), 138 deletions(-) delete mode 100644 api-reference/rest-apis/v2/workspace/apikey-copy.mdx diff --git a/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx b/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx index a54cc033e..e5b6f2167 100644 --- a/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx @@ -295,7 +295,7 @@ Prior to using this API, you must: } ``` -Agent annotations in the response carry `type: "suggestion"` and `sourceType: "agent"` at the annotation root, and the `agent` block on the agent-authored comment (`comments[].agent`) — there is no annotation-root `agent` object in the response (see Response Field Notes below). +Agent annotations in the response carry `type: "suggestion"` and `sourceType: "agent"` at the annotation root, the annotation-root `agent` block, and the `agent` block on the agent-authored comment (`comments[].agent`). Both `agent` blocks are returned lean — only the internal `agentFields` filter tokens are omitted (see Response Field Notes below). # Response @@ -307,7 +307,7 @@ Agent annotations in the response carry `type: "suggestion"` and `sourceType: "a - `createdAt` and `lastUpdated`: Timestamps are returned in milliseconds since epoch for annotations and reactions, and in ISO 8601 format for comments. - `type`: Annotation kind, either `comment` (a regular collaboration comment) or `suggestion` (an agent-produced finding). - `sourceType`: How the annotation/comment was created. `rest-api` for annotations created via this REST API, or `agent` for agent-authored annotations and comments. -- `agent`: Present only on agent-authored **comments** (`comments[].agent`) — the response does not include an `agent` object at the annotation root. Contains `agentId`, `agentType` (`built-in` / `custom` / `external`), `agentSource` (`velt` / `external`), `executionId`, `agentName`, `url`, and the `reason` finding object (`title`, `description`, `severity`, `findingType`, etc.). The internal `agentFields` filter tokens are not returned. +- `agent`: Returned at the annotation root (for agent-authored annotations) and on each agent-authored **comment** (`comments[].agent`). Contains `agentId`, `agentType` (`built-in` / `custom` / `external`), `agentSource` (`velt` / `external`), `executionId`, `agentName`, `url`, and the `reason` finding object (`title`, `description`, `severity`, `findingType`, etc.). The internal `agentFields` filter tokens are not returned on either block. - `suggestion`: Lifecycle object present only when `type` is `suggestion`, e.g. `{ "status": "pending" }`. `status` is one of `pending`, `accepted`, or `rejected`. - `visibilityConfig`: Visibility of the annotation, e.g. `{ "type": "public" }`. `type` is one of `public`, `organizationPrivate`, or `restricted`. - `context.access` / `context.accessFields`: Access control metadata for the annotation (e.g. `{ "default": "velt" }`). When `visibility` is set on creation, the resolved access tokens appear in `context.accessFields`. diff --git a/api-reference/rest-apis/v2/workspace/apikey-copy.mdx b/api-reference/rest-apis/v2/workspace/apikey-copy.mdx deleted file mode 100644 index 66ca3456b..000000000 --- a/api-reference/rest-apis/v2/workspace/apikey-copy.mdx +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: "Copy API Key" -api: "POST https://api.velt.dev/v2/workspace/apikey/copy" ---- - -Use this API to copy the entire configuration from one API key into another. Both the source and (if it already exists) the target API key must belong to the authenticated workspace. If the target does not exist, a new API key document is created with the provided target ID; if it exists and belongs to the same workspace, it is overwritten. - - -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. - - -# Endpoint - -`POST https://api.velt.dev/v2/workspace/apikey/copy` - -# Headers - - - Your Workspace ID. - - - - Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. - - -# Body - -#### Params - - - - - The API key ID to copy data from. Must belong to the authenticated workspace. - - - The API key ID to copy data into. Created if it doesn't exist; overwritten if it exists and belongs to the same workspace. - - - - -# Example Request - -```JSON -{ - "data": { - "sourceApiKey": "velt_api_key_source", - "targetApiKey": "velt_api_key_target" - } -} -``` - -# Example Response - -#### Success Response - -```JSON -{ - "result": { - "status": "success", - "message": "API key copied successfully.", - "data": { - "sourceApiKey": "velt_api_key_source", - "targetApiKey": "velt_api_key_target", - "created": true - } - } -} -``` - - -`created` is `true` when the target API key document was newly created, and `false` when an existing document was overwritten. - - -#### Failure Response - -##### If either field is empty - -```JSON -{ - "error": { - "status": "INVALID_ARGUMENT", - "message": "API key ID is required" - } -} -``` - -##### If `sourceApiKey` and `targetApiKey` are the same - -```JSON -{ - "error": { - "status": "INVALID_ARGUMENT", - "message": "sourceApiKey and targetApiKey must be different" - } -} -``` - -##### If the source API key does not exist - -```JSON -{ - "error": { - "status": "NOT_FOUND", - "message": "Source API key not found: velt_api_key_source" - } -} -``` - -##### If the source (or existing target) belongs to a different workspace - -```JSON -{ - "error": { - "status": "PERMISSION_DENIED", - "message": "Source API key does not belong to the authenticated workspace" - } -} -``` - - -```js -{ - "result": { - "status": "success", - "message": "API key copied successfully.", - "data": { - "sourceApiKey": "velt_api_key_source", - "targetApiKey": "velt_api_key_target", - "created": true - } - } -} -``` - diff --git a/docs.json b/docs.json index 0cf605971..28cb96924 100644 --- a/docs.json +++ b/docs.json @@ -878,8 +878,7 @@ "pages": [ "api-reference/rest-apis/v2/workspace/apikey-create", "api-reference/rest-apis/v2/workspace/apikeys-get", - "api-reference/rest-apis/v2/workspace/apikey-update", - "api-reference/rest-apis/v2/workspace/apikey-copy" + "api-reference/rest-apis/v2/workspace/apikey-update" ] }, { From 09f967f94a3428794eeb1ac84fa7e7f5b77b1aef Mon Sep 17 00:00:00 2001 From: raghul-velt Date: Thu, 4 Jun 2026 22:12:43 +0530 Subject: [PATCH 6/7] docs: update activity, email, notification, and webhook configuration documentation - Enhanced the default behavior notes for activity logs, email service, notification service, and webhook configurations to clarify trigger settings and merging behavior. - Updated response structures to reflect the latest post-write state for activity, email, notification, and webhook configurations. - Improved clarity regarding the presence of default triggers and the merging of user-specified values in the respective configurations. --- .../v2/workspace/activityconfig-get.mdx | 4 +-- .../v2/workspace/activityconfig-update.mdx | 26 ++++++++++++++--- .../v2/workspace/emailconfig-update.mdx | 26 +++++++++++++++-- .../workspace/notificationconfig-update.mdx | 28 +++++++++++++++++-- .../v2/workspace/webhookconfig-update.mdx | 24 ++++++++++++++-- 5 files changed, 93 insertions(+), 15 deletions(-) diff --git a/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx b/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx index fd725f77b..30d0629e6 100644 --- a/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx +++ b/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx @@ -52,7 +52,7 @@ If a workspace has never configured activity logs, `activityServiceConfig` defau "activityServiceConfig": { "isEnabled": false, "immutable": false, - "triggers": { "comment": { } } + "triggers": { "comment": { "added" : true } } } } } @@ -80,7 +80,7 @@ If a workspace has never configured activity logs, `activityServiceConfig` defau "activityServiceConfig": { "isEnabled": false, "immutable": false, - "triggers": { "comment": { } } + "triggers": { "comment": { "added" : true } } } } } diff --git a/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx b/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx index a2c75c741..0c2a21623 100644 --- a/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx @@ -10,7 +10,11 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut -**Defaults on first enable.** If you enable activity logs (`activityServiceConfig.isEnabled: true`) and no `activityServiceConfig` exists yet, defaults are seeded automatically: the standard `comment` triggers are turned on, `immutable` is set to `true`, and `enabledTime` is stamped with the current timestamp when you don't provide one. Any values you send in the same request (including `immutable: false` or your own `enabledTime`) are merged on top of these defaults. +**Defaults on first enable.** If you enable activity logs (`activityServiceConfig.isEnabled: true`) and no `activityServiceConfig` exists yet, defaults are seeded automatically: the standard `comment` triggers are turned on (including the `comment_annotation.suggestion_accept` / `comment_annotation.suggestion_reject` triggers, which are active by default for activity logs), `immutable` is set to `true`, and `enabledTime` is stamped with the current timestamp when you don't provide one. Any values you send in the same request (including `immutable: false` or your own `enabledTime`) are merged on top of these defaults. + + + +The response `data` echoes the latest post-write state as `{ activityServiceConfig }` — the same shape returned by [Get Activity Config](/api-reference/rest-apis/v2/workspace/activityconfig-get), including any seeded defaults. `isEnabled` is always present (defaults to `false` when neither your request nor the stored config sets it). # Endpoint @@ -46,7 +50,7 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut Whether activity logs are immutable. - Event triggers that produce activity logs. Supports the `comment` trigger group — a map of event-type string to a boolean to enable (`true`) or disable (`false`) that trigger. See [Webhooks](/webhooks/advanced) for the full list of event types. The `comment_annotation.suggestion_accept` / `comment_annotation.suggestion_reject` triggers are opt-in (disabled by default) — enable them explicitly to log suggestion accept/reject events. + Event triggers that produce activity logs. Supports the `comment` trigger group — a map of event-type string to a boolean to enable (`true`) or disable (`false`) that trigger. See [Webhooks](/webhooks/advanced) for the full list of event types. The `comment_annotation.suggestion_accept` / `comment_annotation.suggestion_reject` triggers are active by default for activity logs — set them to `false` to stop logging suggestion accept/reject events. @@ -74,7 +78,14 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut { "result": { "status": "success", - "message": "Activity logs configuration updated successfully." + "message": "Activity logs configuration updated successfully.", + "data": { + "activityServiceConfig": { + "isEnabled": true, + "immutable": false, + "enabledTime": 1717520000000 + } + } } } ``` @@ -97,7 +108,14 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut { "result": { "status": "success", - "message": "Activity logs configuration updated successfully." + "message": "Activity logs configuration updated successfully.", + "data": { + "activityServiceConfig": { + "isEnabled": true, + "immutable": false, + "enabledTime": 1717520000000 + } + } } } ``` diff --git a/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx b/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx index cbf9fbb7b..329a51b7b 100644 --- a/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx @@ -10,7 +10,11 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut -**Defaults on first enable.** If you enable the service — either with `useEmailService: true` or by sending `emailServiceConfig.type: "custom"` — and no `emailServiceConfig` exists yet, defaults are seeded automatically: the service is marked as a custom provider (`type: "custom"`), the standard `comment` triggers and all `huddle` triggers are turned on, and `useEmailService` is set to `true`. Any `emailServiceConfig` values you send in the same request are merged on top of these defaults. +**Defaults on first enable.** If you enable the service — either with `useEmailService: true` or by sending `emailServiceConfig.type: "custom"` — and the stored config has no `triggers` yet (defaults are seeded even if `type` / SendGrid fields already exist), defaults are seeded automatically: the service is marked as a custom provider (`type: "custom"`), the standard `comment` triggers and all `huddle` triggers are turned on, and `useEmailService` is set to `true`. Existing non-trigger fields are preserved, and any `emailServiceConfig` values you send in the same request are merged on top of these defaults. + + + +The response `data` echoes the latest post-write state as `{ useEmailService, emailServiceConfig }` — the same shape returned by [Get Email Config](/api-reference/rest-apis/v2/workspace/emailconfig-get). Fields not part of your request fall back to the existing stored values. # Endpoint @@ -101,7 +105,15 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut "result": { "status": "success", "message": "Email configuration updated successfully.", - "data": null + "data": { + "useEmailService": true, + "emailServiceConfig": { + "type": "sendgrid", + "apiKey": "SG.xxxxxxxxxx", + "fromEmail": "noreply@example.com", + "fromCompany": "Example Corp" + } + } } } ``` @@ -123,7 +135,15 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut "result": { "status": "success", "message": "Email configuration updated successfully.", - "data": null + "data": { + "useEmailService": true, + "emailServiceConfig": { + "type": "sendgrid", + "apiKey": "SG.xxxxxxxxxx", + "fromEmail": "noreply@example.com", + "fromCompany": "Example Corp" + } + } } } ``` diff --git a/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx b/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx index fbc5bf615..b4f345e5e 100644 --- a/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx @@ -17,7 +17,11 @@ The numeric delay/batching fields must be integers within these ranges, otherwis -**Defaults on first enable.** If you enable the service (`useNotificationService: true`) and no `notificationServiceConfig` exists yet, a default set of triggers is seeded automatically: the standard `comment` triggers and all `huddle` triggers are turned on. Delay and batching stay off — no `delayConfig` or `batchConfig` is written. Any `notificationServiceConfig` values you send in the same request are merged on top of these defaults. +**Defaults on first enable.** If you enable the service (`useNotificationService: true`) and the stored config has no `triggers` yet (defaults are seeded even if `delayConfig` / `batchConfig` already exist), a default set of triggers is seeded automatically: the standard `comment` triggers and all `huddle` triggers are turned on. Delay and batching stay off — no `delayConfig` or `batchConfig` is written by the seeding. Existing non-trigger fields are preserved, and any `notificationServiceConfig` values you send in the same request are merged on top of these defaults. + + + +The response `data` echoes the latest post-write state as `{ useNotificationService, notificationServiceConfig }` — the same shape returned by [Get Notification Config](/api-reference/rest-apis/v2/workspace/notificationconfig-get). Fields not part of your request fall back to the existing stored values. # Endpoint @@ -122,7 +126,16 @@ The numeric delay/batching fields must be integers within these ranges, otherwis { "result": { "status": "success", - "message": "Notification configuration updated successfully." + "message": "Notification configuration updated successfully.", + "data": { + "useNotificationService": true, + "notificationServiceConfig": { + "delayConfig": { + "isEnabled": true, + "delaySeconds": 30 + } + } + } } } ``` @@ -143,7 +156,16 @@ The numeric delay/batching fields must be integers within these ranges, otherwis { "result": { "status": "success", - "message": "Notification configuration updated successfully." + "message": "Notification configuration updated successfully.", + "data": { + "useNotificationService": true, + "notificationServiceConfig": { + "delayConfig": { + "isEnabled": true, + "delaySeconds": 30 + } + } + } } } ``` diff --git a/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx b/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx index 2877d4bc9..e14349c86 100644 --- a/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx @@ -14,7 +14,11 @@ Currently only supported for Basic Webhooks. -**Defaults on first enable.** If you enable the service (`useWebhookService: true`) and no `webhookServiceConfig` exists yet, defaults are seeded automatically: the standard `comment` triggers and all `huddle` triggers are turned on, the `crdt` and `recorder` triggers are off, and `enableDataProtection` is `false`. The opt-in `suggestion_accept` / `suggestion_reject` comment triggers stay off until you enable them explicitly. Any `webhookServiceConfig` values you send in the same request are merged on top of these defaults. +**Defaults on first enable.** If you enable the service (`useWebhookService: true`) and the stored config has no `triggers` yet (defaults are seeded even if `authToken` / URLs already exist), defaults are seeded automatically: the standard `comment` triggers and all `huddle` triggers are turned on, the `crdt` and `recorder` triggers are off, and `enableDataProtection` is `false`. The opt-in `suggestion_accept` / `suggestion_reject` comment triggers stay off until you enable them explicitly. Existing non-trigger fields are preserved, and any `webhookServiceConfig` values you send in the same request are merged on top of these defaults. + + + +The response `data` echoes the latest post-write state as `{ useWebhookService, webhookServiceConfig }` — the same shape returned by [Get Webhook Config](/api-reference/rest-apis/v2/workspace/webhookconfig-get). Fields not part of your request fall back to the existing stored values. # Endpoint @@ -128,7 +132,14 @@ Currently only supported for Basic Webhooks. "result": { "status": "success", "message": "Webhook configuration updated successfully.", - "data": null + "data": { + "useWebhookService": true, + "webhookServiceConfig": { + "authToken": "webhook_auth_token_here", + "rawNotificationUrl": "https://example.com/webhooks/raw", + "processedNotificationUrl": "https://example.com/webhooks/processed" + } + } } } ``` @@ -150,7 +161,14 @@ Currently only supported for Basic Webhooks. "result": { "status": "success", "message": "Webhook configuration updated successfully.", - "data": null + "data": { + "useWebhookService": true, + "webhookServiceConfig": { + "authToken": "webhook_auth_token_here", + "rawNotificationUrl": "https://example.com/webhooks/raw", + "processedNotificationUrl": "https://example.com/webhooks/processed" + } + } } } ``` From c2db9b457b8f3bfdbbabae4932f1dbff52625aef Mon Sep 17 00:00:00 2001 From: raghul-velt Date: Thu, 4 Jun 2026 23:25:54 +0530 Subject: [PATCH 7/7] docs: clarify agent name requirements in comment annotations - Updated the documentation for `add-comment-annotations` and `add-comments` to specify that the agent name is **required** when the `agentSource` is `external`, emphasizing its role as the source of truth for external agents. - Removed the `agentFields` parameter from the `get-comment-annotations-v2` documentation to streamline the agent filter options. --- .../comment-annotations/add-comment-annotations.mdx | 2 +- .../comment-annotations/get-comment-annotations-v2.mdx | 6 +----- .../rest-apis/v2/comments-feature/comments/add-comments.mdx | 2 +- 3 files changed, 3 insertions(+), 7 deletions(-) diff --git a/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx b/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx index e7f357eef..bd8d35908 100644 --- a/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx @@ -172,7 +172,7 @@ Use this API to add comment annotations to a document within an organization. Execution / run ID for this agent invocation. - Display name for the agent. Used only when `agentSource` is `external` (for `velt` agents the name is resolved server-side). + Display name for the agent. **Required when `agentSource` is `external`** (the only source of truth for an external agent's name). Not used for `velt` agents (their name is resolved server-side). Page URL associated with the finding. diff --git a/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx b/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx index e5b6f2167..02eb683af 100644 --- a/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx @@ -97,12 +97,8 @@ Prior to using this API, you must: When true, returns all agent annotations regardless of status. - - Raw agent-field token filter (advanced). Prefer the friendly agent filters above. - - - Only one agent filter (`agentId`, `executionId`, `agentType`, `agentSource`, `agentSuggestions`, `agentComments`, or `agentFields`) may be supplied per request. + Only one agent filter (`agentId`, `executionId`, `agentType`, `agentSource`, `agentSuggestions`, or `agentComments`) may be supplied per request. diff --git a/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx b/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx index 1cef87f59..60e6c8ae8 100644 --- a/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx @@ -161,7 +161,7 @@ Use this API to add comments within a specific CommentAnnotation. Execution / run ID for this agent invocation. - Display name for the agent. Used only when `agentSource` is `external` (for `velt` agents the name is resolved server-side). + Display name for the agent. **Required when `agentSource` is `external`** (the only source of truth for an external agent's name). Not used for `velt` agents (their name is resolved server-side). Page URL associated with the finding.