---
title: "Ask the multi-agent Director for editing advice (never writes)"
method: POST
path: "/v1/projects/{id}/consult"
tags: ["consult"]
---

# Ask the multi-agent Director for editing advice (never writes)

`POST /v1/projects/{id}/consult`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/projects/{id}/consult`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.cueframe.ai/api/auth/mcp/authorize`, token URL `https://api.cueframe.ai/api/auth/mcp/token`, scopes: `projects:write`)
  - API key in header `PAYMENT-SIGNATURE`

Ask the Director for editing advice on the project's current composition — it NEVER saves; you stay the decider. Async: poll the returned job for the advisory envelope. Modes: 'advise' = the planner agent (fast, ~30s-2min) returns a PLAN (framing/cuts/captions/graphics intents) as guidance you re-author from — no grounded scores; 'amend' = the full author→judge→refine loop (minutes) returns a GRADED assessment + an adoptable fix candidate (adopt via POST /compose/jobs/:jobId/select with its candidateIndex). ('explore' — a ranked slate of directions — is coming soon.)

## Path parameters

- `id` string, required

## Request body

- ConsultRequest: POST /projects/:id/consult body.
  - `intent` string, required: Plain-English goal — what you're trying to achieve with this edit.
  - `mode` 'advise' | 'amend' | 'explore': advise = proposer-only (no render/judge, no grounded assessment); amend (default) = grade the current composition + author the fix for the weakest criterion; explore = ranked slate of diverse directions. All modes are async — poll the returned job.
  - `focus` 'editorial' | 'spatial' | 'brand' | 'caption': Optional criterion to concentrate the advice on.
  - `ifMatch` string: Etag of the composition the advice is computed against. Proposals are bound to it; apply a proposal BEFORE any other edit or it will 409.

## Response `202`

Consult job queued.

- ConsultResponse: POST /projects/:id/consult response.
  - `consultJobId` string, required: Opaque consult job id; poll it for the advisory result.
  - `projectId` string, required
  - `status` 'queued' | 'failed', required: queued = normal; failed = startup failed and the job is already terminal.
  - `streamUrl` string: Relative SSE endpoint to stream this job's events.

## Other responses

- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required — billing_required or x402 payment_*.
- `403`: Forbidden — permission insufficient.
- `404`: Resource not found.
- `422`: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
- `429`: Rate limited. Retry-After header present.
- `500`: Internal error.
- `503`: Service unavailable — billing_unavailable / honest-503 for runtime deps.

---

[API](https://skmtc.dev/cueframe/apis/cueframe-api.md) · [All operations](https://skmtc.dev/cueframe/apis/cueframe-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cueframe/apis/cueframe-api/revisions/8f9bfe362b4a?raw)