> ## Documentation Index
> Fetch the complete documentation index at: https://www.composer.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Manuscript API

> The Manuscript API serves the full record behind a published score: assessments, documents, surveys, workflows and signed PDFs, with signed webhooks.

The Manuscript API serves the record behind a decision to the people entitled to it: the programme's MSP and its reporting suites. This page covers what the manuscript holds, the twelve endpoints, how webhook deliveries are signed, and how the Intent ID joins the manuscript to the published score.

A destination system receives the **score**: a valid request carrying the Intent ID. The **manuscript** is everything behind it: the scored diagnostic, the answers, the documents, the workflow and its signed PDF. Destinations never receive the manuscript.

<Info>
  The Manuscript API runs on Deployed's production backend, WorkAuthor, at `https://deployed.workauthor.com/api/v1`. Calls are service to service with per-customer API keys, webhook deliveries are HMAC-SHA256 signed, and access is granted per programme. Everything on this page matches the service's published v1 OpenAPI document.
</Info>

## What the manuscript holds

<AccordionGroup>
  <Accordion title="Assessments" description="The scored diagnostics" icon="list">
    Each response carries the score, its description, per-section scores, every question and answer, notes, and the ranked outcomes the decision was made from.
  </Accordion>

  <Accordion title="Documents" description="Records created from templates" icon="file-text">
    Created from a template with a field payload and returned with an id and a URL. Each carries its full dated lifecycle: created, completed, published, in review, review completed, archived.
  </Accordion>

  <Accordion title="Surveys" description="Secondary evidence" icon="message-square">
    Who submitted, when, and every question and answer. Surveys have no score fields.
  </Accordion>

  <Accordion title="Workflows" description="The approval record behind a document" icon="workflow">
    Includes the signed PDF: the evidence entry the Compliance File points at.
  </Accordion>

  <Accordion title="Correlation" description="externalId carries the Intent ID" icon="hash">
    `externalId` on assessments and documents carries the Intent ID, so the manuscript and the published score join both ways with no lookup table. `CreateDocumentBody.externalId` declares a maximum of 64 characters; the assessment and document response schemas declare it as a plain nullable string.
  </Accordion>
</AccordionGroup>

## Endpoints

All twelve operations are relative to `https://deployed.workauthor.com/api/v1`. List operations page with `Page` and `PageSize`. Every operation, parameter and schema is on the endpoint pages in this tab, generated from the service's own OpenAPI document.

| Endpoint                          | What it returns                                                                                                                                                                                                                                                                       |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /assessments`                | Paged list of assessments: name, group, status, tags and response counts.                                                                                                                                                                                                             |
| `GET /assessments/{Id}`           | Paged list of one assessment's scored responses, filterable by `From` and `To` dates.                                                                                                                                                                                                 |
| `GET /assessments/responses/{Id}` | The full scored response: `responseId`, `depReference`, `externalId`, `user`, `startDate` and `endDate`, `score`, `scoreDescription`, `sectionScores[]`, `questions[]`, `notes[]`, `rankedScores[]`.                                                                                  |
| `GET /surveys`                    | Paged list of surveys.                                                                                                                                                                                                                                                                |
| `GET /surveys/{Id}`               | Paged responses for one survey, filterable by `From` and `To`.                                                                                                                                                                                                                        |
| `GET /surveys/responses/{Id}`     | A survey response: `user`, `submitted`, and `questions[]` with `question`, `rating` and `answer`.                                                                                                                                                                                     |
| `GET /documents/templates`        | Paged list of templates, filterable by `UserEmail`.                                                                                                                                                                                                                                   |
| `GET /documents/templates/{Id}`   | A template's fields and their types (`TextShort`, `TextLong`, `Number`, `CustomLookup`, `Address`): what a create call must supply.                                                                                                                                                   |
| `POST /documents`                 | Creates a document from `templateId` and `templateFields`, with `ownerEmail`, `coAuthorEmail`, `documentName` (at most 200 characters), `externalId` (at most 64) and an optional per-document `eventNotification` of `webhookUrl` and `events[]`. Returns `201` with `id` and `url`. |
| `GET /documents/{Id}`             | `status` plus the dated lifecycle: `createdDate`, `completedDate`, `publishedDate`, `inReviewDate`, internal and external review started and completed dates, `reviewCompletedDate`, `archivedDate`; plus owner, co-authors, collaborators, `entities` and `workflows[]`.             |
| `GET /workflows/{Id}`             | `parentId`, `parentType`, `type`, `status`, created and last-updated dates.                                                                                                                                                                                                           |
| `GET /workflows/{Id}/signed-pdf`  | The signed PDF for the workflow: the Compliance File's `pdf_signed` evidence source.                                                                                                                                                                                                  |

Errors share one shape across every operation: `type`, `title`, `status`, an `errors[]` array of `code`, `description` and `type`, and a `traceId`.

## Signed webhooks

Deliveries are signed so a receiver can prove they came from WorkAuthor. Verify every delivery in this order.

<Steps>
  <Step title="Read the raw request body">
    Use the body exactly as received. Never digest a parsed or re-serialised payload.
  </Step>

  <Step title="Compute a digest with each active signing key">
    For each of your active signing keys, compute the HMAC-SHA256 digest of the raw body and Base64-encode it. Several keys can be active at once during rotation.
  </Step>

  <Step title="Compare against every signature header">
    The request carries one or more `X-Signature-HMAC-SHA256-{n}` headers, one per active key on the sending side. Compare each computed digest against each header value with a timing-safe comparison. The numeric suffix is an identifier only; it maps to no particular key.
  </Step>

  <Step title="Accept on any match, otherwise reject">
    The request is valid if any computed digest matches any supplied header. A request with no valid signature is rejected, not queued.
  </Step>
</Steps>

`POST /documents` accepts an `eventNotification` so a single document can notify a chosen URL on chosen events. [Signed webhooks](/api-reference/manuscript/webhooks) quotes the rules and the vendor's C# and Node.js examples in full, and [Webhook events](/api-reference/manuscript/webhook-events) lists the event types. The reference verifier, with the rotation and timing-safe rules as tests, is `adapter/webhook_verify.py` in the composerID reference code.

## One ID, score and manuscript

Every intent carries one Intent ID (`itn_...`, up to 64 characters). At publish time it lands in the destination record; at creation time it is written into the manuscript's `externalId`. The same ID therefore finds the published score in the destination system and the full manuscript here, in either direction, with no lookup table.

## Access

<Info>
  Manuscript access is granted per programme, to the MSP and reporting systems the client names, with API keys and signing keys issued at onboarding. The OpenAPI document declares no security scheme because API-key authentication is configured per customer, outside the specification. Manuscript credentials are separate from the Intent API's: [Authentication](/authentication) covers the Intent API only. Manuscript access is never part of a destination integration: destinations receive the score, not the manuscript. [Score and manuscript](/concepts/two-paths) explains the boundary.
</Info>

## Next steps

<Columns cols={3}>
  <Card title="Signed webhooks" icon="shield-check" href="/api-reference/manuscript/webhooks">
    The signing rules as quoted from the OpenAPI document, with verifier examples.
  </Card>

  <Card title="Webhook events" icon="webhook" href="/api-reference/manuscript/webhook-events">
    The event types and the per-document notification configuration.
  </Card>

  <Card title="Score and manuscript" icon="split" href="/concepts/two-paths">
    Why destinations receive the score and only the MSP receives the manuscript.
  </Card>
</Columns>