---
title: "Explicitly write a form definition or final submission batch to GitHub through the optional writeback app."
method: POST
path: "/api/v1/forms/{formId}/destinations/writeback"
tags: ["Forms"]
---

# Explicitly write a form definition or final submission batch to GitHub through the optional writeback app.

`POST /api/v1/forms/{formId}/destinations/writeback`

## Request

- Base URL: `https://commentary.dev`
- URL: `https://commentary.dev/api/v1/forms/{formId}/destinations/writeback`
- Auth: HTTP bearer

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.

## Path parameters

- `formId` string, required

## Headers

- `X-Commentary-Workspace-Id` string
- `X-Correlation-Id` string

## Request body

- object
  - `targetType` 'form_definition' | 'submission'
  - `submissionId` string
  - `submissionIds` string[]
  - `target` object
    - `owner` string
    - `repo` string
    - `branch` string
    - `path` string
    - `baseBranch` string
    - `createBranch` boolean
  - `format` 'json' | 'yaml'
  - `commitMessage` string
  - `openPullRequest` boolean
  - `pullRequestTitle` string
  - `pullRequestBody` string

## Response `202`

Successful response.

- object
  - `ok` unknown
  - `formId` string
  - `submissionId` string
  - `submissionIds` string[]
  - `writeback` object

## Other responses

- `400`: The request was invalid.
- `401`: Authentication is required.
- `403`: The token or session does not have permission for this resource.
- `404`: The resource was not found.
- `429`: The request was rate limited.

---

[API](https://skmtc.dev/commentary/apis/commentary-public-api.md) · [All operations](https://skmtc.dev/commentary/apis/commentary-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/commentary/apis/commentary-public-api/revisions/7aaafc198c52?raw)