Agency

Start a client project

Create one deep client report against the shared Agency project quota. Never falls back to personal credits. Async: 202 on a new dispatch, 200 with reused=true when the clientRunId replays an existing report. clientRunId is scoped to the calling key; reusing one that belongs to a different workspace is 409 CLIENT_RUN_ID_CONFLICT. A response carrying dispatchPending=true means the dispatch outcome is unknown - retry the same clientRunId and arguments after 60 seconds; recovery reuses the original report and credit. 503 TRIGGER_DISPATCH_FAILED is a definite rejection: the credit was restored and that request stays failed on replay, so a new attempt needs a new clientRunId. Creating a report here does not email the client or publish a share link.

post/api/agent/agency/analyses

Request

  • Base URL: https://preuve.ai
  • URL: https://preuve.ai/api/agent/agency/analyses
  • Auth: API key in header x-preuve-key

Request body

clientRunIdstring required

Idempotency key, scoped to the calling API key.

ideastring required
targetMarketstring
targetCountrystring
stagestring
budgetstring
languagestring
scanType'deep'

Optional and deep-only. An Agency project always spends one shared deep project credit; any other value is 400 INVALID_SCAN_TYPE.

publishfalse

Not accepted here. Client share links are created in the Agency dashboard; publish=true is 400 INVALID_INPUT.

Response

Existing report replayed via clientRunId (reused=true).

reportIdstring
status'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED'
scanType'starter' | 'deep'
analysisTierstring
readyForExportboolean
reportUrlstring uri
createdAtstring date-time
pollAfterSecondsinteger

Present only while the report is not terminal.

reusedboolean

Present when this clientRunId replayed an existing report.

dispatchPendingboolean

The dispatch outcome is unknown. Retry the same clientRunId and arguments after 60 seconds; recovery reuses the original report and credit. Past 23 hours the recovery text directs you to support instead of risking a duplicate job.

recoverystring

What to do next, present alongside dispatchPending.

Changes

No recorded changes to this operation across all 1 revision of this API.