AI Pipeline & Export

Pipeline operations are asynchronous. They return 202 Accepted immediately and process in the background. Use webhooks to get notified when each stage completes, or poll GET /proposals/:id and check the status field.

Analyze Proposal

POST /api/v1/proposals/:id/analyze

Scope: proposals:generate

Runs AI analysis on the client brief. Extracts requirements, identifies project type, and structures the scope.

Prerequisites

• Proposal must be in draft status
• rawInputText must be set (the client brief)

Response — 202 Accepted

{
  "data": {
    "id": "360db97a-...",
    "status": "analyzing"
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

Webhook events

• proposal.analysis_completed — analysis finished, proposal status changes to analyzed
• proposal.analysis_failed — analysis errored, proposal resets to draft

---

Generate Proposal

POST /api/v1/proposals/:id/generate

Scope: proposals:generate

Generates the full proposal document with pricing breakdown and timeline. Analysis must have completed first.

Prerequisites

• Proposal must be in analyzed status

Response — 202 Accepted

{
  "data": {
    "id": "360db97a-...",
    "status": "generating"
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

Webhook events

• proposal.generation_completed — proposal generated, status changes to ready
• proposal.generation_failed — generation errored

---

Score Proposal

POST /api/v1/proposals/:id/score

Scope: proposals:generate

Scores the generated proposal on quality, completeness, and persuasiveness. Returns an overall score (0–100) with category breakdowns.

Response — 202 Accepted

{
  "data": {
    "id": "360db97a-...",
    "status": "scoring"
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

Webhook events

• proposal.scoring_completed
• proposal.scoring_failed

---

Export Proposal

POST /api/v1/proposals/:id/export

Scope: proposals:read

Exports the proposal to a downloadable file and returns a signed URL valid for 15 minutes.

Request body

{
  "format": "pdf"
}

Available formats

pdf — Available on all plans (including Free)

docx — Requires Solo plan or higher

pptx — Requires Solo plan or higher

Response

{
  "data": {
    "downloadUrl": "https://...",
    "format": "pdf",
    "expiresAt": "2026-03-17T10:45:00.000Z"
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

Download the file from downloadUrl before it expires. Fires a proposal.exported webhook event.

---

Get Usage

GET /api/v1/usage

Scope: proposals:read

Returns your current plan, usage counts, and billing period.

Response

{
  "data": {
    "plan": "solo",
    "proposalsUsed": 10,
    "proposalsLimit": 25,
    "addonCredits": 0,
    "periodStart": "2026-03-01T00:00:00.000Z",
    "periodEnd": "2026-03-31T23:59:59.999Z"
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

---

Pipeline status flow

Understanding the proposal status transitions:

draft → analyzing → analyzed → generating → ready
  ↑         |                       |
  └─────────┘                       └── (on failure, resets to previous status)

draft — Created, not yet analyzed

analyzing — AI analysis in progress

analyzed — Analysis complete, ready for generation

generating — Proposal document being written

ready — Fully generated, can be exported and shared

scoring — Being scored (proposal stays ready after)

sent — Marked as sent to client

archived — Soft-deleted