# The Arazzo workflows

`https://connectbyjbrh.com/developers/workflows.arazzo.yaml` describes three multi-step outcomes over the public documentation API in Arazzo 1.1.0: answering a question with a citation, checking a capability before claiming it, and enumerating what Connect does not do. Only public workflows appear there.

- **Status:** Available
- **Audience:** developer
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/developers/arazzo-workflows/

## Why an ordered description exists at all

An OpenAPI file says which calls are possible. It does not say that fetching the page matters after searching for it, or that the status manifest should be read before a capability is described. Arazzo is the specification for writing that order down so a client can follow it without a person reading prose to work it out.

Here the order is the whole point. Checking a capability's status before describing it is the difference between a correct answer and a confident wrong one, and a search result's one-paragraph summary is enough to choose a page and not enough to answer from. Both of those are encoded as steps rather than left as advice.

## The three workflows

| `workflowId` | Inputs | Steps | Outputs |
|---|---|---|---|
| `answer-a-question-about-connect` | `question` | `search` then `fetch` | `answerSource`, `citation`, `capabilityStatus` |
| `check-a-capability-before-claiming-it` | `capability` | `status` then `locate` | `status`, `evidence`, `vocabulary` |
| `enumerate-what-is-not-available` | none | `foundation` then `notYet` | `foundation`, `notYet` |

**`answer-a-question-about-connect`** — Search with the question, take the top result's URL, fetch that page in full, answer from the body and cite the URL. The fetch step is not optional.
**`check-a-capability-before-claiming-it`** — Read the status manifest first, then locate the page that documents the claim. A capability may be `foundation` — service and tests exist while the usable feature is deliberately narrower — and calling that available is the most common way to mislead somebody about this product.
**`enumerate-what-is-not-available`** — List pages with status `foundation`, then pages with status `not_yet`. The inverse question, and often the more useful one when somebody is deciding whether to buy or build.

## Running one by hand

A runner is not required. Each step is one of the operations in the OpenAPI file, so the first workflow is two `curl` calls where the second argument comes from the first response.

```bash
# step: search
curl -sS 'https://connectbyjbrh.com/api/public/docs/search?q=call+recording&limit=5'
#   -> results[0].url  and results[0].status

# step: fetch
curl -sS 'https://connectbyjbrh.com/api/public/docs/page?ref=<results[0].url>&body=true'
#   -> body (the answer) and url (the citation)
```

The document names its success criteria explicitly — HTTP `200`, and for the search step a `results` array that is present — so a runner knows what counts as a completed step rather than guessing from the absence of an exception. Step outputs are addressed with JSON pointers such as `$response.body#/results/0/url`, and a later step refers to them as `$steps.search.outputs.topPage`.

## Does Connect run these itself?

No. The Arazzo document is a description for callers, not an engine inside the product. Connect's own end-to-end flows — a call arriving, a draft being approved and sent, a prospect being researched — are the product, and they are documented for people at [End-to-end workflows](/docs/workflows/). They are deliberately not exposed as a developer API, and nothing in this file touches a workspace.

The file is generated by the documentation build alongside the OpenAPI description it references, and names it in `sourceDescriptions` as `publicDocsApi`. Both are overwritten on the next build, so the workflow steps cannot drift from the operations they call.

## Questions

### Do I need an Arazzo runner to use these?

No. They are ordinary sequences of two HTTP calls each, and reading the file as documentation is a legitimate use of it. A runner buys you the success criteria and the output wiring for free.

### Why are there only three?

Because only public, unauthenticated outcomes belong in it, and the public API has five read operations. Three sequences cover the useful combinations; a longer file would be padding.

### Can I add my own workflow to it?

Not to the published file, which is generated. Nothing stops you writing your own Arazzo document that references the same `openapi.yaml` as a source description — that is what the format is for.

## Related

- [The OpenAPI description](https://connectbyjbrh.com/developers/openapi-description/)
- [The public API](https://connectbyjbrh.com/developers/public-api/)
- [Developers and AI agents](https://connectbyjbrh.com/developers/)
- [Arazzo](https://connectbyjbrh.com/docs/protocols/arazzo/)
- [End-to-end workflows](https://connectbyjbrh.com/docs/workflows/)
- [Building an agent on Connect safely](https://connectbyjbrh.com/developers/agent-safety/)

## What this page is based on

- `webapp/developers/workflows.arazzo.yaml`
- `webapp/developers/openapi.yaml` — the source description it references
- Arazzo 1.1.0 — https://spec.openapis.org/arazzo/latest.html