Skip to main content

Building Your First API with AgentHub

Combining your AgentHub automation with webhook triggers allows you to build APIs visually with no code!

Webhooks#

All AgentHub automations can be triggered via your own external app using Webhooks.

To see the code necessary to trigger your automation, navigate to your automation and click the 'Your Triggers' on the left side of the pipeline builder.

Select the option 'Webhook' and your preffered language.

Alt text

Inputs#

Most useful automations require an input in from the user. Many automations require multiple. Inputs are defined using Input nodes and these inputs can be passed in using webhooks as well!

The following example takes in 3 seperate inputs and sends an email. The inputs represent the recipients email, the email subject and the email body.

Alt text

The 'input_name' values represent the id of that input field. These input names are used to map the information you send via the webhook to the appropriate nodes.

The inputs are sent in the JSON body in an attribute pipeline_inputs. This attribute is a list containing JSON objects with two key-value pairs, one representing the input_name and one representing the value to be passed in for the input.

The following is an example of how you would populate these 3 expected fields in an api call (cURL request).

curl -X POST \      https://api-v2.agenthub.dev/remote_start_pipeline \      -H "Content-Type: application/json" \      -H "x-auth-key: xxxxxxxxxxxxxx" \      -d '{        "user_id": "xxxxxxxxxxxxxx",        "saved_item_id": "xxxxxxxxxxxxxx",        "api_key": "xxxxxxxxxxxxxx",        "pipeline_inputs": [{"input_name": "recepient_address", "value": "recepient@gmail.com"}, {"input_name": "email_subject", "value": "Example of an Email Subject Line"}, {"input_name": "email_body", "value": "Example of the Text of an Email Body"}]      }'

Here is the same request in Python using the requests library:

import requestsimport json
url = "https://api-v2.agenthub.dev/remote_start_pipeline"headers = {    "Content-Type": "application/json",    "x-auth-key": "xxxxxxxxxxxxxx"}data = {    "user_id": "xxxxxxxxxxxxxx",    "saved_item_id": "xxxxxxxxxxxxxx",    "api_key": "xxxxxxxxxxxxxx",    "pipeline_inputs": [        {"input_name": "recepient_address", "value": "recepient@gmail.com"},        {"input_name": "email_subject", "value": "Example of an Email Subject Line"},        {"input_name": "email_body", "value": "Example of the Text of an Email Body"}    ]}
response = requests.post(url, headers=headers, data=json.dumps(data))

And here is the same request in JavaScript using the fetch API:

const url = 'https://api-v2.agenthub.dev/remote_start_pipeline';const headers = {  'Content-Type': 'application/json',  'x-auth-key': 'xxxxxxxxxxxxxx',};const data = {  user_id: 'xxxxxxxxxxxxxx',  saved_item_id: 'xxxxxxxxxxxxxx',  api_key: 'xxxxxxxxxxxxxx',  pipeline_inputs: [    { input_name: 'recepient_address', value: 'recepient@gmail.com' },    { input_name: 'email_subject', value: 'Example of an Email Subject Line' },    { input_name: 'email_body', value: 'Example of the Text of an Email Body' },  ],};
fetch(url, {  method: 'POST',  headers: headers,  body: JSON.stringify(data),})  .then((response) => response.json())  .then((data) => console.log(data));

Outputs#

When you run an agenthub pipeline remotely, the POST request to https://api-v2.agenthub.dev/remote_start_pipeline will return a URL that links to the automation run.

Here is an example of the response:

https://www.agenthub.dev/pipeline?run_id=B7uiXDngvzFvUWxHRKQFAD&agent_id=q3dasHQBidkNeXvAZo6Dby

We can then extract that run_id: B7uiXDngvzFvUWxHRKQFAD. There are a few ways to do this:

  • In Python you can do this:
def extract_run_id_from_url(url: str) -> str:    parsed_url = urlparse(url)    query_params = parse_qs(parsed_url.query)    run_id = query_params.get('run_id', [None])[0]    return run_id
  • In JavaScript you can do this:
const extractRunIdFromUrl = (url) => {  const urlObj = new URL(url);  const params = urlObj.searchParams;  return params.get('run_id');};
  • Or you can use a simple regex pattern which would only match the run_id like the following:
/run_id=([a-zA-Z0-9]+)/

You can use this run id to poll a separate endpoint to get information about the ongoing run like the status, logs, and outputs when it is completed.

In order to poll, make a GET request to https://api-v2.agenthub.dev/plrun with run_id as a query parameter.

Here is an example of a GET request with cURL, Python, JavaScript and their outputs:

Request with cURL

curl 'https://api-v2.agenthub.dev/plrun?run_id=B7uiXDngvzFvUWxHRKQFAD' \  -H 'x-auth-key: your_user_id' \

Request with Python

import requests
url = "https://api-v2.agenthub.dev/plrun?run_id=B7uiXDngvzFvUWxHRKQFAD"headers = {    "x-auth-key": "your_user_id"}
response = requests.get(url, headers=headers)print(response.json())

Request with JavaScript

const url = 'https://api-v2.agenthub.dev/plrun?run_id=B7uiXDngvzFvUWxHRKQFAD';const headers = {  'x-auth-key': 'your_user_id',};
fetch(url, {  method: 'GET',  headers: headers,})  .then((response) => response.json())  .then((data) => console.log(data));

Output

{    "created_ts": "2023-11-19T18:06:31.102786+00:00",    "finished_ts": null,    "log": [        "\u001b[34m__system__: __STARTING__:Read files from GitHub\u001b[0m"    ],    "memory_objects_written": [],    "outputs": {},    "pl_config_hash": "101fd9fe8509edba3f98cad316d9b7b3eef0be2e092b98e75e5d2f787bff635f",    "run_id": "B7uiXDngvzFvUWxHRKQFAD",    "state": "RUNNING",    "user_id": "your_user_id"}

The key attributes here are log, state, and outputs.

log: Contains a running log of each node and the activities within it.

state: One of "STARTED", "RUNNING", "TERMINATED", "FAILED" or "DONE".

outputs: A JSON object with key-value pair where the key is the output name and the value is the output value. This will only be populated when your pipeline reaches a "DONE" state and you have named output nodes in your pipeline.