openapi: 3.0.1
info:
  title: Datagrok API
  version: 1.0.0
  description: API for managing Datagrok dataframes, dashboards, and functions.
servers:
  - url: https://public.datagrok.ai/api
  - url: https://dev.datagrok.ai/api
  - url: http://localhost:8082
paths:
  /public/v1/tables/{name}:
    get:
      summary: Download table from Datagrok
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: Identificator of a table in datagrok.
                       Can be either ID in UUID format or name, both can be accessed from table's context menu.
          example: project.table
      responses:
        '200':
          description: Table downloaded successfully, returned in CSV
          content:
            text/plain:
              schema:
                type: string
                description: Dataframe serialized to CSV
                example: col1,col2\nval1,val2

    post:
      summary: Upload table to Datagrok
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          example: project.table
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Table uploaded successfully
          content:
            application/json:
              schema:
                description: Identifiers of created table
                properties:
                  ID:
                    type: string
                    description: Identifier of the table
                  Grok name:
                    type: string
                    description: Grok name for the table
                  Markup:
                    type: string
                    description: Markup representation of the table
                  URL:
                    type: string
                    description: URL to access the table
  /public/v1/files/{connector}/{path}:
    get:
      summary: Download file from connector by path
      parameters:
        - name: connector
          in: path
          required: true
          schema:
            type: string
          example: system.demofiles
        - name: path
          in: path
          required: true
          schema:
            type: string
          example: demog.csv
      responses:
        '200':
          description: File downloaded successfully
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary 
    post:
      summary: Upload file to connector under path
      parameters:
        - name: connector
          in: path
          required: true
          schema:
            type: string
          description: Identificator of Datagrok connection.
        - name: path
          in: path
          required: true
          schema:
            type: string
          description: Path to file to create or overwrite.
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
        description: File body
      responses:
        '200':
          description: File uploaded successfully
  /public/v1/dashboards/{id}/shares:
    get:
      summary: Give access to dashboard for groups 
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: project
          description: Identifier of a dashboard
        - name: groups
          in: query
          required: true
          schema:
            type: string
            example: 'Developers'
          description: Comma-separated list of identifiers of groups or users to share with. 
        - name: access
          in: query
          required: false
          schema:
            type: string
            enum: [View, Edit]
            default: View
          description: Permissions for dashboard.
      responses:
        '200':
          description: Dashboard shared successfully
  /public/v1/dashboards/{name}/{table_ids}:
    post:
      summary: Create dashboard with tables
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
            example: newproject
          description: Dashboard name.
        - name: table_ids
          in: path
          required: true
          schema:
            type: string
            example: project.table,12345678-1111-2222-3333-1234567890123456
          description: Comma-separated list of table identificators.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              description: Layout file for project (optional).
      responses:
        '200':
          description: Dashboard created successfully
          content:
            application/json:
              schema:
                description: Identifiers of created dashboard
                properties:
                  ID:
                    type: string
                    description: Identifier of the dashboard
                  Grok name:
                    type: string
                    description: Grok name for the dashboard
                  Markup:
                    type: string
                    description: Markup representation of the dashboard
                  URL:
                    type: string
                    description: URL to access the dashboard
  /public/v1/{name}/call:
    post:
      summary: Perform a function call
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: Identifier of a function
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              format: json
              example: {intField: 1, stringField: "foo", dataframe: "dataframeId", column: "dataframeId/columnName"}
              description: JSON with invocation parameters. To pass Dataframes, you can use table identificators. To pass columns, you can use syntax "dataframeId/columnName".
      responses:
        '200':
          description: Function called successfully
          content:
            application/json:
              schema:
                type: string
                format: json
                example:
                  - 123
                  - "foo" 
                  - "col1,col2\nval1,val2"
                description: If function has one output parameter, returns exactly one value in json. Otherwise returns array of output values.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key must be prefixed with "Bearer "'
security:
  - ApiKeyAuth: []