> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract Agents from File

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 `prompt` for each.

Map `prompt` onto the `instructions` field of [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md) and supply the remaining config blocks yourself. Extraction does not produce `contextGathering` or `execution` config; use [Resolve Config](https://velt.dev/docs/api-reference/rest-apis/v2/agents/config/resolve.md) 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

**x-velt-api-key** `string` *required*

Your API key.

**x-velt-auth-token** `string` *required*

Your [Auth Token](https://velt.dev/docs/security/auth-tokens.md).

# Body

#### Params

**data** `object` *required*

**properties**

**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"`, `"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.

**fileName** `string`

Optional original file name. Forwarded to the ingest pipeline for provenance/traceability.

## **Example Requests**

#### 1. Extract from a CSV checklist

```JSON theme={null}
{
  "data": {
    "fileBase64": "QWdlbnQgTmFtZSxEZXNjcmlwdGlvbixJbnN0cnVjdGlvbnMK...",
    "mimeType": "text/csv",
    "fileName": "qa-checklist.csv"
  }
}
```

#### 2. Extract from a PDF checklist

```JSON theme={null}
{
  "data": {
    "fileBase64": "JVBERi0xLjcKJeLjz9MK...",
    "mimeType": "application/pdf"
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "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. |

**Extracted agent fields (`agents[]`):**

| Field | Type | Description |
| - | - | - |
| `name` | string | Short, descriptive agent name. Maps to `name` on [Create Agent](https://velt.dev/docs/api-reference/rest-apis/v2/agents/create.md). |
| `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`. |

> [!NOTE]
>
> 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

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

**Errors:**

* `INVALID_ARGUMENT`: missing, empty, or whitespace-only `fileBase64`; missing or empty `mimeType`; 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.

```js theme={null}
{
  "result": {
    "status": "success",
    "message": "Agents parsed successfully",
    "data": {
      "extractionResult": {
        "agents": [],
        "summary": "Extracted 0 agents",
        "skipped": [],
        "totalTasksParsed": 0,
        "memory": { "sourceId": "src_8f2b1c94" }
      }
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.