Explicitly write a form definition or final submission batch to GitHub through the optional writeback app.
POST /api/v1/forms/{formId}/destinations/writeback
Requires commentary.forms.writeback, the forms.github_writeback license feature, a configured optional GitHub writeback app, an installed repository target, and a valid branch/path target. Submission writeback accepts submissionId or submissionIds, writes one canonical JSON result file per submission in one commit, overwrites existing result paths, can explicitly create target branches with target.createBranch and target.baseBranch, and can optionally open a pull request. Commentary storage remains available when writeback is unavailable.
Access
Section titled “Access”Use a credential with commentary.forms.writeback.
Provider access, workspace membership, and agent grants are enforced separately. A token does not expand access to a repository or resource. Set up developer access.
Parameters
Section titled “Parameters”| Name | Location | Type | Required | Description |
|---|---|---|---|---|
formId |
path | string | Yes | Form id or reference id. |
X-Commentary-Workspace-Id |
header | string | No | Must match the credential workspace. This header cannot widen grant authority. |
X-Correlation-Id |
header | string | No |
Request body
Section titled “Request body”Required. Supported content types: application/json.
| Field | Type | Required | Description |
|---|---|---|---|
targetType |
"form_definition" · "submission" |
No | |
submissionId |
string | No | |
submissionIds |
array of string | No | |
target |
object | No | |
format |
"json" · "yaml" |
No | |
commitMessage |
string | No | |
openPullRequest |
boolean | No | |
pullRequestTitle |
string | No | |
pullRequestBody |
string | No |
Call the endpoint
Section titled “Call the endpoint”Replace path placeholders and your credential. For body operations, create request.json using the required fields above; this command does not invent resource identifiers or consent.
curl --request POST \ 'https://commentary.dev/api/v1/forms/<formId>/destinations/writeback' \ --header 'Authorization: Bearer <your-token>' \ --header 'Content-Type: application/json' \ --data-binary @request.jsonResponses
Section titled “Responses”| Status | Meaning | Payload |
|---|---|---|
202 |
Successful response. | object |
400 |
The request was invalid. | ExternalError |
401 |
Authentication is required. | ExternalError |
403 |
The token or session does not have permission for this resource. | ExternalError |
404 |
The resource was not found. | ExternalError |
429 |
The request was rate limited. | ExternalError |
Successful response fields
Section titled “Successful response fields”| Field | Type | Required | Description |
|---|---|---|---|
ok |
true |
No | |
formId |
string | No | |
submissionId |
string | No | |
submissionIds |
array of string | No | |
writeback |
object | No |
Recover from errors
Section titled “Recover from errors”Use the returned status and error body. Correct invalid fields before retrying; reconnect or narrow the target for authentication and permission errors. For conditional writes, reload the latest version before preparing a new request. Respect rate-limit headers and retry only when the operation’s idempotency contract permits it.
Contract and related guidance
Section titled “Contract and related guidance”Operation ID: writeFormArtifactToGitHub. Download the OpenAPI contract for complete constraints and code generation. Browse endpoints.