# QuantOS Allocation Exposure

> Compute optimal allocation weights for a portfolio.

`POST https://api.bavest.co/v2/quant-os/allocate`

Group: Bavest QuantOS. Route id: `v2_quant_os_allocate`. Included in: Growth.

## Authentication

Send your API key in the `x-api-key` header on every request. No key yet? Sign up at https://dashboard.bavest.co/sign-up (free trial). The examples read the key from the `BAVEST_API_KEY` environment variable.

## Parameters

None.

## Request body

JSON, required. Symbols, weights, and date range for analysis.

| Field | Type | Always present | Description |
|---|---|---|---|
| `portfolioItems` | array of object | yes | Portfolio positions with symbol, allocation weight, and purchase date. |
| `portfolioItems[].symbol` | string | yes | Ticker symbol. Example: `AAPL`. |
| `portfolioItems[].weight` | number | yes | Allocation weight (all weights must sum to 1.0) Example: `0.4`. |
| `portfolioItems[].buyDate` | string (date) | yes | Purchase date (YYYY-MM-DD). Converted to Unix timestamp internally. Example: `2026-09-01`. |
| `portfolioItems[].amount` | number | no | Number of shares held. |
| `startDate` | string (date) | no | Analysis start date (YYYY-MM-DD) Example: `2026-09-01`. |
| `endDate` | string (date) | no | Analysis end date (YYYY-MM-DD) Example: `2026-09-30`. |
| `currency` | string | no | Target currency for valuation (ISO 4217) Example: `USD`. |
| `resolution` | string | no | Data resolution for time series. One of `D`, `W`, `M`. Example: `D`. |

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | array of object | no |  |
| `data[].symbol` | string | no |  |
| `data[].percentage` | number (double) | no |  |
| `meta` | ResponseMeta | no | Response envelope metadata. Always present on a 200: `time` is set by `core/response.py` on every successful response. Errors carry the same block, built by the same code, so a client parses one meta shape whether the call succeeded or failed. |
| `meta.time` | integer | no | Server-side processing time in milliseconds. Example: `17`. |
| `meta.parameters` | object | no | Echo of the request parameters the endpoint resolved. |

## Example request

```bash
curl -X POST 'https://api.bavest.co/v2/quant-os/allocate' \
  -H "x-api-key: $BAVEST_API_KEY" \
  -H 'content-type: application/json' \
  --data '{"portfolioItems":[{"symbol":"AAPL","weight":0.4,"buyDate":"2026-09-01"},{"symbol":"MSFT","weight":0.35,"buyDate":"2026-09-01"},{"symbol":"GOOGL","weight":0.25,"buyDate":"2026-09-01"}],"startDate":"2026-09-01","endDate":"2026-09-30","currency":"USD","resolution":"D"}'
```

## Example response

```json
{
  "data": [
    {
      "symbol": "AAPL",
      "percentage": 40
    },
    {
      "symbol": "MSFT",
      "percentage": 35
    }
  ],
  "meta": {
    "parameters": {
      "startDate": "2026-09-01",
      "endDate": "2026-09-30",
      "currency": "USD",
      "resolution": "D",
      "portfolio_items": [
        {
          "symbol": "AAPL",
          "weight": 0.4,
          "buy_date": 1788220800000
        },
        {
          "symbol": "MSFT",
          "weight": 0.35,
          "buy_date": 1788220800000
        },
        {
          "symbol": "GOOGL",
          "weight": 0.25,
          "buy_date": 1788220800000
        }
      ],
      "from": 1788220800,
      "to": 1790726400
    },
    "time": 5130
  }
}
```

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid request parameters. Returned when required query parameters are missing, have invalid types, or violate constraints (e.g., providing both symbol and isin when they are mutually exclusive). |
| 401 | Missing or invalid API key. |
| 404 | Resource not found. |
| 429 | Rate limit exceeded. Retry after the `Retry-After` header interval. |
| 500 | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |
| 502 | Upstream data provider returned an error or is temporarily unavailable. Retry after a short delay. |
| 504 | The request timed out waiting for a response from the upstream data provider. This may occur for complex queries or during peak load. |
| default | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |

- `403` from the gateway: the API key is invalid or switched off.
- `429` with message `Limit Exceeded`: the monthly quota of the key is used up. With `Too Many Requests`: the key is throttled, or this route is not in the key's plan. Wait for `Retry-After` when it is sent.

## Links

- HTML page: https://dashboard.bavest.co/docs/v2_quant_os_allocate
- OpenAPI: https://dashboard.bavest.co/openapi.json (YAML: https://dashboard.bavest.co/openapi.yaml)
- Authentication: https://dashboard.bavest.co/docs/authentication.md
- MCP server for AI agents: https://dashboard.bavest.co/docs/mcp.md
- All routes: https://dashboard.bavest.co/llms.txt