MerQube Index API

openapi: 3.2.0
info:
  title: Merqube Index API
  version: 4.40.0
  contact:
    email: support@merqube.com
    name: API Support
    url: https://www.merqube.com/contact
  description: 'Operations tagged index across 3 of this provider''s published API definitions: merqube-api-openapi.json, merqube-api-raw.yaml, merqube-stoplight-docs-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- description: Production server
  url: https://api.merqube.com
- description: Testing server for next generation features
  url: https://api.staging.merqube.com
- url: https://staging.api.merqube.com
  description: Testing server for next generation features
tags:
- description: APIs for MerQube Indices
  name: index
paths:
  /index:
    get:
      description: Get all MerQube indices.
      operationId: index
      parameters:
      - $ref: '#/components/parameters/filterParam'
      - $ref: '#/components/parameters/idsParam'
      - $ref: '#/components/parameters/nameParam'
      - $ref: '#/components/parameters/namesParam'
      - $ref: '#/components/parameters/namespaceParam'
      - $ref: '#/components/parameters/fieldsParam'
      - $ref: '#/components/parameters/debugParam'
      - $ref: '#/components/parameters/formatParam'
      - description: By default only "prod" indices are shown; comma delimited list of other "types"
        in: query
        name: type
        required: false
        schema:
          example: test,prod
          type: string
      - description: will return an additional section, linked_resources, that contains all identifier objects that the calling user has permission to that are linked to this index
        in: query
        name: fetch_identifiers
        required: false
        schema:
          enum:
          - 'true'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  error_codes:
                    $ref: '#/components/schemas/ErrorCodes'
                  results:
                    items:
                      $ref: '#/components/schemas/IndexDefinitionPatchPutGet'
                    type: array
                type: object
          description: 200 response
      summary: Get all MerQube indices.
      tags:
      - index
    post:
      description: Create a new MerQube index
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/IndexDefinitionPost'
              - $ref: '#/components/schemas/CopyFromManifest'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  id:
                    description: the uuid of this index
                    type: string
                  intraday_security_id:
                    description: the uuid of the secapi (type intraday_index) security for this index
                    type: string
                  security_id:
                    description: the uuid of the secapi (type index) security for this index
                    type: string
                  status:
                    type: string
                title: Index Creation Response Schema
                type: object
          description: OK
        '400':
          description: illegal request body
        '403':
          description: not authorized to perform this operation
      summary: Create a new MerQube index
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index-documents:
    index/{uuid}/identifier/{identifier_uuid}: null
    delete:
      description: Delete an identifier from an index
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      - $ref: '#/components/parameters/identifierParam'
      responses:
        '200':
          description: OK
        '403':
          description: not authorized
        '404':
          description: index or identifier does not exist
      tags:
      - index
    get:
      description: List of index documents
      parameters:
      - description: UUID of the index.  Optional for index-specific documents.
        in: query
        name: id
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  results:
                    schema:
                      properties:
                        filename:
                          type: string
                        last_modified:
                          $ref: '#/components/schemas/IsoTS'
                          description: UTC ISO timestamp when file was last modified
                        shared:
                          description: If this file is shared by multiple indices or not
                          type: boolean
                      type: object
                    type: array
                type: object
          description: Returned list of valid documents in bucket
      tags:
      - index
    put:
      description: Upload a document for an index
      parameters:
      - description: UUID of the index.  Optional for index-specific documents.
        in: query
        name: id
        required: false
        schema:
          type: string
      - description: Overwrite a document
        in: query
        name: force_overwrite
        required: false
        schema:
          default: false
          type: boolean
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                document:
                  format: binary
                  type: string
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: string
                type: object
          description: OK status of upload
        '400':
          description: Invalid multipart request, or file exists and requires overwrite flag.
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}:
    parameters:
    - $ref: '#/components/parameters/uuidParam'
    delete:
      description: Delete a MerQube index. Also tries to delete its identifiers.
      responses:
        '200':
          description: OK
        '403':
          description: not authorized
        '404':
          description: index does not exist
      summary: Delete a MerQube index.
      tags:
      - index
    get:
      description: Returns the MerQube index with this uuid
      operationId: index_uuid
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexDefinitionPatchPutGet'
          description: 200 response
        '403':
          description: not authorized to perform this operation
        '404':
          description: index does not exist
      summary: Returns the MerQube index with this uuid
      tags:
      - index
    patch:
      description: Partialy update a MerQube index.
      requestBody:
        content:
          application/json:
            schema:
              type: object
        description: any fields from an Index Manifest
      responses:
        '200':
          description: OK
        '400':
          description: illegal request body
        '403':
          description: not authorized
        '404':
          description: index does not exist
      summary: Partially update a MerQube index
      tags:
      - index
    put:
      description: Replace a MerQube index.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexDefinitionPatchPutGet'
      responses:
        '200':
          description: OK
        '400':
          description: illegal request body
        '403':
          description: not authorized
        '404':
          description: index does not exist
      summary: Replace a MerQube index
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/caps:
    get:
      description: Get the caps of buffer MerQube index
      operationId: index_caps
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      - in: query
        name: base_symbol
        schema:
          type: string
      - in: query
        name: base_name
        schema:
          type: string
      - in: query
        name: base_plot_metric
        schema:
          type: string
      - $ref: '#/components/parameters/formatParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  results:
                    items:
                      properties:
                        caps:
                          description: object
                          example:
                            SPY: 0.9036144578
                            cap: 16.8152652821
                            performance: 0.9364820847
                          type: object
                        date:
                          description: date
                          example: '2019-07-20'
                          type: string
                        id:
                          description: currently, the date
                          example: '2019-07-20'
                          type: string
                      type: object
                    type: array
                type: object
          description: 200 response
        '403':
          description: not authorized to see this namespace
        '404':
          description: index or caps does not exist
      summary: Get the caps of buffer MerQube index
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/data_collections:
    get:
      description: get the timeseries of data collections for an index
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDataCollections'
                additionalProperties: true
                properties:
                  data_collection:
                    $ref: '#/components/schemas/DataCollectionsSpec'
                type: object
          description: OK
        '403':
          description: not authorized to see this namespace
        '404':
          description: index or data collection does not exist
      tags:
      - index
    put:
      description: create or replace the data collection specification for this index
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                data_collections:
                  items:
                    $ref: '#/components/schemas/DataCollectionsSpec'
                  type: array
              type: object
      responses:
        '200':
          description: OK, data collection successfully written and validated.
        '400':
          description: bad data collection or request
        '403':
          description: not authorized
        '404':
          description: index does not exist
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/data_collections/data:
    get:
      description: fetch the data collections from s3
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      - $ref: '#/components/parameters/dataCollectionsNameParam'
      - $ref: '#/components/parameters/startDateParam'
      - $ref: '#/components/parameters/endDateParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    description: Dynamic, depends on the data collection csv.
                    type: array
                type: object
          description: OK
        '400':
          description: a required query param is missing
        '403':
          description: not authorized to see this namespace
        '404':
          description: index or data collection does not exist
        '409':
          description: Metadata consistency -- malformed s3 URI, or invalid date col
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/data_collections/raw:
    get:
      description: Get a presigned raw file redirect for s3
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      - $ref: '#/components/parameters/dataCollectionsNameParam'
      responses:
        '302':
          description: Moved
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/documents:
    get:
      description: Get documentation for an index
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      - description: Document key in the index manifest which contains the file name.  Defaults to "methodology".
        in: query
        name: document_type
        required: false
        schema:
          default: methodology
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  url:
                    type: string
                type: object
          description: File found and returning presigned url to file
        '400':
          description: No documents found in the index manifest, or invalid document type
        '403':
          description: not authorized to see this namespace
        '404':
          description: Document not found
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/portfolio:
    get:
      description: Get the portfolio of a MerQube index over time
      operationId: index_portfolio
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      - description: include only dates and no portfolio data
        in: query
        name: dates_only
        required: false
        schema:
          enum:
          - 'true'
          type: string
      - $ref: '#/components/parameters/startDateParam'
      - $ref: '#/components/parameters/endDateParam'
      - in: query
        name: time
        schema:
          format: date-time
          type: string
      - in: query
        name: download
        schema:
          description: either true or false
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  results:
                    items:
                      properties:
                        date:
                          description: date
                          example: '2005-07-15T00:00:00'
                          type: string
                        id:
                          description: currently, the date
                          example: '2005-07-15T00:00:00'
                          type: string
                        portfolio:
                          description: object where each key is a holding
                          example:
                            OPTION:SPY:CALL:0.0:2006-07-21:BUY:
                              buy_sell: BUY
                              exchgcntry: US
                              exercise_type: European
                              expiry: '2006-07-21'
                              mic: XCME
                              option_type: CALL
                              price: 120.31612463831256
                              price_date: '2005-07-15'
                              root: SPY
                              shares: 8.143322475570033
                              strike: '0.0'
                              strike_percentage: 0
                              symbol: OPTION:SPY:CALL:0.0:2006-07-21:BUY
                              weight: 8.143322475570033
                            OPTION:SPY:CALL:143.4491457664114:2006-07-21:SELL:
                              buy_sell: SELL
                              exchgcntry: US
                              exercise_type: European
                              expiry: '2006-07-21'
                              mic: XCME
                              option_type: CALL
                              price: 0.5857132916126346
                              price_date: '2005-07-15'
                              root: SPY
                              shares: -8.143322475570033
                              strike: '143.4491457664114'
                              strike_percentage: 116.81526528209396
                              symbol: OPTION:SPY:CALL:143.4491457664114:2006-07-21:SELL
                              weight: 8.143322 475570033
                          type: object
                      type: object
                    type: array
                type: object
          description: 200 response
        '400':
          description: illegal query arg value (e.g., time is not a date-time)
        '403':
          description: not authorized
        '404':
          description: index or portfolio does not exist
      summary: Get the portfolio of a MerQube index over time
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/portfolio_allocations:
    get:
      description: Get the allocations of a MerQube index
      operationId: index_portfolio_allocations
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  results:
                    items:
                      properties:
                        date:
                          description: date
                          example: '2005-07-15T00:00:00'
                          type: string
                        id:
                          description: currently, the date
                          example: '2005-07-15T00:00:00'
                          type: string
                        portfolio:
                          description: object
                          example:
                            'OPTION: SPY:PUT:116.66:2006-07-21:BUY': 8.143322475570033,
                            OPTION:SPY:CALL:0.0:2006-07-21:BUY: 8.143322475570033,
                            OPTION:SPY:CALL:0.0:2007-07-20:BUY: null,
                          type: object
                      type: object
                    type: array
                type: object
          description: 200 response
        '403':
          description: not authorized to see this namespace
        '404':
          description: index or portfolio does not exist
      summary: Get the allocations of a MerQube index
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/run_state:
    get:
      description: get the latest run state of the index. May be enhanced in the future to support quering for a given eff_ts (e.g., historically).
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunState'
          description: OK
        '403':
          description: not authorized to see this index namespace
        '404':
          description: index or does not exist
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/stats:
    get:
      description: Returns stats associated with a specific MerQube index
      operationId: index_stats
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      - $ref: '#/components/parameters/startDateParam'
      - $ref: '#/components/parameters/endDateParam'
      - description: 'Metric to compute stats on (default: total_return)'
        in: query
        name: metric
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stats'
          description: 200 response
        '403':
          description: not authorized to see this namespace
        '404':
          description: index does not exist
      summary: Returns stats associated with a specific MerQube index
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/stats2:
    get:
      description: Returns stats associated with a specific MerQube index
      operationId: index_stats
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatsRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResponse'
          description: 200 response
        '403':
          description: not authorized to see this namespace
        '404':
          description: index does not exist
      summary: Returns stats associated with a specific MerQube index
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/target_portfolio:
    get:
      description: get the timeseries of target portfolios for an index
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      - $ref: '#/components/parameters/startDateParam'
      - $ref: '#/components/parameters/endDateParam'
      - description: a comma seperated list of portfolio statuses to filter by
        in: path
        name: statuses
        required: false
        schema:
          default: FINAL
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  results:
                    items:
                      properties:
                        eff_ts:
                          $ref: '#/components/schemas/IsoTS'
                        target_portfolio:
                          $ref: '#/components/schemas/BasketPortfolio'
                      type: object
                    type: array
                type: object
          description: OK
        '403':
          description: not authorized to see this namespace
        '404':
          description: index or portfolio does not exist
      tags:
      - index
    put:
      description: replace the portfolio for this index. Will eventually but not immediately affect /index/uuid/portfolio.
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BasketPortfolioPutIn'
      responses:
        '200':
          description: OK, portfolio successfully written and validated.
        '400':
          description: bad portfolio or request
        '403':
          description: not authorized
        '404':
          description: index does not exist
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  /index/{uuid}/target_portfolio/{target_portfolio_uuid}:
    delete:
      description: Deletes an existing target portfolio
      responses:
        '200':
          description: OK, target_portfolio deleted
        '403':
          description: Not authorized
        '404':
          description: Index or target_portfolio with the provided UUIDs does not exist
      tags:
      - index
    get:
      description: Get an existing target portfolio
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  eff_ts:
                    $ref: '#/components/schemas/IsoTS'
                  target_portfolio:
                    $ref: '#/components/schemas/BasketPortfolio'
                type: object
          description: OK, portfolio successfully retrieved
        '400':
          description: Bad request
        '403':
          description: Not authorized
        '404':
          description: Index or target portfolio does not exist
      tags:
      - index
    patch:
      description: Update an existing target portfolio
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BasketPortfolioPatchIn'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasketPortfolio'
          description: OK, portfolio successfully updated
        '400':
          description: Bad request
        '403':
          description: Not authorized
        '404':
          description: Index or target portfolio does not exist
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  index/{uuid}/identifier/{provider}:
    post:
      description: Add an identifier to an index
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      - $ref: '#/components/parameters/providerParam'
      requestBody:
        content:
          application/json:
            schema:
            - $ref: '#/components/schemas/IndexIdentifierUUIDPost'
      responses:
        '200':
          description: OK
        '400':
          description: bad request
        '403':
          description: not authorized
        '404':
          description: index does not exist
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
  index/{uuid}/identifier/{provider}/{identifier_name}:
    delete:
      description: Delete an identifier from an index
      parameters:
      - $ref: '#/components/parameters/uuidParam'
      - $ref: '#/components/parameters/providerParam'
      - $ref: '#/components/parameters/identifierNameParam'
      responses:
        '200':
          description: OK
        '403':
          description: not authorized
        '404':
          description: index or identifier does not exist
      tags:
      - index
    servers:
    - description: Production server
      url: https://api.merqube.com
    - description: Testing server for next generation features
      url: https://api.staging.merqube.com
