openapi: 3.1.0
info:
  title: Upvest Investment Account Transfers Instruments 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: Instruments
  description: Query available financial instruments and their metadata.
paths:
  /instruments:
    get:
      operationId: listInstruments
      summary: Upvest List instruments
      description: Retrieve a paginated list of available financial instruments including equities, ETFs, and other tradeable securities.
      tags:
      - Instruments
      parameters:
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      - name: isin
        in: query
        description: Filter instruments by ISIN code.
        schema:
          type: string
        example: DE0005140008
      - name: type
        in: query
        description: Filter instruments by type.
        schema:
          type: string
          enum:
          - EQUITY
          - ETF
          - BOND
          - FUND
        example: EQUITY
      responses:
        '200':
          description: A paginated list of instruments
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Instrument'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              examples:
                listInstruments200Example:
                  summary: Default listInstruments 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      isin: {}
                      wkn: {}
                      name: {}
                      type: {}
                      currency: {}
                      exchanges: {}
                      tradeable: {}
                      fractional_trading_enabled: {}
                    meta:
                      offset: 0
                      limit: 20
                      count: 100
                      total: 100
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                listInstruments401Example:
                  summary: Default listInstruments 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /instruments/{instrument_id}:
    get:
      operationId: retrieveInstrument
      summary: Upvest Retrieve an instrument
      description: Retrieve details for a specific financial instrument.
      tags:
      - Instruments
      parameters:
      - $ref: '#/components/parameters/InstrumentId'
      responses:
        '200':
          description: Instrument details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instrument'
              examples:
                retrieveInstrument200Example:
                  summary: Default retrieveInstrument 200 response
                  x-microcks-default: true
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    isin: DE0005140008
                    wkn: example-value
                    name: Example Name
                    type: EQUITY
                    currency: EUR
                    exchanges:
                    - {}
                    tradeable: true
                    fractional_trading_enabled: true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                retrieveInstrument401Example:
                  summary: Default retrieveInstrument 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
        '404':
          description: Instrument not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                retrieveInstrument404Example:
                  summary: Default retrieveInstrument 404 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:
    Exchange:
      type: object
      description: A securities exchange where instruments are traded.
      properties:
        id:
          type: string
          description: The exchange identifier.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        name:
          type: string
          description: The exchange name.
          example: Example Name
        mic:
          type: string
          description: The Market Identifier Code (ISO 10383).
          example: example-value
    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
    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
    Instrument:
      type: object
      description: A tradeable financial instrument such as a stock, ETF, or bond.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the instrument.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        isin:
          type: string
          description: The International Securities Identification Number.
          pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
          example: DE0005140008
        wkn:
          type: string
          description: The Wertpapierkennnummer (German securities ID).
          example: example-value
        name:
          type: string
          description: The name of the instrument.
          example: Example Name
        type:
          type: string
          enum:
          - EQUITY
          - ETF
          - BOND
          - FUND
          description: The instrument type.
          example: EQUITY
        currency:
          type: string
          description: The trading currency as an ISO 4217 code.
          pattern: ^[A-Z]{3}$
          example: EUR
        exchanges:
          type: array
          items:
            $ref: '#/components/schemas/Exchange'
          description: Exchanges where the instrument is traded.
          example:
          - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
            name: Example Name
            mic: example-value
        tradeable:
          type: boolean
          description: Whether the instrument is currently tradeable.
          example: true
        fractional_trading_enabled:
          type: boolean
          description: Whether fractional shares are supported for this instrument.
          example: true
  parameters:
    InstrumentId:
      name: instrument_id
      in: path
      required: true
      description: The unique identifier of the instrument.
      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/