# Staging — canonical payload contracts

Temporary public HTTPS URL for large files (max 1 GiB, ~24h TTL). Upload: HTTP multipart POST /staging/upload, staging_put_text (UTF-8, no base64), staging_put_base64 (small binaries), or staging_ingest_url.

**Service id:** `staging`  
**Docs:** [https://mcp.glc-rag.hu/guide/staging](https://mcp.glc-rag.hu/guide/staging)  
**Markdown docs:** [https://mcp.glc-rag.hu/guide/staging.md](https://mcp.glc-rag.hu/guide/staging.md)  
**MCP resource:** `docs://staging/payload`

POST `https://mcp.glc-rag.hu/mcp`. Values below are **type slots** from the live input schema (e.g. `<string, required>`), not example data. Fill them from the user task.

RPC result wrapper: `result.structuredContent` is the object in **Output schema**. `result.isError` mirrors `structuredContent.is_error`.

## `staging_ingest_url`

Download a public http(s) URL into staging and return a temporary public https URL on this platform (max 1 GiB). Use when the file is already online and you need a stable short-lived URL for whisper_job_start or other tools. Returns immediately after the download finishes (may take time for large files).

**Required arguments:** `url`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "staging_ingest_url",
    "arguments": {
      "url": "<string, required>",
      "filename": "<string, optional>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Public http(s) source URL to copy into staging"
    },
    "filename": {
      "type": "string",
      "description": "Optional filename hint"
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "object_id": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "bytes": {
      "type": "integer"
    },
    "expires_at": {
      "type": "string"
    },
    "content_type": {
      "type": "string"
    },
    "filename": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "object_id",
    "url"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `staging_put_text`

Store UTF-8 text (markdown, HTML, plain text, JSON, …) in staging and return a public URL. Prefer this over base64 for documents — models handle plain text tool args reliably. Then pass url to markdown_to_pdf / markdown_to_docx / html_to_*. Size-limited (default 2 MiB). For large binaries use POST /staging/upload.

**Required arguments:** `text`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "staging_put_text",
    "arguments": {
      "text": "<string, required>",
      "filename": "<string, optional>",
      "content_type": "<string, optional>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "UTF-8 document body (markdown/HTML/plain text)"
    },
    "filename": {
      "type": "string",
      "description": "Optional filename hint (e.g. report.md, page.html)"
    },
    "content_type": {
      "type": "string",
      "description": "Optional MIME type; default guessed from filename (text/markdown, text/html, text/plain, …)"
    }
  },
  "required": [
    "text"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "object_id": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "bytes": {
      "type": "integer"
    },
    "expires_at": {
      "type": "string"
    },
    "content_type": {
      "type": "string"
    },
    "filename": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "object_id",
    "url"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `staging_put_base64`

Store small/medium base64 content in staging and return a public URL. Hard limit 1 GiB but base64 through MCP is impractical above tens of MB — for documents prefer staging_put_text; for large audio use HTTP POST /staging/upload.

**Required arguments:** `content_base64`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "staging_put_base64",
    "arguments": {
      "content_base64": "<string, required>",
      "filename": "<string, optional>",
      "content_type": "<string, optional, default 'application/octet-stream'>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "content_base64": {
      "type": "string"
    },
    "filename": {
      "type": "string"
    },
    "content_type": {
      "type": "string",
      "default": "application/octet-stream"
    }
  },
  "required": [
    "content_base64"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "object_id": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "bytes": {
      "type": "integer"
    },
    "expires_at": {
      "type": "string"
    },
    "content_type": {
      "type": "string"
    },
    "filename": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "object_id",
    "url"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `staging_info`

Return metadata for a staging object_id if it still exists and has not expired.

**Required arguments:** `object_id`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "staging_info",
    "arguments": {
      "object_id": "<string, required>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "object_id": {
      "type": "string"
    }
  },
  "required": [
    "object_id"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "object_id": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "bytes": {
      "type": "integer"
    },
    "expires_at": {
      "type": "string"
    },
    "content_type": {
      "type": "string"
    },
    "filename": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "additionalProperties": true,
  "required": [
    "object_id",
    "url"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `staging_delete`

Delete a staging object early (before TTL).

**Required arguments:** `object_id`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "staging_delete",
    "arguments": {
      "object_id": "<string, required>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "object_id": {
      "type": "string"
    }
  },
  "required": [
    "object_id"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "object_id": {
      "type": "string"
    },
    "deleted": {
      "type": "boolean"
    }
  },
  "additionalProperties": true,
  "required": [
    "object_id",
    "deleted"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```