canonical: https://jentic.com/apis/buddy.works/buddy-works

# Buddy Works Buddy

Buddy is a CI/CD platform API for managing workspaces, projects, pipelines, actions, environments, and Git repository data on buddy.works. The spec covers full CRUD on projects, pipelines, and actions; environment variable management; and read access to commits, branches, and tags on the connected Git repository. It is the integration entry point for triggering builds, programmatic pipeline configuration, ChatOps deployments, and synchronising Buddy resources with infrastructure-as-code.

## For AI agents

Manage Buddy CI/CD projects, pipelines, actions, and environments and read commits, branches, and tags from the connected repository.

## Scope

Does not handle source-code hosting, secret rotation, or infrastructure provisioning - use for managing Buddy CI/CD projects, pipelines, actions, and reading repository metadata only.

## Capabilities

- Create and configure Buddy projects with linked Git repositories under a workspace
- Define pipelines with triggers (push, manual, scheduled) and ordered actions per project
- Add, update, and remove pipeline actions such as build, deploy, Slack, and SSH steps
- Manage workspace-level environment variables for use across pipelines
- List and inspect commits, branches, and tags on a project's connected repository
- Trigger pipeline runs by updating triggering metadata via the API
- Delete projects, pipelines, and actions for offboarding and cleanup

## Use cases

### Programmatic Pipeline Provisioning

Stand up consistent CI/CD pipelines across many Buddy projects by scripting createProject, createPipeline, and addAction calls instead of clicking through the Buddy UI. The same script can apply identical lint, test, and deploy stages to every microservice and update them in place via updatePipeline and updateAction. Useful for platform teams maintaining dozens of services on Buddy.

Example prompt: Call createProject for the new repo, then createPipeline with trigger 'ON_EVERY_PUSH', then addAction for build, test, and deploy steps in order

### ChatOps Deployment Triggering

Wire a Slack or chat command to fetch the latest commit on a branch via `/workspaces/{workspace}/projects/{projectName}/repository/branches` and trigger the deploy pipeline by updating its triggering metadata. The bearer-token model lets a chat bot run on a service account so engineers can ship from chat without leaving the conversation. Buddy returns the resulting build status which the bot can post back.

Example prompt: Call listBranches to confirm the branch exists, then update the pipeline to start it, and post the resulting status back to Slack

### Repository Activity Monitoring