components:
  schemas:
    PortfolioUom:
      description: Used to indicate if portfolio amounts are absolute or relative. weight indicates portfolio amounts are relative weights units indicates portfolio amounts are absolute values, e.g. shares or number of contracts
      enum:
      - SHARES
      - WEIGHT
      title: PortfolioUom
      type: string
    MetricsSchema:
      properties:
        data_type:
          enum:
          - string
          - number64
          - datetime64
          - int64
          - bool
          - object
          type: string
        description:
          description: a description of what this metric represents
          type: string
        name:
          description: metric name
          type: string
        object_schema:
          description: optional - this supports complex objects, ie you can specify the  metric is of this schema. THis allows you to upload a json schema itself of this metric. THis is for downstream users of this metric.
          type: object
      required:
      - data_type
      - description
      - name
      type: object
    CrudExtra:
      additionalProperties: false
      properties:
        id:
          type: string
        namespace:
          type: string
        status:
          $ref: '#/components/schemas/Status'
      required:
      - id
      - status
      - namespace
      type: object
    BasketPortfolioRaw:
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/BasketPortfolioPutIn'
      - properties:
          created_ts:
            $ref: '#/components/schemas/IsoTS'
          finalized_ts:
            $ref: '#/components/schemas/IsoTS'
          id:
            example: 0000699a-fcd7-45d4-8ce4-064a4ffeced0
            type: string
          status:
            $ref: '#/components/schemas/PortfolioStatus'
            default: FINAL
          status_change_reason:
            type: string
        required:
        - id
        - status
        type: object
      description: 'Target Portfolio. Supports equities, futures, and options. This object captures all information needed to execute externally defined rebalances. This is the raw data from the data store layer.

        '
      type: object
    FsymEquityPosition:
      allOf:
      - $ref: '#/components/schemas/BasketPosition'
      - $ref: '#/components/schemas/FsymSpecific'
      description: Equity position, identified by a FSYM + country code
    IdentifierUUIDPost:
      additionalProperties: false
      description: Identifier for a given provider. Will be referenced via the name field of the Identifier section
      properties:
        display_name:
          type: string
        index_name:
          type: string
        metric:
          type: string
        name:
          description: unique name among all other Identifiers of the provider resource type.
          pattern: ^[^!*'() ;:@&=+$,/?%#\[\]]
          type: string
        namespace:
          type: string
        num_days:
          description: Number of days to disseminate data for
          minimum: 0
          type: integer
        provider_kwargs:
          anyOf:
          - $ref: '#/components/schemas/BloombergProviderKwargs'
          - $ref: '#/components/schemas/ReutersProviderKwargs'
          - $ref: '#/components/schemas/SecapiProviderKwargs'
          - $ref: '#/components/schemas/NasdaqProviderKwargs'
        rounding_decimals:
          description: If rounding_type=standard, corresponds to number of decimal places to round to. If rounding_type=sigfig, corresponds to number of significant figures to round to.
          type: integer
        rounding_type:
          default: standard
          description: Type of rounding to apply to the disseminated data. standard = no

# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/merqube/refs/heads/main/openapi/merqube-index-api-openapi.yml