jb/paseo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ccb4e444ed556c3ae6a8a98a22c9499ce8287a85
paseo/public-docs/hub/api.md
T
Mohamed BoudraandGitHub ccb4e444ed Rework Hub workflow docs around explicit delivery and GitHub authority (#3086) 
* docs(hub): name the Hub tools in workflow prompts

Every Hub workflow example now tells the agent which tool to call:
hub.reply for the user-facing response, hub.finish_execution to
complete the step and record structured output. Granting a capability
through allow_outputs makes the tool available; it does not make an
agent use it, and an agent that is not told answers in its own
transcript and leaves the step to its idle timeout. Explicit
instructions are what worked against real agents.

Classifier and other intermediate steps name hub.finish_execution
alone, so the docs do not imply every step must reply.

Drops the github.reply allow_outputs blocks from the GitHub examples.
The GitHub provider registers no output capabilities, so that
declaration never materializes a tool; those agents comment through
their scoped GH_TOKEN with gh, which the reference and trigger pages
already said. The read-only answer branch has no network authority for
that, so it only finishes.

Also quotes the "Request: ${{ paseo.prompt }}" prompt block in the
reference, which was invalid YAML as written.

* docs(hub): wrap triggering input in its own prompt block

Every Hub YAML example now ends its prompt with the raw triggering
message wrapped in <user-prompt> tags, as a separate block after the
workflow instructions. The agent can see where your instructions stop
and the request starts, which matters most on the steps that read
external Slack, Discord, and GitHub text.

The first workflow explains the convention in two sentences and points
at Hub security for the controls that actually limit an agent. Tags
label the input; they are not containment, and the docs do not claim
otherwise.

Replaces the earlier quoting fix in the prompt-blocks reference: the
message now lives in a block scalar, so the colon needs no quoting.

* docs: base worktree examples on origin/main

Every branch-off example now passes a remote-tracking ref. Paseo
fetches remote refs in the background, so origin/main is current while
the local main is whatever was last pulled, and base resolution tries
refs/heads first: an unqualified main silently branches off stale
history. The gotcha is explained once, next to the first branch-off
example in the worktrees guide; the other pages just use the ref, and
the Hub environment reference links there.

Also points the safety-gate classifier at the structured-output
section, which shows the output wrapper the finish call takes.

* docs(hub): configure Codex read-only through provider options

Hub examples described a read-only Codex step as mode: read-only. That
Paseo mode preset pairs the read-only sandbox with approval_policy
on-request, so an unattended Hub step stops to ask a question nobody is
there to answer. It is also not one of the modes the Codex provider
advertises.

Every read-only step now uses the provider-native passthrough proven by
the real-provider evidence in #3025: approval_policy never,
sandbox_mode read-only, web_search disabled. The security guide already
used this block; the workflow guide, examples, and reference now agree
with it, and the reference says plainly that a Paseo mode ID is a
separate surface from these options.

mode: full-access is unchanged. It maps to approval_policy never, so it
does not stall an unattended step.

* docs(hub): show a classifier choosing the repository and the model

Both routing jobs were only documented as caller-supplied inputs, so
there was no example of the thing people actually want: one read-only
classifier that reads the request, picks the repository it belongs to
and the model it needs, and hands both to a worker. Replaces the
caller-only model example, which the new one covers through its
override values.

The two axes are not symmetric and the example says so. A model is a
value, so values.selected_model goes straight into agent.model. An
environment cannot come from an expression at all: the compiler accepts
a literal name or paseo.inputs.<name> and nothing else, so each
repository needs its own environment and its own conditional step. One
classifier, exactly one worker.

Corrects the routing section, which listed environment among the fields
an agent output may select. It never could.

Also puts a blank line between adjacent steps and environments in the
deadline and repository-routing examples, and bases the daemon worktree
example on origin/main, which the earlier sweep missed.

* fix(website): keep development requests local

Canonical host redirects were applied to LAN-addressed development traffic, including inspector WebSockets. The redirected socket retained the Vite port and caused the development proxy to terminate when the public host timed out.

* docs(hub): order the workflow scenarios from simple to hard

The Hub pages were arranged by the shape of the configuration schema
rather than by what a reader is trying to do, which showed up three
ways: the overview opened on the storage hierarchy, workflow
configurations were split between workflows.md and a separate examples
page, and the examples that existed started with the hardest one.

workflows.md is now a ladder. One Slack trigger answering in a thread
stays inline as the first workflow, and nine further scenarios sit
under it as collapsible blocks, each a complete configuration adding
one idea to the one above: full access, repeated replies, a GitHub
trigger, two ordered steps, a typed input, two triggers, a classifier
choosing a model, a classifier choosing a repository, and last the
override composed with ??. configuration/examples.md is removed and its
configurations live there now.

Two claims in the old material were wrong and are corrected. Nothing
carries between steps except a declared output, so the planning
scenario passes its plan through output.schema instead of telling the
second agent to follow a plan it cannot see, and a worktree environment
creates a worktree per execution rather than sharing one. GH_TOKEN
authenticates the gh CLI but does not configure git, so the pages no
longer imply a step can push without a commit identity and credential
helper on the daemon host.

The overview drops the organization/connections/daemons/projects tree,
which concepts.md already owns, in favour of the smallest configuration
that does something. Hosting is now a link from the product pages
rather than a section in them.

* docs(hub): make GitHub access an explicit step grant

GitHub authority gets its own page. A step holds a token only when it
declares a github block — connection, repositories, permissions,
duration — and Hub supplies GH_TOKEN plus environment-only git
configuration, revoked when the step ends. No credential is ever
implied by the trigger source.

Rewrites the issue-to-pull-request scenario onto the block, repoints
the trigger, reference, FAQ, and concepts pages, and sweeps the Hub
pages for announcing sentences and compressed paragraphs.

* docs(hub): lighten dense reference prose

Restructure paragraph walls into short paragraphs, lists, and code
blocks: logout behavior in daemons, deploy paths and precedence in
configuration, install limits and dispatch fields in the API page,
required outputs and partial resolution in the reference, and the
policy translation and secrets guidance in security. Fixes two
remaining trigger-derived credential claims in triggers/index.

* fix(nix): update npm dependency hash

* docs(hub): document shared prompts and authority defaults
2026-08-09 16:59:00 +02:00

270 lines
10 KiB
Markdown
Raw Blame History

---
title: Hub public API
description: Use organization credentials to list projects, validate or install configuration, dispatch runs, and enroll daemons.
nav: Public API
order: 79
category: Hub
---
# Hub public API
The Hub public API lets automation operate on projects and daemons in one
organization. Set the Hub origin in `PASEO_HUB_URL` below, for example
`https://hub.example.com`.
## API reference
- [Interactive API reference](https://hub.paseo.sh/api/reference)
- [OpenAPI 3.1 document](https://hub.paseo.sh/api/openapi.json)
These are the canonical reference endpoints for the hosted Paseo Hub. A self-hosted Hub exposes the same `/api/reference` and `/api/openapi.json` paths on its own origin.
## Authentication
Run `paseo hub login [origin]` for interactive CLI access. After browser approval, Paseo stores a durable, revocable organization credential under `PASEO_HOME` for that exact origin. Without an explicit origin, the CLI uses `PASEO_HUB_URL`, then the active stored login, then `https://hub.paseo.sh`.
For automation, create an organization API key from the Hub dashboard under **API keys**. Both credential types are bearer tokens:
```http
Authorization: Bearer paseo_pk_...
Content-Type: application/json
```
API keys are organization-scoped. The organization that owns the key determines
which projects and daemon enrollment tokens it can reach; there is no
organization ID to add to these requests. A project slug from another
organization is not accessible through the key.
Each key has one or more selectable scopes:
| Scope | Operation |
| ------------------------ | --------------------------------------------------- |
| `projects:read` | List active projects in the organization. |
| `configuration:validate` | Validate configuration without changing Hub state. |
| `configuration:install` | Replace and activate a project's configuration. |
| `runs:dispatch` | Dispatch a configured manual trigger for a project. |
| `daemons:enroll` | Issue a short-lived daemon enrollment token. |
API keys do not grant dashboard access. They cannot manage connections,
projects, or organization members.
CLI credentials have the current CLI operation scopes and remain revocable independently of daemon relationships. `paseo hub logout` deletes the active local CLI credential; it does not revoke or disconnect the daemon identity.
API failures use RFC 9457 problem details. Missing, invalid, or revoked credentials return `401` with `application/problem+json`:
```json
{
"type": "https://hub.example.com/problems/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Provide a valid organization API key."
}
```
A valid key without the scope required by an endpoint returns `403` in the same format.
## Project list
`GET /api/v1/projects` returns active projects in the bearer credential's organization. `paseo hub projects` renders the projects as a table. With `--json`, it returns `{ "origin": "...", "projects": [...] }` so even an empty result records the resolved Hub.
```json
{
"projects": [
{
"id": "00000000-0000-4000-8000-000000000000",
"slug": "my-project",
"name": "My project"
}
]
}
```
## Configuration validation
`POST /api/v1/configurations/validate` accepts the same `projectSlug`, `yaml`, and optional `partials` body as configuration install. It performs the same compilation and resource resolution without recording a revision or changing the active configuration.
On success, Hub returns `200`:
```json
{
"projectSlug": "my-project",
"valid": true
}
```
`paseo hub deploy --dry-run` calls this endpoint with the identical locally resolved payload that a deployment would send.
## Configuration install
`configuration:install` replaces the project's current configuration with the
supplied YAML after Hub validates and compiles it, then activates the new
revision.
```http
POST /api/v1/configurations/install
```
Request body:
```json
{
"projectSlug": "my-project",
"yaml": "environments:\n - name: production\n kind: daemon\n daemon: build-server\n cwd: /workspace\ntriggers:\n - name: deploy\n on: manual.run\n max_runtime: 2h\n filters:\n from_users: [automation]\n steps:\n - id: deploy\n environment: production\n max_runtime: 90m\n idle_timeout: 10m\n agent:\n provider: opencode\n mode: full-access\n prompt:\n - text: Deploy the project",
"partials": [
{
"path": "docs/safety.md",
"content": "Follow the safety checklist."
}
]
}
```
`projectSlug` picks the target project; the API key fixes the organization. Replace the example daemon, working directory, and trigger values with resources in your organization.
`partials` is optional for inline-only configurations. When the YAML uses prompt `include` blocks, send exactly one entry per referenced file, with a path relative to `.paseo/partials/` and the file's UTF-8 content. Hub rejects missing, extra, duplicate, unsafe, or oversized entries.
Limits:
- YAML: 1,000,000 characters.
- Partials: at most 100 files.
- Partial path: canonical, at most 512 characters.
- Partial content: at most 1,000,000 bytes per file, 5,000,000 bytes combined.
On success, Hub returns `201`:
```json
{
"projectSlug": "my-project",
"versionId": "00000000-0000-4000-8000-000000000000",
"version": 3,
"active": true
}
```
Common responses are `400` for a missing or malformed body, `404` for an inactive or unknown project in the key's organization, and `422` for invalid YAML or an invalid configuration. Validation problem details include field issues. A failed install does not replace the active revision.
Example:
```bash
curl --fail-with-body -sS -X POST "$PASEO_HUB_URL/api/v1/configurations/install" \
-H "Authorization: Bearer $PASEO_HUB_API_KEY" \
-H "Content-Type: application/json" \
--data @configuration-install.json
```
For a local YAML file, `paseo hub deploy [file]` calls this endpoint and preserves the file contents. The command uses an exact-origin stored login when flags and environment credentials are absent. See [Deploy from the CLI](/docs/hub/configuration#deploy-from-the-cli) for project precedence and credential precedence.
## Manual run dispatch
`runs:dispatch` dispatches a configured `manual.run` trigger for a project.
The trigger must exist in the active configuration, and `actor` must be listed
in that trigger's `filters.from_users` allowlist.
```http
POST /api/manual-runs
```
Request body:
```json
{
"projectSlug": "my-project",
"expectedVersionId": "00000000-0000-4000-8000-000000000000",
"trigger": "deploy",
"actor": "automation",
"deliveryKey": "deploy-2026-08-04-001",
"input": "repo=project investigate the failed sync"
}
```
- `expectedVersionId` is optional. When supplied, Hub rejects the dispatch if that revision is no longer active.
- `input` is the same string a provider message uses: leading `key=value` tokens are parsed as declared inputs, and the remainder becomes `${{ paseo.prompt }}`.
- `deliveryKey` should be unique and stable per dispatch. Reusing one resolves to the existing trigger instead of starting a duplicate run.
On success, Hub returns `200`:
```json
{
"deliveryKey": "deploy-2026-08-04-001",
"triggerId": "00000000-0000-4000-8000-000000000000",
"executionId": "00000000-0000-4000-8000-000000000000",
"status": "spawning",
"daemonId": "00000000-0000-4000-8000-000000000000",
"agentId": "agent-id"
}
```
Common responses are `400 {"error":"invalid_request"}`, `404` for an
unknown project, missing configuration, or missing trigger, `403
{"error":"actor_forbidden"}` when the actor is not allowed by the trigger,
and `409` when the daemon is offline, the expected configuration is no longer
current, or the run could not be dispatched.
Example:
```bash
curl --fail-with-body -sS -X POST "$HUB_URL/api/manual-runs" \
-H "Authorization: Bearer $PASEO_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"projectSlug": "my-project",
"trigger": "deploy",
"actor": "automation",
"deliveryKey": "deploy-2026-08-04-001",
"input": "repo=project investigate the failed sync"
}'
```
See [Hub workflows](/docs/hub/workflows) for input types, defaults, choices,
rejected input, and manual invocation examples.
## Daemon enrollment
`daemons:enroll` issues a short-lived enrollment token for a daemon. The API
key mints this token; it is not the daemon's long-lived credential and must not
be used as one.
```http
POST /api/v1/daemons/enrollment-tokens
```
Send an empty JSON object as the request body. On success, Hub returns `201`:
```json
{
"token": "short-lived-enrollment-token",
"expiresAt": "2026-08-04T12:10:00.000Z"
}
```
The token expires after 10 minutes and is consumed when the daemon enrolls.
`paseo hub connect [origin]` performs this request with `--api-key`, `PASEO_HUB_API_KEY`, or the matching stored login, then passes the one-time token to the daemon's enrollment operation. The daemon generates and keeps its own relationship credential.
```bash
curl --fail-with-body -sS -X POST \
"$HUB_URL/api/v1/daemons/enrollment-tokens" \
-H "Authorization: Bearer $PASEO_API_KEY" \
-H "Content-Type: application/json" \
--data '{}'
```
Direct API consumers can pass the returned token to the daemon enrollment protocol. The Paseo CLI intentionally does not accept raw enrollment tokens; `connect` owns the authenticated single-flow exchange.
An enrollment token cannot be reused. Revoking the API key immediately rejects
future API requests and expires any unconsumed enrollment tokens that key
issued. A race between revocation and issuance is resolved by Hub before a new
token is stored.
## Keys, scopes, and audit information
The complete API-key secret is shown once, immediately after creation. Store it
in your deployment's secret manager; Hub does not show it again. The dashboard
retains only the key's prefix and shows its selected scopes, creation time,
last-used time, and status.
Hub updates `last used` after a key successfully authenticates for a scoped API
operation. API operations retain the key attribution in Hub's audit evidence,
so configuration revisions, manual dispatches, and daemon enrollment tokens
can be traced to the organization key that created them.
Reference in New Issue View Git Blame Copy Permalink