> ## Documentation Index > Fetch the complete documentation index at: https://docs.atlasyield.club/llms.txt > Use this file to discover all available pages before exploring further. # Build a portfolio > The Atlas Engine as a service. Give it a risk tier, a timeline, and a principal; it runs the mean-variance allocator over the current scored universe and returns the resulting allocation, sized in dollars. Unlike /scores and /catalog, this endpoint **fails closed on stale scoring**: an allocation is an active recommendation, so if the most recent scoring run is too old the endpoint returns 503 rather than allocating on stale data. The allocator is deterministic — the same inputs against the same scoring snapshot return the same portfolio. ## OpenAPI ````yaml api-reference/openapi.yaml GET /portfolio openapi: 3.1.0 info: title: AtlasYield API version: '1.0' description: >- Read-only access to the Atlas Score Index: neutral 16-factor vault scores across four pillars — Yield, Safety, Liquidity, Sustainability — plus the tracked vault catalog and the Atlas Engine, which turns those scores into a risk-adjusted allocation. Research and information, not investment advice. servers: - url: https://api.atlasyield.club/v1 security: [] paths: /portfolio: get: summary: Build a portfolio description: >- The Atlas Engine as a service. Give it a risk tier, a timeline, and a principal; it runs the mean-variance allocator over the current scored universe and returns the resulting allocation, sized in dollars. Unlike /scores and /catalog, this endpoint **fails closed on stale scoring**: an allocation is an active recommendation, so if the most recent scoring run is too old the endpoint returns 503 rather than allocating on stale data. The allocator is deterministic — the same inputs against the same scoring snapshot return the same portfolio. operationId: getPortfolio parameters: - name: riskTier in: query required: true schema: type: string enum: - conservative - balanced - aggressive description: Which tier policy to allocate under. See the tier policy page. example: balanced - name: principal in: query required: true schema: type: number minimum: 100 maximum: 1000000 description: Amount to allocate, USD. Must be between 100 and 1,000,000. example: 10000 - name: timeline in: query required: false schema: type: string enum: - short - medium - long default: medium description: >- Investment horizon. Nudges risk appetite within the tier's band — short is more variance-averse, long more return-seeking — and a short horizon also tightens the cap on vaults with little history. example: medium responses: '200': description: The proposed allocation. content: application/json: schema: type: object properties: success: type: boolean example: true riskTier: type: string example: balanced timeline: type: string example: medium principal: type: number example: 10000 strategy: type: string enum: - MVO - naive - none description: >- Which allocator produced the result. MVO is the mean-variance optimiser; naive is the equal-weight fallback; none means no allocation could be produced (see `note`). example: MVO fallback: type: boolean description: >- True when the result came from the fallback path rather than MVO. example: false allocations: type: array items: $ref: '#/components/schemas/PortfolioSlice' expectedApy: type: number nullable: true description: >- Principal-weighted expected APY of the allocation, percentage points. example: 4.69 expectedSharpe: type: number description: Expected Sharpe-like ratio of the allocation. example: 14.58 unallocatedUsd: type: number description: >- Principal left in cash because policy caps could not be satisfied. Surfaced honestly rather than force-fitted into a vault. example: 0 scorerVersion: type: string example: 2.1.0 generatedAt: type: string format: date-time description: ISO-8601 UTC timestamp the allocation was produced. disclaimer: type: string example: Research and information, not investment advice. note: type: string description: >- Present only when the allocator could not fully allocate; explains why. '400': $ref: '#/components/responses/ValidationError' '503': description: >- Scoring data is stale, so no allocation was produced. Carries a `Retry-After` header (seconds). content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Scoring data is stale — portfolio unavailable components: schemas: PortfolioSlice: type: object description: One position in the proposed allocation. properties: vaultId: type: string description: Vault identifier (same as vaultId in /scores). example: morpho:1:0xbeefc1cdafc5b4a649b54d07afc6bf0f75c6f4e2 protocol: type: string example: morpho chainId: type: integer example: 1 asset: type: string description: Underlying asset symbol. example: USDC name: type: string description: Vault display name. example: STEAKUSDTBETHENA apy: type: number description: Current APY in percentage points. example: 12.18706 tvl: type: number description: Total value locked, USD. example: 11780173 composite: type: number description: The vault's 0–100 Atlas Score at allocation time. example: 78.762 fraction: type: number description: Share of principal as a fraction, rounded to 1e-4. example: 0.15 allocationPct: type: number description: Share of principal as a percentage, 2 dp. example: 15 allocationUsd: type: number description: Dollar amount allocated to this vault. example: 1500 vaultAddress: type: string description: On-chain vault contract address. example: '0xbeefc1cdafc5b4a649b54d07afc6bf0f75c6f4e2' underlyingToken: type: string description: Address of the token the vault accepts. example: '0xc139190f447e929f090edeb554d95abb8b18ac1c' responses: ValidationError: description: >- A query parameter is missing or out of range. The body carries per-field detail under `details.fieldErrors`. content: application/json: schema: type: object properties: success: type: boolean example: false error: type: string example: Validation error details: type: object description: Zod field errors, keyed by parameter name. ````