openapi: 3.1.0
info:
  title: Upvest Investment Account Transfers Portfolios API
  description: The Upvest Investment API provides a unified interface for building embedded investment experiences. It supports placing and managing orders, creating portfolios, configuring savings plans, handling securities transfers, and managing user accounts and positions. The API covers the full order lifecycle with asynchronous processing and webhook notifications for real-time event handling. Financial institutions can use the API to offer fractional investing, automated portfolio management, and localized investment products across European and UK markets.
  version: 1.0.0
  contact:
    name: Upvest Support
    url: https://upvest.co/
  termsOfService: https://upvest.co/legal
servers:
- url: https://api.upvest.co
  description: Production Server
- url: https://sandbox.upvest.co
  description: Sandbox Server
security:
- oauth2ClientCredentials: []
tags:
- name: Portfolios
  description: Create and manage portfolios with custom asset allocations.
paths:
  /portfolios:
    get:
      operationId: listPortfolios
      summary: Upvest List portfolios
      description: Retrieve a paginated list of portfolios.
      tags:
      - Portfolios
      parameters:
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A paginated list of portfolios
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Portfolio'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              examples:
                listPortfolios200Example:
                  summary: Default listPortfolios 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      account_id: {}
                      name: {}
                      status: {}
                      created_at: {}
                      updated_at: {}
                    meta:
                      offset: 0
                      limit: 20
                      count: 100
                      total: 100
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listPortfolios401Example:
                  summary: Default listPortfolios 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createPortfolio
      summary: Upvest Create a portfolio
      description: Create a new portfolio with a defined set of target allocations across instruments.
      tags:
      - Portfolios
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortfolioCreate'
            examples:
              createPortfolioRequestExample:
                summary: Default createPortfolio request
                x-microcks-default: true
                value:
                  account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  name: Example Name
                  allocations:
                  - {}
      responses:
        '201':
          description: Portfolio created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Portfolio'
              examples:
                createPortfolio201Example:
                  summary: Default createPortfolio 201 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    name: Example Name
                    status: ACTIVE
                    created_at: '2025-03-15T14:30:00Z'
                    updated_at: '2025-03-15T14:30:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                createPortfolio400Example:
                  summary: Default createPortfolio 400 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                createPortfolio401Example:
                  summary: Default createPortfolio 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /portfolios/{portfolio_id}:
    get:
      operationId: retrievePortfolio
      summary: Upvest Retrieve a portfolio
      description: Retrieve details for a specific portfolio including its allocations and current state.
      tags:
      - Portfolios
      parameters:
      - $ref: '#/components/parameters/PortfolioId'
      responses:
        '200':
          description: Portfolio details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Portfolio'
              examples:
                retrievePortfolio200Example:
                  summary: Default retrievePortfolio 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    name: Example Name
                    status: ACTIVE
                    created_at: '2025-03-15T14:30:00Z'
                    updated_at: '2025-03-15T14:30:00Z'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                retrievePortfolio401Example:
                  summary: Default retrievePortfolio 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '404':
          description: Portfolio not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                retrievePortfolio404Example:
                  summary: Default retrievePortfolio 404 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updatePortfolio
      summary: Upvest Update a portfolio
      description: Update portfolio settings or metadata.
      tags:
      - Portfolios
      parameters:
      - $ref: '#/components/parameters/PortfolioId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortfolioUpdate'
            examples:
              updatePortfolioRequestExample:
                summary: Default updatePortfolio request
                x-microcks-default: true
                value:
                  name: Example Name
      responses:
        '200':
          description: Portfolio updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Portfolio'
              examples:
                updatePortfolio200Example:
                  summary: Default updatePortfolio 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    account_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    name: Example Name
                    status: ACTIVE
                    created_at: '2025-03-15T14:30:00Z'
                    updated_at: '2025-03-15T14:30:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                updatePortfolio400Example:
                  summary: Default updatePortfolio 400 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                updatePortfolio401Example:
                  summary: Default updatePortfolio 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    PaginationMeta:
      type: object
      description: Pagination metadata for list responses.
      properties:
        offset:
          type: integer
          description: The current offset.
          example: 0
        limit:
          type: integer
          description: The page size.
          example: 20
        count:
          type: integer
          description: The total number of items in the current page.
          example: 100
        total:
          type: integer
          description: The total number of items available.
          example: 100
    Portfolio:
      type: object
      description: A portfolio with defined target allocations across instruments.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the portfolio.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        account_id:
          type: string
          format: uuid
          description: The account this portfolio belongs to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: The portfolio name.
          example: Example Name
        status:
          type: string
          enum:
          - ACTIVE
          - CLOSED
          description: The portfolio status.
          example: ACTIVE
        created_at:
          type: string
          format: date-time
          description: When the portfolio was created.
          example: '2025-03-15T14:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the portfolio was last updated.
          example: '2025-03-15T14:30:00Z'
    Error:
      type: object
      description: An API error response.
      properties:
        type:
          type: string
          description: The error type identifier.
          example: standard
        status:
          type: integer
          description: The HTTP status code.
          example: 100
        title:
          type: string
          description: A short human-readable summary of the error.
          example: example-value
        detail:
          type: string
          description: A detailed human-readable explanation of the error.
          example: example-value
    PortfolioAllocationCreate:
      type: object
      description: Request body for defining a portfolio allocation.
      required:
      - instrument_id
      - weight
      properties:
        instrument_id:
          type: string
          format: uuid
          description: The instrument to allocate to.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        weight:
          type: string
          description: The target weight as a decimal string between 0 and 1.
          example: example-value
    PortfolioCreate:
      type: object
      description: Request body for creating a portfolio.
      required:
      - account_id
      - name
      - allocations
      properties:
        account_id:
          type: string
          format: uuid
          description: The account to create the portfolio for.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: The portfolio name.
          example: Example Name
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/PortfolioAllocationCreate'
          description: The initial target allocations.
          example:
          - instrument_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
            weight: example-value
    PortfolioUpdate:
      type: object
      description: Request body for updating a portfolio.
      properties:
        name:
          type: string
          description: The updated portfolio name.
          example: Example Name
  parameters:
    PortfolioId:
      name: portfolio_id
      in: path
      required: true
      description: The unique identifier of the portfolio.
      schema:
        type: string
        format: uuid
    Offset:
      name: offset
      in: query
      description: The number of items to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    Limit:
      name: limit
      in: query
      description: The maximum number of items to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 client credentials flow. Obtain an access token by providing your client ID and client secret.
      flows:
        clientCredentials:
          tokenUrl: /auth/token
          scopes:
            users:read: Read user data
            users:admin: Onboard and manage users
            accounts:read: Read account data
            accounts:admin: Create and manage accounts
            orders:read: Read order data
            orders:admin: Place and manage orders
            instruments:read: Read instrument data
            portfolios:read: Read portfolio data
            portfolios:admin: Create and manage portfolios
            positions:read: Read position data
            payments:read: Read payment data
            payments:admin: Manage payments and direct debits
            reports:read: Read reports
            webhooks:read: Read webhook subscriptions
            webhooks:admin: Manage webhook subscriptions
            transactions:read: Read transaction data
            fees:read: Read fee data
            fees:admin: Configure fees
externalDocs:
  description: Upvest API Documentation
  url: https://docs.upvest.co/