Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
contact:
email: ecosystem@atlassian.com
description: Jira Cloud platform REST API documentation
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
title: Jira Cloud platform REST Issue custom field configuration…
version: 1001.0.0-SNAPSHOT-82b018affa468e58f284fbe4df33536469d757df
servers:
- url: https://your-domain.atlassian.net
tags:
- description: This resource represents configurations stored against a custom field context by a Forge app. Configurations are information used by the Forge app at runtime to determine how to handle or process the data in a custom field in a given context. Use this resource to set and read configurations.
name: Issue Custom Field Configuration (Apps)
paths:
/rest/api/3/app/field/context/configuration/list:
post:
deprecated: false
description: 'Returns a paginated list of configurations for list of custom fields of a type created by a Forge app.
The result can be filtered by one of these criteria:
* `id`.
* `fieldContextId`.
* `issueId`.
* `projectKeyOrId` and `issueTypeId`.
Otherwise, all configurations for the provided list of custom fields are returned.
**Permissions required:** *Administer Jira* global permission. Jira permissions are not required for the Forge app that provided the custom field type.'
operationId: getCustomFieldsConfigurations
parameters:
- description: 'The list of configuration IDs. To include multiple configurations, separate IDs with an ampersand: `id=10000&id=10001`. Can''t be provided with `fieldContextId`, `issueId`, `projectKeyOrId`, or `issueTypeId`.'
in: query
name: id
schema:
items:
format: int64
type: integer
type: array
uniqueItems: true
- description: 'The list of field context IDs. To include multiple field contexts, separate IDs with an ampersand: `fieldContextId=10000&fieldContextId=10001`. Can''t be provided with `id`, `issueId`, `projectKeyOrId`, or `issueTypeId`.'
in: query
name: fieldContextId
schema:
items:
format: int64
type: integer
type: array
uniqueItems: true
- description: The ID of the issue to filter results by. If the issue doesn't exist, an empty list is returned. Can't be provided with `projectKeyOrId`, or `issueTypeId`.
in: query
name: issueId
schema:
format: int64
type: integer
- description: The ID or key of the project to filter results by. Must be provided with `issueTypeId`. Can't be provided with `issueId`.
in: query
name: projectKeyOrId
schema:
type: string
- description: The ID of the issue type to filter results by. Must be provided with `projectKeyOrId`. Can't be provided with `issueId`.
in: query
name: issueTypeId
schema:
type: string
- description: The index of the first item to return in a page of results (page offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 100
format: int32
type: integer
requestBody:
content:
application/json:
example:
fieldIdsOrKeys:
- customfield_10035
- customfield_10036
schema:
$ref: '#/components/schemas/ConfigurationsListParameters'
required: true
responses:
'200':
content:
application/json:
example: '{"isLast":true,"maxResults":1000,"startAt":0,"total":2,"values":[{"customFieldId":"customfield_10035","fieldContextId":"10010","id":"10000"},{"configuration":{"maxValue":10000,"minValue":0},"customFieldId":"customfield_10036","fieldContextId":"10011","id":"10001","schema":{"properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]}}]}'
schema:
$ref: '#/components/schemas/PageBeanBulkContextualConfiguration'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user is not a Jira admin or the request is not authenticated as from the app that provided the field.
'404':
description: Returned if the custom field is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Bulk get custom field configurations
tags:
- Issue Custom Field Configuration (Apps)
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- read:custom-field-contextual-configuration:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: INACCESSIBLE
/rest/api/3/app/field/{fieldIdOrKey}/context/configuration:
get:
deprecated: false
description: 'Returns a paginated list of configurations for a custom field of a type created by a Forge app.
The result can be filtered by one of these criteria:
* `id`.
* `fieldContextId`.
* `issueId`.
* `projectKeyOrId` and `issueTypeId`.
Otherwise, all configurations are returned.
**Permissions required:** *Administer Jira* global permission. Jira permissions are not required for the Forge app that provided the custom field type.'
operationId: getCustomFieldConfiguration
parameters:
- description: The ID or key of the custom field, for example `customfield_10000`.
in: path
name: fieldIdOrKey
required: true
schema:
type: string
- description: 'The list of configuration IDs. To include multiple configurations, separate IDs with an ampersand: `id=10000&id=10001`. Can''t be provided with `fieldContextId`, `issueId`, `projectKeyOrId`, or `issueTypeId`.'
in: query
name: id
schema:
items:
format: int64
type: integer
type: array
uniqueItems: true
- description: 'The list of field context IDs. To include multiple field contexts, separate IDs with an ampersand: `fieldContextId=10000&fieldContextId=10001`. Can''t be provided with `id`, `issueId`, `projectKeyOrId`, or `issueTypeId`.'
in: query
name: fieldContextId
schema:
items:
format: int64
type: integer
type: array
uniqueItems: true
- description: The ID of the issue to filter results by. If the issue doesn't exist, an empty list is returned. Can't be provided with `projectKeyOrId`, or `issueTypeId`.
in: query
name: issueId
schema:
format: int64
type: integer
- description: The ID or key of the project to filter results by. Must be provided with `issueTypeId`. Can't be provided with `issueId`.
in: query
name: projectKeyOrId
schema:
type: string
- description: The ID of the issue type to filter results by. Must be provided with `projectKeyOrId`. Can't be provided with `issueId`.
in: query
name: issueTypeId
schema:
type: string
- description: The index of the first item to return in a page of results (page offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 100
format: int32
type: integer
responses:
'200':
content:
application/json:
example: '{"isLast":true,"maxResults":1000,"startAt":0,"total":2,"values":[{"id":"10000","fieldContextId":"10010"},{"id":"10001","fieldContextId":"10011","configuration":{"minValue":0,"maxValue":10000},"schema":{"properties":{"amount":{"type":"number"},"currency":{"type":"string"}},"required":["amount","currency"]}}]}'
schema:
$ref: '#/components/schemas/PageBeanContextualConfiguration'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user is not a Jira admin or the request is not authenticated as from the app that provided the field.
'404':
description: Returned if the custom field is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Get custom field configurations
tags:
- Issue Custom Field Configuration (Apps)
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- read:custom-field-contextual-configuration:jira
state: Beta
x-atlassian-connect-scope: ADMIN
put:
deprecated: false
description: 'Update the configuration for contexts of a custom field of a type created by a Forge app.
**Permissions required:** *Administer Jira* global permission. Jira permissions are not required for the Forge app that created the custom field type.'
operationId: updateCustomFieldConfiguration
parameters:
- description: The ID or key of the custom field, for example `customfield_10000`.
in: path
name: fieldIdOrKey
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
configurations:
- id: '10000'
- configuration:
maxValue: 10000
minValue: 0
id: '10001'
schema:
properties:
amount:
type: number
currency:
type: string
required:
- amount
- currency
schema:
$ref: '#/components/schemas/CustomFieldConfigurations'
required: true
responses:
'200':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user is not a Jira admin or the request is not authenticated as from the app that provided the field.
'404':
description: Returned if the custom field is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Update custom field configurations
tags:
- Issue Custom Field Configuration (Apps)
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- write:custom-field-contextual-configuration:jira
state: Beta
x-atlassian-connect-scope: ADMIN
components:
schemas:
PageBeanBulkContextualConfiguration:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/BulkContextualConfiguration'
readOnly: true
type: array
type: object
BulkContextualConfiguration:
additionalProperties: false
description: Details of the contextual configuration for a custom field.
properties:
configuration:
description: The field configuration.
customFieldId:
description: The ID of the custom field.
type: string
fieldContextId:
description: The ID of the field context the configuration is associated with.
readOnly: true
type: string
id:
description: The ID of the configuration.
type: string
schema:
description: The field value schema.
required:
- customFieldId
- fieldContextId
- id
type: object
CustomFieldConfigurations:
additionalProperties: false
description: Details of configurations for a custom field.
properties:
configurations:
description: The list of custom field configuration details.
items:
$ref: '#/components/schemas/ContextualConfiguration'
maxItems: 1000
minItems: 1
type: array
uniqueItems: true
required:
- configurations
type: object
writeOnly: true
ContextualConfiguration:
additionalProperties: false
description: Details of the contextual configuration for a custom field.
properties:
configuration:
description: The field configuration.
fieldContextId:
description: The ID of the field context the configuration is associated with.
readOnly: true
type: string
id:
description: The ID of the configuration.
type: string
schema:
description: The field value schema.
required:
- fieldContextId
- id
type: object
ConfigurationsListParameters:
additionalProperties: false
description: List of custom fields identifiers which will be used to filter configurations
properties:
fieldIdsOrKeys:
description: List of IDs or keys of the custom fields. It can be a mix of IDs and keys in the same query.
items:
type: string
minItems: 1
type: array
required:
- fieldIdsOrKeys
type: object
writeOnly: true
PageBeanContextualConfiguration:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/ContextualConfiguration'
readOnly: true
type: array
type: object
securitySchemes:
OAuth2:
description: OAuth2 scopes for Jira
flows:
authorizationCode:
authorizationUrl: https://auth.atlassian.com/authorize
scopes:
delete:async-task:jira: Delete asynchronous task.
delete:attachment:jira: Delete issue attachments.
delete:avatar:jira: Delete system and custom avatars.
delete:comment.property:jira: Delete issue comment properties.
delete:comment:jira: Delete issue comments.
delete:dashboard.property:jira: Delete dashboard properties.
delete:dashboard:jira: Delete dashboards.
delete:field-configuration-scheme:jira: Delete field configuration schemes.
delete:field-configuration:jira: Delete field configurations.
delete:field.option:jira: Delete field options.
delete:field:jira: Delete fields.
delete:filter.column:jira: Delete filter columns.
delete:filter:jira: Delete filters.
delete:group:jira: Delete user groups.
delete:issue-link-type:jira: Delete issue link types.
delete:issue-link:jira: Delete issue links.
delete:issue-type-scheme:jira: Delete issue type schemes.
delete:issue-type-screen-scheme:jira: Delete issue type screen schemes.
delete:issue-type.property:jira: Delete issue type properties.
delete:issue-type:jira: Delete issue types.
delete:issue-worklog.property:jira: Delete issue worklog properties.
delete:issue-worklog:jira: Delete issue worklogs.
delete:issue.property:jira: Delete issue properties.
delete:issue.remote-link:jira: Delete issue remote links.
delete:issue:jira: Delete issues.
delete:permission-scheme:jira: Delete permission schemes.
delete:permission:jira: Delete permissions.
delete:project-category:jira: Delete project categories.
delete:project-role:jira: Delete project roles.
delete:project-version:jira: Delete project versions.
delete:project.avatar:jira: Delete project avatars.
delete:project.component:jira: Delete project components.
delete:project.property:jira: Delete project properties.
delete:project:jira: Delete projects and their details, such as issue types, project lead, and avatars.
delete:screen-scheme:jira: Delete screen schemes.
delete:screen-tab:jira: Delete screen tabs.
delete:screen:jira: Delete screens.
delete:screenable-field:jira: Delete screenable fields.
delete:user-configuration:jira: Delete user configurations.
delete:user.property:jira: Delete user properties.
delete:webhook:jira: Delete webhooks.
delete:workflow-scheme:jira: Delete workflow schemes.
delete:workflow.property:jira: Delete workflow properties.
delete:workflow:jira: Delete workflows.
manage:jira-configuration: Configure Jira settings that require the Jira administrators permission, for example, create projects and custom fields, view workflows, manage issue link types.
manage:jira-project: Create and edit project settings and create new project-level objects, for example, versions, components.
manage:jira-webhook: Manage Jira webhooks. Enables an OAuth app to register and unregister dynamic webhooks in Jira. It also provides for fetching of registered webhooks.
read:app-data:jira: Read app data.
read:application-role:jira: View application roles.
read:attachment:jira: View issue attachments.
read:audit-log:jira: View audit logs.
read:avatar:jira: View system and custom avatars.
read:comment.property:jira: View issue comment properties.
read:comment:jira: View issue comments.
read:custom-field-contextual-configuration:jira: Read custom field contextual configurations.
read:dashboard.property:jira: View dashboard properties.
read:dashboard:jira: View dashboards.
read:email-address:jira: View email addresses of all users regardless of the user's profile visibility settings.
read:field-configuration-scheme:jira: View field configuration schemes.
read:field-configuration:jira: Read field configurations.
read:field.default-value:jira: View field default values.
read:field.option:jira: View field options.
read:field.options:jira: Read field options.
read:field:jira: View fields.
read:filter.column:jira: View filter columns.
read:filter.default-share-scope:jira: View filter default share scopes.
read:filter:jira: View filters.
read:group:jira: View user groups.
read:instance-configuration:jira: View instance configurations.
read:issue-details:jira: View issue details.
read:issue-event:jira: Read issue events.
read:issue-field-values:jira: View issue field valueses.
read:issue-link-type:jira: View issue link types.
read:issue-link:jira: View issue links.
read:issue-meta:jira: View issue meta.
read:issue-security-level:jira: View issue security levels.
read:issue-security-scheme:jira: View issue security schemes.
read:issue-status:jira: View issue statuses.
read:issue-type-hierarchy:jira: Read issue type hierarchies.
read:issue-type-scheme:jira: View issue type schemes.
read:issue-type-screen-scheme:jira: View issue type screen schemes.
read:issue-type.property:jira: View issue type properties.
read:issue-type:jira: View issue types.
read:issue-worklog.property:jira: View issue worklog properties.
read:issue-worklog:jira: View issue worklogs.
read:issue.changelog:jira: View issue changelogs.
read:issue.property:jira: View issue properties.
read:issue.remote-link:jira: View issue remote links.
read:issue.time-tracking:jira: View issue time trackings.
read:issue.transition:jira: View issue transitions.
read:issue.vote:jira: View issue votes.
read:issue.votes:jira: View issue voteses.
read:issue.watcher:jira: View issue watchers.
read:issue:jira: View issues.
read:jira-expressions:jira: View jira expressions.
read:jira-user: View user information in Jira that you have access to, including usernames, email addresses, and avatars.
read:jira-work: Read project and issue data. Search for issues and objects associated with issues (such as attachments and worklogs).
read:jql:jira: View JQL.
read:label:jira: View labels.
read:license:jira: View licenses.
read:notification-scheme:jira: View notification schemes.
read:permission-scheme:jira: View permission schemes.
read:permission:jira: View permissions.
read:priority:jira: View priorities.
read:project-category:jira: View project categories.
read:project-role:jira: View project roles.
read:project-type:jira: View project types.
read:project-version:jira: View project versions.
read:project.avatar:jira: Read project avatars.
read:project.component:jira: View project components.
read:project.email:jira: View project emails.
read:project.feature:jira: Read project features.
read:project.property:jira: View project properties.
read:project:jira: View projects.
read:resolution:jira: View resolutions.
read:role:jira: View roles.
read:screen-field:jira: View screen fields.
read:screen-scheme:jira: View screen schemes.
read:screen-tab:jira: View screen tabs.
read:screen:jira: View screens.
read:screenable-field:jira: View screenable fields.
read:status:jira: View statuses.
read:user-configuration:jira: View user configurations.
read:user.columns:jira: View user columnses.
read:user.property:jira: View user properties.
read:user:jira: View users.
read:webhook:jira: View webhooks.
read:workflow-scheme:jira: View workflow schemes.
read:workflow.property:jira: View workflow properties.
read:workflow:jira: View workflows.
send:notification:jira: Send notifications.
validate:jql:jira: Validate JQL.
write:app-data:jira: Write app data.
write:attachment:jira: Create and update issue attachments.
write:avatar:jira: Create and update system and custom avatars.
write:comment.property:jira: Create and update issue comment properties.
write:comment:jira: Create and update issue comments.
write:custom-field-contextual-configuration:jira: Save custom field contextual configurations.
write:dashboard.property:jira: Create and update dashboard properties.
write:dashboard:jira: Create and update dashboards.
write:field-configuration-scheme:jira: Create and update field configuration schemes.
write:field-configuration:jira: Save field configurations.
write:field.default-value:jira: Create and update field default values.
write:field.option:jira: Create and update field options.
write:field:jira: Create and update fields.
write:filter.column:jira: Create and update filter columns.
write:filter.default-share-scope:jira: Create and update filter default share scopes.
write:filter:jira: Create and update filters.
write:group:jira: Create and update user groups.
write:instance-configuration:jira: Create and update instance configurations.
write:issue-link-type:jira: Create and update issue link types.
write:issue-link:jira: Create and update issue links.
write:issue-type-scheme:jira: Create and update issue type schemes.
write:issue-type-screen-scheme:jira: Create and update issue type screen schemes.
write:issue-type.property:jira: Create and update issue type properties.
write:issue-type:jira: Create and update issue types.
write:issue-worklog.property:jira: Create and update issue worklog properties.
write:issue-worklog:jira: Create and update issue worklogs.
write:issue.property:jira: Create and update issue properties.
write:issue.remote-link:jira: Create and update issue remote links.
write:issue.time-tracking:jira: Create and update issue time trackings.
write:issue.vote:jira: Create and update issue votes.
write:issue.watcher:jira: Create and update issue watchers.
write:issue:jira: Create and update issues.
write:jira-work: Create and edit issues in Jira, post comments, create worklogs, and delete issues.
write:permission-scheme:jira: Create and update permission schemes.
write:permission:jira: Create and update permissions.
write:project-category:jira: Create and update project categories.
write:project-role:jira: Create and update project roles.
write:project-version:jira: Create and update project versions.
write:project.avatar:jira: Create and update project avatars.
write:project.component:jira: Create and update project components.
write:project.email:jira: Create and update project emails.
write:project.feature:jira: Save project features.
write:project.property:jira: Create and update project properties.
write:project:jira: Create and update projects.
write:screen-scheme:jira: Create and update screen schemes.
write:screen-tab:jira: Create and update screen tabs.
write:screen:jira: Create and update screens.
write:screenable-field:jira: Create and update screenable fields.
write:user-configuration:jira: Create and update user configurations.
write:user.property:jira: Create and update user properties.
write:webhook:jira: Create and update webhooks.
write:workflow-scheme:jira: Create and update workflow schemes.
write:workflow.property:jira: Create and update workflow properties.
write:workflow:jira: Create and update workflows.
tokenUrl: https://auth.atlassian.com/oauth/token
type: oauth2
basicAuth:
description: You can access this resource via basic auth.
scheme: basic
type: http
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
x-atlassian-narrative:
documents:
- anchor: about
body: "The Jira REST API enables you to interact with Jira programmatically. Use this API to \n[build apps](https://developer.atlassian.com/cloud/jira/platform/integrating-with-jira-cloud/), script interactions with \nJira, or develop any other type of integration. This page documents the REST resources available in Jira Cloud, including \nthe HTTP response codes and example requests and responses."
title: About
- anchor: version
body: "This documentation is for **version 3** of the Jira Cloud platform REST API, which is the latest\nversion. [Version 2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) and\nversion 3 of the API offer the same collection of operations. However, version 3 provides support for\nthe [Atlassian Document Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)\n(ADF) in:\n- `body` in comments, including where comments are used in issue, issue link, and transition resources.\n- `comment` in worklogs.\n- `description` and `environment` fields in issues.\n- `textarea` type custom fields (multi-line text fields) in issues. Single line custom fields\n (`textfield`) accept a string and don't handle Atlassian Document Format content.\n"
title: Version
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jira/refs/heads/main/openapi/jira-issue-custom-field-configuration-apps-api-openapi.yml