Aladdin Graph API

openapi: 3.0.3
info:
  title: Aladdin Graph API
  description: >-
    The Aladdin Graph API provides RESTful access to portfolio data, securities,
    positions, risk analytics, and Aladdin platform capabilities. Powers the
    AladdinSDK Python client with OpenAPI-generated bindings for institutional
    asset managers, risk teams, and quantitative researchers.
  version: 1.0.0
  contact:
    name: Aladdin Studio
    url: https://www.blackrock.com/aladdin/products/apis
  license:
    name: Proprietary
    url: https://www.blackrock.com/aladdin/products/aladdin-studio
  x-generated-from: documentation
servers:
  - url: https://api.blackrock.com/v1
    description: Aladdin API production server
security:
  - OAuth2: []
  - BasicAuth: []
paths:
  /portfolios:
    get:
      operationId: listPortfolios
      summary: Aladdin Studio List Portfolios
      description: >-
        Retrieve a paginated list of portfolios accessible to the authenticated
        user. Returns portfolio metadata including identifiers, names, and
        classification attributes.
      tags:
        - Portfolios
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            example: 1
        - name: pageSize
          in: query
          description: Number of results per page
          schema:
            type: integer
            example: 100
      responses:
        '200':
          description: List of portfolios
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioList'
              examples:
                listPortfolios200Example:
                  summary: Default listPortfolios 200 response
                  x-microcks-default: true
                  value:
                    portfolios:
                      - portfolioId: PF-123456
                        name: Global Equity Fund
                        currency: USD
                        status: active
                    totalCount: 1
                    page: 1
                    pageSize: 100
        '401':
          description: Unauthorized - invalid or missing authentication
        '403':
          description: Forbidden - insufficient permissions for this portfolio
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /portfolios/{portfolioId}:
    get:
      operationId: getPortfolio
      summary: Aladdin Studio Get Portfolio
      description: >-
        Retrieve detailed information about a specific portfolio including
        metadata, benchmark, currency, and classification attributes.
      tags:
        - Portfolios
      parameters:
        - name: portfolioId
          in: path
          required: true
          description: Unique portfolio identifier
          schema:
            type: string
            example: PF-123456
      responses:
        '200':
          description: Portfolio details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Portfolio'
              examples:
                getPortfolio200Example:
                  summary: Default getPortfolio 200 response
                  x-microcks-default: true
                  value:
                    portfolioId: PF-123456
                    name: Global Equity Fund
                    currency: USD
                    status: active
                    benchmarkId: MSCI-WORLD
                    inceptionDate: "2020-01-15"
        '404':
          description: Portfolio not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /portfolios/{portfolioId}/positions:
    get:
      operationId: getPortfolioPositions
      summary: Aladdin Studio Get Portfolio Positions
      description: >-
        Retrieve current positions for a portfolio including security
        identifiers, market values, quantities, and weights.
      tags:
        - Positions
      parameters:
        - name: portfolioId
          in: path
          required: true
          description: Unique portfolio identifier
          schema:
            type: string
            example: PF-123456
        - name: asOfDate
          in: query
          description: Position date in YYYY-MM-DD format
          schema:
            type: string
            format: date
            example: "2026-04-19"
      responses:
        '200':
          description: Portfolio positions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionList'
              examples:
                getPortfolioPositions200Example:
                  summary: Default getPortfolioPositions 200 response
                  x-microcks-default: true
                  value:
                    positions:
                      - securityId: US0378331005
                        securityName: Apple Inc
                        quantity: 1000
                        marketValue: 195000.00
                        weight: 0.025
                        currency: USD
                    asOfDate: "2026-04-19"
                    portfolioId: PF-123456
        '404':
          description: Portfolio not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /portfolios/{portfolioId}/risk:
    get:
      operationId: getPortfolioRisk
      summary: Aladdin Studio Get Portfolio Risk Analytics
      description: >-
        Retrieve risk analytics for a portfolio including factor exposures,
        tracking error, VaR, and contribution metrics computed by Aladdin's
        risk engine.
      tags:
        - Risk
      parameters:
        - name: portfolioId
          in: path
          required: true
          description: Unique portfolio identifier
          schema:
            type: string
            example: PF-123456
        - name: asOfDate
          in: query
          description: Risk calculation date in YYYY-MM-DD format
          schema:
            type: string
            format: date
            example: "2026-04-19"
        - name: model
          in: query
          description: Risk model to use for calculation
          schema:
            type: string
            example: AXUS4
      responses:
        '200':
          description: Portfolio risk analytics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioRisk'
              examples:
                getPortfolioRisk200Example:
                  summary: Default getPortfolioRisk 200 response
                  x-microcks-default: true
                  value:
                    portfolioId: PF-123456
                    asOfDate: "2026-04-19"
                    trackingError: 0.0342
                    var95: -0.0285
                    beta: 1.02
                    factorExposures:
                      - factorName: Market
                        exposure: 1.02
                      - factorName: Size
                        exposure: -0.15
        '404':
          description: Portfolio not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /securities/{securityId}:
    get:
      operationId: getSecurity
      summary: Aladdin Studio Get Security
      description: >-
        Retrieve security reference data for a given identifier including
        name, asset class, sector, country, and other classification attributes.
      tags:
        - Securities
      parameters:
        - name: securityId
          in: path
          required: true
          description: Security identifier (ISIN, CUSIP, SEDOL, or internal ID)
          schema:
            type: string
            example: US0378331005
        - name: idType
          in: query
          description: Type of security identifier provided
          schema:
            type: string
            enum:
              - ISIN
              - CUSIP
              - SEDOL
              - INTERNAL
            example: ISIN
      responses:
        '200':
          description: Security reference data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Security'
              examples:
                getSecurity200Example:
                  summary: Default getSecurity 200 response
                  x-microcks-default: true
                  value:
                    securityId: US0378331005
                    name: Apple Inc
                    ticker: AAPL
                    assetClass: Equity
                    sector: Technology
                    country: US
                    currency: USD
        '404':
          description: Security not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication supporting client_credentials and refresh_token flows
      flows:
        clientCredentials:
          tokenUrl: https://api.blackrock.com/oauth/token
          scopes:
            portfolio:read: Read portfolio data
            risk:read: Read risk analytics
            trading:read: Read trading data
            trading:write: Create and manage orders
        authorizationCode:
          authorizationUrl: https://api.blackrock.com/oauth/authorize
          tokenUrl: https://api.blackrock.com/oauth/token
          scopes:
            portfolio:read: Read portfolio data
            risk:read: Read risk analytics
    BasicAuth:
      type: http
      scheme: basic
      description: Basic authentication using API token and user credentials
  schemas:
    Portfolio:
      title: Portfolio
      type: object
      description: An Aladdin portfolio with associated metadata
      properties:
        portfolioId:
          type: string
          description: Unique portfolio identifier
          example: PF-123456
        name:
          type: string
          description: Portfolio display name
          example: Global Equity Fund
        currency:
          type: string
          description: Base currency ISO code
          example: USD
        status:
          type: string
          description: Portfolio status
          enum:
            - active
            - inactive
            - pending
          example: active
        benchmarkId:
          type: string
          description: Benchmark identifier
          example: MSCI-WORLD
        inceptionDate:
          type: string
          format: date
          description: Portfolio inception date
          example: "2020-01-15"
        assetClass:
          type: string
          description: Primary asset class
          example: Equity
        strategy:
          type: string
          description: Investment strategy
          example: Long Only
    PortfolioList:
      title: PortfolioList
      type: object
      description: Paginated list of portfolios
      properties:
        portfolios:
          type: array
          description: Array of portfolio objects
          items:
            $ref: '#/components/schemas/Portfolio'
        totalCount:
          type: integer
          description: Total number of portfolios
          example: 125
        page:
          type: integer
          description: Current page number
          example: 1
        pageSize:
          type: integer
          description: Number of results per page
          example: 100
    Position:
      title: Position
      type: object
      description: A security position within a portfolio
      properties:
        securityId:
          type: string
          description: Security identifier
          example: US0378331005
        securityName:
          type: string
          description: Security name
          example: Apple Inc
        quantity:
          type: number
          description: Number of shares or units held
          example: 1000
        marketValue:
          type: number
          description: Current market value in portfolio base currency
          example: 195000.00
        weight:
          type: number
          description: Portfolio weight as decimal
          example: 0.025
        currency:
          type: string
          description: Security trading currency
          example: USD
        assetClass:
          type: string
          description: Asset class classification
          example: Equity
        sector:
          type: string
          description: GICS sector
          example: Technology
    PositionList:
      title: PositionList
      type: object
      description: List of portfolio positions as of a date
      properties:
        positions:
          type: array
          description: Array of position objects
          items:
            $ref: '#/components/schemas/Position'
        portfolioId:
          type: string
          description: Portfolio identifier
          example: PF-123456
        asOfDate:
          type: string
          format: date
          description: Position date
          example: "2026-04-19"
        totalMarketValue:
          type: number
          description: Total portfolio market value
          example: 7800000.00
    FactorExposure:
      title: FactorExposure
      type: object
      description: Risk factor exposure for a portfolio
      properties:
        factorName:
          type: string
          description: Risk factor name
          example: Market
        exposure:
          type: number
          description: Factor exposure value
          example: 1.02
        contribution:
          type: number
          description: Contribution to portfolio risk
          example: 0.0285
    PortfolioRisk:
      title: PortfolioRisk
      type: object
      description: Risk analytics for a portfolio computed by Aladdin's risk engine
      properties:
        portfolioId:
          type: string
          description: Portfolio identifier
          example: PF-123456
        asOfDate:
          type: string
          format: date
          description: Risk calculation date
          example: "2026-04-19"
        trackingError:
          type: number
          description: Annualized tracking error vs benchmark
          example: 0.0342
        var95:
          type: number
          description: 95% Value at Risk (1-day)
          example: -0.0285
        beta:
          type: number
          description: Portfolio beta vs benchmark
          example: 1.02
        volatility:
          type: number
          description: Annualized portfolio volatility
          example: 0.152
        factorExposures:
          type: array
          description: Factor exposure breakdown
          items:
            $ref: '#/components/schemas/FactorExposure'
        riskModel:
          type: string
          description: Risk model used for calculation
          example: AXUS4
    Security:
      title: Security
      type: object
      description: Security reference data from Aladdin
      properties:
        securityId:
          type: string
          description: Internal Aladdin security identifier
          example: US0378331005
        name:
          type: string
          description: Security full name
          example: Apple Inc
        ticker:
          type: string
          description: Exchange ticker symbol
          example: AAPL
        isin:
          type: string
          description: ISIN identifier
          example: US0378331005
        cusip:
          type: string
          description: CUSIP identifier
          example: 037833100
        assetClass:
          type: string
          description: Asset class classification
          example: Equity
        sector:
          type: string
          description: GICS sector
          example: Technology
        country:
          type: string
          description: Country of domicile ISO code
          example: US
        currency:
          type: string
          description: Trading currency ISO code
          example: USD
        exchange:
          type: string
          description: Primary exchange
          example: NASDAQ
tags:
  - name: Portfolios
    description: Portfolio metadata and management operations
  - name: Positions
    description: Portfolio position and holdings data
  - name: Risk
    description: Risk analytics and factor exposure calculations
  - name: Securities
    description: Security reference data and classification