openapi: 3.0.0
info:
  title: Jsonify Platform API
  version: '2.0.0'
  description: The Jsonify platform API lets you create and manage agent and data tasks.

servers:
  - url: https://api.jsonify.com
    description: Production server

paths:

  /api/v2/workflow/{workflow_id}/node/{node_id}/start:
    post:
      summary: Start a workflow with a webhook
      description: If a workflow has a webhook input action, you can start it with this API.
                   See the documentation in the workflow editor for details 
      security:
        - bearerAuth: []
      parameters:
        - name: workflow_id
          in: path
          required: true
          description: The GUID of a wokflow
          schema:
            type : string
            format: uuid
            example: 00000000-0000-0000-0000-000000000000
        - name: node_id
          in: path
          required: true
          description: The GUID of a wokflow
          schema:
            type : string
            format: uuid
            example: 00000000-0000-0000-0000-000000000000
      responses:
        '200':    # status code
          description: A task result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  /api/v2/workflow/{workflow_id}/latest.json:
    get:
      summary: Returns the latest result for a workflow
      security:
        - bearerAuth: []
      parameters:
        - name: workflow_id
          in: path
          required: true
          description: The workflow GUID
          schema:
            type : string
            format: uuid
            example: 00000000-0000-0000-0000-000000000000
      responses:
        '200':    # status code
          description: A workflow result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'


  /api/v2/results/{run_id}:
    get:
      summary: Retrieve the list of results of a workflow run, by run ID
      description: When an agent task runs, it creates a set of results. These results contain the findings from the agent, as well as metadata about the run.
      security:
        - bearerAuth: []
      parameters:
        - name: run_id
          in: path
          required: true
          description: The GUID of the workflow run
          schema:
            type: string
      responses:
        '200':    # status code
          description: A task result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  /api/v2/results/{run_id}/{result_id}:
    get:
      summary: Retrieve a single row from a workflow run, by run ID and row id
      description: When an agent task runs, it creates a set of results. These results contain the findings from the agent, as well as metadata about the run. This endpoint returns a single row.
      security:
        - bearerAuth: []
      parameters:
        - name: run_id
          in: path
          required: true
          description: The GUID of the workflow run
          schema:
            type: string
        - name: result_id
          in: path
          required: true
          description: The GUID of the workflow row
          schema:
            type: string
      responses:
        '200':    # status code
          description: A task result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

  /api/v2/results/{run_id}/first:
    get:
      summary: Retrieve the first row from a workflow run, by run ID and row id
      description: When an agent task runs, it creates a set of results. These results contain the findings from the agent, as well as metadata about the run. This endpoint returns the first row -- handy for workflows with only a single input
      security:
        - bearerAuth: []
      parameters:
        - name: run_id
          in: path
          required: true
          description: The GUID of the workflow run
          schema:
            type: string
      responses:
        '200':    # status code
          description: A task result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'


  /api/v2/result/{result_id}/extract_data:
    post:
      summary: Extract more data from a previous workflow run
      description: This re-scans a previous result wth a different data structure or directive. Requires either schema or directive, not both. Does not save the updated schema.
      security:
        - bearerAuth: []
      parameters:
        - name: result_id
          in: path
          required: true
          description: The result GUID
          schema:
            type: string
        - name: directive
          in: query
          required: false
          description: A human-readable directive to the AI about how to rephrase the data
          schema:
            type: string
          
      requestBody: 
        required: false
        content:
          application/json:
            schema:
                type : string
                description: A JSON schema to extract against. Must be valid JSON.
                example: {"name": "<the site name>"}
      responses:
        '200':    # status code
          description: A task result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'


  /api/v2/extract/start:
    post:
      summary: Turn a single URL to data without a workflow, ad-hoc
      description: Send an agent to extract data from a URL, optionally transforming it to a specific data schema
      security:
        - bearerAuth: []
      parameters:
        - name: url
          in: query
          required: true
          description: The URL to extract from
          example: https://example.com
          schema:
            type: string
        
        - name: additional_instructions
          in: query
          required: false
          description: Additional hints to the AI about what you want to extract
          example: I want a list of people
          schema:
            type: string

        - name: model
          in: query
          required: false
          description: The model to use. Large is slower but may be more accurate. Small is faster but may be less accurate. 
          schema:
            type: string
            enum: [auto, large, small]

        - name: extended
          in: query
          required: false
          description: Attempt to extract extended metadata, like URLs and images
          schema:
            type: boolean

        - name: cap_screenshots
          in: query
          required: false
          description: Increasing this will cause the AI to scroll further down the page
          schema:
            type: integer
            default: 5
                      
      requestBody: 
        required: false
        content:
          application/json:
            schema:
                type : string
                description: A JSON schema to extract against
                example: {"schema": {"name": "<the site name>"}}
      responses:
        '200':    # status code
          description: An in-progress result, which you can retrieve later with /result/{result_id}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'

    
  /api/v2/extract/result/{result_id}:
    get:
      summary: Return the result from an ad-hoc extract run
      description: This returns the agent result from a run previously started with /extract/start
      security:
        - bearerAuth: []
      parameters:
        - name: result_id
          in: path
          required: true
          description: The result GUID, from /extract/start
          schema:
            type: string
        
      responses:
        '200':    # status code
          description: A task result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'
        


  /api/v2/document/start:
    post:
      summary: Turn a single document to data without a workflow, ad-hoc.
      description: Send an agent to extract data from a document, optionally transforming it to a specific data schema. POST a file called 'file'. Must be a filetype readable from the dashboard document task (ie pdf or image)
      security:
        - bearerAuth: []
      consumes:
        - multipart/form-data
      parameters:
        - name: additional_instructions
          in: query
          required: false
          description: Additional hints to the AI about what you want to extract
          example: I want a list of people
          schema:
            type: string

        - name: model
          in: query
          required: false
          description: The model to use. Large is slower but may be more accurate. Small is faster but may be less accurate. 
          schema:
            type: string
            enum: [auto, large, small]

        - name: extended
          in: query
          required: false
          description: Attempt to extract extended metadata, like URLs and images
          schema:
            type: boolean

        - name: cap_screenshots
          in: query
          required: false
          description: Increasing this will cause the AI to scroll further down the page
          schema:
            type: integer
            default: 5
                      
      requestBody: 
        required: false
        content:
          application/json:
            schema:
                type : string
                description: A JSON schema to extract against
                example: {"schema": {"name": "<the site name>"}}
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':    # status code
          description: An in-progress result, which you can retrieve later with /result/{result_id}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'

  /api/v2/document/result/{result_id}:
    get:
      summary: Return the result from an ad-hoc document run
      description: This returns the agent result from a run previously started with /document/start
      security:
        - bearerAuth: []
      parameters:
        - name: result_id
          in: path
          required: true
          description: The result GUID, from /document/start
          schema:
            type: string
        
      responses:
        '200':    # status code
          description: A task result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'

        

  /api/v2/dataset/start:
    post:
      summary: Build a dataset based on a description, without a workflow, ad-hoc
      description: This sends an agent to build a dataset with a specific data schema
      security:
      - bearerAuth: []
      parameters:
        - name: query
          in: query
          required: true
          description: The query to make
          example: sama@openai.com
          schema:
            type: string

        - name: method
          in: query
          required: false
          description: Method to use, 'simple' or 'advanced'. Advanced may return better results, but uses more credits
          schema:
            type : string
            example: simple
                      
      requestBody: 
        required: true
        content:
          application/json:
            schema:
                type : string
                description: A JSON schema to extract against
                example: {"name": "<the users name>", "company": "<the users company>"}
      responses:
        '200':    # status code
          description: An in-progress result, which you can retrieve later with /result/{result_id}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'


  /api/v2/dataset/result/{result_id}:
    get:
      summary: Return the result from an ad-hoc dataset run
      description: This returns the agent result from a run previously started with /dataset/start
      security:
        - bearerAuth: []
      parameters:
        - name: result_id
          in: path
          required: true
          description: The result GUID, from /dataset/start
          schema:
            type: string
        
      responses:
        '200':    # status code
          description: A task result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'











