PORTIQA
Dashboard
Developer Documentation

API Reference.

Integrate PORTIQA's portfolio evaluation engine directly into your applications.

Portfolio Evaluation Endpoint

The core endpoint for PORTIQA. Send cash and stock positions plus an optional risk profile; PORTIQA enriches the request from its database and returns scoring, risk analysis, and actionable insights.

POST https://portiqa.ai/evaluate

Authentication

Authenticate requests using a standard Bearer token in the Authorization header. You can generate your API key in the Dashboard. For shared hosting/FastCGI environments that strip Authorization, PORTIQA also accepts X-Portfolio-Evaluator-Token with the same token.

Authorization: Bearer ptq_YOUR_API_KEY_HERE X-Portfolio-Evaluator-Token: ptq_YOUR_API_KEY_HERE

Request Payload (JSON)

Each request must contain a positions array. The number of unique tickers per evaluation is capped by your plan: 5 (Free/Hobby), 10 (Pro), 20 (Business). Requests above the cap return 413. Enterprise has no cap.

Parameter Type Required Description
positions Array Yes An array of portfolio positions with essential inputs only. E.g., [{"ticker": "AAPL", "market_value": 25000, "amount": 10}, ...]. Legacy clients may also send this as holdings.
risk_level String No The target risk profile. Valid options: low, medium (default), high.
cash_balance Number No Cash balance in the same currency as market values. Used to report current cash/invested percentages.
{ "risk_level": "medium", "cash_balance": 5000, "positions": [ {"ticker": "AAPL", "amount": 10, "market_value": 25000}, {"ticker": "MSFT", "amount": 8, "market_value": 22000}, {"ticker": "EQNR.OL", "amount": 50, "market_value": 15000} ] }

Response Payload

A successful response returns HTTP 200 with evaluator metrics. PORTIQA enriches ticker data, sectors, factor context, and market regime data before scoring.

{ "ok": true, "evaluation": { "score": 78.1, "health_score": 78.1, "status": "Good", "weighted_score": 75.4, "top_sector": "Technology", "top_sector_weight": 75.8, "exposure_plan": { "target_invested_pct": 72.0, "target_cash_pct": 28.0, "stance": "balanced" }, "portfolio_input": { "cash_balance": 5000, "holdings_value": 62000, "total_value": 67000, "cash_pct": 7.5, "invested_pct": 92.5 }, "holding_analysis": [ { "ticker": "AAPL", "weight_pct": 40.3, "score": 72.0, "signal": "BUY", "sector": "Technology" } ], "suggestions": [] } }

Error Handling

Status Code Meaning
400 Bad Request Invalid JSON payload, or no positions could be matched to stock data.
401 Unauthorized Missing or invalid API key.
402 Payment Required Subscription is past due, canceled, or otherwise inactive. Update billing to resume access.
413 Payload Too Large Request exceeds your plan's per-evaluation ticker cap (Free/Hobby: 5, Pro: 10, Business: 20). Upgrade or split the portfolio across calls.
429 Too Many Requests Monthly call limit reached for your plan (Free: 5, Hobby: 30, Pro: 100, Business: 1,000). Upgrade or wait for the next billing period — there is no automatic overage.
500 Internal Server Error The evaluation engine failed to process the request.

Interactive Playground

Test the API directly from your browser. Enter your API key and configure the payload to see a live response.

Easy mode is for a quick score check. Add holdings with ticker and market_value in your account currency; PORTIQA enriches the rest. Stay within your plan's ticker cap (5 / 10 / 20).