Updated 19th September 2025 to include changes to proposed payloads incorporating feedback and aligning with Jira’s upcoming terminology refresh.
Summary of Project:
- Publish: December 2025
- Discuss: During early access starting at 1st October 2025
- Resolve: TBC end of early access
Problem
With the changes our team is making to the field configuration model, we’ll be replacing existing APIs to be compatible with our new model.
This RFC provides new APIs that perform any read and write operations that support backup and restoration of configurations.
Proposed Solution
The below APIs will not be compatible with projects using the existing field configuration model. So during the transition 3rd party integrations will need to support projects on either model. To enable this we’ve added another API allowing you to check which scheme a project is using (see Get Field Scheme for Projects).
Field Scheme APIs
1. Get Field Schemes
GET /rest/api/3/config/fieldschemes
Returns a paginated list of field schemes. Supports filtering/search via query parameters. matchedFilters is only included when a query or projectIds filter is provided and matches the scheme.
Query parameters:
-
query(string): Filter by name or description. -
projectId(integer): Filter by associated project. -
startAt(integer) -
maxResults(integer, maximum: 100)
Response:
{
"isLast": true,
"maxResults": 2,
"startAt": 0,
"total": 2,
"values": [
{
"id": 10000,
"name": "Default Field Scheme",
"description": "Default field scheme",
"isDefault": true,
"links": {
"associations": "rest/api/3/config/fieldschemes/10000/associations",
"projects": "rest/api/3/config/fieldschemes/10000/projects"
},
"matchedFilters": {
"query": "Field Scheme"
}
},
{
"id": 10001,
"name": "Legal Team Field Scheme",
"description": "Field scheme for Legal teams",
"links": {
"associations": "rest/api/3/config/fieldschemes/10001/associations",
"projects": "rest/api/3/config/fieldschemes/10001/projects"
},
"matchedFilters": {
"query": "Field Scheme",
"projectIds": [10000, 10001],
}
},
{
"id": 10002,
"name": "HR Team Field Scheme",
"description": "Field scheme for HR teams",
"links": {
"associations": "rest/api/3/config/fieldschemes/10002/fields",
"projects": "rest/api/3/config/fieldschemes/10002/projects"
},
"matchedFilters": {
"query": "Field Scheme",
"projectIds": [10000],
}
}
]
}
2. Get Field Scheme by ID
GET /rest/api/3/config/fieldschemes/{schemeId}
Returns details for a specific field scheme.
Path parameters:
schemeId(integer, required)
Response:
{
"id": 10001,
"name": "Legal Field Scheme",
"description": "Field scheme for Legal teams",
"isDefault": false,
"links": {
"associations": "rest/api/3/config/fieldschemes/10001/fields",
"projects": "rest/api/3/config/fieldschemes/10001/projects"
}
}
3. Create Field Scheme
POST /rest/api/3/config/fieldschemes
Creates field scheme with name and description provided via request body.
Request:
-
name(string, required): Name of the field scheme. -
description(string, optional): Description of the field scheme.
{
"description": "My field configuration description",
"name": "My Field Scheme"
}
Response:
{
"id": 10001,
"name": "Legal Field Scheme",
"description": "Field scheme for Legal teams",
"links": {
"associations": "rest/api/3/config/fieldschemes/10001/associations",
"projects": "rest/api/3/config/fieldschemes/10001/projects"
}
}
4. Update Field Scheme
PUT /rest/api/3/config/fieldschemes/{schemeId}
Updates existing field scheme with name and description provided via request body.
Path parameters:
schemeId(integer, required)
Request:
-
name(string, optional): New name for the field scheme. -
description(string, optional): New description for the field scheme.
{
"description": "We can use this one for software projects.",
"name": "Field Scheme for software related projects"
}
Response:
{
"id": 10003
"name": "Finance Field Scheme",
"description": "Field scheme for Finance teams",
"links": {
"associations": "rest/api/3/config/fieldschemes/10003/associations",
"projects": "rest/api/3/config/fieldschemes/10003/projects"
}
}
5. Delete Field Scheme
DELETE /rest/api/3/config/fieldschemes/{schemeId}
Deletes existing field scheme for the scheme id provided.
Path parameters:
schemeId(integer, required)
Response:
{
"id": 10001,
"deleted": true
}
Field Scheme Project APIs
1. Get Projects associated with a Field Scheme
GET /rest/api/3/config/fieldschemes/{schemeId}/projects
Returns a paginated list of projects associated with the current field scheme. Supports filtering/search via query parameters.
Path parameters:
schemeId(integer, required)
Query parameters:
-
startAt(integer) -
maxResults(integer) -
query(string): Filter by the name of the project.
Response:
{
"isLast": true,
"maxResults": 50,
"nextPage": "/rest/api/3/config/fieldschemes/10000/projects?startAt=2"
"startAt": 0,
"total": 2,
"values": [
{
"id": 10000,
"name": "Scrum Project"
},
{
"id": 10001,
"name": "Awesome Project"
}
]
}
2. Update Field Scheme for Project
PUT /rest/api/3/config/fieldschemes/projects
Updates which projects are associated with a scheme.
Request:
-
schemeId(integer, required): The ID of the field scheme to update. This is the key of the request objects. -
projectIds(array, required): The ID of the projects to associate.
{
"10001": {
projectIds: [10000, 10001]
},
"10002": {
projectIds: [10000, 10001]
}
}
Response:
{
"results": [
{
projectId: 10001,
schemeId: 10000,
success: true
},
{
projectId: 10002,
schemeId: 10000,
success: false,
error: {
"code": "Error Code",
"message": "Error message"
}
}
]
}
3. Get Field Scheme for Projects
GET /rest/api/3/config/fieldschemes/projects
Gets projects which are using the new field scheme model. This can be used by integrations to determine if a project is using the new model as any requested projects that aren’t won’t be returned.
-
Query Parameters:
-
projectId- (array, required) -
startAt(integer) -
maxResults(integer, maximum: 100)
-
Request:
{
"isLast": true,
"maxResults": 50,
"startAt": 0,
"total": 1,
"values": [
{
"projectId": 10001,
"schemeId": 1
}
]
}
Field Scheme Item APIs
1. Get Field Scheme Items
GET /rest/api/3/config/fieldschemes/{schemeId}/fields
Returns a paginated list of all fields associated with the current field scheme. Supports filtering/search via query parameters.
Path parameters:
schemeId(integer, required)
Query parameters:
-
startAt(integer) -
maxResults(integer) -
fieldIds(array)
Response:
{
"isLast": true,
"maxResults": 50,
"nextPage": "/rest/api/3/config/fieldschemes/{schemeId}/fields?startAt=5"
"startAt": 0,
"total": 5,
"values": [{
"fieldId": "customfield_10000",
"allowedOperations": ["REMOVE", "CHANGE_REQUIRED", "CHANGE_DESCRIPTION"]
"parameters": {
"isRequired": true
"description": "Default description"
},
"workTypeParameters": [
{
"workTypeId": 10010
"isRequired": false,
"description": "Special description for issue type 10010"
},
{
"workTypeId" : 10011
"description": "Special description for issue type 10011"
}
]
},
{
// This field is only available in a single issue type
"fieldId": "customfield_10001",
"allowedOperations": ["REMOVE", "CHANGE_REQUIRED", "CHANGE_DESCRIPTION"]
"restrictedToWorkTypes": [100010],
"workTypeParameters": [
{
"workTypeId": 10010,
"isRequired": true
"description": "Default description"
}
]
},
{
-- this field is available in all issue types and all issue types have the same parameters
"fieldId": "customfield_10002",
"allowedOperations": ["REMOVE", "CHANGE_REQUIRED", "CHANGE_DESCRIPTION"]
"parameters": {
"isRequired": true
"description": "Default description"
},
"workTypeParameters": []
},
{
"fieldId": "customfield_10003",
"allowedOperations": ["REMOVE"]
"parameters": {
"isRequired": false
},
"workTypeParameters": []
}
]
}
2. Remove fields associated with a Field Scheme
DELETE /rest/api/3/config/fieldschemes/fields
Deletes the field associations to field schemes.
-
Maximum of 100 fields can be provided in a single request
-
Maximum of 50 schemes can be provided per field in a single request
Request:
{
"customfield_10000": {
"schemeIds": [10000, 10001]
},
"customfield_10001": {
"schemeIds": [10000, 10001]
}
}
Response:
{
"results": [
{
fieldId: 10001,
schemeId: 10000,
success: true
},
{
fieldId: 10002,
schemeId: 10000,
success: false,
error: {
"code": "Error Code",
"message": "Error message"
}
}
]
}
3. Update Fields associated with Field Schemes
PUT /rest/api/3/config/fieldschemes/fields
Updates the field association to field schemes. When restrictedToWorkTypes is not included the field will be associated with all work types. When restrictedToWorkTypes is included it overrides the associated work types with those provided.
-
Maximum of 100 fields can be provided in a single request
-
Maximum of 50 schemes can be provided per field in a single request
Request:
{
"customfield_10000": [
{
"schemeIds": [10000, 10001],
"restrictedToWorkTypes":[10001]
},
{
"schemeIds": [10003],
"restrictedToWorkTypes": null
}
],
"customfield_10001": [
{
"schemeIds": [10000, 10001],
"restrictedToWorkTypes":[10001]
}
]
}
Response:
{
"results": [
{
"fieldId": "customfield_10000",
"schemeId": 10000,
"workTypeIds": [10011],
"success": true
},
{
"fieldId": "customfield_10001",
"schemeId": 10000,
"success": false,
"error": {
"code": "Error Code",
"message": "Error message"
}
}
]
}
4. Get the Field parameters of a Field in a Field Scheme
GET /rest/api/3/config/fieldschemes/{schemeId}/fields/{fieldId}/parameters
Returns all parameters for a field in a field scheme.
Path parameters:
-
schemeId(integer, required) -
fieldId
Response:
{
"fieldId": "customfield_10001",
"parameters": {
"isRequired": true,
"description": "Example description"
},
"workTypeParameters": [
{
"workTypeId": 10010,
"isRequired": false
}
]
}
5. Delete Field parameters in Field Schemes
PUT /rest/api/3/config/fieldschemes/fields/parameters
Deletes the field work type parameters in field schemes.
-
Maximum of 100 parameters can be deleted in a single request
-
Maximum of 50 work types can be provided per parameter in a single request
Request:
{
"customfield_10001": [
{
"schemeId": 10000,
"workTypeIds": [10010],
"workTypeParameters": ["isRequired", "description"]
},
{
"schemeId": 10001,
"workTypeIds": [10010, 10011],
"workTypeParameters": ["isRequired"]
}
],
"customfield_10002": [
{
"schemeId": 10001,
"parameters": ["description"]
}
]
}
Response:
{
"results": [
{
"fieldId": "customfield_10001",
"schemeId": 10001,
"workTypeIds": [10011],
"success": true
},
{
"fieldId": "customfield_10001",
"schemeId": 10001,
"workTypeIds": [10011],
"success": false,
"error": {
"code": "Error Code",
"message": "Error Message"
}
}
]
}
6. Update Field Parameters for Field Schemes
PUT /rest/api/3/config/fieldschemes/fields/parameters
Updates the field parameters for field schemes. parameters can be provided to set the scheme level parameters for the field. workTypeParameters can be provided to override parameters for specific work types.
-
Maximum of 100 fields can be provided in a single request
-
Maximum of 50 parameters per field can be provided in a single request
Request:
{
"customfield_10001": [
{
"schemeIds": [10000],
"workTypeParameters": [
{
"workTypeId": 10010,
"isRequired": true,
"description": "Example"
}
]
},
{
"schemeIds": [10001],
"parameters": {
"description": "Work Type Description"
}
},
{
"schemeIds": [10002],
"parameters": {
"isRequired": true
},
"workTypeParameters": [
{
"workTypeId": 10010,
"isRequired": false
}
]
}
]
}
Response:
{
"results": [
{
"fieldId": "customfield_10001",
"schemeId": 10001,
"workTypeIds": [10011],
"success": true
},
{
"fieldId": "customfield_10001",
"schemeId": 10001,
"workTypeIds": [10011],
"success": false,
"error": {
"code": "Error Code",
"message": "Error Message"
}
}
]
}
Use Cases & Examples
Field Association Use Cases
PUT /rest/api/3/config/fieldschemes/fields
| Use Case | |
|---|---|
| Associate fields to all or specific work types | For scheme 10001, associate customfield_10000 to all work types and customfield_10001 to work types 10010 and 10011. |
Request:
{
"customfield_10000": [
{
"schemeIds": [10001]
}
],
"customfield_10001": [
{
"schemeIds": [10001],
"restrictedToWorkTypes":[10010, 10011]
}
]
}
| Use Case | |
|---|---|
| Add association to new work types, keep existing | or scheme 10001, associate customfield_10001 to new work type 10012 and keep existing (10010, 10011). |
Request:
{
"customfield_10001": [
{
"schemeIds": [10001],
"restrictedToWorkTypes":[10010, 10011, 10012]
}
]
}
| Use Case | |
|---|---|
| Replace association with new work types | For scheme 10001, associate customfield_10001 only to work type 10012 (removes others). |
Request:
{
"customfield_10001": [
{
"schemeIds": [10001],
"restrictedToWorkTypes":[10012]
}
]
}
| Use Case | |
|---|---|
| Remove association from specific work types | For scheme 10001, unassociate customfield_10001 from work type 10012. |
Request:
{
"customfield_10001": [
{
"schemeIds": [10001],
"restrictedToWorkTypes":[10010, 10011]
}
]
}
| Use Case | |
|---|---|
| Remove association from scheme completely | For scheme 10001, unassociate customfield_10001 from the scheme. |
DELETE /rest/api/3/config/fieldschemes/fields
Request:
{
"customfield_10001": {
"schemeIds": [10001]
}
}
Field Parameters Use Cases
PUT /rest/api/3/config/fieldschemes/fields/parameters
| Use Case | |
|---|---|
| Update description and make required for a work type | For scheme 10001, update customfield_10000 to set description and make required for work type 10011. |
Request:
{
"customfield_10000": [
{
"schemeIds": [10001],
"workTypeParameters": [
{
"workTypeId": 10011,
"isRequired": true,
"description": "Example"
}
]
}
]
}
| Use Case | |
|---|---|
| Update description and remove required configuration | For scheme 10001, update description and remove required for customfield_10000 on work type 10011. |
Request:
{
"customfield_10000": [
{
"schemeIds": [10001],
"workTypeParameters": [
{
"workTypeId": 10011,
"isRequired": null,
"description": "Example"
}
]
}
]
}
| Use Case | |
|---|---|
| Update multiple work type configurations | For scheme 10001, update customfield_10001: 1. Set description for work type 10012 2. Make optional and set description for default mapping |
Request:
{
"customfield_10001": [
{
"schemeIds": [10001],
"workTypeParameters": [
{
"workTypeId": 10012,
"isRequired": false,
"description": "Work Type Example"
}
],
"parameters": [
{
"isRequired": false,
"description": "Default Example"
}
]
}
]
}
Early access and feedback
We want to gather the feedback to understand how users are using existing field configuration API and whether the new API can replace the existing APIs
If you’d like to join, fill out an expression of interest form here.
Affected APIs
These APIs will no longer available to use after the existing field configuration model is fully deprecated.
The following APIs allows users to fetch or update field configuration, field configuration scheme, items and mappings.
- Get all field configurations
- Create field configuration
- Update field configuration
- Delete field configuration
- Get all field configuration schemes
- Create field configuration scheme
- Update field configuration scheme
- Delete field configuration scheme
- Get field configuration schemes for projects
- Assign field configuration scheme to project
- Get field configuration issue type items
- Get field configuration items
- Update field configuration items
- Assign issue types to field configurations
- Remove issue types from field configuration scheme