Questionnaire Generation

Overview

The Questionnaire Generation endpoint analyzes an uploaded document and extracts all possible questions using AI. It identifies questions, question types, context, and example answers from the document, returning a structured questionnaire ready for answering.

Use this endpoint to:

Extract questions from documents, surveys, and questionnaires
Automatically generate questionnaires from any document
Identify question types (factual, MCQ, open-ended)
Extract example answers and multiple-choice options
Build intelligent questionnaire processing workflows

Endpoint Details

Method: POST
Endpoint: /api/agent/questionnaire/generate
Base URL: https://api.k-v.ai
Authentication: Access Key (Required)

Request Specification

Headers

Header	Type	Required	Description
access-key	string	Yes	Your unique access-key generated from the platform UI
Content-Type	string	Yes	Must be application/json

Request Body

{
    "doc_process_id": "264dfa262b748d15ccbeaada89430c68",
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
}

Body Fields

Field	Type	Required	Description
doc_process_id	string	Yes	Document ID to extract questionnaire from (obtained from Upload or List Documents APIs)
model_data	object	Yes	AI model configuration
model_data.model_name	string	Yes	AI model to use for questionnaire extraction (see supported models below)
model_data.api_key	string	No	Your own LLM API key (leave empty to use platform's default keys)

Supported AI Models

Model Name	Provider
gpt-5.1	OpenAI
gpt-5-mini	OpenAI
claude-sonnet-4-5-20250929	Anthropic
gemini/gemini-2.5-flash-lite	Google
gemini/gemini-2.5-pro	Google
gemini/gemini-3-pro-preview	Google
mistral/mistral-small-latest	Mistral AI
mistral/mistral-medium-latest	Mistral AI
llama3.1-70b	Meta

Using Your Own LLM API Keys

Platform Keys (Default)

{
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
}

Your Own Keys

{
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": "sk-your-openai-api-key-here"
    }
}

Response Specification

Success Response (200 OK)

{
    "data": {
        "document_id": "Settlement Agreement (1).pdf",
        "questionnaire": [
            {
                "question": "What is the name of the agreement entered into between ABC Software Corporation and Widget Corporation?",
                "type": "factual",
                "options": null,
                "example": "Settlement Agreement and Release",
                "user_value": {
                    "source": null,
                    "possible_value": null
                }
            },
            {
                "question": "Does the Plaintiff's release in this Agreement cover past, present, or future claims related to the faxed advertisement?",
                "type": "mcq",
                "options": [
                    "Only past claims",
                    "Only present claims",
                    "Only future claims",
                    "Past, present, and future claims"
                ],
                "example": "Past, present, and future claims",
                "user_value": {
                    "source": null,
                    "possible_value": null
                }
            },
            {
                "question": "What is the primary purpose of this Settlement Agreement as described in the recitals?",
                "type": "open-ended",
                "options": null,
                "example": "To provide for certain payments in full settlement and discharge of all claims relating to the faxed advertisement, under the terms and conditions set forth in the Agreement.",
                "user_value": {
                    "source": null,
                    "possible_value": null
                }
            }
        ]
    },
    "message": "Questionnaire created successfully"
}

Response Fields

Field	Type	Description
data	object	Response data object
data.document_id	string	Original document filename
data.questionnaire	array	Array of question objects extracted from the document
data.questionnaire[].question	string	The extracted question text
data.questionnaire[].type	string	Question type: factual, mcq (multiple choice), or open-ended
data.questionnaire[].options	array/null	Available options for mcq type questions, null for other types
data.questionnaire[].example	string	Example answer extracted from the document
data.questionnaire[].user_value	object	User value object (empty in generation, filled during questionnaire filling)
data.questionnaire[].user_value.source	string/null	Source document for the answer (null in generation)
data.questionnaire[].user_value.possible_value	any/null	Extracted answer value (null in generation)
message	string	Human-readable response message

Understanding user_value Structure

In the Questionnaire Generation response, user_value is always empty:

{
    "user_value": {
        "source": null,        // Will be filled during Questionnaire Filling
        "possible_value": null // Will be filled during Questionnaire Filling
    }
}

