---
title: "Create a workbench (so a workflow has somewhere to write)"
method: POST
path: "/workflows/workbenches"
tags: ["Workflows"]
---

# Create a workbench (so a workflow has somewhere to write)

`POST /workflows/workbenches`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/workflows/workbenches`
- Auth: HTTP bearer

Create an empty workbench and return its `workbench_id`.

The missing half of the loop: an agent could be TOLD a workbench id but could
never make one, so "build me a workflow that collects X into a new workbench"
always needed a human to go and click New Workbench first.

``entity_type`` is optional and must be ``contact`` or ``company`` when given;
a blank workbench may defer it, which is what the underlying command already
allows. ``created_by`` is the authenticated caller and is never read from the
request, so a key cannot attribute a workbench to someone else.

The webhook API key the browser route returns on create is deliberately NOT
surfaced here. It is a write credential for a different ingestion path, it is
returned exactly once, and nothing in the workflow surface needs it — an agent
that never sees it cannot leak it into a workflow config or a chat transcript.

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Request body

- object: {name, entity_type?, description?}

## Response `201`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/2e7cfa0ca921?raw)