Upload sessions
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.
-
Create a session (API key required)
Terminal window curl -s -X POST https://api.portfoliointel.co.in/api/v1/upload-session \-H "X-API-Key: $PI_KEY"{ "session_id": "usess_…", "upload_url": "https://api.portfoliointel.co.in/api/v1/upload-session/usess_…", "expires_in": 900 } -
Show the user
upload_url. It opens an upload form in their browser; no key needed. The page accepts one PDF. -
Parse by session id with the MCP
parse_castool:{ "name": "parse_cas", "arguments": { "session_id": "usess_…", "password": "optional" } }Over MCP the same flow is one tool call:
request_upload_urlreturns the link and the id.
- 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 |