Extract Agents from File

POST /v2/agents/extract

Extract Agents from File

cURL

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>"
  }
}
'

{
  "result": {
    "status": "success",
    "message": "Agents extracted successfully",
    "data": {
      "extractionResult": {
        "agents": [],
        "summary": "Extracted 0 agents",
        "skipped": []
      }
    }
  }
}

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.

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

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Show properties

fileBase64 · string · required

Min 1 char. Base64-encoded file content.

mimeType · string · required

Min 1 char. MIME type of the uploaded file (e.g. "text/csv", "application/pdf", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet").

provider · string

LLM provider override: "gemini" or "claude".

Example Requests

1. Extract from a CSV checklist

{
  "data": {
    "fileBase64": "QWdlbnQgTmFtZSxEZXNjcmlwdGlvbixJbnN0cnVjdGlvbnMK...",
    "mimeType": "text/csv"
  }
}

2. Extract from a PDF checklist

{
  "data": {
    "fileBase64": "JVBERi0xLjcKJeLjz9MK...",
    "mimeType": "application/pdf"
  }
}

Response

Success Response

{
  "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 <a class='cta'> 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 <h1>, <h2>, and <h3> 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.
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

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

Errors: INVALID_ARGUMENT (missing or empty fileBase64 / mimeType, or unsupported MIME type).

{
  "result": {
    "status": "success",
    "message": "Agents extracted successfully",
    "data": {
      "extractionResult": {
        "agents": [],
        "summary": "Extracted 0 agents",
        "skipped": []
      }
    }
  }
}