components:

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT  # optional, for documentation purposes only

  schemas:
    AgentResponse:
      type: object
      properties:
        message:
          type: string
          example: started
        result:
          $ref: '#/components/schemas/Agent'
        success:
          type: boolean
          example: true
    
    Agent:
        type: object
        properties:
          id:
            $ref: '#/components/schemas/AgentID'

    AgentID:
        type: string
        format: uuid
        example: "e4ab8b5b-45bd-4e0f-8abb-5ce8a4db255e"
    ResultResponse:
      type: object
      properties:
        message:
          type: string
        result:
          $ref: '#/components/schemas/Result'
        success:
          type: boolean

    Result:
      type: object
      properties:
        changed:
          type: boolean
        credits:
          $ref: '#/components/schemas/Credits'
        details:
          $ref: '#/components/schemas/Details'
        json:
          $ref: '#/components/schemas/JsonData'
        screenshots:
          type: array
          items:
            type: string
            format: uri
        when:
          type: integer
          format: int64
        done:
          type: boolean
          description: whether the result has finished processing or not. poll until true.
        id:
          type: string

    Credits:
      type: object
      properties:
        remaining:
          type: integer
        used:
          type: integer

    Details:
      type: object
      properties:
        descr:
          type: string

    JsonData:
      type: object
      properties:
        data:
          type: boolean
    Task:
      type: object
      properties:
        category:
          type: string
        id:
          type: string
        inputs:
          type: array
          items:
            type: string
        last_updated:
          type: integer
          format: int64
        name:
          type: string
        schedule_interval:
          type: integer
          description: seconds
        when_added:
          type: integer
          description: unix timestamp
          nullable: true