/
REST APIs for Grid Custom Field

REST APIs for Grid Custom Field

This guide explains how to use REST APIs for the Grid Custom Field of Table Grid Next Generation (TGNG) on Jira Cloud.

These endpoints come from the Table Grid Next Generation Forge app and require Atlassian OAuth 2.0 (3LO) access tokens. Do not use Atlassian API tokens or legacy TGNG (basic-auth) tokens for these endpoints.

Summary steps to use REST APIs for Grid Custom Field:

  1. Enable App REST APIs for Table Grid Next Generation App.

  2. Generate Access Token
    2.1. Create an OAuth 2.0 integration in Developer Console.
    2.2. Add TGNG scopes and the Jira Forge app product scope.
    2.3. Configure the callback URL.
    2.4. Open the authorization URL and copy the authorization code.
    2.5. Exchange the authorization code for an access token.

  3. Call Grid Custom Field REST APIs with Authorization: Bearer ACCESS_TOKEN.

Endpoints and Methods:

  1. Base URL (choose one):
    https://api.atlassian.com/svc/jira/{cloudId}/apps/{appId}_{environmentId}
    or:
    https://{your_domain_name}.atlassian.net/gateway/api/svc/jira/apps/{appId}_{environmentId}

  2. Resource path: /grids/{customFieldId}/issue/{issueIdOrKey}

  3. Supported HTTP methods:

GET /grids/{customFieldId}/issue/{issueIdOrKey}

POST /grids/{customFieldId}/issue/{issueIdOrKey}

PUT /grids/{customFieldId}/issue/{issueIdOrKey}

DELETE /grids/{customFieldId}/issue/{issueIdOrKey}

 

Contents

Postman Collection

You can use this Postman collection to experiment with REST APIs for Grid Custom Field. To use it, import it in Postman, then set the appropriate values to collection variables (click on three dots → Edit → Variables).

Prerequisites

App REST APIs are disabled by default for each site. A site or organization admin must enable them before users can call TGNG REST endpoints.

If App REST APIs are disabled, calls to TGNG REST endpoints will be blocked for that site.

  1. Go to Atlassian Administration and select your organization.

  2. Go to Apps → Sites, then select the site where Table Grid Next Generation is installed.

  3. In the left navigation, select Connected apps.

  4. Find Table Grid Next Generation and click View app details.

  5. Open the Details tab.

image-20260707-092339.png

  1. In the App REST APIs section, click Enable.

image-20260707-092503.png
image-20260707-092555.png
image-20260707-092627.png

Authorization

Prerequisites

You have access to:

Step 1: Create an OAuth 2.0 integration

  1. Go to Atlassian Developer Console.

  2. Click Create and select OAuth 2.0 integration.

    image-20260707-080829.png

  3. Enter a name, for example Grid Custom Field API Client, then create the integration.

    image-20260707-080950.png

Step 2: Add TGNG app permissions

  1. Open your OAuth 2.0 integration.

  2. Go to the Permissions section.

  3. Click Add Marketplace or custom app.

    image-20260707-081148.png

  4. Select the Jira site where Table Grid Next Generation is installed. Then, select Table Grid Next Generation (Production) app for Marketplace app.

    image-20260707-081604.png

  5. Select the scopes required by your integration:

  • read:grid:custom - read Grid Custom Field data.

  • write:grid:custom - create, update, or delete Grid Custom Field data.

Select only the scopes your integration needs. For example, if your integration only reads grid data, use read:grid:custom and do not select write:grid:custom.

image-20260707-082257.png

  1. Click Add.

Note: Also add the Forge app product scope for Jira: read:forge-app:jira
In the Permissions page, click Add button for Jira API and then click Configure

image-20260707-082603.png

Navigate to Granular scopes and click Edit Scopes button

image-20260707-082902.png

Add read:forge-app:jira and click Save button

image-20260707-082810.png

Step 3: Configure the callback URL

  1. In your OAuth 2.0 integration, go to the Authorization section.

    image-20260707-085102.png

  2. Add a Callback URL. Example:

https://your-app.example.com/callback

Click Save changes button. After the callback URL is configured, Developer Console shows an authorization URL for your integration. This URL already includes the TGNG scopes and Jira Forge app product scopes you selected.

image-20260707-155322.png

Step 4: Get the authorization code

  1. Copy and open the authorization URL of Table Grid Next Generation in a browser.

  2. Log in with your Atlassian account.

  3. Review the requested permissions and click Accept.

  4. Atlassian redirects the browser to your callback URL with a code query parameter.

Example redirect URL:

https://your-app.example.com/callback?code=AUTHORIZATION_CODE&state=YOUR_RANDOM_STATE

Copy the value of AUTHORIZATION_CODE. You will use it in the next step.

Step 5: Exchange the authorization code for an access token

Send a POST request to Atlassian OAuth token endpoint:

curl --request POST \ --url https://auth.atlassian.com/oauth/token \ --header 'Content-Type: application/json' \ --data '{ "grant_type": "authorization_code", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "code": "AUTHORIZATION_CODE", "redirect_uri": "YOUR_CALLBACK_URL" }'

In your OAuth 2.0 integration, go to Settings to find your client_id and client_secret

image-20260707-155039.png

Example response:

{ "access_token": "eyJhbGciOiJSUzI1NiIs...", "expires_in": 3600, "scope": "6d..." "token_type": "Bearer" }

Store the access_token securely.

