Write API
The Write API lets scripts and integrations put rows into a Connected Table: a
ScriptRunner script, a Python job, a CI pipeline, a Jira Automation rule, or a one-off
migration from another table app. You send one HTTPS POST request with an API
token; Connected Table validates the rows against the table’s columns and saves them
to the issue.
Reading a table doesn’t need this API — use the standard Jira REST API (see Reading a table).
How it works
- A Jira administrator creates an API token on the app’s admin page and gives it to the script.
- The script sends a JSON body — which issue, which field, which rows, and how to apply them (
replace,appendorupsert) — to the endpoint URL shown on the same page. - Connected Table checks the token, then validates every row against the table’s column configuration: types, options, required columns, column defaults and the table size limit.
- If anything is wrong, nothing is saved and the response names the kind of problem. The row- and column-level details are in the call log on the admin page.
- Otherwise the table is saved to the issue. The change appears in the issue’s history like any other edit.
Use "dryRun": true to run all the checks without saving — ideal for testing a script
or a migration on a few issues first.
Quick start
1. Create a token
- Go to Jira settings → Apps → Connected Table Admin → Write API. You need Jira administrator permission.
- Copy the Endpoint URL — it’s specific to your site.
- Click Create token…, give it a name that says where it’s used (for example ScriptRunner migration), and click Create token.
- Copy the token from the dialog and store it somewhere safe. It’s shown only once.
Write API
Scripts and integrations (ScriptRunner, Python, CI, migrations) can write Connected Table rows by sending a POST request with an API token.
Endpoint
API tokens
A token can write the table on any issue on this site, regardless of the caller's Jira permissions. Treat it like an admin password and revoke tokens you no longer use.
Tokens stay in your Jira site. Connected Table keeps only a one-way hash of each token; the token itself is shown only once, when you create it.
| Name | Created by | Created | |
|---|---|---|---|
| ScriptRunner migration | Alex Morgan | 14.10.2026, 12:13 | Revoke… |
| Nightly ERP sync | Priya Shah | 02.11.2026, 09:40 | Revoke… |
Copy your new token
Token ScriptRunner migration was created. Copy it now and store it somewhere safe, such as your script's secret settings. It won't be shown again.
ctapi_q7VZr2LxN0b4Tg8YwKc1Hs5JmE9dUa3PfR6iWoBn2. Find the field id and column ids
- Field id — the custom field’s id, such as
customfield_10106. In Jira settings → Issues → Custom fields, open the field’s ⋯ menu and choose an action such as Edit details or Contexts and default value: the page URL containsid=10106, so the field id iscustomfield_10106. Or callGET /rest/api/3/fieldand look for the field’sid. - Column ids — rows are keyed by column id, not column title. In the field context’s column editor, each column shows its Id. Ids are stable even if you rename the column title.
3. Validate with a dry run
curl -X POST 'https://<your endpoint URL>' \ -H 'Authorization: Bearer <your token>' \ -H 'Content-Type: application/json' \ -d '{ "issueKey": "OPS-117", "fieldId": "customfield_10106", "mode": "append", "dryRun": true, "rows": [ { "item": "Keyboard", "qty": 6, "price": 49.9, "status": "Ordered" } ] }'A valid request returns 200 {"ok":true,"dryRun":true,"message":"Valid. Nothing was saved."}.
4. Write for real
Send the same request with "dryRun": false (or without dryRun). A successful write
returns 200 {"ok":true,"dryRun":false}. Reload the issue to see the new rows.
Endpoint and authentication
| URL | The Endpoint shown on the Write API admin page. It’s unique to your site and doesn’t change when the app is updated. |
| Method | POST (any other method returns 405). |
| Headers | Authorization: Bearer <token> and Content-Type: application/json. |
| Body | A JSON object, described below. One request writes one issue’s table. |
There is no separate login: the token is the credential. A missing, mistyped or
revoked token returns 401 unauthorized, and nothing else is checked or logged.
Request body
{ "issueKey": "OPS-117", "fieldId": "customfield_10106", "mode": "upsert", "rows": [ { "id": "row-1788117662716-1", "qty": 8 }, { "item": "Docking station", "qty": 2, "status": "Requested" } ], "dryRun": false, "timeZone": "Europe/Kyiv", "clientRef": "erp-sync-2026-11-06"}| Property | Required | Description |
|---|---|---|
issueKey | Yes | Issue key (OPS-117, case-insensitive) or numeric issue id. |
fieldId | Yes | The Connected Table field, e.g. customfield_10106. |
mode | Yes | replace, append or upsert — see Modes. |
rows | Yes | Array of row objects (up to 1,000), keyed by column id. May be empty. |
dryRun | No | true validates without saving. Default false. |
timeZone | No | IANA time zone (e.g. Europe/Kyiv, America/New_York) used for relative date defaults in new rows. See Date defaults and time zones. |
clientRef | No | Your own reference (up to 100 characters), shown in the call log — handy for matching log entries to script runs. |
Row objects
Each row is an object whose keys are column ids:
{ "id": "row-1788117662716-1", "item": "Keyboard", "qty": 6, "tags": ["IT", "Office"] }id(optional) — the row’s id. Needed to update an existing row withupsert, or to keep a row’s identity (and its merged cells) withreplace. Omit it for new rows; Connected Table generates one. Ids are strings of up to 100 characters and must be unique within the request.width(optional) — the row’s height in pixels, as returned when reading a table. Accepted so a table you read can be written back unchanged;nullresets it.- Every other key must be a column id of the table. An unknown key is rejected (
unknown-column) so a typo can’t silently drop data. - A cell value of
null(or"") leaves the cell empty — inupsert, it clears the existing value. - Cells you don’t include: new rows get the column’s default value; existing rows keep their value in
upsert. - Formula and sequence columns are calculated by the table. Values sent for them are ignored (noted as a warning in the call log).
- Row Formula columns take the formula text, for example
"[Qty] * [Unit price]"— see Cell values.
Modes
| Mode | What it does | Typical use |
|---|---|---|
replace | The table becomes exactly the rows you send, in that order. Rows not sent are removed. | Migrations, full syncs from another system, “write back what I read”. |
append | Adds the rows after the existing ones. Existing rows are untouched. An id that already exists is rejected. | Logging events, adding line items. |
upsert | Rows whose id matches an existing row are updated (only the cells you send change). Rows without an id, or with an unknown id, are added at the end. | Keeping a table in sync while users also edit it. |
More details:
replacewith ids: a row sent with theidof an existing row keeps that id, its row height and any merged cells it belongs to; its cells become exactly what you send. Rows without an id are new rows and get column defaults.- Merged cells are kept as long as the merged rows still exist and are still next to each other; otherwise the merge is dropped.
- Empty field: if the issue has no table yet,
appendandupsertstart from the field’s default rows — the same rows a user would see. - Required columns are checked on every row the request adds, updates or replaces. Rows you don’t touch aren’t re-checked, so an old incomplete row never blocks an
append.
Cell values
Values can be native JSON (numbers, booleans, arrays) or text in the same forms the file import accepts. Values are stored in the column’s own format, exactly as if typed in the table.
| Column type | Accepted values | Stored as |
|---|---|---|
| Text / Text area | Any string. Numbers and booleans are converted to text. Text longer than a text area’s maximum length is shortened (warning in the call log). | The text, trimmed |
| Number | A JSON number (1234.5) or text in either decimal style ("1,234.5", "1 234,5"). | A number, rounded to the column’s decimal places |
| Integer | A whole number (6 or "6"). Fractions are rejected. | A number |
| Checkbox | true / false, or text: yes/no, 1/0, x, on/off, checked/unchecked. | true / false |
| Date / Date-time / Time | Text in the column’s format, or ISO: "2026-11-06", "2026-11-06 14:30", "2026-11-06T14:30", "14:30". | Text in the column’s format |
| Single select | One of the column’s options (case doesn’t matter). | The option’s exact spelling |
| Multi-select | An array (["IT", "Office"]), the JSON text returned when reading ("[\"IT\",\"Office\"]"), or "IT, Office" / "IT; Office". Every item must be an option. | The table’s multi-select format |
| User | An Atlassian account ID (for example 5cb4ae0e4b97ab11a18e00c7). Names and emails aren’t looked up — use GET /rest/api/3/user/search first if you only have an email. | The account ID |
| Row Formula | Formula text, with columns referenced by name ("[Qty] * [Unit price]") or by id ("$(qty) * $(price)"). A plain number such as 500 is also accepted. The formula isn’t checked — an invalid one shows an error in the table. | The formula text, with column names replaced by column ids |
| Formula / Sequence | Ignored — calculated by the table. | — |
Date defaults and time zones
When a new row gets a relative date default — for example a date-time column that defaults to current date + 7 days — “now” has to be in some time zone:
- the request’s
timeZone, if you send one; - otherwise the Jira profile time zone of the admin who created the token;
- otherwise UTC.
The table UI uses each viewer’s own browser time zone, so with option 2 a row added by a script gets the same defaults as a row the token’s creator adds by hand. Values you send explicitly are never changed. The call log shows which time zone was used.
Dry run
With "dryRun": true, Connected Table does everything except save: it loads the issue
and the table configuration, converts and validates every cell, applies the mode,
column defaults and merge rules, and checks the size limit. You get the same response
you would get for a real write (dry-run-ok instead of ok), and the call log records
how many rows would be added and updated.
Responses
Every response is JSON with a fixed body for its outcome: ok, error (a category),
and a short message. Responses never contain table or issue data, so per-row
details are recorded in the call log instead.
| HTTP | error | Meaning | Saved? |
|---|---|---|---|
200 | — ("dryRun": false) | The table was saved. | Yes |
200 | — ("dryRun": true) | Dry run: everything is valid. | No |
400 | bad-request | The body isn’t valid JSON, or a property is missing or invalid (unknown mode, bad issueKey/fieldId, more than 1,000 rows, unknown timeZone, …). | No |
401 | unauthorized | Missing, unknown or revoked token. | No |
403 | unlicensed | Connected Table has no active licence on this site. | No |
404 | issue-not-found | The issue doesn’t exist. | No |
405 | method-not-allowed | Use POST. | No |
409 | field-not-configured | The field has no column configuration yet. | No |
413 | too-large | The resulting table would exceed Jira’s field size limit. | No |
422 | not-a-table-field | fieldId isn’t a Connected Table field. | No |
422 | unknown-column | A row uses a key that isn’t a column id of the table. | No |
422 | invalid-row-id | A row id is empty, too long, repeated in the request, or (with append) already exists. | No |
422 | invalid-cell | A value doesn’t match its column — not a number, not one of the options, not an account ID, an invalid date, … | No |
422 | missing-required | A required column is empty in a row the request adds or changes. | No |
429 | — | Too many requests. Wait until the time in the X-Ratelimit-Reset header, then retry. | No |
500 | internal-error | Unexpected error before saving. Retry later. | No |
502 | write-failed | Jira rejected the update. See the call log for Jira’s message. | No |
If a request has several problems, the response reports the most fundamental one, in
this order: bad-request, unknown-column, invalid-row-id, invalid-cell,
missing-required, too-large. The call log lists all of them.
Scripts should treat any status other than 200 as “nothing was written” and stop or
retry. All checks run before saving, so a failed request never leaves a half-written
table.
Call log
The Recent calls section of the Write API admin page lists the last 25 calls made
with a valid token: when, which token, which issue and field, mode, dry run, result,
and the resulting row count. Click Details to see every problem with its row
(rows[3] is the fourth row of your request) and column, plus warnings, your
clientRef, and the time zone used for date defaults.
Recent calls
RefreshClear logThe last 25 authenticated calls. Error responses only carry a category; the row and column details are here.
| Time | Token | Issue | Mode | Result | Rows | |
|---|---|---|---|---|---|---|
| 06.11.2026, 10:21 | ScriptRunner migration | OPS-118 · customfield_10106 | replace | ok | 12 (+12 / ~0) | |
| 06.11.2026, 10:20 | ScriptRunner migration | OPS-117 · customfield_10106 | replace (dry run) | invalid-cell | 9 (+9 / ~0) | Hide |
| ||||||
| 06.11.2026, 10:18 | Nightly ERP sync | OPS-90 · customfield_10106 | upsert | ok | 31 (+2 / ~4) | |
Calls with a missing or wrong token aren’t logged. The log is kept in your Jira site alongside the app’s settings; Clear log empties it.
Reading a table
Read the table with Jira’s standard REST API, using your normal Jira authentication (for example an Atlassian API token, or ScriptRunner’s built-in access):
curl -u you@example.com:<atlassian-api-token> \ 'https://your-site.atlassian.net/rest/api/3/issue/OPS-117?fields=customfield_10106'The field value looks like this:
{ "rows": [ { "id": "row-1788117662716-1", "item": "Keyboard", "qty": 6, "price": 49.9, "status": "Ordered", "tags": "[\"IT\",\"Office\"]", "owner": "5cb4ae0e4b97ab11a18e00c7", "due": "2026-11-20" }, { "id": "row-1788117662885-2", "item": "Mouse", "qty": 6, "price": 24.5 } ], "merges": [ { "columnId": "status", "rowIds": ["row-1788117662716-1", "row-1788117662885-2"] } ], "editedBy": "712020:e9f71c35-3605-4ede-90b5-6d6387177331", "editedVia": "api"}rows— one object per row, keyed by column id. Empty cells are simply absent. Formula and sequence values aren’t stored; they’re calculated when the table is shown. Row Formula cells contain the formula text, with columns referenced by id — for example"$(qty) * $(price)".merges— merged cells: for each, the column and the ids of the adjacent rows it spans.editedBy/editedVia— who last saved the table, and"api"if it was saved through the Write API.- The field is
nullif nobody has saved a table on the issue yet.
Examples
Python
import osimport timeimport requests
URL = os.environ["CT_API_URL"]TOKEN = os.environ["CT_API_TOKEN"]
def write_table(payload): for attempt in range(3): r = requests.post(URL, json=payload, timeout=60, headers={"Authorization": f"Bearer {TOKEN}"}) if r.status_code != 429: return r.status_code, r.json() time.sleep(max(1, int(r.headers.get("X-Ratelimit-Reset", "0")) - int(time.time()))) return r.status_code, r.json()
status, body = write_table({ "issueKey": "OPS-117", "fieldId": "customfield_10106", "mode": "append", "rows": [{"item": "Keyboard", "qty": 6, "price": 49.9}],})print(status, body)ScriptRunner for Jira Cloud (Script Console)
ScriptRunner Cloud scripts run outside Jira, so they call the Write API like any other
HTTP client. Unirest is available without an import; the editor may underline it in
red — that’s only a type-checking warning and the script runs.
import groovy.json.JsonOutput
def url = '<your endpoint URL>'def token = '<your token>'def fieldId = 'customfield_10106'
// Read the current table with ScriptRunner's own Jira accessdef issue = get("/rest/api/3/issue/OPS-117?fields=${fieldId}").asObject(Map).bodydef rows = (issue.fields[fieldId]?.rows ?: []) as List<Map>
// Example: mark every row that is still "Requested" as "Ordered"def changes = rows.findAll { it.status == 'Requested' }.collect { [id: it.id, status: 'Ordered'] }
def response = Unirest.post(url) .header('Authorization', "Bearer ${token}") .header('Content-Type', 'application/json') .body(JsonOutput.toJson([ issueKey : 'OPS-117', fieldId : fieldId, mode : 'upsert', dryRun : false, clientRef: 'scriptrunner-console', rows : changes ])) .asString()
return "${response.status} ${response.body}"Jira Automation
Use the Send web request action:
| Setting | Value |
|---|---|
| Web request URL | Your endpoint URL |
| HTTP method | POST |
| Web request body | Custom data, for example {"issueKey": "{{issue.key}}", "fieldId": "customfield_10106", "mode": "append", "rows": [{"item": "{{issue.summary}}", "qty": 1}]} |
| Headers | Authorization: Bearer <token> and Content-Type: application/json |
Anyone who can edit the rule can see its headers, so give each rule its own token and revoke it if the rule is deleted or handed over.
Migrating from another table app
The Write API is designed for moving table data into Connected Table — for example from Table Grid or a spreadsheet that lives outside Jira. The pattern is the same whatever the source:
- Create the target field and configure its columns (types, options, required columns) to match the source table.
- Write down the column mapping — source column → Connected Table column id — and how values convert (dates, option labels, users as account IDs).
- Read the source rows for an issue using the source app’s own API or export, with its authentication. Connected Table never connects to the other app — your script does.
- Send them with
"mode": "replace"and"dryRun": truefor a handful of issues. Fix the mapping until the call log shows no problems. - Run the migration with
dryRunoff, issue by issue. Stop on the first non-200response, fix the cause, and resume — re-runningreplacefor an issue is safe. - Spot-check a few issues in Jira, then revoke the migration token.
A ScriptRunner sketch for step 3–5, looping over a JQL search:
import groovy.json.JsonOutput
def url = '<your endpoint URL>'def token = '<your token>'def fieldId = 'customfield_10106'def dryRun = true
def issues = get('/rest/api/3/search/jql') .queryString('jql', 'project = OPS AND "Line items" is not EMPTY') .queryString('fields', 'key') .queryString('maxResults', '50') .asObject(Map).body.issues
def results = issues.collect { issue -> List<Map> rows = readSourceRows(issue.key).collect { src -> [item: src['Item'], qty: src['Quantity'], status: src['State']] } def r = Unirest.post(url) .header('Authorization', "Bearer ${token}") .header('Content-Type', 'application/json') .body(JsonOutput.toJson([issueKey: issue.key, fieldId: fieldId, mode: 'replace', dryRun: dryRun, clientRef: "migration ${issue.key}", rows: rows])) .asString() "${issue.key}: ${r.status} ${r.body}"}return results.join('\n')
List<Map> readSourceRows(String issueKey) { // Read the rows from the source app here (its REST API or an export) and // return one map per row, keyed by the source column names. []}Tables have a size limit of roughly 100–150 rows;
a source table that’s bigger is rejected with too-large rather than cut short.
Security and permissions
- A token can write the table on any issue on the site, whatever the caller’s own Jira permissions — the write is made by the app. Treat tokens like admin passwords: one token per script or integration, stored in a secret store, revoked when no longer needed.
- Only Jira administrators can see the endpoint, create and revoke tokens, and view the call log.
- Tokens stay in your Jira site. Connected Table stores only a one-way (SHA-256) hash of each token, plus its name, creator and creation date, in the app’s data in your Jira site. The token itself is shown once and isn’t stored anywhere; nothing is sent to Flokker or any other service.
- Revoking is immediate. Calls with a revoked token get
401straight away. Up to 20 tokens can exist at a time. - Responses carry no data. The endpoint only returns fixed status messages, so a token can’t be used to read tables or issues.
- Attribution. Jira’s own History tab shows API writes as made by the app. The Connected Table History tab shows the admin who created the token, marked via API.
- No new permissions. The Write API uses the same permissions the app already has. See How it works.
Limits and good practice
| Limit | Value |
|---|---|
| Rows per request | 1,000 (the table size limit is usually reached first) |
| Table size | One field value of up to 32,768 characters — roughly 100–150 rows |
| Issues per request | 1 |
| Tokens | 20 per site |
| Call log | Last 25 calls |
| Rate limiting | Atlassian’s platform limits; 429 with X-Ratelimit-Reset when exceeded |
- One writer at a time per issue. A write replaces the stored table as a whole, and there is no locking: if a user saves the same table while your script is running, the later save wins. For tables people edit by hand, prefer
upsertwith row ids, and run bulk jobs when the table isn’t being edited. - Open issue views don’t refresh by themselves. After an API write, reload the issue to see the new rows.
- Start with
dryRun, and send aclientRefso log entries are easy to match to script runs.
Troubleshooting
| Symptom | What to do |
|---|---|
401 unauthorized | Check the Authorization: Bearer <token> header and that the token hasn’t been revoked. Create a new token if it was lost. |
424 Failed Dependency or 404 with no error field | The URL is wrong or out of date. Copy the endpoint from the Write API admin page again. |
422 unknown-column | Use column ids (shown in the column editor), not column titles. |
422 invalid-cell on a user column | Send the person’s Atlassian account ID, not their name or email. |
422 invalid-row-id with append | The row id already exists — use upsert to update it, or leave id out to add a new row. |
409 field-not-configured | Configure the field’s columns in its field context first. |
413 too-large | Split the data across issues or fields, or remove unneeded rows/columns. |
| Dates in new rows are a few hours off | Send "timeZone" with your IANA time zone, or set the token creator’s time zone in their Jira profile. |
| The write succeeded but the table on screen didn’t change | Reload the issue. |
ScriptRunner: unable to resolve class kong.unirest.Unirest | Remove the import — Unirest is available without one. |