openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Create API
  description: Allow clients to fetch precalculated Analytics through predeterministic URLs.
  contact:
    name: FactSet Research Systems
    url: https://developer.factset.com/contact
    email: api@factset.com
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.0.0
servers:
- url: https://api.factset.com
  description: Production
- url: https://api-sandbox.factset.com
  description: Sandbox
security:
- basicAuth: []
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'
  /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
  /v1/create-book:
    post:
      tags:
      - Create
      summary: Factset Kicks Off Request to Create a Book With Reports of Your Choice
      description: This end point retrieves book name and book_id for the PDF book you create. All the book options such as name of the book, ticker, pagination options, 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/createBookPostRequest'
      responses:
        '200':
          description: Successful response contains book name and book ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enable_Book_Info'
        '400':
          description: Invalid ticker/section_id/report_id
        '401':
          description: Missing or invalid authentication
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/create-book-from-template:
    post:
      tags:
      - Create
      summary: Factset Kicks Off Request to Create a Book With Template
      description: This endpoint retrieves book status, book name, and book ID for ticker requested in JSON format. This end-point excepts ticker and template_id as inputs. If the template_id input is not used, a book will be created with FactSet's default template.</br></br>Please try out the below template ids to quickly get the FactSet curated books</br></br>Company Quick Book - <b>g_20210415065838185</b></br>Post-Earnings Call - <b>g_20210415070044785</b> </br>Public Information Book(PIB) - <b>g_20210415070353151</b></br></br> Take a look at the example books attached under API documentation below.</br></br>If you are scheduling Post Earnings Call curated book, please note that in contains Corrected Transcript that takes a little while to be available.</br> </br>Once a Raw Transcript is published, FactSet's editors review the call to produce a Corrected Transcript. They listen to the entire audio file again to confirm that all of the terms and numbers are correctly transcribed. FactSet aims to publish a Corrected Transcript within six times the length of the event, measured from the beginning of the event. That means for a typical one-hour call, FactSet will produce a Corrected Transcript within approximately five hours of the call's completion. Visit [OA 13208](https://my.apps.factset.com/oa/pages/13208)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createBookFromTemplatePostRequest'
      responses:
        '200':
          description: Successful response contains request status, book name, and book ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enable_Book_Info_From_Template'
        '400':
          description: Invalid ticker or Unknown error
        '401':
          description: Missing or invalid authentication
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    createBookPostRequest:
      title: Request Body for Post Request
      description: The request body allows users to input the name of the book, ticker
      type: object
      properties:
        book_name:
          type: string
          description: name of the book
          example: Company Book for FDS
        ticker:
          type: string
          description: Identifier.
          example: FDS-US
        pagination:
          type: object
          description: options for pagination
          properties:
            cover:
              example: 'true'
            divider:
              example: 'true'
            toc:
              example: 'true'
          example: example_value
        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: []
    createBookFromTemplatePostRequest:
      title: Request Body for Post Request
      description: It is a request body to allow users to input ticker and template id.
      type: object
      properties:
        ticker:
          type: string
          description: ticker
          example: FDS-US
        template_id:
          type: string
          description: Template ID
          example: g_20210415065838185
    403ForbiddenError:
      description: Error response for a user without entitlements to the API.
      type: string
    Enable_Book_Info:
      title: Book Information Request
      description: Request to enable book information for the client.
      type: object
      properties:
        bookName:
          type: string
          description: Report Name
          example: Apple Inc.
        bookID:
          type: string
          description: Book ID
          example: 20200317133713790
    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
    401UnauthorizedError:
      description: Error response for a user without authentication to use the API.
      type: string
    Error:
      description: Wrapper containing metadata and appropriate errors as thrown by the API
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
    RateLimitExceededError:
      description: Error response when rate limit has been exceeded.
      type: object
      properties:
        message:
          type: string
          enum:
          - API rate limit exceeded
    Enable_Book_Info_From_Template:
      title: Book Information Request
      description: Request to enable book information for the client.
      type: object
      properties:
        status:
          type: string
          description: Request status
          example: OK
        bookName:
          type: string
          description: Report Name
          example: Apple Inc.
        bookID:
          type: string
          description: Book ID
          example: 20200317133713790
    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
    ErrorObject:
      description: Represents a single error, with error name and identifiers
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        code:
          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
  examples:
    401UnauthorizedErrorExample:
      value: Authentication Failed
    CreateChatResponseExample:
      value:
        data:
          conversationId: 9c1031c2-5463-47ae-81b3-126a68f0c2a6
          status: executing
    RateLimitExceededErrorExample:
      value:
        message: API rate limit exceeded
    403ForbiddenErrorExample:
      value: 'Client does not have the required CACCESS: {00QAI}, Request key: 65CA96B3129489A6'
    CreateChatRequestExample:
      value:
        data:
          query: What is Tesla's enterprise value?
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation