Approvals

hlix keeps two delivery decisions with people: approving the initial proposal when a new agency delivery project requires one, and merging finished work into the repository’s default branch. During delivery, agents can also ask questions or request a tool decision.

Initial proposal approval

A new project starts by itself. You turn initial proposal review on for a project on purpose; without it the proposal is still written and stays open to read and change, and hlix posts a message in the project chat when the whole plan is ready. For a project that requires an initial proposal, setup and initial planning run in parallel. The first build agent waits until an agency member approves the current ready specification and statement of work. The proposal shows the actual accepted cycles, tasks, dependencies and frozen quotes.

Review the ready revision on the project’s proposal surface. Approval applies to that exact revision and content hash. Optional client review or acceptance does not replace agency approval. Later operational replans proceed autonomously.

Before the first build agent starts

1. Prepare the scopeThe project manager plans the cycles, tasks, and quotes.
2. Agency approvesAn agency member approves the exact ready proposal revision.
3. Delivery beginsBuild agents do the work, review agents check it, and the accepted scope integrates into the preview.

For projects using an initial proposal, environment setup runs alongside planning. Client approval does not replace agency approval.

For API integrations, read GET /v1/api/projects/:id/initial-proposal, then approve with POST /v1/api/projects/:id/initial-proposal/approve, passing the current revisionId and contentHash. Resolve requested changes through the proposal’s revision workflow; a generic approval does not approve the specification.

Approvals

An approval records a question or decision associated with a project, cycle or task. Most approval types record your answer without starting or resuming delivery. A tool_permission approval can pause the calling agent’s chat until a decision is supplied. That is separate from the project’s initial proposal and final merge.

Prerequisites

• A project you can administer (agency owner, admin, or member)

Finding what is waiting

curl -sS "$HLIX_BASE_URL/v1/api/pending-requests?status=pending" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

status, cycleId, and taskId are the supported query filters. A per-cycle read is also available at GET /v1/api/cycles/:id/pending-requests.

Read each approval’s title, context, intended recipient and status before deciding. Its blocking field indicates whether an agent is waiting.

In the dashboard, Approvals lists every approval across the workspace.

Approval types

• Tool permissions (tool_permission) can pause the calling agent. Resolving a waiting approval lets that chat continue.
• Questions and other approvals record your answer and its audit trail. Read the approval’s context to see what it needs.

Use the proposal workflow above for initial scope approval and Review for the final merge.

Deciding

Set status to approved or denied when resolving an approval:

curl -sS -X POST "$HLIX_BASE_URL/v1/api/pending-requests/$REQUEST_ID/resolve" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
  -H 'content-type: application/json' \
  -d '{"status":"approved","decision":"Approved. The migration is reversible."}'

status is approved or denied and is required; decision is optional free text up to 5000 characters. The response is the updated approval with status, decision, decidedBy, and decidedAt written. Every decision is written to the audit log.

To withdraw an approval instead of deciding it:

curl -sS -X POST "$HLIX_BASE_URL/v1/api/pending-requests/$REQUEST_ID/cancel" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

Cancelling withdraws the approval. For a waiting tool-permission approval, cancellation denies the tool call.

Asking the client a question

POST /v1/api/pending-requests/client-question opens a non-blocking requirement_clarification addressed to the portal client:

curl -sS -X POST "$HLIX_BASE_URL/v1/api/pending-requests/client-question" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
  -H 'content-type: application/json' \
  -d '{"cycleId":"'"$CYCLE_ID"'","title":"Invoice numbering","question":"Should invoice numbers restart each fiscal year?"}'

Send cycleId, title and question. Agency members can ask; the named client can answer.

If an approval will not resolve

• {"error":"Request already approved"} — someone decided it first. Re-read the approval before acting.
• {"error":"Not found"} — check the approval ID and Workspace. Portal clients can only access approvals addressed to them.
• A recorded approval did not start work — most approval decisions only record an answer. For an initial proposal, approve the current ready revision through the proposal workflow.

Next steps

Cycles

Run cycles, follow progress, and review their results.

Review & QA gates

How Hlix checks changes before you merge.

Triage

How Hlix judges a new request before it becomes work.

Reviewing output

Inspect changes and check results before you merge.