Factset Create API

openapi: 3.2.0
info:
  title: Factset Create API
  version: '1.0'
  description: 'Operations tagged Create across 2 of this provider''s published API definitions: conversational-api-powered-by-mercury-openapi-original.yml, factset-bookbuilder-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.factset.com/conversational/v0
- url: https://api.factset.com/book-builder-api/
  description: Base URL Production
tags:
- name: Create
paths:
  /create:
    post:
      operationId: createChat
      summary: Factset Create a chat request for a given natural language query.
      description: "Returns a chat ID for polling the response to a natural language query for financial data.\n\n  This endpoint is an interface for initializing a request for an answer from FactSet Mercury, our large language model for surfacing FactSet datasets through conversational natural language queries. Use the `/create` endpoint to start generating responses for one-off questions. Responses contain a chat ID and status for the chat process.\n"
      tags:
      - Create
      requestBody:
        description: Natural language query for FactSet data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatRequest'
            examples:
              Example question:
                $ref: '#/components/examples/CreateChatRequestExample'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatResponse'
              examples:
                Example question:
                  $ref: '#/components/examples/CreateChatResponseExample'
          headers:
            Location:
              description: Relative URL to check the status of the request.
              schema:
                type: string
                enum:
                - /status
            Api-Supported-Versions:
              description: Comma-separated list of supported major versions.
              schema:
                type: string
              example: '0'
            Api-Version:
              description: Full semantic version of the API.
              schema:
                type: string
              example: 0.1.0
            RateLimit-Limit:
              description: Request limit per minute.
              schema:
                type: integer
              example: 50
            RateLimit-Remaining:
              description: Number of available requests in the minute.
              schema:
                type: integer
              example: 49
            RateLimit-Reset:
              description: Time remaining (in seconds) until request limit is reset.
              schema:
                type: integer
              example: 24
            X-DataDirect-Request-Key:
              description: FactSet request ID.
              schema:
                type: string
              example: 65C6BC290A11FB4F
            X-RateLimit-Limit-Hour:
              description: Request limit per hour.
              schema:
                type: integer
              example: 1000
            X-RateLimit-Remaining-Hour:
              description: Number of available requests in the hour.
              schema:
                type: integer
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - You are not properly authenticated for use of this API. Please make sure you are logged in to the developer portal or using a valid API key (managed [here](https://developer.factset.com/manage-api-keys)) for access. If you believe you are seeing this message in error, please reach out to your FactSet Support Team representative.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/401UnauthorizedError'
              examples:
                Example error:
                  $ref: '#/components/examples/401UnauthorizedErrorExample'
        '403':
          description: Forbidden - You do not have the entitlements enabled for this service. Please reach out to your FactSet Support Team representative to receive the proper entitlements.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/403ForbiddenError'
              examples:
                Example error:
                  $ref: '#/components/examples/403ForbiddenErrorExample'
        '429':
          description: Too Many Requests - The /create endpoint is currently rate-limited to 50 requests per minute and 1000 requests per hour for an individual organization. If you are receiving an unexpected amount of these errors, please contact the API team at [genai.offplatform@factset.com](genai.offplatform@factset.com).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
              examples:
                Example error:
                  $ref: '#/components/examples/RateLimitExceededErrorExample'
          headers:
            RateLimit-Limit:
              description: Request limit per minute.
              schema:
                type: integer
              example: 50
            RateLimit-Remaining:
              description: Number of available requests.
              schema:
                type: integer
              example: 49
            RateLimit-Reset:
              description: Time remaining (in seconds) until request limit is reset.
              schema:
                type: integer
              example: 24
            Retry-After:
              description: How long (in seconds) to wait before attempting to send a new request.
              schema:
                type: integer
              example: 24
            X-DataDirect-Request-Key:
              description: FactSet request ID.
              schema:
                type: string
              example: 65C6BC290A11FB4F
            X-RateLimit-Limit-Hour:
              description: Request limit per hour.
              schema:
                type: integer
              example: 1000
            X-RateLimit-Remaining-Hour:
              description: Number of available requests in the hour.
              schema:
                type: integer
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - FactSetApiKey: []
      - FactSetOAuth2: []
    servers:
    - url: https://api.factset.com/conversational/v0
  /v1/create-template/:
    post:
      tags:
      - Create
      summary: Factset Kick Off Request to Create Template With Reports of Your Choice
      description: This end point retrieves template name and template_id of the template you create. All the book options such as name of the template, type, and reports can be specified in the request body. Please refer to the documentation for valid section ids and report ids.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createTemplatePostRequest'
      responses:
        '200':
          description: Successful response contains book name and book ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enable_Template_Info_Post'
        '400':
          description: Invalid template type/section_id/report_id
        '401':
          description: Missing or invalid authentication
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - BasicAuth: []
    servers:
    - url: https://api.factset.com/book-builder-api/
      description: Base URL Production
components:
  schemas:
    ErrorObject:
      description: Represents a single error, with error name and identifiers
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        code:
          type: string
    RateLimitExceededError:
      description: Error response when rate limit has been exceeded.
      type: object
      properties:
        message:
          type: string
          enum:
          - API rate limit exceeded
    403ForbiddenError:
      description: Error response for a user without entitlements to the API.
      type: string
    401UnauthorizedError:
      description: Error response for a user without authentication to use the API.
      type: string
    CreateChatRequest:
      description: Request body containing the query to be sent to the LLM
      properties:
        data:
          type: object
          required:
          - query
          properties:
            query:
              description: Natural language query for FactSet data
              type: string
              title: Query
      required:
      - data
      type: object
    CreateChatResponse:
      description: Response from `/create` containing the chat ID and executing status
      type: object
      properties:
        data:
          type: object
          properties:
            conversationId:
              type: string
              format: uuid
            status:
              type: string
              enum:
              - executing
    Error:
      description: Wrapper containing metadata and appropriate errors as thrown by the API
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
    createTemplatePostRequest:
      title: Request Body for Template Request
      description: The request body allows users to input the name of the template, ticker
      type: object
      properties:
        tmpl_name:
          type: string
          description: name of the template
          example: Quick Financials
        tmpl_type:
          type: string
          description: Type of the template (public,pc,pe,fi)
          example: public
        content:
          type: array
          description: Content sections
          items:
            oneOf:
            - type: object
              properties:
                section_id:
                  example: COMPANY_OVERVIEW
                reports:
                  type: array
                  items:
                    oneOf:
                    - type: string
                      example: COMPANY_SNAPSHOT_IB
                    - type: string
                      example: COMPANY_SNAPSHOT_IM
                    - type: string
                      example: ENTITY_STRUCTURE
          example: []
    Enable_Template_Info_Post:
      title: Template Request
      description: Request to enable template list information for the client.
      type: object
      properties:
        tmpl_id:
          type: string
          description: Template ID
          example: 20200623094829450
        tmpl_name:
          type: string
          description: Template name
          example: Financials
  examples:
    403ForbiddenErrorExample:
      value: 'Client does not have the required CACCESS: {00QAI}, Request key: 65CA96B3129489A6'
    CreateChatResponseExample:
      value:
        data:
          conversationId: 9c1031c2-5463-47ae-81b3-126a68f0c2a6
          status: executing
    RateLimitExceededErrorExample:
      value:
        message: API rate limit exceeded
    401UnauthorizedErrorExample:
      value: Authentication Failed
    CreateChatRequestExample:
      value:
        data:
          query: What is Tesla's enterprise value?
  securitySchemes:
    FactSetOAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.factset.com/as/token.oauth2
          scopes: {}
    FactSetApiKey:
      type: http
      scheme: basic
    BasicAuth:
      type: http
      scheme: basic
externalDocs:
  description: API Documentation
  url: https://developer.factset.com/api-catalog/conversational-api-powered-factset-mercury
x-refined-from:
- conversational-api-powered-by-mercury-openapi-original.yml
- factset-bookbuilder-api-openapi.yml