API Reference: Deliverables

Deliverables are the output artifacts produced by engagement runs. Each deliverable is a markdown document associated with a specific task. Deliverables support versioning (new versions are created on re-runs), approval workflows, targeted reruns, and PDF export.

All endpoints require authentication (cookie or API key Bearer token). Data is automatically scoped to your tenant.

List Deliverables

GET /api/engagements/:id/deliverables

Returns all deliverables for an engagement, sorted by creation date (newest first). This includes all versions of each deliverable.

By default, internal engine files (filenames starting with _, such as _run_report_*, _operations_review_*, _library_entry_*) are excluded. Use ?include_internal=true to include them.

Auth: Required (cookie or API key)

Path parameters:

Parameter	Description
`id`	Engagement ID (cuid)

Query parameters:

Parameter	Default	Description
`include_internal`	`false`	Set to `true` to include engine internal files (run reports, operations reviews, library entries)

Response:

[
  {
    "id": "clx3del001...",
    "filename": "digital-presence-strategy.md",
    "version": 2,
    "wordCount": 2680,
    "taskId": "digital_strategy",
    "createdAt": "2025-10-16T10:30:00.000Z"
  },
  {
    "id": "clx3del002...",
    "filename": "digital-presence-strategy.md",
    "version": 1,
    "wordCount": 2450,
    "taskId": "digital_strategy",
    "createdAt": "2025-10-15T08:55:00.000Z"
  },
  {
    "id": "clx3del003...",
    "filename": "competitive-analysis.md",
    "version": 1,
    "wordCount": 1800,
    "taskId": "competitive_analysis",
    "createdAt": "2025-10-15T08:50:00.000Z"
  }
]

curl example:

curl -H "Authorization: Bearer gt_live_YOUR_KEY" \
  https://app.groundtruth.ai/api/engagements/clx1abc2d0001/deliverables

Get Version History

GET /api/engagements/:id/deliverables/:filename/versions

Returns all versions of a specific deliverable, sorted by version number (newest first). The :filename parameter is URL-encoded.

Auth: Required (cookie or API key)

Path parameters:

Parameter	Description
`id`	Engagement ID (cuid)
`filename`	Deliverable filename (URL-encoded, e.g., `digital-presence-strategy.md`)

Response:

{
  "versions": [
    {
      "id": "clx3del001...",
      "version": 2,
      "wordCount": 2680,
      "createdAt": "2025-10-16T10:30:00.000Z",
      "approvalStatus": "pending_review"
    },
    {
      "id": "clx3del002...",
      "version": 1,
      "wordCount": 2450,
      "createdAt": "2025-10-15T08:55:00.000Z",
      "approvalStatus": "revision_requested"
    }
  ]
}

curl example:

curl -H "Authorization: Bearer gt_live_YOUR_KEY" \
  https://app.groundtruth.ai/api/engagements/clx1abc2d0001/deliverables/digital-presence-strategy.md/versions

Submit Review

POST /api/engagements/:id/deliverables/:filename/review

Submits a review for the latest version of a deliverable. The review updates the approval status and optionally includes notes (useful for revision requests).

This endpoint dispatches a webhook event based on the action taken:

approve dispatches deliverable.approved
request_revision dispatches deliverable.revision_requested
reject dispatches deliverable.rejected

Auth: Required + write access

Rate limit tier: api

Path parameters:

Parameter	Description
`id`	Engagement ID (cuid)
`filename`	Deliverable filename (URL-encoded)

Request body:

Field	Type	Required	Description
`action`	string	Yes	One of: `approve`, `request_revision`, `reject`
`notes`	string	No	Review notes or revision instructions

Response:

{
  "deliverableId": "clx3del001...",
  "approvalStatus": "approved",
  "reviewedAt": "2025-10-16T14:00:00.000Z",
  "reviewedBy": "Jane Smith"
}

Error responses:

Status	Error	Cause
`400`	`"Invalid JSON"`	Request body is not valid JSON
`400`	`"action must be: approve, request_revision, or reject"`	Missing or invalid `action` value
`403`	`"Read-only API key"`	API key does not have write access
`404`	`"Not found"`	Deliverable or engagement not found

