Guides

Using REST APIs

Suggest Edits

Overview

Welcome to the Kognitos REST API documentation. This guide provides detailed information about the various endpoints available for automation triggering and status retrieval using Kognitos.

API Information


Access

To access the Kognitos REST API, an API key is required. The key should be included in the request headers as follows:

x-api-key="the api key given to you by Kognitos"

Endpoints

https://rest-api.app.kognitos.com


1. Start a New Automation Run

  • Endpoint: POST /v1/invoke/{share_id}
  • Description: Asynchronously starts an automation run given a share ID.
  • Path Parameters:
    • share_id (required)
  • Consumes: application/json
  • Request Body (optional):
    • body (object): Any parameters to start the run with.
  • Produces: application/json
  • Responses:
    • 201: Successful operation. Returns workerResponseAsync.
    • 400: Mismatch with department. Returns departmentMismatch.
    • 403: Invalid API key. Returns invalidApiKeyResponse.
    • 404: Invalid share ID. Returns invalidShareIdResponse.
    • 500: Internal server error. Returns internalServerError.

Example Response Body

{
  "worker_id": "6moof09dp5yjlpdunoth3m80s"
}

2. Get Status of an Automation Run

  • Endpoint: GET /v1/run/{worker_id}
  • Description: Gets the status and any outputs of an automation run.
  • Path Parameters:
    • worker_id (required)
  • Produces: application/json
  • Responses:
    • 200: Successful operation. Returns statusResponse.
    • 400: Mismatch with department. Returns departmentMismatch.
    • 403: Invalid API key. Returns invalidApiKeyResponse.
    • 404: Invalid worker ID. Returns invalidWorkerIdResponse.
    • 500: Internal server error. Returns internalServerError.

Example Response Body

{
  "state": "done",
  "answer": "{json having key and value of each output}"
}

Models

Department Mismatch (departmentMismatch)

  • Fields:
    • statusCode (Integer)
    • message (String)

Inline Response 201 (inline_response_201)

  • Fields: N/A

Internal Server Error (internalServerError)

  • Fields:
    • statusCode (Integer)
    • message (String)

Invalid API Key Response (invalidApiKeyResponse)

  • Fields:
    • message (String)

Invalid Share ID Response (invalidShareIdResponse)

  • Fields:
    • statusCode (Integer)
    • message (String)

Invalid Worker ID Response (invalidWorkerIdResponse)

  • Fields:
    • statusCode (Integer)
    • message (String)

Status Response (statusResponse)

  • Fields:
    • state (String)
    • answer (Object)

Worker Response Async (workerResponseAsync)

  • Fields:
    • worker_id (String)

Worker Response Sync Fail (workerResponseSyncFail)

  • Fields:
    • worker_id (String)
    • state (String)
    • time_taken (Integer)
    • error (String)

Worker Response Sync Success (workerResponseSyncSuccess)

  • Fields:
    • worker_id (String)
    • state (String)
    • answer (Object, optional)
    • time_taken (Integer, optional)

Example Requests

Start a New Automation Run

curl -X POST "<https://api.kognitos.com/v1/invoke/{share_id}>" -H "x-api-key: your_api_key" -H "Content-Type: application/json" -d '{"body": {"parameter1": "value1"}}'

Get Status of an Automation Run

curl -X GET "<https://api.kognitos.com/v1/run/{worker_id}>" -H "x-api-key: your_api_key"


This guide covers the essential aspects of using the Kognitos REST API. For further information or assistance, please contact us at [email protected].

Updated about 1 month ago