Skip to main content
POST
/
v2
/
agents
/
create
Create Agent
curl --request POST \
  --url https://api.velt.dev/v2/agents/create \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "name": "<string>",
    "description": "<string>",
    "rawInstructions": "<string>",
    "instructions": "<string>",
    "enabled": true,
    "metadata": {},
    "contextGathering": {},
    "execution": {},
    "response": {},
    "postProcess": {},
    "input": {},
    "scope": {},
    "setup": {}
  }
}
'
{
  "result": {
    "status": "success",
    "message": "Agent created successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://velt-raghul-agent-docs.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

​
x-velt-api-key
string
required
Your API key.
​
x-velt-auth-token
string
required
Your Auth Token.

​
Body

​
Params

​
data
object
required

​
Response Descriptions

All fields are optional strings that instruct the AI on how to populate each finding field:
FieldDescription
summarySummary text of the overall analysis.
titleShort title of the finding.
descriptionDetailed description of the finding.
severitySeverity level. Values: critical, high, medium, low, info.
targetTextThe exact text on the page this finding refers to.
suggestionSuggested fix or recommendation.
isPageLeveltrue for visual/layout findings; false when targetText is real DOM text.
htmlSelectorCSS selector of the DOM element.
issueTypeIssue type for match-and-merge keying (short, lowercase, hyphenated).
confidenceConfidence score from 0 to 100.
findingTypeFinding type classification.

​
Example Requests

​
1. Minimal agent

{
  "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

{
  "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

{
  "result": {
    "status": "success",
    "message": "Agent created successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}
FieldTypeDescription
data.agentIdstringFirestore document ID of the new agent

​
Failure Response

{
  "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). 
{
  "result": {
    "status": "success",
    "message": "Agent created successfully",
    "data": {
      "agentId": "abc123def456"
    }
  }
}