SimplyPut API Ask Endpoint

Overview

The SimplyPut API provides a flexible way to query and receive various types of responses including graphs, tables, and direct AI responses. This document outlines the usage of the SimplyPut.ai API endpoint.

Prerequisites

API Key: Ensure you have a valid API key ( x-api-key ) for authentication.
Organization ID: Know your organization ID ( org_id ), which is unique to your account.

Making a Request

Use the curl command to send POST requests to the API. The basic structure of the request is as follows:

terminal

curl -X POST http://rest.simplyput.ai/org/<org id>/ask 
   -H "Content-Type: application/json" 
   -H "x-api-key: <api key>" 
   -d '{"question" :"<user question>"}'

Replace org id with your organization ID and api key with your API key. The user question is your query to the API.

Response Types

The API can return three main types of responses:

Graphing Example: This type of response returns data in a graphical format. The request should specify a question that leads to a data visualization outcome.
terminal
```
curl -X POST http://rest.simplyput.ai/org/<org id>/ask 
    -H "Content-Type: application/json" 
    -H "x-api-key: <api key>" 
    -d '{"question" :"How many units were sold for each city?"}'
```
This returns a JSON response with data and metadata needed to construct a graph, such as SQL query, explanation, and the data itself.
Table Results Example: This response type provides tabular data. It is suitable for queries that require detailed listings or summaries.
terminal
```
curl -X POST http://rest.simplyput.ai/org/<org id>/ask 
    -H "Content-Type: application/json" 
    -H "x-api-key: <api key>" 
    -d '{"question" :"show me the last 10 sales?"}'
```
The response includes a table with columns and rows, detailing the last 10 sales.
AI Response Example: For general queries or when the question does not fit into a graph or table format, the API provides a direct AI response.
terminal
```
curl -X POST http://rest.simplyput.ai/org/<org id>/ask 
    -H "Content-Type: application/json" 
    -H "x-api-key: <api key>" 
    -d '{"question" :"Hi there"}'
```
This will return a simple AI-generated message response.

Handling the Response

The JSON response contains various fields, including:

ai_response : The AI's interpretation and response to the query.
result : The main content of the response, which can be a graph, table, or problem statement.
suggestions : Follow-up questions or related queries suggested by the AI.

OpenAPI Spec

yaml

openapi: 3.0.0
info:
  title: SimplyPut.ai API
  version: 1.0.0
  description: API for querying and receiving responses in various formats including graphs, tables, and direct AI responses.

servers:
  - url: https://rest-stg.simplyput.ai

paths:
  /org/{orgId}/ask:
    post:
      summary: Post a question to the API
      operationId: postQuestion
      parameters:
        - name: orgId
          in: path
          required: true
          schema:
            type: string
          description: Organization ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                question:
                  type: string
                  description: User question to be processed by the API
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/GraphResponse'
                  - $ref: '#/components/schemas/TableResponse'
                  - $ref: '#/components/schemas/AiMessageResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

components:
  schemas:
    GraphResponse:
      type: object
      properties:
        ai_response:
          $ref: '#/components/schemas/AiResponse'
        result:
          type: object
          properties:
            Content:
              type: object
              properties:
                Graph:
                  $ref: '#/components/schemas/GraphContent'
            thread_id:
              type: string
            suggestions:
              type: array
              items:
                type: string
    TableResponse:
      type: object
      properties:
        ai_response:
          $ref: '#/components/schemas/AiResponse'
        result:
          type: object
          properties:
            Content:
              type: object
              properties:
                Table:
                  $ref: '#/components/schemas/TableContent'
            thread_id:
              type: string
            suggestions:
              type: array
              items:
                type: string
    AiMessageResponse:
      type: object
      properties:
        ai_response:
          $ref: '#/components/schemas/AiResponse'
        result:
          type: object
          properties:
            Content:
              type: object
              properties:
                Problem:
                  $ref: '#/components/schemas/ProblemContent'
            thread_id:
              type: string
            suggestions:
              type: array
              items:
                type: string
    AiResponse:
      type: object
      properties:
        question_id:
          type: string
        created_at:
          type: string
          format: date-time
        Resp:
          type: object
    GraphContent:
      type: object
      properties:
        columns:
          type: array
          items:
            $ref: '#/components/schemas/Column'
        rows:
          type: array
          items:
            type: object
            properties:
              row:
                type: object
    TableContent:
      type: object
      properties:
        columns:
          type: array
          items:
            $ref: '#/components/schemas/Column'
        rows:
          type: array
          items:
            type: object
            properties:
              row:
                type: object
    ProblemContent:
      type: object
      properties:
        title:
          type: string
        detail:
          type: string
    Column:
      type: object
      properties:
        name:
          type: string
        display_name:
          type: string
        simple_type:
          type: integer

security:
  - ApiKeyAuth: []

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: x-api-key