How to Build with the Buddy API: Quick Start for Developers

Automating Deployments with the Buddy API: Step‑by‑Step Tutorial

Automating deployments with the Buddy API lets you move faster and reduce human error by triggering pipelines, monitoring runs, and integrating deployment steps into CI/CD workflows. This tutorial walks through a practical end-to-end example: triggering a pipeline on a Git push, monitoring the pipeline run, and handling success or failure notifications.

Prerequisites

Buddy account with a project and at least one pipeline configured.
API token with pipeline run permissions (create, read).
Basic knowledge of HTTP requests and JSON.
A machine with curl or a script environment (Node.js or Python).

Overview of steps

Create an API token in Buddy.
Identify your project and pipeline IDs.
Trigger a pipeline run via the Buddy API.
Poll the run status until completion.
React to the final status (notify, rollback, etc.).
Optional: automate from a Git hook or CI job.

1 — Create an API token

In Buddy, generate an access token scoped to the operations you need (pipeline runs, read project). Store it securely (environment variable or secret store). Example env var:

BUDDY_TOKEN=your_tokenhere

2 — Find project and pipeline IDs

Use the API to list projects and pipelines, or find IDs in the Buddy UI.

Example: list projects

Code
GET https://api.buddy.works/workspaces/:workspace/projects Authorization: Bearer

Replace :workspace with your workspace name. Note the project ID from the response. Then list pipelines:

Code
GET https://api.buddy.works/projects/:project_domain/:project_name/pipelines Authorization: Bearer

From the response, copy the pipeline ID you want to trigger.

3 — Trigger a pipeline run

Trigger the pipeline by creating a new pipeline execution. Minimal example using curl:

Code
curl -X POST “https://api.buddy.works/workspaces/:workspace/projects/:project/pipelines/:pipeline/runs” -H “Authorization: Bearer \(BUDDY_TOKEN" -H "Content-Type: application/json" -d '{"branch":"main","variables": [{"key":"DEPLOY_ENV","value":"staging"}]}' </code></div></div></pre> Key fields: <ul> <li>branch: branch to run the pipeline on.</li> <li>variables: optional pipeline variables to override.</li> </ul> Successful response returns run metadata including run ID. <h3>4 — Poll the run status</h3> The run proceeds asynchronously. Poll the run endpoint until status changes to success, failed, or canceled. Poll example (curl): <pre><div class="XG2rBS5V967VhGTCEN1k"><div class="nHykNMmtaaTJMjgzStID"><div class="HsT0RHFbNELC00WicOi8"><svg width="16" height="16" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" fill-rule="evenodd" clip-rule="evenodd" d="M15.434 7.51c.137.137.212.311.212.49a.694.694 0 0 1-.212.5l-3.54 3.5a.893.893 0 0 1-.277.18 1.024 1.024 0 0 1-.684.038.945.945 0 0 1-.302-.148.787.787 0 0 1-.213-.234.652.652 0 0 1-.045-.58.74.74 0 0 1 .175-.256l3.045-3-3.045-3a.69.69 0 0 1-.22-.55.723.723 0 0 1 .303-.52 1 1 0 0 1 .648-.186.962.962 0 0 1 .614.256l3.541 3.51Zm-12.281 0A.695.695 0 0 0 2.94 8a.694.694 0 0 0 .213.5l3.54 3.5a.893.893 0 0 0 .277.18 1.024 1.024 0 0 0 .684.038.945.945 0 0 0 .302-.148.788.788 0 0 0 .213-.234.651.651 0 0 0 .045-.58.74.74 0 0 0-.175-.256L4.994 8l3.045-3a.69.69 0 0 0 .22-.55.723.723 0 0 0-.303-.52 1 1 0 0 0-.648-.186.962.962 0 0 0-.615.256l-3.54 3.51Z"></path></svg>Code</div><div class="CF2lgtGWtYUYmTULoX44"><button type="button" class="st68fcLUUT0dNcuLLB2_ ffON2NH02oMAcqyoh2UU MQCbz04ET5EljRmK3YpQ CPXAhl7VTkj2dHDyAYAf" data-copycode="true" role="button" aria-label="Copy Code"><svg viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" fill-rule="evenodd" clip-rule="evenodd" d="M9.975 1h.09a3.2 3.2 0 0 1 3.202 3.201v1.924a.754.754 0 0 1-.017.16l1.23 1.353A2 2 0 0 1 15 8.983V14a2 2 0 0 1-2 2H8a2 2 0 0 1-1.733-1H4.183a3.201 3.201 0 0 1-3.2-3.201V4.201a3.2 3.2 0 0 1 3.04-3.197A1.25 1.25 0 0 1 5.25 0h3.5c.604 0 1.109.43 1.225 1ZM4.249 2.5h-.066a1.7 1.7 0 0 0-1.7 1.701v7.598c0 .94.761 1.701 1.7 1.701H6V7a2 2 0 0 1 2-2h3.197c.195 0 .387.028.57.083v-.882A1.7 1.7 0 0 0 10.066 2.5H9.75c-.228.304-.591.5-1 .5h-3.5c-.41 0-.772-.196-1-.5ZM5 1.75v-.5A.25.25 0 0 1 5.25 1h3.5a.25.25 0 0 1 .25.25v.5a.25.25 0 0 1-.25.25h-3.5A.25.25 0 0 1 5 1.75ZM7.5 7a.5.5 0 0 1 .5-.5h3V9a1 1 0 0 0 1 1h1.5v4a.5.5 0 0 1-.5.5H8a.5.5 0 0 1-.5-.5V7Zm6 2v-.017a.5.5 0 0 0-.13-.336L12 7.14V9h1.5Z"></path></svg>Copy Code</button><button type="button" class="st68fcLUUT0dNcuLLB2_ WtfzoAXPoZC2mMqcexgL ffON2NH02oMAcqyoh2UU MQCbz04ET5EljRmK3YpQ GnLX_jUB3Jn3idluie7R"><svg fill="none" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" fill-rule="evenodd" d="M20.618 4.214a1 1 0 0 1 .168 1.404l-11 14a1 1 0 0 1-1.554.022l-5-6a1 1 0 0 1 1.536-1.28l4.21 5.05L19.213 4.382a1 1 0 0 1 1.404-.168Z" clip-rule="evenodd"></path></svg>Copied</button></div></div><div class="mtDfw7oSa1WexjXyzs9y" style="color: var(--sds-color-text-01); font-family: var(--sds-font-family-monospace); direction: ltr; text-align: left; white-space: pre; word-spacing: normal; word-break: normal; font-size: var(--sds-font-size-label); line-height: 1.2em; tab-size: 4; hyphens: none; padding: var(--sds-space-x02, 8px) var(--sds-space-x04, 16px) var(--sds-space-x04, 16px); margin: 0px; overflow: auto; border: none; background: transparent;"><code class="language-text" style="color: rgb(57, 58, 52); font-family: Consolas, "Bitstream Vera Sans Mono", "Courier New", Courier, monospace; direction: ltr; text-align: left; white-space: pre; word-spacing: normal; word-break: normal; font-size: 0.9em; line-height: 1.2em; tab-size: 4; hyphens: none;">GET https://api.buddy.works/workspaces/:workspace/projects/:project/pipelines/:pipeline/runs/:run_id -H "Authorization: Bearer \)BUDDY_TOKEN”

Check the JSON field status (possible values: INPROGRESS, SUCCESSFUL, FAILED, CANCELED). Use exponential backoff (e.g., poll every 5s, then 10s) to avoid rate limits.

5 — Handle final status (notify or rollback)

If SUCCESSFUL: notify stakeholders (Slack, email) and optionally promote the deployment (tag release, update DNS).

If FAILED: notify on-call, optionally trigger a rollback pipeline or create an issue with logs.

Example Slack notification (curl webhook):

Code
curl -X POST -H ‘Content-type: application/json’ –data ‘{“text”:“Deployment of project X to staging succeeded (run :run_id).”}’ https://hooks.slack.com/services/...

6 — Automate trigger from Git hook or CI job

In GitHub Actions, add a step that calls the Buddy API to trigger downstream pipeline runs after tests pass.

In server-side Git hooks, use a small script that POSTs to the runs endpoint.