Refer to this Jira documentation for details on enabling APIs for a site and calling them using 3LO (OAuth 2.0)https://developer.atlassian.com/platform/forge/access-rest-apis-exposed-by-a-forge-app/

Value Format

Values in columns are stored in the following format:

  • Checkboxes are stored as booleans.

  • Integers, Numbers, Dates, DateTimes and Times are stored as numbers. Values of Date, DateTime and Time columns are stored in Unix time format in milliseconds.

  • Strings, Textareas, Single Select Lists and Sequences are stored as strings. Value of a single select list is a string containing a selected item's title.

  • Multi Select Lists are stored as lists of strings containing titles of selected items.

  • Formulas are stored as numbers or strings depending on return type.

  • Userlists are stored as Maps with the following entries:

    • "accountId" contains user's account id, which uniquely identifies a user.
      "accountId" may be missing from the result of "Read Grid Data" method call if a user could not be found.
      When using "Add Grid Data" or "Update Grid Data" methods, "accountId" MUST be provided, and the rest of the entries are optional.

    • "value" contains user's full name.

    • "avatar" contains a link to user's avatar.

The term empty value refers to nulls, empty strings and empty lists.

Methods

Read Grid Data

API call: GET {your_domain_name}.atlassian.net/gateway/api/svc/jira/apps/{appID}_{appEnvironmentId}/grids/{customFieldId}/issue/{issueIdOrKey}

appID: 6dfc4bc7-9934-4747-9a1d-6a6c65bacfc3

appEnvironmentId (production) : 9245ffff-b171-4c2f-aa5f-eec3468b9034

Description: Returns all the rows for a grid custom field and an issue

Request

PATH PARAMETERS

customFieldId REQUIRED

string

customFieldId is created by Table Grid App.

issueIdOrKey REQUIRED

string

The ID or key of the issue.

QUERY PARAMETERS

columnIds

Array<string>

A list of columns' ids to return for the Grid. This parameter accepts a comma-separated list.

Note: All columns are returned by default. 

Responses

Add Grid Data

API call: POST {your_domain_name}.atlassian.net/gateway/api/svc/jira/apps/{appID}_{appEnvironmentId}/grids/{customFieldId}/issue/{issueIdOrKey}

appID: 6dfc4bc7-9934-4747-9a1d-6a6c65bacfc3

appEnvironmentId (production) : 9245ffff-b171-4c2f-aa5f-eec3468b9034

Description: Add rows to the grid custom field

Request

PATH PARAMETERS

customFieldId REQUIRED

string

customFieldId is created by Table Grid App.

issueIdOrKey REQUIRED

string

The ID or key of the issue.

QUERY PARAMETERS

acceptInvalidSelectListOption

boolean

Indicates whether to accept invalid values for single or multi-select list columns.

Default: false

Note: When set to true, the system will accept values that are not currently defined in the select list options.

bypassRequiredValidation

boolean

Indicates whether to bypass required column validation when adding a row.

Default: false

Note: When set to true, the system will accept the request even if one or more required columns are left empty. This applies to both individually required columns and grids with the "Require All Columns" setting enabled.

BODY

Example (application/json)

{ "rows":[ { "status":"Open", "user":"Stephen Curry", "summary":"New row" } ] }

Responses

Update Grid Data

API call: PUT {your_domain_name}.atlassian.net/gateway/api/svc/jira/apps/{appID}_{appEnvironmentId}/grids/{customFieldId}/issue/{issueIdOrKey}

appID: 6dfc4bc7-9934-4747-9a1d-6a6c65bacfc3

appEnvironmentId (production) : 9245ffff-b171-4c2f-aa5f-eec3468b9034

Description: Update rows of the Grid custom field

Request

PATH PARAMETERS

customFieldId REQUIRED

string

customFieldId is created by Table Grid App.

issueIdOrKey REQUIRED

string

The ID or key of the issue.

QUERY PARAMETERS

acceptInvalidSelectListOption

boolean

Indicates whether to accept invalid values for single or multi-select list columns.

Default: false

Note: When set to true, the system will accept values that are not currently defined in the select list options.

bypassRequiredValidation

boolean

Indicates whether to bypass required column validation when updating a row.

Default: false

Note: When set to true, the system will accept the request even if one or more required columns are left empty. This applies to both individually required columns and grids with the "Require All Columns" setting enabled.

BODY

Example (application/json)

{ "rows":[ { "rowId":"row_b089f167-9475-401b-88bd-2c2d25052196", "columns":{ "status":"Open", "user":"Blake Griffin", "summary":"Updated value" } } ] }

Responses

Delete Grid Data

API call: DELETE {your_domain_name}.atlassian.net/gateway/api/svc/jira/apps/{appID}_{appEnvironmentId}/grids/{customFieldId}/issue/{issueIdOrKey}

appID: 6dfc4bc7-9934-4747-9a1d-6a6c65bacfc3

appEnvironmentId ( production ) : 9245ffff-b171-4c2f-aa5f-eec3468b9034

Description: Delete rows of the Grid custom field

Request

PATH PARAMETERS

customFieldId REQUIRED

string

customFieldId is created by Table Grid App.

issueIdOrKey REQUIRED

string

The ID or key of the issue.

BODY

Example (application/json)

{ "rows":[ "rowId_823e747c-a38a-4f14-8fe4-2ee565124503", "rowId_7424bd1a-4c1f-404c-988b-1059756f3d72" ] }

Responses

Tips:

  • You can find the CustomField ID on the Fields page in Jira Admin settings.

image-20260707-103946.png