Create Upload URL

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

{
  "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

{
  "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": true,
  "$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.
If your OAuth grant covers several workspaces, also pass organization_id with the workspace to act in, from List My Organizations.

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.

{
  "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 for the full envelope and failure behavior.

Verify the result

Confirm the response is not marked isError, upload the file to the returned slot, then call the returned finalize_tool with the upload_id. The slot itself creates nothing to read back.

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.

Preview Batch Call Leads: preview_batch_call_leads
Create Batch Call: create_batch_call
Add Workflow Leads: add_workflow_leads
Upload Knowledge Base Document: upload_knowledge_base_document

Start Here

Tool Reference

Parameters

Complete input schema

Registered output schema

Before you call

Example MCP request

Verify the result

Retry safety

​Parameters

​Complete input schema

​Registered output schema

​Before you call

​Example MCP request

​Verify the result

​Retry safety

​Related MCP tools

​Related guides

Parameters

Complete input schema

Registered output schema

Before you call

Example MCP request

Verify the result

Retry safety

Related MCP tools

Related guides