> ## Documentation Index > Fetch the complete documentation index at: https://docs.preuve.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/agent/agency/analyses openapi: 3.1.0 info: title: Preuve Agent API version: '2.0' description: > API for programmatic startup idea validation. Every request carries a single x-preuve-key header holding the whole API key - no signing, no bearer token. See the Authentication guide. servers: - url: https://preuve.ai security: - preuveKey: [] paths: /api/agent/agency/analyses: post: tags: - Agency summary: Start a client project description: > 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. operationId: createAgencyAnalysis requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgencyAnalysisRequest' responses: '200': description: Existing report replayed via clientRunId (reused=true). content: application/json: schema: $ref: '#/components/schemas/AgencyReportStatus' '202': description: Client report created and dispatched. content: application/json: schema: $ref: '#/components/schemas/AgencyReportStatus' '400': description: > Invalid body (CLIENT_RUN_ID_REQUIRED, IDEA_TOO_SHORT, INVALID_SCAN_TYPE, INVALID_INPUT, INVALID_JSON). content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: > Key does not carry agency:write (INSUFFICIENT_SCOPE), no shared project credits (AGENCY_QUOTA_EXCEEDED), workspace pending approval (AGENCY_NOT_APPROVED), billing setup required, account suspended (ACCOUNT_SUSPENDED), or blocked address (IP_BLOCKED). agency:write is not implied by analysis:write and did not exist before 2026-09-09, so a key created earlier always fails this check - see the AgencyInsufficientScope response for the recovery and the condition on each of its two routes. content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': $ref: '#/components/responses/AgencyNotFound' '409': description: > clientRunId belongs to another workspace (CLIENT_RUN_ID_CONFLICT) or the reservation is still settling (REQUEST_IN_PROGRESS - retry the same clientRunId). content: application/json: schema: $ref: '#/components/schemas/ApiError' '413': description: Body over the size limit (PAYLOAD_TOO_LARGE). content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': $ref: '#/components/responses/RateLimited' '503': description: > Dispatch definitively rejected (TRIGGER_DISPATCH_FAILED, credit restored) or generation paused (LLM_PAUSED). content: application/json: schema: $ref: '#/components/schemas/ApiError' components: schemas: CreateAgencyAnalysisRequest: type: object required: - clientRunId - idea properties: clientRunId: type: string maxLength: 200 description: Idempotency key, scoped to the calling API key. idea: type: string minLength: 40 maxLength: 50000 targetMarket: type: string maxLength: 180 targetCountry: type: string maxLength: 80 default: global stage: type: string maxLength: 80 budget: type: string maxLength: 80 language: type: string maxLength: 12 default: en scanType: type: string enum: - deep description: > Optional and deep-only. An Agency project always spends one shared deep project credit; any other value is 400 INVALID_SCAN_TYPE. publish: type: boolean enum: - false description: > Not accepted here. Client share links are created in the Agency dashboard; publish=true is 400 INVALID_INPUT. AgencyReportStatus: type: object properties: reportId: type: string status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED scanType: type: string enum: - starter - deep analysisTier: type: string readyForExport: type: boolean reportUrl: type: string format: uri createdAt: type: string format: date-time pollAfterSeconds: type: integer description: Present only while the report is not terminal. reused: type: boolean description: Present when this clientRunId replayed an existing report. dispatchPending: type: boolean description: > 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. recovery: type: string description: What to do next, present alongside dispatchPending. ApiError: type: object required: - error - code properties: error: type: string description: Human-readable message. code: type: string description: Stable machine-readable code. Branch on this. details: description: Optional context (validation errors, limits, ...). responses: AgencyNotFound: description: > No Agency workspace on this account, or workspace membership was removed (AGENCY_NOT_FOUND). Membership is resolved live on every call. content: application/json: schema: $ref: '#/components/schemas/ApiError' RateLimited: description: Rate limited (RATE_LIMITED or DAILY_LIMIT_REACHED). content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: preuveKey: type: apiKey in: header name: x-preuve-key description: > Your API key (prv_...), sent as-is. It is the only credential the API needs - see the Authentication guide. ````