# Upload sessions

> Let a user upload a CAS from their own browser when the agent can't pass the file.

Hosted agents often can't hand a local file to the API — the PDF is on the
user's laptop, not in the agent's sandbox. An upload session gives the user a
one-time link to upload it themselves; the agent then parses it by id.

1. **Create a session** (API key required)

   ```bash
   curl -s -X POST https://api.portfoliointel.co.in/api/v1/upload-session \
     -H "X-API-Key: $PI_KEY"
   ```

   ```json
   { "session_id": "usess_…", "upload_url": "https://api.portfoliointel.co.in/api/v1/upload-session/usess_…", "expires_in": 900 }
   ```

2. **Show the user `upload_url`.** It opens an upload form in their browser; no
   key needed. The page accepts one PDF.

3. **Parse by session id** with the MCP `parse_cas` tool:

   ```json
   { "name": "parse_cas", "arguments": { "session_id": "usess_…", "password": "optional" } }
   ```

   Over MCP the same flow is one tool call: `request_upload_url` returns the
   link and the id.

## Rules

- **Single use, 15 minutes.** The PDF is deleted when it is parsed or when the
  session expires, whichever is first.
- **Owned by the key that created it.** A session id alone can't be used by
  another key — it travels through chat transcripts and URLs, so it is not
  treated as a secret.
- **Bounded.** Each key may hold 5 open sessions; the service caps total
  pending uploads.

| Status | Code | When |
| --- | --- | --- |
| `400` | `NO_FILE` / `INVALID_FILE` | Nothing attached, or not a PDF |
| `404` | `SESSION_NOT_FOUND` | Unknown or expired id |
| `409` | `ALREADY_UPLOADED` | The session already has a file |
| `503` | `UPLOAD_CAPACITY` | Too many pending uploads — retry in a few minutes |

> **Note**
>
> If you can send bytes directly, skip this: post the file to
> [`/api/v1/parse`](https://docs.portfoliointel.co.in/api-reference/parse).

Source: https://docs.portfoliointel.co.in/api-reference/upload-sessions/
