Prototype extract schema

[jnu]

First draft extraction schema

[sentry]

Bug: The OpenAPI callback definition only documents the callback for the first document in a multi-document request, contradicting the description that implies callbacks for all documents.
_{Severity: MEDIUM}

Suggested Fix

Since OpenAPI 3.0 cannot express callbacks for each item in an array, either redesign the callback mechanism to use a single, top-level callbackUrl or update the description to clarify that only the first document's callback URL is officially documented and used.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: app/schema/openapi.yaml#L418

Potential issue: The OpenAPI callback definition for the `POST /extract` endpoint uses
the runtime expression `{$request.body#/documents/0/callbackUrl}`. This expression only
points to the callback URL of the first document in the request array. However, the API
accepts multiple documents and the description states, "This callback is made for each
input document". This creates a misleading specification, as OpenAPI 3.0 does not
support runtime expressions that iterate over an array, so callbacks for documents other
than the first are not documented.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[sentry]

Bug: The OpenAPI schema incorrectly specifies a 201 Created response for callbacks. The implementation is permissive, but the specification should be corrected to 200 OK for semantic accuracy.
_{Severity: LOW}

Suggested Fix

Update the OpenAPI schema in app/schema/openapi.yaml to expect a 200 OK response for the extractionComplete and redactionComplete callbacks instead of 201 Created. This aligns the documentation with industry best practices for webhook acknowledgments.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: app/schema/openapi.yaml#L1449-L1452

Potential issue: The OpenAPI schema for the `extractionComplete` callback specifies that
the expected response is HTTP `201 Created`. This is semantically incorrect for a
webhook acknowledgment; `200 OK` is the standard. The implementation in
`app/server/tasks/callback.py` uses `response.raise_for_status()`, which accepts any 2xx
status code, so this discrepancy has no functional impact. However, it represents a
documentation/specification issue that could mislead API clients.