---
title: Automation & OpenAPI
description: Integrate orchestrators, event producers, approval-required proposals, triggers, and bounded webhook execution.
slug: automation
path: /automation
section: Integrations
availability: supported
nav_order: 7
canonical_url: https://developers.basaltnotes.com/automation
markdown_url: https://developers.basaltnotes.com/automation.md
mirror_url: https://basaltnotes.com/developers/automation
---
# Automation & OpenAPI

The developer automation gateway is mounted under:

```text
/api/dev/automation
```

It uses the Developer entitlement boundary and Basalt workspace permissions. The gateway is suitable for Zapier, n8n, custom webhook/event producers, and other integration backends that should enter Basalt through versioned events and approval-aware proposals rather than silent execution.

## Discovery

```http
GET /api/dev/automation/catalog
GET /api/dev/automation/adapters/:bridge
GET /api/dev/automation/openapi.json
```

The OpenAPI document is generated by the automation gateway and should be preferred over a manually duplicated endpoint schema when configuring compatible orchestrators.

A [public machine-readable copy](/api/content/developers/references/automation-openapi.json) is available for discovery. Calling the automation gateway itself still requires the Developer entitlement and applicable workspace permissions.

## Templates

The current gateway also exposes automation templates:

```http
GET /api/dev/automation/templates
GET /api/dev/automation/templates/:id
GET /api/dev/automation/templates/:id/download
```

Treat downloaded template artifacts as versioned configuration input, not as authority to execute consequential actions.

## Ingest an event

```http
POST /api/dev/automation/events
Idempotency-Key: external-event-123
Content-Type: application/json
```

Event ingestion requires workspace access and the applicable automation-management permission. The event is normalized into Basalt's versioned automation contract and may dispatch matching triggers.

Use an idempotency key for retryable event delivery.

## Propose an action

```http
POST /api/dev/automation/proposals
Idempotency-Key: proposal-123
Content-Type: application/json
```

External bridges can propose bounded actions. A bridge proposal is not equivalent to approval or execution.

```text
external bridge
→ ActionProposal
→ Basalt policy/review
→ approved action
→ bounded Forge executor (where implemented)
→ receipt / audit / undo semantics
```

Do not advertise a provider write executor unless the current code implements that executor.

## Read proposals

```http
GET /api/dev/automation/proposals?workspaceId=<uuid>&state=<state>&limit=<n>
```

Proposal reads are user-scoped and may be filtered by workspace/state.

## Triggers and runs

Workspace-governed trigger management is available through:

```http
GET    /api/dev/automation/triggers?workspaceId=<uuid>
POST   /api/dev/automation/triggers
PATCH  /api/dev/automation/triggers/:id
DELETE /api/dev/automation/triggers/:id
GET    /api/dev/automation/runs?workspaceId=<uuid>
```

Trigger changes require the applicable automation management permission. Scope/policy state is evaluated by Basalt rather than delegated to the external orchestrator.

## Webhook delivery endpoints

The gateway includes bounded webhook endpoint/execution management:

```http
GET    /api/dev/automation/endpoints?workspaceId=<uuid>
POST   /api/dev/automation/endpoints
DELETE /api/dev/automation/endpoints/:id
GET    /api/dev/automation/executions
```

Webhook execution remains within Basalt's approved action boundary. Do not treat endpoint creation as permission to execute unrelated external actions.

## Processing endpoint

```http
POST /api/dev/automation/process
```

The implementation includes this account-scoped operation for processing due triggers and approved action executions. External bridges generally should not depend on manually driving this endpoint unless the deployment/operator contract explicitly calls for it.

## Microsoft Graph adapter boundary

The developer `microsoft-graph` adapter is an ingestion/integration boundary separate from Basalt's native Microsoft account OAuth connection. An external bridge never receives Basalt's native provider credential.

## Workspace roles

Automation management is workspace-governed. Possessing a Developer PAT does not let a user manage automation in a workspace where their role lacks the required permission.