Help Center

    Home > Uncategorized > Consume an Asset via API

    Menu

    Consume an Asset via API

    Consuming an Asset refers to the process of calling or using the Asset to perform a desired action or provide a particular functionality. In this context, it means utilizing an API to access a trained Document AI model to classify documents, extract information from them or consume as a use case.

    Once the Asset is created and published, you will be able to invoke the asset using API. 

    User must have any one of the following policies to Invoke an Asset Through API:

    • Administrator Policy
    • Creator Policy

    This guide will walk you through the below steps on how to invoke your assets using an API.

    1. Activate an asset
    2. Download the API documentation
    3. Invoke an asset through API

    Step 1: Activate the asset

    Once an Asset is published, it can be activated in the Asset Monitor. When an asset is in the deactivated state when trying to use the asset via API, you will get an error stating that the asset is not activated.

    Assets can be activated / deactivated anytime. When an asset is deactivated, already initiated transactions will not be suspended until it is completed.

    You can view the detailed steps to activate an asset here.

    Step 2: Download the API documentation

    API documentation has the necessary information and structure of how an asset can be invoked. Every asset will have a different API definition. Details on the API endpoints and parameters are dynamically generated and will be  available in the API documentation.

    You can download the API documentation by following the below steps:

    1. In the Asset Studio page, click against the asset which you would like to use and select the Download API option. You can download the API documentation for the published assets only.
    2. The Open API specification JSON file will be downloaded to your system.

    Step 3: Execute an asset through API

    API documentation

    • Generated API documentation (REST API)  is OpenAPI 3.0 specification compliant.
    • Each asset and its version will have a different API endpoint.
    • Each API, its definition and endpoints are versioned.

    Authentication

    • Only valid user with proper access can use (Invoke) an asset via API.
    • API keys need to be passed as part of each and every API call. Only requests with valid API keys will be allowed to process.
    • We use JSON Web Token (JWT) for authorization of API requests.

    End points

    There are 3 API endpoints in the API documentation:

    • End Point 1: Get Authenticated
    • End Point 2: Invoke the asset
    • End Point 3: Get the status and result

    End point 1: Get authenticated

    1. First endpoint is for Authentication.
    2. Once the request is successful, the response will be a valid JWT token.
    3. This access token comes with default expiry time which can be configured at the tenant level. 
    4. You need to Send this access token first to get the access from the Asset API to do the GET and POST operations.
    5. To Asset Token access you need to setup the following:
      • Request: GET
      • Service URL : {{baseUrl}}accesstoken/idx
    6. Go to Headers and update the following.
    KeyValue
    apikey{{apikey}}
    usernameusername
    passwordpassword
    Content Typeapplication/json
    1. Enter the API key (replace this {{apikey}} with the actual value of the api key); for each and every tenant, a unique API key is provided.
    2. In username & password,  enter your login credentials.

    End point 2: Invoke the asset

    1. Second endpoint is for executing (invoke) the asset.
    2. Once the request is successful, the response will have a trace_id. 
    3. To execute the Invoke Asset API,  go to Authorization tab
      1. In Type select Bearer Token
      2. In Token enter {{accesstoken}}
    4. Go to Headers and update the following:
      • Enter the API key; for each and every tenant, a unique API key is provided.
    KeyValue
    apikey{{apikey}} 
    Content Typeapplication/json
    1. Go to Body tab
      1. There are different types of input for some cases, and for some cases, no input is required; it all depends on the asset the user creates.
        • Input_file – upload the file from your local storage.
        • S3_file_path – provide the file/folder path from the AWS S3 bucket.
        • No Input – in some cases no input required to execute the asset.
      2. After the successful execution the response is as follows.
        {    "trace_id": "<GENERATED_TRACE_ID>",
            "message": "Asset Invoked Successfully"
        }

    End point 3: Get the status and results

    1. Third endpoint is for getting the status and output of the invoked asset.
    2. Once the request is successful, the final output. 
    3. To execute the Invoke Asset API, go to Authorization tab.
      1. In Type select Bearer Token,
      2. In Token enter {{accesstoken}}
    4. Go to Headers and update the following.
    5. Enter the API key (replace this {{apikey}} with the actual value of the api key); for each and every tenant, a unique API key is provided.
    KeyValue
    apikey{{apikey}} 
    Content Typeapplication/json
    1. Go to the Params tab.
      1. Provide the value for path variable trace_id, the value of the trace_id is the response of the invoke asset api.
      2. After the successful execution of this API, the response is the result of the executed asset.

    Invoking an asset API through curl

    cuRL Request to generate the Access token

    curl –location –request GET ‘https://api.intellectai.com/accesstoken/<YOUR_TENANT_ID>‘ \

           — header ‘apikey: <YOUR_API_KEY>‘ \

           — header ‘username: <YOUR_USER_NAME>‘ \       –header ‘password: <YOUR_PASSWORD>‘

    cuRL Request to invoke the Asset with INPUT

    curl --location --request POST 'https://api.intellectai.com/magicplatform/v1/invokeasset/<YOUR_ASSET_VERSION_ID>/extract' \

    --header 'apikey: <YOUR_API_KEY>' \

    --header 'Content-Type: multipart/form-data' \

    --header 'Accept: application/json' \

    --header 'Authorization: Bearer <YOUR_GENERATED_TOKEN>' \

    --form 'input_file=@"<FILE_LOCATION>"'

    cuRL Request to invoke the Asset with INPUT

    curl --location --request POST 'https://api.intellectai.com/magicplatform/v1/invokeasset/<YOUR_ASSET_VERSION_ID>/extract' \

    --header 'apikey: <YOUR_API_KEY>' \

    --header 'Content-Type: multipart/form-data' \

    --header 'Accept: application/json' \

    --header 'Authorization: Bearer <YOUR_GENERATED_TOKEN>' \

    --form 'input_file=@"<FILE_LOCATION>"'

    cuRL Request to invoke the asset without INPUT

    curl --location --request POST 'https://api.intellectseecstag.com/magicplatform/v1/invokeasset/<YOUR_ASSET_VERSION_ID>/usecase' \

    --header 'apikey: <YOUR_API_KEY>' \

    --header 'Content-Type: application/json' \

    --header 'Accept: application/json' \

    --header 'Authorization: Bearer <YOUR_GENERATED_TOKEN> ' \

    --data-raw '{}'

    cuRL Request to get the status of an asset

    curl --location --request GET 'https://api.intellectai.com//magicplatform/v1/invokeasset/50d6e176-7837-44ef-8564-7847e5170f33/< trace_id >' \

    --header 'apikey: < YOUR_API_KEY >' \

    --header 'Accept: application/json' \--header 'Authorization: Bearer <YOUR_GENERATED_TOKEN>'

    Code examples

    Java

    static HttpResponse<String> getData(String jsonStr, String endpoint, String accessToken)
    throws Exception {
         HttpClient httpClient = HttpClient.newHttpClient();
         HttpRequest httpRequest = HttpRequest.newBuilder()
         .method("GET", body)
         .header("apikey", "<< apikey >>")
         .header("username", "<< username >>")
         .header("password", "<< password >>")
     .uri(URI.create("https://api.intellectai.com/accesstoken/<YOUR_TENANT_ID>”))
         .build();
    HttpResponse<String> httpResponse = httpClient.send(httpRequest,                       HttpResponse.BodyHandlers.ofString());
    }

    Python

     import http.client
    conn = http.client.HTTPSConnection("api.intellectai.com")
    payload = ''
    headers = {
    'apikey': '<< apikey >>',
    'username': '<<  username  >>',
    'password': '<< password >>'
    }
    conn.request("GET", "//accesstoken/<YOUR_TENANT_ID>", payload, headers)
    res = conn.getresponse()
    data = res.read()
    print(data.decode("utf-8"))

    Node Js

    var axios = require('axios');
    var config = {
    method: 'get',
    url: 'https://api.intellectai.com//accesstoken/<YOUR_TENANT_ID>,
    headers: { 
    'apikey': '<< apikey >>', 
    'username': '<<  username  >>', 
    'password': '<< password >>'
    }
    };
    axios(config)
    .then(function (response) {
    console.log(JSON.stringify(response.data));
    })
    .catch(function (error) {
    console.log(error);
    });

    Possible errors and exceptions

    • The API returns exceptions in the HTTP response body when something goes wrong.
    • Possible Error Codes
      • OK – 200
      • CREATED – 201
      • ACCEPTED – 202
      • BAD_REQUEST – 400
      • UNAUTHORIZED – 401
      • FORBIDDEN – 403
      • NOT_FOUND – 404
      • NOT_ACCEPTABLE – 406
      • CONFLICT – 409
      • LENGTH_REQUIRED – 411
      • INTERNAL_SERVER_ERROR – 500
    PropertyDescription
    MessageA more descriptive message regarding the exception.
    StatusCode(Conditional) An error code to find help for the exception.
    ErrorAdditional Information about the exception

    Example

    • Here is a simple 404
      {
      "statusCode": 404,
      "message": "      Asset not found",
      "error": "Not Found"
      }
    • UnAuthorized Request 401
      {
        "statusCode": 401,
       "message": "Not Authorized.",
       "error": "Unauthorized"
      }

    Enable Human in the Loop
    Consume an Asset via Create Transaction
    On this page
    • Loading....

    © ­Intellect Design Arena Ltd,