ExecutionService Endpoints
Create Executions
Prerequisites: Acquire workflowId from orby-web-app.
Go to the “Workflows” page, click the “API Automations” tab, and click the workflow item you want to create execution. You will get to the update workflow page. The workflowId is in the URL. Replace the workflowId in your program. Below are examples to use this API and more details please refer to the API definition.
Curl
Bash | Copy |
|---|---|
#!/bin/bash orby_api_key="<YOUR_API_KEY>" orby_org_id="<YOUR_ORG_ID>" workflow_id="<YOUR_WORKFLOW_ID>" file_path="<YOUR_FILE_PATH>" file_name=$(basename $file_path) mime_type="application/pdf" (echo -n "{ \"workflowId\" : \"${workflow_id}\", \"sources\": [{ \"document\": { \"documentBlob\": { \"mimeType\": \"${mime_type}\", \"content\": \""; base64 -w 0 ${file_path}; echo -n "\", \"name\": \"${file_name}\" } } }] }") | curl -X POST -H "Content-Type: application/json" \ -H "ORBY-API-KEY: ${orby_api_key}" \ -H "ORBY-ORG-ID: ${orby_org_id}" \ -d @- https://api.orby.ai/v1/executions |
Python
Python | Copy |
|---|---|
import requests import base64 import os orby_api_key = '<YOUR_API_KEY>' orby_org_id = '<YOUR_ORG_ID>' workflow_id = '<YOUR_WORKFLOW_ID>' file_path = '<YOUR_FILE_PATH>' file_name = os.path.basename(file_path) # supported mime_types: # "application/pdf", "image/png", "image/jpeg", "image/gif", # "image/tiff", "image/bmp", "image/webp" mime_type = 'application/pdf' with open(file_path, 'rb') as file_obj: file_content = base64.b64encode(file_obj.read()).decode('utf-8') response = requests.post('https://api.orby.ai/v1/executions', json={ "workflowId" : workflow_id, "sources": [ { "document": { "documentBlob": { "name": file_name, "content": file_content, "mimeType": mime_type, } } }, ] }, headers={ "ORBY-API-KEY": orby_api_key, "ORBY-ORG-ID": orby_org_id, "Content-Type": mime_type, }) print(response.status_code) print(json.dumps(response.json(), indent=2, ensure_ascii=False)) |
Go
Go | Copy |
|---|---|
package main import ( "bytes" "encoding/base64" "encoding/json" "fmt" "io/ioutil" "net/http" "os" "path/filepath" ) func main() { orbyAPIKey := "<YOUR_API_KEY>" orbyOrgID := "<YOUR_ORG_ID>" workflowID := "<YOUR_WORKFLOW_ID>" filePath := "<YOUR_FILE_PATH>" // Get file name and MIME type fileName := filepath.Base(filePath) mimeType := "application/pdf" // Change this if needed // Read and base64-encode file content fileContent, err := ioutil.ReadFile(filePath) if err != nil { fmt .Println("Failed to read file:", err) return } encodedContent := base64.StdEncoding.EncodeToString(fileContent) // Build JSON payload payload := map[string]interface{}{ "workflowId": workflowID, "sources": []map[string]interface{}{ { "document": map[string]interface{}{ "documentBlob": map[string]interface{}{ "name": fileName, "content": encodedContent, "mimeType": mimeType, |
},
},
},
},
}
payloadBytes, err := json.Marshal(payload) if err != nil {
fmt .Println("Failed to marshal payload:", err) return
}
// Send the POST request
req, err := http.NewRequest("POST", "https://api.orby.ai/v1/executions", bytes.NewBuffer(payloadBytes))
if err != nil {
fmt .Println("Failed to create request:", err) return
}
req.Header.Set("ORBY-API-KEY", orbyAPIKey) req.Header.Set("ORBY-ORG-ID", orbyOrgID)
req.Header.Set("Content-Type", "application/json") // Note: Not the mimeType
client := &http.Client{} resp, err := client.Do(req)
if err != nil {
fmt .Println("Failed to send request:", err) return
}
defer resp.Body.Close() fmt.Println("Status Code:", resp.StatusCode)
respBody, _ := ioutil.ReadAll(resp.Body) fmt.Println("Response:") fmt.Println(string(respBody))
}
Response example
JSON | Copy |
|---|---|
{"results":[{"executionId":"671cfce7f23b37ea6be9c9"}]} |
Get Execution Status
Get the latest status of one execution by its id. Below are examples to use this API and more details please refer to the API definition.
Curl
curl -H "Content-Type: application/json" \
-H "ORBY-API-KEY: ${orby_api_key}" \
-H "ORBY-ORG-ID: ${orby_org_id}" \ "https://api.orby.ai/v1/executions/${execution_id}"
execution_id="<YOUR_EXECUTION_ID>"
#!/bin/bash
orby_api_key="<YOUR_API_KEY>" orby_org_id="<YOUR_ORG_ID>"
Copy
Bash
Python
Python | Copy |
|---|---|
import requests, base64, json, os orby_api_key = '<YOUR_API_KEY>' orby_org_id = '<YOUR_ORG_ID>' execution_id = '<YOUR_EXECUTION_ID>' response = requests.get(f'https://api.orby.ai/v1/executions/{execution_id}', headers={ "ORBY-API-KEY": orby_api_key, "ORBY-ORG-ID": orby_org_id, }) print(response.status_code) print(json.dumps(response.json(), indent=2, ensure_ascii=False)) |
Go
Go | Copy |
|---|---|
package main import ( "encoding/json" "fmt" "io/ioutil" "net/http" ) func main() { orbyAPIKey := "<YOUR_API_KEY>" orbyOrgID := "<YOUR_ORG_ID>" executionID := "<YOUR_EXECUTION_ID>" url := fmt.Sprintf("https://api.orby.ai/v1/executions/%s", executionID) // Create request req, err := http.NewRequest("GET", url, nil) if err != nil { |
fmt .Println("Failed to create request:", err) return
}
// Set headers
req.Header.Set("ORBY-API-KEY", orbyAPIKey) req.Header.Set("ORBY-ORG-ID", orbyOrgID)
// Send request client := &http.Client{}
resp, err := client.Do(req) if err != nil {
fmt .Println("Failed to send request:", err) return
}
defer resp.Body.Close() fmt.Println("Status Code:", resp.StatusCode)
// Read and print response
body, err := ioutil.ReadAll(resp.Body) if err != nil {
fmt .Println("Failed to read response body:", err) return
}
var result map[string]interface{}
if err := json.Unmarshal(body, &result); err != nil { fmt .Println("Failed to parse JSON:", err)
fmt .Println(string(body)) // fallback return
}
prettyJSON, _ := json.MarshalIndent(result, "", " ") fmt.Println(string(prettyJSON))
}
Response example
}
"execution": {
"id": "671cf31d058c6134f96e43",
"name": "test.pdf",
"workflowId": "671ca15c38e77b99c6ecd4", "workflowName": "test-api-for-extraction", "status": "COMPLETED",
"error": null
}
{
Copy
JSON
Download Execution Result
Whenever the execution’s status becomes “COMPLETED”, use the download API to get the result. Below are examples to use this API and more details please refer to the API definition.
Curl
curl -H "Content-Type: application/json" \
-H "ORBY-API-KEY: ${orby_api_key}" \
-H "ORBY-ORG-ID: ${orby_org_id}" \ "https://api.orby.ai/v1/executions/${execution_id}/result"
execution_id="<YOUR_EXECUTION_ID>"
#!/bin/bash
orby_api_key="<YOUR_API_KEY>" orby_org_id="<YOUR_ORG_ID>"
Copy
Bash
Python
Python | Copy | ||
|---|---|---|---|
import requests, base64, json, os orby_api_key = '<YOUR_API_KEY>' orby_org_id = '<YOUR_ORG_ID>' execution_id = '<YOUR_EXECUTION_ID>' response = requests.get(f'https://api.orby.ai/v1/executions/{execution_id}/result' , headers={ "ORBY-API-KEY": orby_api_key, "ORBY-ORG-ID": orby_org_id, }) print(response.status_code) print(json.dumps(response.json(), indent=2, ensure_ascii=False)) | |||
|
Go
Go | Copy |
|---|---|
package main import ( "encoding/json" "fmt" "io/ioutil" "net/http" ) func main() { orbyAPIKey := "<YOUR_API_KEY>" orbyOrgID := "<YOUR_ORG_ID>" executionID := "<YOUR_EXECUTION_ID>" url := fmt.Sprintf("https://api.orby.ai/v1/executions/%s/result", executionID) // Create HTTP GET request req, err := http.NewRequest("GET", url, nil) |
if err != nil {
fmt .Println("Failed to create request:", err) return
}
// Set request headers req.Header.Set("ORBY-API-KEY", orbyAPIKey) req.Header.Set("ORBY-ORG-ID", orbyOrgID)
// Perform the request client := &http.Client{} resp, err := client.Do(req)
if err != nil {
fmt .Println("Request failed:", err) return
}
defer resp.Body.Close() fmt.Println("Status Code:", resp.StatusCode)
// Read and parse response body body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt .Println("Failed to read response body:", err) return
}
var result map[string]interface{}
if err := json.Unmarshal(body, &result); err != nil { fmt .Println("Failed to parse JSON response:")
fmt .Println(string(body)) // fallback to raw output return
}
prettyJSON, _ := json.MarshalIndent(result, "", " ") fmt.Println(string(prettyJSON))
}
Response example
JSON | Copy |
|---|---|
{ "metadata": { "workflowMetadata": { "workflowDisplayName": "test-api-for-extraction" }, "taskMetadata": { "taskDisplayName": "test.pdf", "taskUri": "/workflows/671ca15c38a99c6ecd4/tasks/671cf31d034f96e43/automation- review", "file": { "path": "https://drive.google.com/file/d/8b6d1483-86df-4672- acdf-286aa", "name": "test.pdf" } } }, "predictions": [ { "extraction": { "entities": [ { "type": "invoice number", "mentionText": "1019297918", "confidence": 0.9791169, "normalizedValue": { "text": "1019297918" } } ] }, "reviews": [ {} ] } ] } |
List Executions
This API is used for querying batch executions statuses other than single execution status.
For example, you can list by filter on workflowIds and statuses. The pageToken is needed if there is more data to be fetched, and it’s the last response’s ‘nextPageToken’ field. For more information on filter options, please refer to the API definition. Below are some examples usage.
Curl
Bash | Copy |
|---|---|
#!/bin/bash orby_api_key="<YOUR_API_KEY>" orby_org_id="<YOUR_ORG_ID>" workflow_id1="671ca15c38e799cecd4" workflow_id2="671c8cab8b5692f2525" curl -H "Content-Type: application/json" \ -H "ORBY-API-KEY: ${orby_api_key}" \ -H "ORBY-ORG-ID: ${orby_org_id}" \ "https://api.orby.ai/v1/executions? filter.workflowIds=${workflow_id1}&filter.workflowIds=${workflow_id2}& filter.statuses=COMPLETED&filter.statuses=FAILED&pageSize=2&pageToken= ZxzzHQWM3GE0%2BW5D" |
Python
Python | Copy |
|---|---|
import requests, base64, json, os orby_api_key = '<YOUR_API_KEY>' orby_org_id = '<YOUR_ORG_ID>' workflow_id1 = '671ca15c38e799cecd4' workflow_id2 = '671c8cab8b5692f2525' response = requests.get("https://api.orby.ai/v1/executions", params={ "filter.workflowIds": [workflow_id1, workflow_id2], "filter.statuses": ["COMPLETED", "FAILED"], "pageSize": "2", "pageToken": "ZxzzHQWM3GE0+W5D", }, headers={ "ORBY-API-KEY": orby_api_key, "ORBY-ORG-ID": orby_org_id, } ) print(response.status_code) print(json.dumps(response.json(), indent=2, ensure_ascii=False)) |
Go
Go | Copy |
|---|---|
package main import ( "encoding/json" "fmt" "io/ioutil" "net/http" "net/url" ) func main() { orbyAPIKey := "<YOUR_API_KEY>" orbyOrgID := "<YOUR_ORG_ID>" |
workflowID1 workflowID2 pageSize
:=
:=
:=
"2"
"671ca15c38e799cecd4" "671c8cab8b5692f2525"
pageToken "ZxzzHQWM3GE0+W5D"
:=
// Construct query parameters
params url.Values{}
:=
params.Add("filter.workflowIds", workflowID1) params.Add("filter.workflowIds", workflowID2) params.Add("filter.statuses", "COMPLETED") params.Add("filter.statuses", "FAILED") params.Add("pageSize", pageSize) params.Add("pageToken", pageToken)
// Build full URL with query string
:=
:=
baseURL fullURL
"https://api.orby.ai/v1/executions" fmt.Sprintf("%s?%s", baseURL, params.Encode())
// Create GET request
:=
req, err
if err
http.NewRequest("GET", fullURL, nil) nil {
fmt .Println("Failed to create request:", err) return
!=
}
// Add headers
req.Header.Set("ORBY-API-KEY", orbyAPIKey) req.Header.Set("ORBY-ORG-ID", orbyOrgID)
// Execute request
client &http.Client{}
:=
resp, err := client.Do(req) if err != nil {
fmt .Println("Request failed:", err) return
}
defer resp.Body.Close() fmt.Println("Status Code:", resp.StatusCode)
// Read and parse response
:=
!=
body, err
if err
ioutil.ReadAll(resp.Body) nil {
fmt .Println("Failed to read response body:", err)
return
}
var result map[string]interface{}
if err := json.Unmarshal(body, &result); err != nil { fmt .Println("Failed to parse JSON. Raw response:") fmt .Println(string(body))
return
}
prettyJSON, _ := json.MarshalIndent(result, "", " ") fmt.Println(string(prettyJSON))
}
Response example
JSON | Copy | |
|---|---|---|
{ | "executions": [ { "id": "671cfce7f2397ea6be9c9", "name": "test1.pdf", "workflowId": "671ca15c38e799cecd4", "workflowName": "test-api-for-extraction1", "status": "COMPLETED", "error": null }, { "id": "671cfcc2c0b03906dbbdf", "name": "test2.pdf", "workflowId": "671c8cab8b5692f2525", "workflowName": "test-api-for-extraction2", "status": "FAILED", "error": null }, | |
} | ], "nextPageToken": "Zxyhcey25a5teM8+" |
Update Execution
This API updates the information of a single execution, currently supporting update ‘customLabels’. We only allow set customLabels now on processed executions (PENDING_REVIEW, COMPLETED, FAILED, CANCELLED). Max 255 characters per label. Custom labels can only contain alphanumeric characters, underscores, and hyphens. No limit on how many labels you can set for a single execution. Below are examples to use this API and more details please refer to the API definition.
Curl
Bash | Copy |
|---|---|
#!/bin/bash orby_api_key="<YOUR_API_KEY>" orby_org_id="<YOUR_ORG_ID>" execution_id="<YOUR_EXECUTION_ID>" curl -X PATCH "https://api.orby.ai/v1/executions/${execution_id}" \ -H "Content-Type: application/json" \ -H "ORBY-API-KEY: ${orby_api_key}" \ -H "ORBY-ORG-ID: ${orby_org_id}" \ --data '{ "customLabels": ["label-1"] }' |
Python
Python | Copy |
|---|---|
import requests, base64, json, os orby_api_key = '<YOUR_API_KEY>' orby_org_id = '<YOUR_ORG_ID>' execution_id = '<YOUR_EXECUTION_ID>' url = f'https://api.orby.ai/v1/executions/{execution_id}' payload = { "customLabels": ["label-1"] } headers = { "ORBY-API-KEY": orby_api_key, "ORBY-ORG-ID": orby_org_id, "Content-Type": "application/json" } response = requests.patch(url, headers=headers, json=payload) print(response.status_code) print(json.dumps(response.json(), indent=2, ensure_ascii=False)) |
Go
Go | Copy |
|---|---|
package main import ( "bytes" "encoding/json" "fmt" "io/ioutil" "net/http" ) func main() { orbyAPIKey := "<YOUR_API_KEY>" orbyOrgID := "<YOUR_ORG_ID>" |
executionID "<YOUR_EXECUTION_ID>"
:=
url fmt.Sprintf("https://api.orby.ai/v1/executions/%s",
:=
executionID)
// Prepare payload
:=
payload
}
map[string]interface{}{ "customLabels": []string{"label-1"},
payloadBytes, err json.Marshal(payload)
:=
if err nil {
!=
fmt .Println("Failed to marshal payload:", err) return
}
// Create PATCH request
req, err http.NewRequest("PATCH", url,
:=
bytes.NewBuffer(payloadBytes))
if err nil {
!=
fmt .Println("Failed to create request:", err) return
}
// Set headers
req.Header.Set("ORBY-API-KEY", orbyAPIKey) req.Header.Set("ORBY-ORG-ID", orbyOrgID) req.Header.Set("Content-Type", "application/json")
// Execute request
client &http.Client{}
:=
resp, err := client.Do(req) if err != nil {
fmt .Println("Request failed:", err) return
}
defer resp.Body.Close() fmt.Println("Status Code:", resp.StatusCode)
// Read and pretty-print response
:=
!=
body, err
if err
ioutil.ReadAll(resp.Body) nil {
fmt .Println("Failed to read response body:", err) return
}
var result map[string]interface{}
if err := json.Unmarshal(body, &result); err != nil { fmt .Println("Failed to parse JSON. Raw response:") fmt .Println(string(body))
return
}
prettyJSON, _ := json.MarshalIndent(result, "", " ") fmt.Println(string(prettyJSON))
}
Response example
JSON | Copy |
|---|---|
{ "execution": { "id": "67fc558ad7fc11573dcd3b47", "name": "Screenshot.png", "workflowId": "67fc5412d7fc11573dcd3b43", "workflowName": "test", "status": "COMPLETED", "error": null, "sourceExecutionId": "", "followingUpExecutionIds": [], "warnings": [], "customLabels": [ "label-1" ] } } |
Batch Update Execution
This API batch-updates multiple executions, currently allows updating custom labels for multiple executions in a single API call. Max 255 characters per label. Custom labels can only contain alphanumeric characters, underscores, and hyphens. The ‘updateMask’ is needed for specifying the field you want to update, current support ‘customLabels’. Below are examples to use this API and more details please refer to the API definition.
Curl
Bash | Copy |
|---|---|
#!/bin/bash orby_api_key="<YOUR_API_KEY>" orby_org_id="<YOUR_ORG_ID>" curl -X POST "https://api.orby.ai/v1/executions/batch-update" \ -H "Content-Type: application/json" \ -H "ORBY-API-KEY: ${orby_api_key}" \ -H "ORBY-ORG-ID: ${orby_org_id}" \ --data '{ "executions": [ { "id": "67fc558ad7fc11573dcd3b47", "custom_labels": ["label-1"] }, { "id": "67f9cdecd7fc11573dcd3b40", "custom_labels": [ "form", "pending" ] } ], "updateMask": "customLabels" }' |
Python
Python | Copy |
|---|---|
import requests, base64, json, os orby_api_key = '<YOUR_API_KEY>' orby_org_id = '<YOUR_ORG_ID>' url = 'https://api.orby.ai/v1/executions/batch-update' payload = { "executions": [ { "id": "67fc558ad7fc11573dcd3b47", "custom_labels": ["label-1"] }, { "id": "67f9cdecd7fc11573dcd3b40", "custom_labels": ["form", "pending"] } ], "updateMask": "customLabels" } headers = { "Content-Type": "application/json", "ORBY-API-KEY": orby_api_key, "ORBY-ORG-ID": orby_org_id } response = requests.post(url, headers=headers, json=payload) print(response.status_code) print(json.dumps(response.json(), indent=2, ensure_ascii=False)) |
Go
Go | Copy |
|---|---|
package main import ( "bytes" "encoding/json" |
"fmt" "io/ioutil" "net/http"
)
func main() { orbyAPIKey orbyOrgID
:=
:=
"<YOUR_API_KEY>" "<YOUR_ORG_ID>"
url
"https://api.orby.ai/v1/executions/batch-update"
// Prepare payload
:=
payload
map[string]interface{}{ "executions": []map[string]interface{}{
{
:=
"id": "67fc558ad7fc11573dcd3b47", "custom_labels": []string{"label-1"},
},
{
"id": "67f9cdecd7fc11573dcd3b40", "custom_labels": []string{"form", "pending"},
},
},
"updateMask": "customLabels",
}
payloadBytes, err json.Marshal(payload)
:=
if err nil {
!=
fmt .Println("Error marshaling payload:", err) return
}
// Create POST request
req, err http.NewRequest("POST", url,
:=
bytes.NewBuffer(payloadBytes))
if err nil {
!=
fmt .Println("Failed to create request:", err) return
}
// Set headers
req.Header.Set("Content-Type", "application/json") req.Header.Set("ORBY-API-KEY", orbyAPIKey) req.Header.Set("ORBY-ORG-ID", orbyOrgID)
// Execute request client := &http.Client{} resp, err := client.Do(req)
if err != nil {
fmt .Println("Request failed:", err) return
}
defer resp.Body.Close() fmt.Println("Status Code:", resp.StatusCode)
// Read and pretty-print response body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt .Println("Failed to read response body:", err) return
}
var result map[string]interface{}
if err := json.Unmarshal(body, &result); err != nil { fmt .Println("Failed to parse JSON. Raw response:") fmt .Println(string(body))
return
}
prettyJSON, _ := json.MarshalIndent(result, "", " ") fmt.Println(string(prettyJSON))
}
Response example
JSON | Copy |
|---|---|
{ "results": [ { "execution": { "id": "67fc558ad7fc11573dcd3b47", "name": "Screenshot.png", "workflowId": "67fc5412d7fc11573dcd3b43", "workflowName": "test", "status": "COMPLETED", "error": null, "sourceExecutionId": "", "followingUpExecutionIds": [], "warnings": [], "customLabels": [ "label-1" ] } }, { "execution": { "id": "67f9cdecd7fc11573dcd3b40", "name": "Frame 2087325327.png", "workflowId": "67e555107e103d0f63f399ca", "workflowName": "test-extraction", "status": "PENDING_REVIEW", "error": null, "sourceExecutionId": "", "followingUpExecutionIds": [], "warnings": [], "customLabels": [ "form", "pending" ] } } ] } |