curl examples:

Approve a deliverable:

curl -X POST \
  -H "Authorization: Bearer gt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve", "notes": "Excellent analysis, ready for client."}' \
  https://app.groundtruth.ai/api/engagements/clx1abc2d0001/deliverables/digital-presence-strategy.md/review

Request a revision:

curl -X POST \
  -H "Authorization: Bearer gt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "request_revision", "notes": "Please add more detail on competitor pricing strategies."}' \
  https://app.groundtruth.ai/api/engagements/clx1abc2d0001/deliverables/digital-presence-strategy.md/review

Targeted Rerun

POST /api/engagements/:id/deliverables/:filename/rerun

Triggers a targeted re-run for a specific deliverable's task. Instead of re-running the entire engagement, only the task that produced this deliverable is re-executed. This creates a new version of the deliverable.

The existing deliverable is automatically versioned (snapshot) before the re-run begins.

Auth: Required + write access + active subscription

Rate limit tier: engine (5 requests per 60 seconds)

Path parameters:

Parameter	Description
`id`	Engagement ID (cuid)
`filename`	Deliverable filename (URL-encoded)

Response:

{
  "runId": "clx2run003...",
  "status": "running",
  "message": "Task rerun started"
}

Error responses:

Status	Error	Cause
`403`	`"Read-only API key"`	API key does not have write access
`403`	`"Active subscription required"`	No active Stripe subscription
`404`	`"Not found"`	Deliverable or engagement not found
`409`	`"Engagement is already running"`	Another run is already in progress
`502`	`"Engine error: ..."`	The execution engine failed to start the rerun

On engine failure, the run and engagement status are rolled back to failed.

curl example:

curl -X POST \
  -H "Authorization: Bearer gt_live_YOUR_KEY" \
  https://app.groundtruth.ai/api/engagements/clx1abc2d0001/deliverables/digital-presence-strategy.md/rerun

Export Deliverable as PDF

GET /api/engagements/:id/deliverables/:filename/export/pdf

Generates and downloads a PDF for a single deliverable (latest version). The PDF includes tenant branding (company name, primary color) and deliverable metadata (engagement name, client, version, word count, approval status).

Auth: Required (cookie or API key, minimum viewer role)

Path parameters:

Parameter	Description
`id`	Engagement ID (cuid)
`filename`	Deliverable filename (URL-encoded)

Query parameters:

Parameter	Default	Description
`include_provenance`	`false`	Set to `true` to add a provenance footer showing which agent and model produced the deliverable, along with observer score and cost

Response: Content-Type: application/pdf

The response is a binary PDF file with a Content-Disposition header:

Content-Disposition: attachment; filename="digital-presence-strategy_md.pdf"

Non-alphanumeric characters in the filename (except _, ., -) are replaced with underscores in the download filename.

Error responses:

Status	Error	Cause
`403`	`"Insufficient permissions"`	User role is below `viewer`
`404`	`"Engagement not found"`	Engagement does not exist
`404`	`"Deliverable not found"`	No deliverable with that filename exists

curl example:

curl -H "Authorization: Bearer gt_live_YOUR_KEY" \
  -o deliverable.pdf \
  https://app.groundtruth.ai/api/engagements/clx1abc2d0001/deliverables/digital-presence-strategy.md/export/pdf

Approval Workflow

Deliverables follow this approval lifecycle:

(created) --> pending_review --> approved
                  |
                  +--> revision_requested --> (rerun) --> pending_review
                  |
                  +--> rejected

Status	Description
`pending_review`	Default status after deliverable is generated
`approved`	Reviewed and accepted
`revision_requested`	Reviewer requested changes; trigger a rerun to produce a new version
`rejected`	Reviewed and rejected

When a revision is requested, use the Targeted Rerun endpoint to re-execute the task. The new version enters pending_review status automatically.

Engagements -- Engagement CRUD and run control endpoints
Overview -- Authentication, rate limiting, error format

API Reference: Deliverables

On this page