Store BUDDYTOKEN in repository or CI secrets (never in plaintext in code).

Example GitHub Actions step (uses curl):

yaml
- name: Trigger Buddy pipeline env: BUDDY_TOKEN: \({{ secrets.BUDDY_TOKEN }} run: | curl -X POST "https://api.buddy.works/workspaces/\)WORKSPACE/projects/\(PROJECT/pipelines/\)PIPELINE/runs” -H “Authorization: Bearer \(BUDDY_TOKEN" -H "Content-Type: application/json" -d '{"branch":"main"}' </code></div></div></pre> <h3>Best practices</h3> <ul> <li>Least privilege: Use tokens limited to necessary scopes.</li> <li>Retries & backoff: Implement exponential backoff when polling.</li> <li>Secrets management: Keep tokens in secret stores (CI secrets, vault).</li> <li>Idempotency: Make deployment steps idempotent to handle retries safely.</li> <li>Logging: Store run IDs and responses for audit and debugging.</li> </ul> <h3>Troubleshooting</h3> <ul> <li>401 Unauthorized: Check token and scopes.</li> <li>404 Not Found: Verify workspace, project, or pipeline identifiers.</li> <li>Rate limiting: Back off and reduce poll frequency.</li> </ul> <h3>Example full script (Node.js)</h3> <pre><div class="XG2rBS5V967VhGTCEN1k"><div class="nHykNMmtaaTJMjgzStID"><div class="HsT0RHFbNELC00WicOi8"><svg width="16" height="16" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" fill-rule="evenodd" clip-rule="evenodd" d="M15.434 7.51c.137.137.212.311.212.49a.694.694 0 0 1-.212.5l-3.54 3.5a.893.893 0 0 1-.277.18 1.024 1.024 0 0 1-.684.038.945.945 0 0 1-.302-.148.787.787 0 0 1-.213-.234.652.652 0 0 1-.045-.58.74.74 0 0 1 .175-.256l3.045-3-3.045-3a.69.69 0 0 1-.22-.55.723.723 0 0 1 .303-.52 1 1 0 0 1 .648-.186.962.962 0 0 1 .614.256l3.541 3.51Zm-12.281 0A.695.695 0 0 0 2.94 8a.694.694 0 0 0 .213.5l3.54 3.5a.893.893 0 0 0 .277.18 1.024 1.024 0 0 0 .684.038.945.945 0 0 0 .302-.148.788.788 0 0 0 .213-.234.651.651 0 0 0 .045-.58.74.74 0 0 0-.175-.256L4.994 8l3.045-3a.69.69 0 0 0 .22-.55.723.723 0 0 0-.303-.52 1 1 0 0 0-.648-.186.962.962 0 0 0-.615.256l-3.54 3.51Z"></path></svg>javascript</div><div class="CF2lgtGWtYUYmTULoX44"><button type="button" class="st68fcLUUT0dNcuLLB2_ ffON2NH02oMAcqyoh2UU MQCbz04ET5EljRmK3YpQ CPXAhl7VTkj2dHDyAYAf" data-copycode="true" role="button" aria-label="Copy Code"><svg viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" fill-rule="evenodd" clip-rule="evenodd" d="M9.975 1h.09a3.2 3.2 0 0 1 3.202 3.201v1.924a.754.754 0 0 1-.017.16l1.23 1.353A2 2 0 0 1 15 8.983V14a2 2 0 0 1-2 2H8a2 2 0 0 1-1.733-1H4.183a3.201 3.201 0 0 1-3.2-3.201V4.201a3.2 3.2 0 0 1 3.04-3.197A1.25 1.25 0 0 1 5.25 0h3.5c.604 0 1.109.43 1.225 1ZM4.249 2.5h-.066a1.7 1.7 0 0 0-1.7 1.701v7.598c0 .94.761 1.701 1.7 1.701H6V7a2 2 0 0 1 2-2h3.197c.195 0 .387.028.57.083v-.882A1.7 1.7 0 0 0 10.066 2.5H9.75c-.228.304-.591.5-1 .5h-3.5c-.41 0-.772-.196-1-.5ZM5 1.75v-.5A.25.25 0 0 1 5.25 1h3.5a.25.25 0 0 1 .25.25v.5a.25.25 0 0 1-.25.25h-3.5A.25.25 0 0 1 5 1.75ZM7.5 7a.5.5 0 0 1 .5-.5h3V9a1 1 0 0 0 1 1h1.5v4a.5.5 0 0 1-.5.5H8a.5.5 0 0 1-.5-.5V7Zm6 2v-.017a.5.5 0 0 0-.13-.336L12 7.14V9h1.5Z"></path></svg>Copy Code</button><button type="button" class="st68fcLUUT0dNcuLLB2_ WtfzoAXPoZC2mMqcexgL ffON2NH02oMAcqyoh2UU MQCbz04ET5EljRmK3YpQ GnLX_jUB3Jn3idluie7R"><svg fill="none" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" fill-rule="evenodd" d="M20.618 4.214a1 1 0 0 1 .168 1.404l-11 14a1 1 0 0 1-1.554.022l-5-6a1 1 0 0 1 1.536-1.28l4.21 5.05L19.213 4.382a1 1 0 0 1 1.404-.168Z" clip-rule="evenodd"></path></svg>Copied</button></div></div><div class="mtDfw7oSa1WexjXyzs9y" style="color: var(--sds-color-text-01); font-family: var(--sds-font-family-monospace); direction: ltr; text-align: left; white-space: pre; word-spacing: normal; word-break: normal; font-size: var(--sds-font-size-label); line-height: 1.2em; tab-size: 4; hyphens: none; padding: var(--sds-space-x02, 8px) var(--sds-space-x04, 16px) var(--sds-space-x04, 16px); margin: 0px; overflow: auto; border: none; background: transparent;"><code class="language-javascript" style="color: rgb(57, 58, 52); font-family: Consolas, "Bitstream Vera Sans Mono", "Courier New", Courier, monospace; direction: ltr; text-align: left; white-space: pre; word-spacing: normal; word-break: normal; font-size: 0.9em; line-height: 1.2em; tab-size: 4; hyphens: none;">// node script to trigger pipeline and wait for result const fetch = require('node-fetch'); const TOKEN = process.env.BUDDY_TOKEN; const BASE = 'https://api.buddy.works'; const workspace = 'your-workspace'; const project = 'your-project'; const pipeline = 'your-pipeline'; async function trigger() { const res = await fetch(`\){BASE}/workspaces/\({workspace}/projects/\){project}/pipelines/\({pipeline}/runs`, { method: 'POST', headers: { 'Authorization': `Bearer \){TOKEN}, 'Content-Type': 'application/json' }, body: JSON.stringify({ branch: 'main' }) }); return res.json(); } async function poll(runId) { while (true) { const res = await fetch(\({BASE}/workspaces/\){workspace}/projects/\({project}/pipelines/\){pipeline}/runs/\({runId}`, { headers: { 'Authorization': `Bearer \){TOKEN}` } }); const data = await res.json(); if ([‘SUCCESSFUL’,‘FAILED’,‘CANCELED’].includes(data.status)) return data; await new Promise(r => setTimeout(r, 8000)); } } (async ()=> { const run = await trigger(); const final = await poll(run.id); console.log(‘Final status:’, final.status); })();

Conclusion

Automating deployments via the Buddy API reduces manual steps and integrates releases into your CI/CD pipeline. Follow the steps above to trigger runs, monitor progress, and react to outcomes. Use secure tokens, polling best practices, and careful error handling to make your automation robust.

How to Build with the Buddy API: Quick Start for Developers

Automating Deployments with the Buddy API: Step‑by‑Step Tutorial

Prerequisites

Overview of steps

1 — Create an API token

2 — Find project and pipeline IDs

3 — Trigger a pipeline run

5 — Handle final status (notify or rollback)

6 — Automate trigger from Git hook or CI job

Conclusion

Comments

Leave a Reply Cancel reply

More posts

Ainvo Copy: A Complete Guide to Smarter AI Writing

10 Pro Tips to Master Hypertext Builder Workflows

Datum Malware Cleaner vs. Competitors: Which Is Best?

Troubleshooting Common Chaport Issues: Quick Fixes and Best Practices