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

# Suggest Fields

> Analyzes an image or text description and suggests fields for extraction

The `/agents/suggest-fields` endpoint analyzes an image and/or text description and suggests appropriate fields for extraction based on the provided content.

## Request

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

<ParamField body="image_url" type="string">
  The URL of the image to analyze. The URL must be publicly accessible.

  **Supported formats**: PNG, JPEG, GIF, WebP, TIFF, BMP, ICO, SVG, EPS, TGA\
  **Maximum file size**: 10MB
</ParamField>

<ParamField body="text_description" type="string">
  A text description of the data you want to extract. For example, "Plant disease detection with severity levels and affected area percentage."
</ParamField>

<ParamField body="with_metadata" type="boolean">
  Whether to include metadata generation (title, description, category, tags) in addition to fields. Defaults to `false`.

  When set to `true`, the response will include a `metadata` object with comprehensive template information that can be used for template creation and organization.
</ParamField>

<Note>
  At least one of `image_url` or `text_description` must be provided. For best results, provide both.
</Note>

## Response

<ResponseField name="template_name" type="string">
  A suggested name for the template based on the image content.
</ResponseField>

<ResponseField name="template" type="array">
  An array of suggested fields for extraction.

  <Expandable title="Template field structure">
    <ResponseField name="name" type="string">
      The name of the field.
    </ResponseField>

    <ResponseField name="description" type="string">
      A description of the field.
    </ResponseField>

    <ResponseField name="required" type="boolean">
      Whether the field is required.
    </ResponseField>

    <ResponseField name="type" type="string">
      The data type of the field. Possible values include: "string", "number", "date", "object", "boolean".
    </ResponseField>

    <ResponseField name="subfields" type="array">
      Nested fields for complex data structures. Each subfield follows the same structure as a top-level field.
    </ResponseField>

    <ResponseField name="return_as_list" type="boolean">
      Whether the field should be returned as a list. Set to true for fields that contain multiple items (like multiple objects detected in an image).
    </ResponseField>

    <ResponseField name="enum_values" type="array">
      Possible values for enum fields. Used when the field should only contain specific values.
    </ResponseField>

    <ResponseField name="value" type="any">
      The extracted value (null in the suggest-fields response). This field is included for consistency with the extract-values response.
    </ResponseField>

    <ResponseField name="include_extraction_output" type="boolean">
      For image fields: whether to include other extracted field values as context for image generation.
    </ResponseField>

    <ResponseField name="enable_reference_image" type="boolean">
      For image fields: whether reference image upload is enabled.
    </ResponseField>

    <ResponseField name="reference_image_url" type="string">
      For image fields: URL of the reference image to guide generation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Template metadata including title, description, category, and tags. Only present when `with_metadata` is set to `true`.

  <Expandable title="Metadata structure">
    <ResponseField name="title" type="string">
      A descriptive title for the extraction template.
    </ResponseField>

    <ResponseField name="description" type="string">
      A detailed description of what this template extracts.
    </ResponseField>

    <ResponseField name="category" type="string">
      The category this template belongs to (e.g., 'Agriculture', 'Medical Imaging', 'Quality Control', etc.).
    </ResponseField>

    <ResponseField name="tags" type="array">
      A list of relevant tags for this template.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Example Request with Image URL

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.vizapi.ai/v1/agents/suggest-fields \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "image_url": "https://example.com/plant-leaf.jpg"
    }'
  ```

  ```javascript Node.js theme={null}
  const fetch = require('node-fetch');

  async function suggestFields() {
    const response = await fetch('https://api.vizapi.ai/v1/agents/suggest-fields', {
      method: 'POST',
      headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        image_url: 'https://example.com/plant-leaf.jpg'
      })
    });
    
    const data = await response.json();
    console.log(data);
  }

  suggestFields();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.vizapi.ai/v1/agents/suggest-fields"
  headers = {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "image_url": "https://example.com/plant-leaf.jpg"
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```
</CodeGroup>

### Example Request with Text Description

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.vizapi.ai/v1/agents/suggest-fields \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations"
    }'
  ```

  ```javascript Node.js theme={null}
  const fetch = require('node-fetch');

  async function suggestFields() {
    const response = await fetch('https://api.vizapi.ai/v1/agents/suggest-fields', {
      method: 'POST',
      headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        text_description: 'Plant disease detection with severity levels, affected area percentage, and treatment recommendations'
      })
    });
    
    const data = await response.json();
    console.log(data);
  }

  suggestFields();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.vizapi.ai/v1/agents/suggest-fields"
  headers = {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations"
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```
</CodeGroup>

### Example Request with Both Inputs

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.vizapi.ai/v1/agents/suggest-fields \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "image_url": "https://example.com/plant-leaf.jpg",
      "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations"
    }'
  ```

  ```javascript Node.js theme={null}
  const fetch = require('node-fetch');

  async function suggestFields() {
    const response = await fetch('https://api.vizapi.ai/v1/agents/suggest-fields', {
      method: 'POST',
      headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        image_url: 'https://example.com/plant-leaf.jpg',
        text_description: 'Plant disease detection with severity levels, affected area percentage, and treatment recommendations'
      })
    });
    
    const data = await response.json();
    console.log(data);
  }

  suggestFields();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.vizapi.ai/v1/agents/suggest-fields"
  headers = {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "image_url": "https://example.com/plant-leaf.jpg",
      "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations"
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```
</CodeGroup>

### Example Request with Metadata Generation

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.vizapi.ai/v1/agents/suggest-fields \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "image_url": "https://example.com/plant-leaf.jpg",
      "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations",
      "with_metadata": true
    }'
  ```

  ```javascript Node.js theme={null}
  const fetch = require('node-fetch');

  async function suggestFieldsWithMetadata() {
    const response = await fetch('https://api.vizapi.ai/v1/agents/suggest-fields', {
      method: 'POST',
      headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        image_url: 'https://example.com/plant-leaf.jpg',
        text_description: 'Plant disease detection with severity levels, affected area percentage, and treatment recommendations',
        with_metadata: true
      })
    });
    
    const data = await response.json();
    console.log(data);
  }

  suggestFieldsWithMetadata();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.vizapi.ai/v1/agents/suggest-fields"
  headers = {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "image_url": "https://example.com/plant-leaf.jpg",
      "text_description": "Plant disease detection with severity levels, affected area percentage, and treatment recommendations",
      "with_metadata": True
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(data)
  ```
</CodeGroup>

### Example Response (without metadata)

```json theme={null}
{
  "template_name": "Plant Disease Detector",
  "template": [
    {
      "name": "plant_species",
      "description": "The species of plant being analyzed",
      "required": true,
      "type": "string",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "name": "disease_detected",
      "description": "Whether disease is present in the plant",
      "required": true,
      "type": "boolean",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "name": "disease_type",
      "description": "The type of disease detected",
      "required": false,
      "type": "string",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "name": "severity_level",
      "description": "The severity level of the detected disease",
      "required": false,
      "type": "string",
      "subfields": [],
      "return_as_list": false,
      "enum_values": ["mild", "moderate", "severe"],
      "value": null
    },
    {
      "name": "affected_area_percentage",
      "description": "Percentage of plant area affected by disease",
      "required": false,
      "type": "number",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "name": "treatment_recommendations",
      "description": "Recommended treatments for the detected disease",
      "required": false,
      "type": "string",
      "subfields": [],
      "return_as_list": true,
      "enum_values": [],
      "value": null
    }
  ]
}
```

### Example Response (with metadata)

```json theme={null}
{
  "template_name": "Plant Disease Analysis System",
  "template": [
    {
      "name": "plant_species",
      "description": "The species of plant being analyzed",
      "required": true,
      "type": "string",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "name": "disease_detected",
      "description": "Whether disease is present in the plant",
      "required": true,
      "type": "boolean",
      "subfields": [],
      "return_as_list": false,
      "enum_values": [],
      "value": null
    },
    {
      "name": "severity_level",
      "description": "The severity level of the detected disease",
      "required": false,
      "type": "string",
      "subfields": [],
      "return_as_list": false,
      "enum_values": ["mild", "moderate", "severe"],
      "value": null
    }
  ],
  "metadata": {
    "title": "Advanced Plant Disease Analysis System",
    "description": "Comprehensive plant health assessment including disease detection, severity classification, and treatment recommendations for agricultural and horticultural applications.",
    "category": "Agriculture",
    "tags": ["plant-health", "disease-detection", "agriculture", "crop-monitoring", "precision-farming"]
  }
}
```

## Error Codes

| Status Code | Description                                                                                                                 |
| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| 400         | Bad Request - The request was malformed, missing required parameters, unsupported image format, or image exceeds 10MB limit |
| 401         | Unauthorized - Invalid or missing API key                                                                                   |
| 500         | Internal Server Error - An unexpected error occurred on our servers                                                         |