Skip to content

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

  1. A Jira administrator creates an API token on the app’s admin page and gives it to the script.
  2. The script sends a JSON body — which issue, which field, which rows, and how to apply them (replace, append or upsert) — to the endpoint URL shown on the same page.
  3. 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.
  4. 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.
  5. 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

  1. Go to Jira settings → Apps → Connected Table Admin → Write API. You need Jira administrator permission.
  2. Copy the Endpoint URL — it’s specific to your site.
  3. Click Create token…, give it a name that says where it’s used (for example ScriptRunner migration), and click Create token.
  4. 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

https://1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d.webtrigger.atlassian.app/public/Xr7Qe2Lm9VbT4kWc Copy

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.

Create token…
Jira settings → Apps → Connected Table Admin → Write API: the endpoint URL to call and the tokens that may call it.
The token is shown once. Connected Table stores only its hash, so a lost token can't be recovered — revoke it and create a new one.

2. 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 contains id=10106, so the field id is customfield_10106. Or call GET /rest/api/3/field and look for the field’s id.
  • 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

Terminal window
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

URLThe Endpoint shown on the Write API admin page. It’s unique to your site and doesn’t change when the app is updated.
MethodPOST (any other method returns 405).
HeadersAuthorization: Bearer <token> and Content-Type: application/json.
BodyA 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"
}
PropertyRequiredDescription
issueKeyYesIssue key (OPS-117, case-insensitive) or numeric issue id.
fieldIdYesThe Connected Table field, e.g. customfield_10106.
modeYesreplace, append or upsert — see Modes.
rowsYesArray of row objects (up to 1,000), keyed by column id. May be empty.
dryRunNotrue validates without saving. Default false.
timeZoneNoIANA time zone (e.g. Europe/Kyiv, America/New_York) used for relative date defaults in new rows. See Date defaults and time zones.
clientRefNoYour 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 with upsert, or to keep a row’s identity (and its merged cells) with replace. 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; null resets 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 — in upsert, 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

ModeWhat it doesTypical use
replaceThe 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”.
appendAdds the rows after the existing ones. Existing rows are untouched. An id that already exists is rejected.Logging events, adding line items.
upsertRows 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:

  • replace with ids: a row sent with the id of 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, append and upsert start 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 typeAccepted valuesStored as
Text / Text areaAny 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
NumberA 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
IntegerA whole number (6 or "6"). Fractions are rejected.A number
Checkboxtrue / false, or text: yes/no, 1/0, x, on/off, checked/unchecked.true / false
Date / Date-time / TimeText 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 selectOne of the column’s options (case doesn’t matter).The option’s exact spelling
Multi-selectAn 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
UserAn 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 FormulaFormula 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 / SequenceIgnored — 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:

  1. the request’s timeZone, if you send one;
  2. otherwise the Jira profile time zone of the admin who created the token;
  3. 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.

HTTPerrorMeaningSaved?
200— ("dryRun": false)The table was saved.Yes
200— ("dryRun": true)Dry run: everything is valid.No
400bad-requestThe 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
401unauthorizedMissing, unknown or revoked token.No
403unlicensedConnected Table has no active licence on this site.No
404issue-not-foundThe issue doesn’t exist.No
405method-not-allowedUse POST.No
409field-not-configuredThe field has no column configuration yet.No
413too-largeThe resulting table would exceed Jira’s field size limit.No
422not-a-table-fieldfieldId isn’t a Connected Table field.No
422unknown-columnA row uses a key that isn’t a column id of the table.No
422invalid-row-idA row id is empty, too long, repeated in the request, or (with append) already exists.No
422invalid-cellA value doesn’t match its column — not a number, not one of the options, not an account ID, an invalid date, …No
422missing-requiredA 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
500internal-errorUnexpected error before saving. Retry later.No
502write-failedJira 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 log

The last 25 authenticated calls. Error responses only carry a category; the row and column details are here.

The call log on the Write API page. "Rows" shows the table's row count after the call, with rows added (+) and updated (~).

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):

Terminal window
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 null if nobody has saved a table on the issue yet.

Examples

Python

import os
import time
import 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 access
def issue = get("/rest/api/3/issue/OPS-117?fields=${fieldId}").asObject(Map).body
def 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:

SettingValue
Web request URLYour endpoint URL
HTTP methodPOST
Web request bodyCustom data, for example {"issueKey": "{{issue.key}}", "fieldId": "customfield_10106", "mode": "append", "rows": [{"item": "{{issue.summary}}", "qty": 1}]}
HeadersAuthorization: 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:

  1. Create the target field and configure its columns (types, options, required columns) to match the source table.
  2. Write down the column mapping — source column → Connected Table column id — and how values convert (dates, option labels, users as account IDs).
  3. 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.
  4. Send them with "mode": "replace" and "dryRun": true for a handful of issues. Fix the mapping until the call log shows no problems.
  5. Run the migration with dryRun off, issue by issue. Stop on the first non-200 response, fix the cause, and resume — re-running replace for an issue is safe.
  6. 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 401 straight 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

LimitValue
Rows per request1,000 (the table size limit is usually reached first)
Table sizeOne field value of up to 32,768 characters — roughly 100–150 rows
Issues per request1
Tokens20 per site
Call logLast 25 calls
Rate limitingAtlassian’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 upsert with 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 a clientRef so log entries are easy to match to script runs.

Troubleshooting

SymptomWhat to do
401 unauthorizedCheck 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 fieldThe URL is wrong or out of date. Copy the endpoint from the Write API admin page again.
422 unknown-columnUse column ids (shown in the column editor), not column titles.
422 invalid-cell on a user columnSend the person’s Atlassian account ID, not their name or email.
422 invalid-row-id with appendThe row id already exists — use upsert to update it, or leave id out to add a new row.
409 field-not-configuredConfigure the field’s columns in its field context first.
413 too-largeSplit the data across issues or fields, or remove unneeded rows/columns.
Dates in new rows are a few hours offSend "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 changeReload the issue.
ScriptRunner: unable to resolve class kong.unirest.UnirestRemove the import — Unirest is available without one.