Gist Answers API (Prorata API Service)

openapi: 3.0.0
info:
  title: Prorata API Service
  version: 1.0.0
  description: API for chat, threads, questions, and publisher management
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Add your API key with the Bearer prefix (e.g., "Bearer YOUR-API-KEY")
  headers:
    X-RateLimit-Limit:
      description: Maximum requests allowed in the current time window
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Number of requests remaining in the current time window
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix timestamp when the rate limit resets
      schema:
        type: integer
servers:
- url: https://api.gist.ai
  description: 'Gist / ProRata API production (verified: GET https://api.gist.ai/v1/health -> 200 application/json)'
paths:
  /v1/chat/attributions/{threadId}/{turnId}:
    get:
      summary: Get attributions for a chat response
      description: '**Authentication Required**: This endpoint requires a valid API key.


        **Important**: This endpoint is part of a sequential flow:

        1. First call `/v1/chat` to create a chat and get `threadId` and `turnId`

        2. Then get `/v1/chat/response/{threadId}/{turnId}` for the AI''s response

        3. Finally use this endpoint to get attributions for that response


        Returns a list of attributions and source documents used in the response.


        **Rate Limiting**: This endpoint is subject to rate limiting based on your organization''s settings.

        The response headers will include:

        - `X-RateLimit-Limit`: Maximum requests allowed in the current time window

        - `X-RateLimit-Remaining`: Number of requests remaining

        - `X-RateLimit-Reset`: Unix timestamp when the rate limit resets

        '
      tags:
      - Chat
      security:
      - apiKeyAuth: []
      parameters:
      - in: header
        name: X-User-ID
        required: true
        schema:
          type: string
        description: Unique identifier for the user making the request
      - in: path
        name: threadId
        required: true
        schema:
          type: string
        description: Thread ID from your previous /v1/chat response
      - in: path
        name: turnId
        required: true
        schema:
          type: string
        description: Turn ID from your previous /v1/chat response
      responses:
        '200':
          description: List of attributions for the response
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  credit_dist:
                    type: object
                    description: Map of source URLs to their attribution percentages
                    additionalProperties:
                      type: number
                    example:
                      string: 0
                  domain_credit_dist:
                    type: object
                    description: Map of domains (e.g., example.com) to their attribution percentages
                    additionalProperties:
                      type: number
                    example:
                      string: 0
                  document_credit_dist:
                    type: object
                    description: Map of document IDs (SHA-256 hashes) to their attribution percentages
                    additionalProperties:
                      type: number
                    example:
                      string: 0
                  publisher_credit_dist:
                    type: object
                    description: Map of publisher UUIDs to their attribution percentages
                    additionalProperties:
                      type: number
                    example:
                      string: 0
        '400':
          description: Invalid thread ID or turn ID format
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Thread, turn, or attributions not found
        '429':
          description: Too Many Requests - Your request was rejected due to rate limit restrictions
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Too Many Requests
                  message:
                    type: string
                    example: Rate limit exceeded
                  statusCode:
                    type: integer
                    example: 429
        '500':
          description: Internal server error
  /v1/chat:
    post:
      summary: Create a new chat
      description: '**Authentication Required**: This endpoint requires a valid API key.

        Please click the "Authorize" button and enter your API key before testing.


        Creates a new chat thread or continues an existing one with the provided prompt.


        **Rate Limiting**: This endpoint is subject to rate limiting based on your organization''s settings.

        The response headers will include:

        - `X-RateLimit-Limit`: Maximum requests allowed in the current time window

        - `X-RateLimit-Remaining`: Number of requests remaining

        - `X-RateLimit-Reset`: Unix timestamp when the rate limit resets

        '
      tags:
      - Chat
      security:
      - apiKeyAuth: []
      parameters:
      - in: header
        name: X-User-ID
        required: true
        schema:
          type: string
        description: Unique identifier for the user making the request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - user_prompt
              properties:
                thread_id:
                  type: string
                  description: Optional thread ID for continuing a conversation
                user_prompt:
                  type: string
                  description: The user's question or prompt
                temperature:
                  type: number
                  minimum: 0
                  maximum: 1
                  default: 0.7
                  description: Controls randomness in the response (Currently not supported - this parameter will be ignored)
                inclusion_list:
                  type: array
                  items:
                    type: string
            examples:
              newChat:
                summary: Start a new chat
                value:
                  thread_id: ''
                  user_prompt: Why is the sky blue?
                  temperature: 0.7
              continueChat:
                summary: Continue existing chat
                value:
                  thread_id: 123e4567-e89b-12d3-a456-426614174000
                  user_prompt: What about during sunset?
                  temperature: 0.7
      responses:
        '200':
          description: Chat created successfully
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  thread_id:
                    type: string
                    description: Unique thread identifier
                  turn_id:
                    type: number
                    description: Turn number in the conversation
                  thread_title:
                    type: string
                    description: Optional title for the thread
                  citations:
                    type: object
                    description: Citation information for the response
                  attributions:
                    type: object
                    description: Attribution information for the response
                  response_time:
                    type: number
                    description: Response generation time in milliseconds
              examples:
                success:
                  summary: Successful response
                  value:
                    thread_id: 123e4567-e89b-12d3-a456-426614174000
                    turn_id: 1
                    thread_title: Discussion about the sky
                    citations: {}
                    attributions: {}
                    response_time: 1234
        '400':
          description: Bad request - Missing user_prompt
        '401':
          description: Unauthorized - Invalid or missing authentication
        '429':
          description: Too Many Requests - Your request was rejected due to rate limit restrictions
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Too Many Requests
                  message:
                    type: string
                    example: Rate limit exceeded
                  statusCode:
                    type: integer
                    example: 429
        '500':
          description: Internal server error
  /v1/chat/citations/{threadId}/{turnId}:
    get:
      summary: Get citations for a chat response
      description: '**Authentication Required**: This endpoint requires a valid API key.


        **Important**: This endpoint is part of a sequential flow:

        1. First call `/v1/chat` to create a chat and get `threadId` and `turnId`

        2. Then get `/v1/chat/response/{threadId}/{turnId}` for the AI''s response

        3. Finally use this endpoint to get citations for that response


        Returns a list of citations and source documents used in the response.


        **Rate Limiting**: This endpoint is subject to rate limiting based on your organization''s settings.

        The response headers will include:

        - `X-RateLimit-Limit`: Maximum requests allowed in the current time window

        - `X-RateLimit-Remaining`: Number of requests remaining

        - `X-RateLimit-Reset`: Unix timestamp when the rate limit resets

        '
      tags:
      - Chat
      security:
      - apiKeyAuth: []
      parameters:
      - in: header
        name: X-User-ID
        required: true
        schema:
          type: string
        description: Unique identifier for the user making the request
      - in: path
        name: threadId
        required: true
        schema:
          type: string
        description: Thread ID from your previous /v1/chat response
      - in: path
        name: turnId
        required: true
        schema:
          type: string
        description: Turn ID from your previous /v1/chat response
      responses:
        '200':
          description: List of citations for the response
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    citationId:
                      type: number
                      description: Unique identifier for the citation
                    id:
                      type: string
                      description: Document identifier
                    publisher_id:
                      type: string
                      description: Publisher identifier
                    url:
                      type: string
                      description: Source document URL
                    domain:
                      type: string
                      description: Publisher domain
                    title:
                      type: string
                      description: Document title
                    date:
                      type: string
                      description: Publication date
                    source:
                      type: string
                      description: Source name
                    first_words:
                      type: string
                      description: Opening text of the document
                    image:
                      type: string
                      description: Document image URL
                    favicon:
                      type: string
                      description: Publisher favicon URL
                    favicon40:
                      type: string
                      description: 40px favicon URL
                    favicon24:
                      type: string
                      description: 24px favicon URL
        '400':
          description: Invalid thread ID or turn ID format
        '401':
          description: Unauthorized - Invalid or missing API key
        '404':
          description: Thread, turn, or citations not found
        '429':
          description: Too Many Requests - Your request was rejected due to rate limit restrictions
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Too Many Requests
                  message:
                    type: string
                    example: Rate limit exceeded
                  statusCode:
                    type: integer
                    example: 429
        '500':
          description: Internal server error
  /v1/chat/completions:
    post:
      summary: Stream AI completions (Experimental)
      description: '**Authentication Required**: This endpoint requires a valid API key.

        Please click the "Authorize" button and enter your API key before testing.


        Streams AI-generated completions based on provided messages. (Experimental)

        Each generating event contains only the new content (delta) to append.


        **Conversation Handling**: To continue a conversation, include an assistant message with metadata from the previous
        response.


        **Rate Limiting**: This endpoint is subject to rate limiting based on your organization''s settings.

        The response headers will include:

        - `X-RateLimit-Limit`: Maximum requests allowed in the current time window

        - `X-RateLimit-Remaining`: Number of requests remaining

        - `X-RateLimit-Reset`: Unix timestamp when the rate limit resets

        '
      tags:
      - Chat
      security:
      - apiKeyAuth: []
      parameters:
      - in: header
        name: X-User-ID
        required: true
        schema:
          type: string
        description: Unique identifier for the user making the request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - messages
              properties:
                messages:
                  type: array
                  items:
                    oneOf:
                    - type: object
                      required:
                      - role
                      - content
                      properties:
                        role:
                          type: string
                          enum:
                          - user
                          description: Role of the message sender
                        content:
                          type: string
                          description: User message content
                    - type: object
                      required:
                      - role
                      - metadata
                      properties:
                        role:
                          type: string
                          enum:
                          - assistant
                          description: Role of the assistant
                        content:
                          type: string
                          description: Optional assistant message content
                        metadata:
                          type: object
                          required:
                          - thread_id
                          - turn_id
                          properties:
                            thread_id:
                              type: string
                              description: Thread ID from previous response metadata
                            turn_id:
                              oneOf:
                              - type: string
                              - type: number
                              description: Turn ID from previous response metadata
                temperature:
                  type: number
                  minimum: 0
                  maximum: 1
                  default: 0.7
                  description: Controls randomness in the response (Currently not supported - this parameter will be ignored)
                stream:
                  type: boolean
                  default: true
                  description: Whether to stream the response (Currently not configurable - responses are always streamed)
            examples:
              newConversation:
                summary: Starting a new conversation
                value:
                  messages:
                  - role: user
                    content: Why is the sky blue?
                  temperature: 0.7
              continueConversation:
                summary: Continuing an existing conversation
                value:
                  messages:
                  - role: user
                    content: What about during sunset?
                  - role: assistant
                    metadata:
                      thread_id: 123e4567-e89b-12d3-a456-426614174000
                      turn_id: 1
                  temperature: 0.7
      responses:
        '200':
          description: Successful response with streaming content
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            text/event-stream:
              schema:
                type: object
                properties:
                  event:
                    type: string
                    enum:
                    - metadata
                    - generating
                    - complete
                    description: Event type - metadata for thread info, generating for partial responses, complete for final
                  data:
                    type: object
                    properties:
                      threadId:
                        type: string
                        description: Unique thread identifier (only in metadata event)
                      turnId:
                        type: string
                        description: Turn identifier (only in metadata event)
                      title:
                        type: string
                        description: Optional thread title (only in metadata event)
                      content:
                        type: string
                        description: The response text chunk (only in generating/complete events)
                      response_time:
                        type: number
                        description: Total response time in ms (only in complete event)
              examples:
                newConversationResponse:
                  summary: Response to a new conversation
                  value: 'event: metadata

                    data: {"threadId": "123e4567-e89b-12d3-a456-426614174000", "turnId": "1", "title": "Why is the sky blue?"}


                    event: generating

                    data: {"content": "The"}


                    event: generating

                    data: {"content": " sky"}


                    event: generating

                    data: {"content": " appears"}


                    event: generating

                    data: {"content": " blue"}


                    event: complete

                    '
                continuedConversationResponse:
                  summary: Response to a continued conversation
                  value: 'event: metadata

                    data: {"threadId": "123e4567-e89b-12d3-a456-426614174000", "turnId": "2", "title": "Why is the sky blue?"}


                    event: generating

                    data: {"content": "During"}


                    event: generating

                    data: {"content": " sunset"}


                    event: generating

                    data: {"content": ","}


                    event: generating

                    data: {"content": " the"}


                    event: generating

                    data: {"content": " sky"}


                    event: complete

                    '
        '400':
          description: Bad request - Missing required fields
        '401':
          description: Unauthorized - Invalid or missing authentication
        '429':
          description: Too Many Requests - Your request was rejected due to rate limit restrictions
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Too Many Requests
                  message:
                    type: string
                    example: Rate limit exceeded
                  statusCode:
                    type: integer
                    example: 429
        '500':
          description: Internal server error
  /v1/health:
    get:
      tags:
      - Health
      summary: Get detailed service health status
      description: '**Public Endpoint**: This endpoint is publicly accessible and does not require authentication.

        Returns detailed health status of the service and its dependencies.

        '
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - timestamp
                - uptime
                - services
                properties:
                  status:
                    type: string
                    enum:
                    - healthy
                    - unhealthy
                    example: healthy
                  timestamp:
                    type: string
                    format: date-time
                    example: '2024-02-05T16:42:28.232Z'
                  uptime:
                    type: number
                    example: 12.415816542
                  services:
                    type: object
                    properties:
                      database:
                        type: object
                        properties:
                          status:
                            type: string
                            enum:
                            - operational
                            - failed
                      redis:
                        type: object
                        properties:
                          status:
                            type: string
                            enum:
                            - operational
                            - failed
                      inference:
                        type: object
                        properties:
                          status:
                            type: string
                            enum:
                            - operational
                            - failed
                          error:
                            type: string
                            example: fetch failed
                      publishers:
                        type: object
                        properties:
                          status:
                            type: string
                            enum:
                            - operational
                            - failed
                      questions:
                        type: object
                        properties:
                          status:
                            type: string
                            enum:
                            - operational
                            - failed
        '500':
          description: Internal server error
  /v1/publishers:
    get:
      summary: Get publisher information
      description: '**Authentication Required**: This endpoint requires a valid API key.


        Returns information about the publisher group associated with your organization, including

        the publisher group ID, name, description, and a list of publisher IDs.


        **Caching**: This endpoint uses Redis caching with a TTL of 1 hour.

        - First request fetches from the external service and caches the response

        - Subsequent requests within 1 hour return the cached data

        - Cache headers are included in the response

        '
      tags:
      - Publishers
      security:
      - apiKeyAuth: []
      parameters:
      - in: header
        name: X-User-ID
        required: true
        schema:
          type: string
        description: Unique identifier for the user making the request
      responses:
        '200':
          description: Publisher group information
          headers:
            Cache-Control:
              schema:
                type: string
              description: Cache control header (e.g., "public, max-age=3600")
            Expires:
              schema:
                type: string
              description: Expiration date of the cached response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Publisher group ID
                  name:
                    type: string
                    description: Publisher group name
                  description:
                    type: string
                    nullable: true
                    description: Publisher group description
                  publishers:
                    type: array
                    items:
                      type: string
                      format: uuid
                    description: Array of publisher IDs
        '401':
          description: Unauthorized - Invalid or missing API key
        '500':
          description: Internal server error
  /v1/publishers/{id}:
    get:
      summary: Get specific publisher details
      description: '**Authentication Required**: This endpoint requires a valid API key.


        Returns detailed information about a specific publisher identified by its ID. The publisher must be

        part of the publisher group associated with your organization.


        **Caching**: This endpoint uses Redis caching with a TTL of 1 hour.

        - First request fetches from the external service and caches the response

        - Subsequent requests within 1 hour return the cached data

        - Cache headers are included in the response

        '
      tags:
      - Publishers
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: Publisher ID to retrieve details for
      - in: header
        name: X-User-ID
        required: true
        schema:
          type: string
        description: Unique identifier for the user making the request
      responses:
        '200':
          description: Publisher details
          headers:
            Cache-Control:
              schema:
                type: string
              description: Cache control header (e.g., "public, max-age=3600")
            Expires:
              schema:
                type: string
              description: Expiration date of the cached response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Publisher ID
                  name:
                    type: string
                    description: Publisher name
                  description:
                    type: string
                    nullable: true
                    description: Publisher description
                  enabled:
                    type: boolean
                    description: Whether the publisher is enabled
                  config:
                    type: object
                    properties:
                      domain:
                        type: string
                        description: Publisher domain
                      location:
                        type: string
                        description: Publisher location
                      private_role_name:
                        type: string
                        description: Private role name
                    description: Publisher configuration
                  sites:
                    type: array
                    items:
                      type: string
                      format: uuid
                    description: Array of site IDs
        '400':
          description: Bad request - Missing publisher ID
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Publisher not in organization's publisher group
        '404':
          description: Publisher not found
        '500':
          description: Internal server error
  /v1/questions/recommended:
    get:
      summary: Get recommended questions
      description: '**Authentication Required**: This endpoint requires a valid API key.


        Returns a list of recommended questions for users to ask.


        **Rate Limiting**: This endpoint is subject to rate limiting based on your organization''s settings.

        The response headers will include:

        - `X-RateLimit-Limit`: Maximum requests allowed in the current time window

        - `X-RateLimit-Remaining`: Number of requests remaining

        - `X-RateLimit-Reset`: Unix timestamp when the rate limit resets

        '
      tags:


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