Extract Agents from File
curl --request POST \
--url https://api.velt.dev/v2/agents/extract \
--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": {
"fileBase64": "<string>",
"mimeType": "<string>",
"provider": "<string>",
"fileName": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/extract"
payload = { "data": {
"fileBase64": "<string>",
"mimeType": "<string>",
"provider": "<string>",
"fileName": "<string>"
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
fileBase64: '<string>',
mimeType: '<string>',
provider: '<string>',
fileName: '<string>'
}
})
};
fetch('https://api.velt.dev/v2/agents/extract', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.velt.dev/v2/agents/extract",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'fileBase64' => '<string>',
'mimeType' => '<string>',
'provider' => '<string>',
'fileName' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.velt.dev/v2/agents/extract"
payload := strings.NewReader("{\n \"data\": {\n \"fileBase64\": \"<string>\",\n \"mimeType\": \"<string>\",\n \"provider\": \"<string>\",\n \"fileName\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/agents/extract")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"fileBase64\": \"<string>\",\n \"mimeType\": \"<string>\",\n \"provider\": \"<string>\",\n \"fileName\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/extract")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"fileBase64\": \"<string>\",\n \"mimeType\": \"<string>\",\n \"provider\": \"<string>\",\n \"fileName\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Agents parsed successfully",
"data": {
"extractionResult": {
"agents": [],
"summary": "Extracted 0 agents",
"skipped": [],
"totalTasksParsed": 0,
"memory": { "sourceId": "src_8f2b1c94" }
}
}
}
}
Agents
Extract Agents from File
POST
/
v2
/
agents
/
extract
Extract Agents from File
curl --request POST \
--url https://api.velt.dev/v2/agents/extract \
--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": {
"fileBase64": "<string>",
"mimeType": "<string>",
"provider": "<string>",
"fileName": "<string>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/extract"
payload = { "data": {
"fileBase64": "<string>",
"mimeType": "<string>",
"provider": "<string>",
"fileName": "<string>"
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
fileBase64: '<string>',
mimeType: '<string>',
provider: '<string>',
fileName: '<string>'
}
})
};
fetch('https://api.velt.dev/v2/agents/extract', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.velt.dev/v2/agents/extract",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'fileBase64' => '<string>',
'mimeType' => '<string>',
'provider' => '<string>',
'fileName' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.velt.dev/v2/agents/extract"
payload := strings.NewReader("{\n \"data\": {\n \"fileBase64\": \"<string>\",\n \"mimeType\": \"<string>\",\n \"provider\": \"<string>\",\n \"fileName\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/agents/extract")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"fileBase64\": \"<string>\",\n \"mimeType\": \"<string>\",\n \"provider\": \"<string>\",\n \"fileName\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/extract")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"fileBase64\": \"<string>\",\n \"mimeType\": \"<string>\",\n \"provider\": \"<string>\",\n \"fileName\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Agents parsed successfully",
"data": {
"extractionResult": {
"agents": [],
"summary": "Extracted 0 agents",
"skipped": [],
"totalTasksParsed": 0,
"memory": { "sourceId": "src_8f2b1c94" }
}
}
}
}
Use this API to extract agent definitions from an uploaded file. An LLM parses the file and returns a list of draft agent definitions: a name, a description, and a consolidated QA
Extracted agent fields (
Errors:
prompt for each.
Map prompt onto the instructions field of Create Agent and supply the remaining config blocks yourself. Extraction does not produce contextGathering or execution config; use Resolve Config to derive those from the extracted prompt.
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
string
required
Your API key.
string
required
Your Auth Token.
Body
Params
object
required
Show properties
Show properties
string
required
Min 1 char. Base64-encoded file content.
string
required
Min 1 char. MIME type of the uploaded file (e.g.
"text/csv", "application/pdf", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet").string
LLM provider override:
"gemini", "claude", or "openai". Any other value is accepted by the request schema but then fails the call with INTERNAL. Omit the field to use the platform default.string
Optional original file name. Forwarded to the ingest pipeline for provenance/traceability.
Example Requests
1. Extract from a CSV checklist
{
"data": {
"fileBase64": "QWdlbnQgTmFtZSxEZXNjcmlwdGlvbixJbnN0cnVjdGlvbnMK...",
"mimeType": "text/csv",
"fileName": "qa-checklist.csv"
}
}
2. Extract from a PDF checklist
{
"data": {
"fileBase64": "JVBERi0xLjcKJeLjz9MK...",
"mimeType": "application/pdf"
}
}
Response
Success Response
{
"result": {
"status": "success",
"message": "Agents parsed successfully",
"data": {
"extractionResult": {
"agents": [
{
"name": "Brand Color Check",
"description": "Verify all CTAs use the primary brand color",
"prompt": "Check that every <a class='cta'> element uses the primary brand color {{brandColor}}. Report any CTA rendered in a different color.",
"sourceTasks": [
"All CTAs must use the primary brand color",
"Secondary buttons must not use the CTA color"
],
"userContextFields": [
{
"id": "brandColor",
"title": "Primary brand color",
"type": "string",
"example": "#1A73E8"
}
]
},
{
"name": "Heading Font Check",
"description": "Verify all headings use the brand font",
"prompt": "Check that every <h1>, <h2>, and <h3> element uses font-family 'Inter'.",
"sourceTasks": ["Headings use Inter"]
}
],
"summary": "Extracted 2 agents from CSV file",
"skipped": [
{
"originalText": "Make the page feel premium",
"reason": "Too subjective to express as a checkable rule."
}
],
"totalTasksParsed": 4,
"memory": { "sourceId": "src_8f2b1c94" }
}
}
}
}
| Field | Type | Description |
|---|---|---|
data.extractionResult.agents | object[] | Draft agent definitions. See the field table below. |
data.extractionResult.summary | string | Human-readable summary of the extraction. |
data.extractionResult.skipped | object[] | Entries the engine could not turn into agents. Each is { originalText, reason }. |
data.extractionResult.totalTasksParsed | number | Total individual checks identified in the file, before grouping into agents or skipping. Optional: omitted when the extraction model does not report it. |
data.extractionResult.memory | object | { sourceId }. Always present on a successful extraction. Every uploaded file is persisted as a workspace knowledge source, and sourceId identifies it. |
agents[]):
| Field | Type | Description |
|---|---|---|
name | string | Short, descriptive agent name. Maps to name on Create Agent. |
description | string | One-sentence description of what the agent checks. Maps to description. |
prompt | string | Consolidated QA instruction covering every check grouped into this agent. Maps to instructions. |
sourceTasks | string[] | The original task texts from the uploaded file that were grouped into this agent. Provenance only; not sent to Create Agent. |
userContextFields | object[] | Values the agent needs before it can run, each { id, title, type, example? }. Maps to input.userContextFields. |
Extraction returns at most 50 agents per file. Anything beyond that is dropped from
agents[], and totalTasksParsed still reflects the full count found in the file.Failure Response
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
INVALID_ARGUMENT: missing, empty, or whitespace-onlyfileBase64; missing or emptymimeType; an unsupported MIME type; or a file whose decoded size exceeds 5 MB.INTERNAL: the ingest pipeline failed to process the file, or it produced no readable content.DEADLINE_EXCEEDED: the ingest pipeline did not finish within the processing budget.UNAVAILABLE: the ingest queue is temporarily unavailable. Retry the request.
{
"result": {
"status": "success",
"message": "Agents parsed successfully",
"data": {
"extractionResult": {
"agents": [],
"summary": "Extracted 0 agents",
"skipped": [],
"totalTasksParsed": 0,
"memory": { "sourceId": "src_8f2b1c94" }
}
}
}
}
Was this page helpful?
⌘I

