> ## Documentation Index > Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Upload URL > Use the create_upload_url MCP tool on the DialNexa remote MCP server. Changes state - verify before retry Prepares a secure, one-time upload slot for a real file that lives on a machine you control, so it never has to be pasted into the conversation: a PDF/text document for a knowledge base (kind kb\_document, target\_id = kb\_id), or a CSV/Excel leads file for a batch call (kind batch\_leads, target\_id = agent\_id) or a workflow (kind workflow\_leads, target\_id = workflow\_id). Returns an upload\_id valid for 10 minutes. DO NOT call this for a file the user attached in the chat: pass that attachment as the `file` argument of the target tool instead (preview\_batch\_call\_leads, create\_batch\_call, add\_workflow\_leads, upload\_knowledge\_base\_document). The bytes must be PUT to the Azure storage host named in upload\_host by whoever holds the file. Set reveal\_url: true ONLY if you are a CLI agent or script running with open internet access; then PUT the file to the returned URL with the returned headers and call the finalize tool named in the result. Hosted chat sandboxes (ChatGPT code interpreter, Claude's default sandbox) cannot reach Azure storage: do not attempt the PUT from one, it will fail on DNS. No in-chat upload panel is available on this server, so the user cannot upload through the chat. Rule of thumb: content under \~50 KB that you already have goes inline as file\_text (or file\_base64 for a small .xlsx on disk); anything larger on your own disk comes through here. Nothing is stored until the file is actually uploaded. ## Parameters | Name | Type | Required | Description | | ------------ | -------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | `kind` | enum: `kb_document` \| `batch_leads` \| `workflow_leads` | Yes | What the file is for: kb\_document, batch\_leads or workflow\_leads | | `target_id` | `string` | Yes | The resource the file is for: kb\_id for kb\_document, agent\_id for batch\_leads, workflow\_id for workflow\_leads | | `file_name` | `string` | Yes | File name with extension, e.g. policy.pdf, leads.csv, leads.xlsx | | `reveal_url` | `boolean` | No | Set true ONLY if you will perform the HTTP PUT yourself (CLI agent or script). Chat assistants leave this unset. | ## Complete input schema ```json theme={null} { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "kb_document", "batch_leads", "workflow_leads" ], "description": "What the file is for: kb_document, batch_leads or workflow_leads" }, "target_id": { "type": "string", "description": "The resource the file is for: kb_id for kb_document, agent_id for batch_leads, workflow_id for workflow_leads" }, "file_name": { "type": "string", "description": "File name with extension, e.g. policy.pdf, leads.csv, leads.xlsx" }, "reveal_url": { "type": "boolean", "description": "Set true ONLY if you will perform the HTTP PUT yourself (CLI agent or script). Chat assistants leave this unset." } }, "required": [ "kind", "target_id", "file_name" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` ## Registered output schema ```json theme={null} { "type": "object", "properties": { "upload_id": { "type": "string", "description": "Opaque id to pass to the finalize tool once the file is uploaded" }, "kind": { "type": "string", "description": "The upload kind" }, "target_id": { "type": "string", "description": "The target id as given" }, "file_name": { "type": "string", "description": "The sanitised file name the upload will be stored under" }, "accepted_types": { "type": "array", "items": { "type": "string" }, "description": "Extensions accepted for this kind" }, "max_bytes": { "type": "number", "description": "Maximum file size in bytes" }, "expires_at": { "type": "string", "description": "When the upload URL stops working" }, "finalize_tool": { "type": "string", "description": "Tool to call with upload_id after the file is uploaded" }, "upload_host": { "type": "string", "description": "Host the file is PUT to (Azure storage). Allow it for network egress if your sandbox restricts outbound traffic" }, "next_step": { "type": "string", "description": "What to do next" }, "upload": { "type": "object", "properties": { "url": { "type": "string" }, "method": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "url", "method", "headers" ], "additionalProperties": false, "description": "Present only when reveal_url is true: where and how to PUT the bytes" } }, "required": [ "upload_id", "kind", "target_id", "file_name", "accepted_types", "max_bytes", "expires_at", "finalize_tool", "upload_host", "next_step" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` ## Before you call * Connect and initialize the MCP client with OAuth or an API key for the intended workspace. * Provide the required parameters: `kind`, `target_id`, `file_name`. ## Example MCP request Send `tools/call` after your client completes MCP initialization. Replace placeholder values with IDs and inputs from your workspace. For object and array parameters, follow the nested requirements in the parameter description instead of treating an empty value as complete. ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "create_upload_url", "arguments": { "kind": "kb_document", "target_id": "kb_abc123", "file_name": "support-faq.txt" } } } ``` Successful results include `structuredContent` and a text content block containing the same JSON. Check `isError` first, then read `structuredContent` or parse `content[0].text`. See [MCP responses and errors](/docs/mcp-tools/errors) for the full envelope and failure behavior. ## Verify the result Confirm the response is not marked `isError`. Call [Preview Batch Call Leads](/docs/mcp-tools/batch-calls/preview-batch-call-leads) to read the affected resource. Verify that the intended state is visible before making another change. ## Retry safety This tool changes workspace state. After a timeout, read the affected resource before retrying so you do not create duplicate or conflicting changes. ## Related MCP tools * [Preview Batch Call Leads](/docs/mcp-tools/batch-calls/preview-batch-call-leads): `preview_batch_call_leads` * [Create Batch Call](/docs/mcp-tools/batch-calls/create-batch-call): `create_batch_call` * [Add Workflow Leads](/docs/mcp-tools/workflows/add-workflow-leads): `add_workflow_leads` * [Upload Knowledge Base Document](/docs/mcp-tools/knowledge-base/upload-knowledge-base-document): `upload_knowledge_base_document` ## Related guides * [Connect to the DialNexa MCP server](/docs/mcp-tools/overview) * [File Uploads MCP tools](/docs/mcp-tools/uploads/overview) * [MCP responses and errors](/docs/mcp-tools/errors)