Skip to content

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.

  1. 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 }
  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:

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

  • 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.
StatusCodeWhen
400NO_FILE / INVALID_FILENothing attached, or not a PDF
404SESSION_NOT_FOUNDUnknown or expired id
409ALREADY_UPLOADEDThe session already has a file
503UPLOAD_CAPACITYToo many pending uploads — retry in a few minutes