This structure will be populated when using the Questionnaire Filling API.

Error Responses

401 Unauthorized

{
    "data": {},
    "message": "Invalid or missing access key"
}

Cause: Missing or invalid access-key header.

422 Unprocessable Entity - Invalid Model Name

{
    "detail": [
        {
            "type": "literal_error",
            "loc": [
                "body",
                "model_data",
                "model_name"
            ],
            "msg": "Input should be 'gpt-5-chat-latest', 'gpt-5.1', 'gpt-5-mini', 'claude-sonnet-4-5-20250929', 'gemini/gemini-2.5-flash-lite', 'mistral/mistral-small-latest', 'mistral/mistral-medium-latest', 'gemini/gemini-2.5-pro', 'gemini/gemini-3-pro-preview' or 'llama3.1-70b'",
            "input": "",
            "ctx": {
                "expected": "'gpt-5-chat-latest', 'gpt-5.1', 'gpt-5-mini', 'claude-sonnet-4-5-20250929', 'gemini/gemini-2.5-flash-lite', 'mistral/mistral-small-latest', 'mistral/mistral-medium-latest', 'gemini/gemini-2.5-pro', 'gemini/gemini-3-pro-preview' or 'llama3.1-70b'"
            }
        }
    ]
}

Cause: Invalid or unsupported model_name in model_data. See supported models list above.

400 Bad Request - Invalid Document IDs

{
    "data": {},
    "message": "Invalid docs selected"
}

Causes:

Missing or invalid doc_process_ids.

500 Internal Server Error - Invalid LLM API Key

{
    "data": {},
    "message": "litellm.AuthenticationError: AuthenticationError: OpenAIException - Incorrect API key provided: tyrdfuih**uhf7. You can find your API key at https://platform.openai.com/account/api-keys."
}

Cause: The api_key provided in model_data is invalid or expired. Verify your LLM provider API key.

500 Internal Server Error - General Error

{
    "data": {},
    "message": "Something went wrong"
}

Causes:

LLM service temporarily unavailable
Server-side processing error

Code Snippets

curl --location 'https://api.k-v.ai/api/agent/questionnaire/generate' \
--header 'access-key: YOUR_ACCESS_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "doc_process_id": "264dfa262b748d15ccbeaada89430c68",
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
}'

import requests
import json

url = "https://api.k-v.ai/api/agent/questionnaire/generate"

payload = json.dumps({
    "doc_process_id": "264dfa262b748d15ccbeaada89430c68",
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
})

headers = {
    'access-key': 'YOUR_ACCESS_KEY',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)

print(response.text)

const axios = require('axios');

let data = JSON.stringify({
    "doc_process_id": "264dfa262b748d15ccbeaada89430c68",
    "model_data": {
        "model_name": "gpt-5.1",
        "api_key": ""
    }
});

let config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://api.k-v.ai/api/agent/questionnaire/generate',
    headers: { 
        'access-key': 'YOUR_ACCESS_KEY',
        'Content-Type': 'application/json'
    },
    data: data
};

axios.request(config)
.then((response) => {
    console.log(JSON.stringify(response.data, null, 2));
})
.catch((error) => {
    console.log(error);
});

Important Notes

Document Processing: Only extract questionnaires from documents with status: "processed" from List Documents API
Question Detection: The AI automatically identifies all questions and their types
Empty user_value: In the generation response, user_value.source and user_value.possible_value are always null
Preserve Structure: Save the complete questionnaire JSON for use with the Questionnaire Filling API
Example Answers: The example field contains answers extracted from the source document

Next Steps

After generating a questionnaire:

Review Questions: Examine all extracted questions and their types
Check Options: For MCQ questions, verify the extracted options
Save Structure: Store the questionnaire JSON for reuse
Prepare Source Documents: Upload documents containing answers to fill the questionnaire
Fill Questionnaire: Use the POST /api/agent/questionnaire/fill API with the questionnaire structure and source documents

Need Help? Contact support at support@k-v.ai

Questionnaire Generation

On this page