Surface repository activity in dashboards and ops tools by listing commits, branches, and tags from `/workspaces/{workspace}/projects/{projectName}/repository`/*. Engineering managers can see which branches are stale, what tags were cut last release, and which commits are queued for the next deploy without giving every viewer access to the underlying Git host.

Example prompt: Call listCommits for the project with branch=main and limit=20 to render the recent commit list in the dashboard

### AI Agent CI/CD Through Jentic

Allow an AI agent to provision pipelines and trigger deploys on Buddy without holding the personal access token. Through Jentic, the agent searches by intent, loads the createPipeline schema, and executes against `/workspaces/{workspace}/projects/{projectName}/pipelines` with the requested configuration. Buddy's bearer token is stored in your Jentic One instance and injected at execution time so credentials never enter the agent's context.

Example prompt: Use Jentic to search 'create a Buddy pipeline', load the createPipeline schema, and execute against the chosen workspace and project

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/workspaces/{workspace}/projects` | Create a project under a workspace |
| GET | `/workspaces/{workspace}/projects` | List projects in a workspace |
| POST | `/workspaces/{workspace}/projects/{projectName}/pipelines` | Create a pipeline on a project |
| GET | `/workspaces/{workspace}/projects/{projectName}/pipelines` | List pipelines on a project |
| POST | `/workspaces/{workspace}/projects/{projectName}/pipelines/{pipelineId}/actions` | Add an action to a pipeline |
| GET | `/workspaces/{workspace}/projects/{projectName}/repository/commits` | List repository commits |
| GET | `/workspaces/{workspace}/projects/{projectName}/repository/branches` | List repository branches |
| POST | `/workspaces/{workspace}/environment` | Create a workspace environment variable |

## Key resources

- **Projects** — Create, retrieve, update, and delete Buddy projects under a workspace
- **Pipelines** — Define and manage CI/CD pipelines per project
- **Actions** — Add and configure ordered build, test, deploy, and notification steps within a pipeline
- **Environments** — Manage workspace-level environment variables used across pipelines
- **Repository** — Read commits, branches, and tags from the project's connected Git repository

## Why Jentic

- **Setup:** Wiring Buddy by hand means learning its bearer token auth against api.buddy.works and threading the workspace and project names through every pipeline and action call yourself. Through Jentic you install once, import Buddy from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Buddy puts the workspace and project in the URL path (`/workspaces/{workspace}/projects/{projectName}/...`), so a rule can pin your agent to one workspace or project: it can list and create pipelines and read commits there and nothing else. You choose the operations it may call, so it can create pipelines without being able to trigger destructive actions unless you add them.
- **Credential handling:** Your Buddy personal access token is stored once, encrypted, by your own Jentic One instance and injected as the Authorization: Bearer header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Buddy pipeline' or 'list recent commits', and Jentic returns the matching Buddy operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Bubble Data API** — Stores Buddy build and deploy metadata in a no-code Bubble app for non-technical visibility
- **Buffer API** — Schedules release announcement posts after a successful Buddy deploy
- **Buddyyen API** — Different vendor with a similarly-named integration surface

## FAQ

### What authentication does the Buddy API use?

Buddy uses OAuth 2.0 bearer tokens. Generate a personal access token in Buddy under My Profile > Access Tokens and send Authorization: Bearer <token> on every request. Through Jentic the access token is stored encrypted in the vault and injected at execution time so the raw token never enters the agent's context.

### Can I create a Buddy pipeline programmatically?

Yes. POST to `/workspaces/{workspace}/projects/{projectName}/pipelines` with a JSON body specifying name, on (e.g., ON_EVERY_PUSH or CLICK), refs (branches), and any priority. Then add steps with addAction at `/workspaces/{workspace}/projects/{projectName}/pipelines/{pipelineId}/actions.` Each action specifies a type such as BUILD, DEPLOY, or SLACK.

### What are the rate limits for the Buddy API?

Buddy applies per-workspace rate limits that are not encoded in the spec. The API returns 429 responses when a client exceeds its share, and clients should back off before retrying. See buddy.works/docs/api for current per-plan limits.

### How do I trigger a Buddy deployment through Jentic?

Install the SDK with pip install jentic, search for 'trigger a Buddy pipeline', load the relevant pipeline-update schema, and execute against `/workspaces/{workspace}/projects/{projectName}/pipelines/{pipelineId}.` Jentic injects the bearer token from the vault and returns the run details.

### Can I read commits and branches from the Buddy API?

Yes. GET `/workspaces/{workspace}/projects/{projectName}/repository/commits` returns the commit list, with a query parameter for branch and a limit. `/repository/branches` and `/repository/tags` return the branches and tags on the connected repository. These endpoints proxy to the underlying Git host that Buddy is connected to.

### Is the Buddy API free?

Buddy offers a free tier with limited concurrent runs and projects, plus paid plans (Pro and Hyper) with higher capacity. API access is available on all plans; rate limits and concurrency scale with the tier. See buddy.works/pricing for current details.

### Can I limit what my agent is allowed to do with the Buddy API?

Yes. Because Jentic One is self-hosted, you set the rules that decide which Buddy operations and credentials your agent may use. Buddy puts the workspace and project in the URL path (`/workspaces/{workspace}/projects/{projectName}/...`), so a rule can pin the agent to a single workspace or project and let it list and create pipelines or read commits, branches, and tags there and nothing else. You also choose the exact operations it may call, so it can create pipelines with createPipeline and addAction while being blocked from delete or trigger operations unless you allow them.