> ## 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](/docs/api-reference/rest-apis/v2/agents/create) and supply the remaining config blocks yourself. Extraction does not produce `contextGathering` or `execution` config; use [Resolve Config](/docs/api-reference/rest-apis/v2/agents/config/resolve) 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

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/docs/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="fileBase64" type="string" required>
      Min 1 char. Base64-encoded file content.
    </ParamField>

    <ParamField body="mimeType" type="string" required>
      Min 1 char. MIME type of the uploaded file (e.g. `"text/csv"`, `"application/pdf"`, `"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"`).
    </ParamField>

    <ParamField body="provider" type="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.
    </ParamField>

    <ParamField body="fileName" type="string">
      Optional original file name. Forwarded to the ingest pipeline for provenance/traceability.
    </ParamField>
  </Expandable>
</ParamField>

## **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](/docs/api-reference/rest-apis/v2/agents/create).                  |
| `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.
</Note>

#### 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.

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