### API Versioning

Source: https://dev.jamasoftware.com/api

Information on how to access different versions of the Jama REST API.

```APIDOC
## API Versioning

### Description
Jama's REST API is versioned to ensure backward compatibility and manage updates. You can specify the API version in your requests.

### Available Versions
- **v0**: Pre-beta version (may be in use by older self-hosted clients).
- **v1**: Current supported version.
- **latest**: Designated for sunset; refer to sunset details.
- **labs**: For new features and feedback; not officially supported and may change.

### Accessing Documentation
To access documentation for different versions, update the swagger URL. For example:
`https://your-instance.jamacloud.com/swagger/index.html?url=/rest/v1/api-docs`

### Querying Available Versions
To determine which API versions are available on your instance, you can issue a request to the base REST endpoint:

#### GET https://your-instance.jamacloud.com/rest

This request will typically return information about the available API versions.
```

--------------------------------

### Reports

Source: https://dev.jamasoftware.com/api

Endpoints for generating and retrieving report metadata.

```APIDOC
## POST /reports/{reportId}

### Description
Create a new report as an asynchronous request. A successful response signifies that the work was started and a work identifier is given.

### Method
POST

### Endpoint
/reports/{reportId}

### Parameters
#### Path Parameters
- **reportId** (integer) - Required - The ID of the report to generate.

#### Request Body
- **parameters** (object) - Optional - Parameters for the report generation.

### Request Example
```json
{
  "parameters": {
    "projectId": 101,
    "format": "PDF"
  }
}
```

### Response
#### Success Response (202)
- **message** (string) - Confirmation that the report generation has started.
- **workId** (string) - The identifier for the asynchronous work.

#### Response Example
```json
{
  "message": "Report generation initiated.",
  "workId": "report-job-12345"
}
```

## GET /reports/metadata

### Description
Get all Reports Metadata for a given project.

### Method
GET

### Endpoint
/reports/metadata

### Parameters
#### Query Parameters
- **projectId** (integer) - Required - The ID of the project to retrieve metadata for.

### Response
#### Success Response (200)
- **metadata** (array) - A list of report metadata objects.
  - **reportId** (integer) - The ID of the report.
  - **name** (string) - The name of the report.
  - **description** (string) - A description of the report.

#### Response Example
```json
{
  "metadata": [
    {
      "reportId": 1,
      "name": "Requirements Traceability Matrix",
      "description": "Shows traceability between requirements."
    }
  ]
}
```
```

--------------------------------

### Project Permission Management

Source: https://dev.jamasoftware.com/api

Endpoints for managing project permissions for users or user groups.

```APIDOC
## GET /projects/{projectId}/permissions

### Description
Retrieve the permission entries for a specified user or user group within a project or folder of projects.

### Method
GET

### Endpoint
/projects/{projectId}/permissions

### Parameters
#### Path Parameters
- **projectId** (integer) - Required - The ID of the project.

#### Query Parameters
- **userOrGroupId** (integer) - Optional - The ID of the user or user group.

### Response
#### Success Response (200)
- **permissions** (array) - A list of permission objects.
  - **userOrGroupId** (integer) - The ID of the user or group.
  - **permissionType** (string) - The type of permission (e.g., READ, WRITE).
  - **accessLevel** (string) - The level of access granted.

#### Response Example
```json
{
  "permissions": [
    {
      "userOrGroupId": 1001,
      "permissionType": "READ",
      "accessLevel": "PROJECT"
    }
  ]
}
```

## POST /projects/{projectId}/permissions

### Description
Create or override a permission entry for a specified user or user group to a specified project or folder of projects.

### Method
POST

### Endpoint
/projects/{projectId}/permissions

### Parameters
#### Path Parameters
- **projectId** (integer) - Required - The ID of the project.

#### Request Body
- **userOrGroupId** (integer) - Required - The ID of the user or user group.
- **permissionType** (string) - Required - The type of permission to grant (e.g., READ, WRITE).
- **accessLevel** (string) - Required - The level of access (e.g., PROJECT, FOLDER).

### Request Example
```json
{
  "userOrGroupId": 1001,
  "permissionType": "WRITE",
  "accessLevel": "PROJECT"
}
```

### Response
#### Success Response (201)
- **message** (string) - Confirmation message of the permission creation.

#### Response Example
```json
{
  "message": "Permission created successfully."
}
```

## PUT /projects/{projectId}/permissions

### Description
Update an existing permission entry for a specified user or user group to a specified project or folder of projects.

### Method
PUT

### Endpoint
/projects/{projectId}/permissions

### Parameters
#### Path Parameters
- **projectId** (integer) - Required - The ID of the project.

#### Request Body
- **userOrGroupId** (integer) - Required - The ID of the user or user group.
- **permissionType** (string) - Required - The type of permission to update.
- **accessLevel** (string) - Required - The new level of access.

### Request Example
```json
{
  "userOrGroupId": 1001,
  "permissionType": "READ",
  "accessLevel": "FOLDER"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the permission update.

#### Response Example
```json
{
  "message": "Permission updated successfully."
}
```

## DELETE /projects/{projectId}/permissions

### Description
Remove an existing permission entry for a specified user or user group to a specified project or folder of projects.

### Method
DELETE

### Endpoint
/projects/{projectId}/permissions

### Parameters
#### Path Parameters
- **projectId** (integer) - Required - The ID of the project.

#### Query Parameters
- **userOrGroupId** (integer) - Required - The ID of the user or user group whose permission should be removed.
- **permissionType** (string) - Optional - The specific permission type to remove.

### Response
#### Success Response (204)
No content, indicates successful removal.

### Response Example
(No response body for 204)
```

--------------------------------

### Baseline Management

Source: https://dev.jamasoftware.com/api

Endpoints for managing baselines, including creation, retrieval, and updates.

```APIDOC
## POST /baselines

### Description
Create a baseline. In Jama Connect 8.86, this endpoint allows creating a baseline without needing to create a source first.

### Method
POST

### Endpoint
/baselines

### Parameters
#### Request Body
- **name** (string) - Required - The name of the baseline.
- **description** (string) - Optional - A description for the baseline.
- **sourceId** (integer) - Optional - The ID of the source item to create the baseline from.

### Request Example
```json
{
  "name": "Baseline for Release 1.0",
  "description": "Snapshot of items before release."
}
```

### Response
#### Success Response (201)
- **id** (integer) - The ID of the newly created baseline.
- **name** (string) - The name of the baseline.
- **creationDate** (string) - The date and time the baseline was created.

#### Response Example
```json
{
  "id": 101,
  "name": "Baseline for Release 1.0",
  "creationDate": "2023-10-27T10:00:00Z"
}
```

## GET /baselines

### Description
Retrieve a list of baselines. In Jama Connect 8.75, this endpoint now returns the baseline pick list option.

### Method
GET

### Endpoint
/baselines

### Response
#### Success Response (200)
- **baselines** (array) - A list of baseline objects.
  - **id** (integer) - The ID of the baseline.
  - **name** (string) - The name of the baseline.
  - **creationDate** (string) - The date and time the baseline was created.
  - **picklistOption** (object) - Information about the baseline's pick list option.

#### Response Example
```json
{
  "baselines": [
    {
      "id": 101,
      "name": "Baseline for Release 1.0",
      "creationDate": "2023-10-27T10:00:00Z",
      "picklistOption": {
        "id": 5,
        "name": "Released"
      }
    }
  ]
}
```

## GET /baselines/{baselineId}

### Description
Retrieve details of a specific baseline. In Jama Connect 8.75, this endpoint now returns the baseline pick list option.

### Method
GET

### Endpoint
/baselines/{baselineId}

### Parameters
#### Path Parameters
- **baselineId** (integer) - Required - The ID of the baseline.

### Response
#### Success Response (200)
- **id** (integer) - The ID of the baseline.
- **name** (string) - The name of the baseline.
- **creationDate** (string) - The date and time the baseline was created.
- **picklistOption** (object) - Information about the baseline's pick list option.

#### Response Example
```json
{
  "id": 101,
  "name": "Baseline for Release 1.0",
  "creationDate": "2023-10-27T10:00:00Z",
  "picklistOption": {
    "id": 5,
    "name": "Released"
  }
}
```

## PUT /baselines/{baselineId}

### Description
Update a baseline's pick list option. In Jama Connect 8.74, this endpoint was introduced.

### Method
PUT

### Endpoint
/baselines/{baselineId}

### Parameters
#### Path Parameters
- **baselineId** (integer) - Required - The ID of the baseline to update.

#### Request Body
- **picklistOptionId** (integer) - Required - The ID of the new pick list option for the baseline.

### Request Example
```json
{
  "picklistOptionId": 6
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the update.

#### Response Example
```json
{
  "message": "Baseline pick list option updated successfully."
}
```

## GET /baselines/{baselineId}/versioneditems

### Description
Retrieve versioned items within a baseline. In Jama Connect 8.80, items in the baseline will include the category applied at the time of the baseline.

### Method
GET

### Endpoint
/baselines/{baselineId}/versioneditems

### Parameters
#### Path Parameters
- **baselineId** (integer) - Required - The ID of the baseline.

### Response
#### Success Response (200)
- **versionedItems** (array) - A list of versioned item objects.
  - **itemId** (integer) - The ID of the item.
  - **version** (integer) - The version number of the item.
  - **appliedCategory** (object) - Snapshot of the category applied at the time of the baseline.
    - **id** (integer) - The ID of the category.
    - **name** (string) - The name of the category.

#### Response Example
```json
{
  "versionedItems": [
    {
      "itemId": 100,
      "version": 3,
      "appliedCategory": {
        "id": 1,
        "name": "Core Requirements"
      }
    }
  ]
}
```

## GET /baselines/{baselineId}/reviewlink

### Description
Retrieve the review ID of the baseline.

### Method
GET

### Endpoint
/baselines/{baselineId}/reviewlink

### Parameters
#### Path Parameters
- **baselineId** (integer) - Required - The ID of the baseline.

### Response
#### Success Response (200)
- **reviewId** (integer) - The review ID associated with the baseline.

#### Response Example
```json
{
  "reviewId": 50
}
```

## GET /baselines/folders

### Description
Retrieve a list of baseline folders.

### Method
GET

### Endpoint
/baselines/folders

### Response
#### Success Response (200)
- **folders** (array) - A list of baseline folder objects.
  - **id** (integer) - The ID of the folder.
  - **name** (string) - The name of the folder.

#### Response Example
```json
{
  "folders": [
    {
      "id": 1,
      "name": "Release Baselines"
    }
  ]
}
```

## POST /baselines/folders

### Description
Create a new baseline folder.

### Method
POST

### Endpoint
/baselines/folders

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new baseline folder.

### Request Example
```json
{
  "name": "Archived Baselines"
}
```

### Response
#### Success Response (201)
- **id** (integer) - The ID of the newly created baseline folder.
- **name** (string) - The name of the new baseline folder.

#### Response Example
```json
{
  "id": 2,
  "name": "Archived Baselines"
}
```

## PUT /baselinetree/{projectId}/move

### Description
Move a baseline source to a folder.

### Method
PUT

### Endpoint
/baselinetree/{projectId}/move

### Parameters
#### Path Parameters
- **projectId** (integer) - Required - The ID of the project containing the baseline source.

#### Request Body
- **baselineSourceId** (integer) - Required - The ID of the baseline source to move.
- **destinationFolderId** (integer) - Required - The ID of the destination folder.

### Request Example
```json
{
  "baselineSourceId": 10,
  "destinationFolderId": 2
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the move operation.

#### Response Example
```json
{
  "message": "Baseline source moved successfully."
}
```
```

--------------------------------

### Picklist Management

Source: https://dev.jamasoftware.com/api

Endpoints for managing picklists, including creating new picklists with options and retrieving picklist details.

```APIDOC
## POST /picklists/{picklistId}/options

### Description
Create a new option for a picklist.

### Method
POST

### Endpoint
/picklists/{picklistId}/options

### Parameters
#### Path Parameters
- **picklistId** (integer) - Required - The ID of the picklist to add an option to.

#### Request Body
- **name** (string) - Required - The name of the new picklist option.
- **type** (string) - Required - The type of the picklist option (e.g., STANDARD, LOOKUP_MATRIX).
- **infoTip** (string) - Optional - The info tip for the new picklist option.

### Request Example
```json
{
  "name": "Medium",
  "type": "STANDARD",
  "infoTip": "Indicates medium priority."
}
```

### Response
#### Success Response (201)
- **id** (integer) - The ID of the newly created picklist option.
- **name** (string) - The name of the new picklist option.
- **type** (string) - The type of the new picklist option.
- **infoTip** (string) - The info tip of the new picklist option.

#### Response Example
```json
{
  "id": 11,
  "name": "Medium",
  "type": "STANDARD",
  "infoTip": "Indicates medium priority."
}
```

## GET /picklist

### Description
Retrieve details of picklists, including their types (STANDARD or LOOKUP_MATRIX).

### Method
GET

### Endpoint
/picklist

### Response
#### Success Response (200)
- **picklists** (array) - A list of picklist objects.
  - **id** (integer) - The ID of the picklist.
  - **name** (string) - The name of the picklist.
  - **type** (string) - The type of the picklist (STANDARD or LOOKUP_MATRIX).

#### Response Example
```json
{
  "picklists": [
    {
      "id": 1,
      "name": "Priority",
      "type": "STANDARD"
    },
    {
      "id": 2,
      "name": "Status",
      "type": "LOOKUP_MATRIX"
    }
  ]
}
```
```

--------------------------------

### Basic Authentication Curl Example for Jama REST API

Source: https://dev.jamasoftware.com/api

An example using curl to demonstrate Basic Authentication for accessing Jama REST API endpoints. Replace 'myusername' and 'mypassword' with your actual credentials.

```bash
curl -u myusername:mypassword http://basepath/rest/v1/projects
```

--------------------------------

### API Access and Swagger UI

Source: https://dev.jamasoftware.com/api

Information on how to access the Jama Software REST API and use the Swagger UI for interactive documentation.

```APIDOC
## Getting Started with Jama REST API

### Description
The Jama REST API is available for both hosted SaaS instances (Jamacloud) and on-premises customers running version 8.0 or above. SOAP is not supported.

### Using Swagger UI
Swagger UI provides an interactive way to explore and test the REST API. It is accessible via `{Context-Path}/api-docs/`.

**Access Requirements:**
- A valid login.
- REST API enabled on your Jama instance.

**Troubleshooting:**
If REST is not enabled, you may encounter the error: `Can't read swagger JSON from {Context-Path}/rest/latest/api-docs`.

**Swagger UI Features:**
- Lists all supported endpoints.
- Details parameters, request objects, and response objects for each endpoint.
- Allows interactive testing with the "Try it out!" feature.
- Provides access to model schemas for request objects.
```

--------------------------------

### Picklist Option Management

Source: https://dev.jamasoftware.com/api

Endpoints for managing picklist options, including retrieving details of a specific option and updating its info tips.

```APIDOC
## GET /picklistoptions/{picklistOptionId}

### Description
Retrieve details of a specific picklist option.

### Method
GET

### Endpoint
/picklistoptions/{picklistOptionId}

### Parameters
#### Path Parameters
- **picklistOptionId** (integer) - Required - The ID of the picklist option.

### Response
#### Success Response (200)
- **id** (integer) - The ID of the picklist option.
- **name** (string) - The name of the picklist option.
- **infoTip** (string) - The info tip associated with the picklist option.

#### Response Example
```json
{
  "id": 10,
  "name": "High",
  "infoTip": "Indicates the highest priority."
}
```

## PUT /picklistoptions/{picklistOptionId}

### Description
Update the info tip for a picklist option.

### Method
PUT

### Endpoint
/picklistoptions/{picklistOptionId}

### Parameters
#### Path Parameters
- **picklistOptionId** (integer) - Required - The ID of the picklist option to update.

#### Request Body
- **infoTip** (string) - Required - The new info tip for the picklist option.

### Request Example
```json
{
  "infoTip": "Updated description for high priority."
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the update.

#### Response Example
```json
{
  "message": "Picklist option info tip updated successfully."
}
```
```

--------------------------------

### Authentication Methods

Source: https://dev.jamasoftware.com/api

Details on how to authenticate your requests to the Jama Software REST API using Basic Authentication and OAuth.

```APIDOC
## API Authentication

### Description
Two primary methods are supported for authenticating REST API calls: Basic Authentication and OAuth.

### Basic Authentication
This method involves providing your username and password in the request header according to RFC 2617.

**Note:** Basic Authentication is not compatible with SAML/SSO environments.

**Example Credentials:**
- Username: `myusername`
- Password: `mypassword`

**Header Format:**
`Authorization: Basic somestringoftext`

**Curl Example:**
```bash
curl -u myusername:mypassword http://basepath/rest/v1/projects
```

### OAuth Authentication
Supported for Jamacloud users and self-hosted users starting with version 8.62. This method uses OAuth client credentials flow.

**Requirements:**
- A client application supporting the OAuth client credentials flow.
- Client ID and Client Secret, which can be generated from your Jama User Profile page by clicking "Set API Credentials".

**OAuth Flow:**
1. **Exchange client credentials for an access token:** This is done once.
2. **Make REST API requests using the access token:** This is done repeatedly until the token expires.

**Token Expiration:**
Access tokens have an expiration time. The Jama OAuth service does not currently support refresh tokens. You must manage token expiration and re-exchange credentials when necessary. The duration of token validity may vary between Jama servers.
```

--------------------------------

### Item Type and Field Management

Source: https://dev.jamasoftware.com/api

Endpoints for managing item types and their fields, including creating and reading info tips for field labels.

```APIDOC
## GET /itemtypes/{itemTypeId}

### Description
Retrieve details of an item type, including its fields and their info tips.

### Method
GET

### Endpoint
/itemtypes/{itemTypeId}

### Parameters
#### Path Parameters
- **itemTypeId** (integer) - Required - The ID of the item type.

### Response
#### Success Response (200)
- **id** (integer) - The ID of the item type.
- **name** (string) - The name of the item type.
- **fields** (array) - A list of fields associated with the item type.
  - **id** (integer) - The ID of the field.
  - **name** (string) - The name of the field.
  - **infoTip** (string) - The info tip for the field label.

#### Response Example
```json
{
  "id": 5,
  "name": "User Story",
  "fields": [
    {
      "id": 20,
      "name": "Description",
      "infoTip": "Detailed explanation of the user story."
    }
  ]
}
```

## POST /itemtypes/{itemTypeId}/fields

### Description
Create an info tip for a field within an item type.

### Method
POST

### Endpoint
/itemtypes/{itemTypeId}/fields

### Parameters
#### Path Parameters
- **itemTypeId** (integer) - Required - The ID of the item type.

#### Request Body
- **fieldId** (integer) - Required - The ID of the field to add an info tip to.
- **infoTip** (string) - Required - The info tip text for the field label.

### Request Example
```json
{
  "fieldId": 20,
  "infoTip": "A concise summary of the user story."
}
```

### Response
#### Success Response (201)
- **message** (string) - Confirmation message of the info tip creation.

#### Response Example
```json
{
  "message": "Info tip created successfully for field."
}
```
```

--------------------------------

### Accessing REST API Endpoints

Source: https://dev.jamasoftware.com/api

Make requests to the Jama REST API using the obtained access token.

```APIDOC
## General REST API Request

### Description
Make requests to the Jama REST API using an access token obtained from the `/rest/oauth/token` endpoint.

### Method
GET, POST, PUT, DELETE, etc. (depending on the specific endpoint)

### Endpoint
/rest/v1/[resource] (or other versioned endpoints)

### Parameters
#### Query Parameters
(Varies by endpoint)

#### Request Body
(Varies by endpoint)

#### Headers
- **Authorization** (string) - Required - `Bearer YOUR_ACCESS_TOKEN`

### Request Example
```bash
curl --request GET https://your-instance.jamacloud.com/rest/v1/users/current \
     --header "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Response
#### Success Response (200)
(Varies by endpoint. Typically includes a `data` object and a `meta` object.)

#### Response Example
```json
{
  "meta": {
    "status": "OK"
  },
  "data": {
    "id": 5,
    "username": "sample"
  }
}
```
```

--------------------------------

### Query Available API Versions (curl)

Source: https://dev.jamasoftware.com/api

This snippet demonstrates how to query the available API versions supported by a Jama Connect instance. It involves making a GET request to the base REST URL (e.g., https://xyz.jamacloud.com/rest). This helps in understanding version compatibility.

```bash
GET https://xyz.jamacloud.com/rest
```

--------------------------------

### Labs POST for Baselines

Source: https://dev.jamasoftware.com/api

This update introduces the capability to use POST requests for baselines within the Labs feature of Jama Connect.

```APIDOC
## POST /labs/baselines

### Description
Creates a new baseline within the Labs feature.

### Method
POST

### Endpoint
/labs/baselines

### Parameters
#### Request Body
- **baselineData** (object) - Required - Data for the new baseline.
  - **name** (string) - Required - The name of the baseline.
  - **description** (string) - Optional - A description for the baseline.

### Request Example
```json
{
  "baselineData": {
    "name": "Baseline for Release 2.0",
    "description": "Snapshot of the project before release."
  }
}
```

### Response
#### Success Response (201)
- **id** (string) - The ID of the newly created baseline.
- **name** (string) - The name of the baseline.

#### Response Example
```json
{
  "id": "b12345",
  "name": "Baseline for Release 2.0"
}
```
```

--------------------------------

### Category Management

Source: https://dev.jamasoftware.com/api

Endpoints for managing categories, including retrieving all category paths, creating new category paths, and updating category visibility.

```APIDOC
## GET /categories

### Description
Retrieve all category paths by name and/or project ID.

### Method
GET

### Endpoint
/categories

### Parameters
#### Query Parameters
- **name** (string) - Optional - Filter category paths by name.
- **projectId** (integer) - Optional - Filter category paths by project ID.

### Response
#### Success Response (200)
- **categories** (array) - A list of category path objects.
  - **id** (integer) - The unique identifier for the category path.
  - **name** (string) - The name of the category path.
  - **projectId** (integer) - The ID of the project this category belongs to.

#### Response Example
```json
{
  "categories": [
    {
      "id": 1,
      "name": "Core Requirements",
      "projectId": 101
    }
  ]
}
```

## POST /categories

### Description
Create a new CategoryPath.

### Method
POST

### Endpoint
/categories

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new category path.
- **projectId** (integer) - Required - The ID of the project to associate the category with.

### Request Example
```json
{
  "name": "New Feature Category",
  "projectId": 102
}
```

### Response
#### Success Response (201)
- **id** (integer) - The ID of the newly created category path.
- **name** (string) - The name of the newly created category path.
- **projectId** (integer) - The ID of the project the category was created in.

#### Response Example
```json
{
  "id": 2,
  "name": "New Feature Category",
  "projectId": 102
}
```

## PUT /categories/{categoryPathId}/visibility

### Description
Update the visibility of a category.

### Method
PUT

### Endpoint
/categories/{categoryPathId}/visibility

### Parameters
#### Path Parameters
- **categoryPathId** (integer) - Required - The ID of the category path to update.

#### Request Body
- **visible** (boolean) - Required - The new visibility status for the category.

### Request Example
```json
{
  "visible": false
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the update.

#### Response Example
```json
{
  "message": "Category visibility updated successfully."
}
```

## DELETE /item/{id}/categories

### Description
Unapply a category from an item.

### Method
DELETE

### Endpoint
/item/{id}/categories

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the item from which to unapply the category.

#### Query Parameters
- **categoryId** (integer) - Required - The ID of the category to unapply.

### Response
#### Success Response (204)
No content, indicates successful removal.

### Response Example
(No response body for 204)

```

--------------------------------

### /latest API Endpoint Sunset

Source: https://dev.jamasoftware.com/api

Information regarding the sunsetting of the '/latest' API endpoint, including the announcement date and end-of-life date.

```APIDOC
## /latest API Endpoint Sunset

### Description
Information regarding the sunsetting of the '/latest' API endpoint, including the announcement date and end-of-life date.

### Endpoint
`/latest`

### Sunset Details
- **Announcement Date**: 2019-11-22
- **End of Life (EOL)**: 2020-05-22

### Additional Information
See community post for more details.
```

--------------------------------

### Example Date Formats in Queries and Responses

Source: https://dev.jamasoftware.com/cookbook

These examples demonstrate how dates are accepted in query parameters and how they are formatted in REST API responses, adhering to the specified ISO 8601 standard with UTC offset. Note the difference in offset for PST.

```text
June 18th 2015 | 2015-06-18T00:00:00.000+0000 | 2015-06-18T00:00:00.000+0000
July 4th 2011 @ 1:59pm PST | 2011-07-4T13:59:00.000-0700 | 2011-07-4T20:59:00.000+0000
```

--------------------------------

### Abstract Item Search with Wildcards and Field Specificity

Source: https://dev.jamasoftware.com/cookbook

This example illustrates using wildcards (*) within double quotes for more flexible matching and specifying fields like 'name' for targeted searches. It shows how to find items where the name starts with 'A' and ends with 'a'.

```curl
curl -X GET 'https://{baseUrl}/rest/v1/abstractitems?contains="name:"A*pha""'
```

--------------------------------

### Item Category Management

Source: https://dev.jamasoftware.com/api

Endpoints for managing categories associated with items, including retrieving an item's categories and applying new categories.

```APIDOC
## GET /items/{itemId}/categories

### Description
Retrieve the categories associated with a specific item.

### Method
GET

### Endpoint
/items/{itemId}/categories

### Parameters
#### Path Parameters
- **itemId** (integer) - Required - The ID of the item to retrieve categories for.

### Response
#### Success Response (200)
- **categories** (array) - A list of category objects associated with the item.
  - **id** (integer) - The ID of the category.
  - **name** (string) - The name of the category.

#### Response Example
```json
{
  "categories": [
    {
      "id": 1,
      "name": "Core Requirements"
    }
  ]
}
```

## POST /items/{itemId}/categories

### Description
Apply a category to an item.

### Method
POST

### Endpoint
/items/{itemId}/categories

### Parameters
#### Path Parameters
- **itemId** (integer) - Required - The ID of the item to apply the category to.

#### Request Body
- **categoryId** (integer) - Required - The ID of the category to apply.

### Request Example
```json
{
  "categoryId": 1
}
```

### Response
#### Success Response (201)
- **message** (string) - Confirmation message of the category application.

#### Response Example
```json
{
  "message": "Category applied successfully."
}
```
```

--------------------------------

### New API Header: x-jama-date-fields-with-time

Source: https://dev.jamasoftware.com/api

Introduces a new API header option, `x-jama-date-fields-with-time`, to enable full ISO-8601 formatting of dates within the fields section of requests.

```APIDOC
## Request Header

### Description
Enables ISO-8601 date formatting for fields.

### Header Name
x-jama-date-fields-with-time

### Values
- `true`: Enables ISO-8601 date formatting.
- `false` (default): Standard date formatting.

### Example Usage
```
POST /api/items
Host: your-jama-instance.com
x-jama-date-fields-with-time: true
Authorization: Basic YOUR_BASE64_ENCODED_CREDENTIALS
Content-Type: application/json

{
  "fields": {
    "created": "2023-10-27T10:00:00Z",
    "modified": "2023-10-27T11:30:00Z"
  }
}
```
```

--------------------------------

### Accessing Swagger UI for Jama REST API Documentation

Source: https://dev.jamasoftware.com/api

Swagger UI provides an interactive way to explore and test Jama REST API endpoints. Access it via the specified URL after logging in. If REST is not enabled, an error message will appear.

```text
“Can't read swagger JSON from {Context-Path}/rest/latest/api-docs”
```

--------------------------------

### Make REST API Request with Access Token (curl)

Source: https://dev.jamasoftware.com/api

This snippet shows how to make a GET request to a REST API endpoint (e.g., /users/current) using an access token obtained from the previous step. The access token is included in the 'Authorization' header as a Bearer token. The response contains metadata and the requested data.

```bash
$ curl --request GET http://basepath/rest/v1/users/current
       --header "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NDQ5MjI4OTcsInNjb3BlIjpbInJlYWQiXSwianRpIjoiNTQ3N2... (et cetera)" 
{
"meta":{
"status":"OK",
"timestamp":"2015-10-28T22:33:16.524+0000"
},
"links":{},
"data":{
"id":5,
"username":"sample",
"firstName":"Sample",
"lastName":"User",
"email":"admin@my.domain.com",
"phone":"",
"title":"",
"location":"",
"licenseType":"NAMED",
"active":true,
"type":"users"
}
}
```

--------------------------------

### Generating API Credentials in Jama UI

Source: https://dev.jamasoftware.com/api

These steps outline how to generate API credentials (Client ID and Client Secret) within the Jama UI, necessary for OAuth authentication. The secret is only displayed once upon creation.

```text
1. Click the “Set API Credentials” button:
2. Enter a name for your application/integration:
3. Click the “Create API Credentials” button:
```

--------------------------------

### User and User Group Permissions

Source: https://dev.jamasoftware.com/api

Access to retrieve users and user groups now requires specific administrative roles. Project admins need to provide a project ID. Permissions checks are enforced for accessing user-specific or user group-specific details.

```APIDOC
## GET /users

### Description
Retrieves a list of users. Requires organization or user admin roles. Project admins must provide a project ID.

### Method
GET

### Endpoint
/users

### Parameters
#### Query Parameters
- **projectId** (string) - Required for Project Admins - The ID of the project to filter users by.

### Response
#### Success Response (200)
- **users** (array) - A list of user objects.
  - **id** (string) - The user's ID.
  - **username** (string) - The user's username.

#### Response Example
```json
{
  "users": [
    {
      "id": "user1",
      "username": "john.doe"
    }
  ]
}
```

## GET /usergroups

### Description
Retrieves a list of user groups. Requires organization or user admin roles. Project admins must provide a project ID.

### Method
GET

### Endpoint
/usergroups

### Parameters
#### Query Parameters
- **projectId** (string) - Required for Project Admins - The ID of the project to filter user groups by.

### Response
#### Success Response (200)
- **userGroups** (array) - A list of user group objects.
  - **id** (string) - The user group's ID.
  - **name** (string) - The user group's name.

#### Response Example
```json
{
  "userGroups": [
    {
      "id": "group1",
      "name": "Developers"
    }
  ]
}
```

## GET /users/{userId}

### Description
Retrieves details for a specific user. Requires the requesting user to have access to the same project as the requested user.

### Method
GET

### Endpoint
/users/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The ID of the user to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The user's ID.
- **username** (string) - The user's username.

#### Response Example
```json
{
  "id": "user1",
  "username": "john.doe"
}
```

## GET /usergroups/{id}

### Description
Retrieves details for a specific user group. Requires the requesting user to have access to the same project as the requested user group.

### Method
GET

### Endpoint
/usergroups/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the user group to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The user group's ID.
- **name** (string) - The user group's name.

#### Response Example
```json
{
  "id": "group1",
  "name": "Developers"
}
```
```

--------------------------------

### Example GET /relationships API Response Payload (JSON)

Source: https://dev.jamasoftware.com/cookbook

Illustrates the JSON payload structure returned by the GET /relationships API call. This includes metadata about the request status, timestamp, and pagination information, as well as the 'data' array containing relationship objects.

```json
{
  "meta": {
    "status": "OK",
    "timestamp": "2023-05-29T12:24:48.962+0000",
    "pageInfo": {
      "startIndex": 0,
      "resultCount": 1,
      "totalResults": 0
    }
  },
  "data": [
    {
      "id": 90901,
      "fromItem": 1010,
      "toItem": 2109,
      "relationshipType": 4,
      "suspect": false,
      "type": "relationships"
    }
  ]
}
```

```json
{
  "meta": {
    "status": "OK",
    "timestamp": "2023-05-29T13:24:48.962+0000",
    "pageInfo": {
      "startIndex": 0,
      "resultCount": 100,
      "totalResults": 0
    }
  },
  "data": [
    {
      "id": 90904,
      "fromItem": 1400,
      "toItem": 2605,
      "relationshipType": 4,
      "suspect": false,
      "type": "relationships"
    },
    {...}
  ]
}
```

--------------------------------

### GET /reports/metadata

Source: https://dev.jamasoftware.com/api

Gets all Reports Metadata for a given project. This endpoint retrieves metadata for reports.

```APIDOC
## GET /reports/metadata

### Description
Get all Reports Metadata for a given project.

### Method
GET

### Endpoint
/reports/metadata

### Parameters
#### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **metadata** (array) - An array of report metadata objects.

#### Response Example
```json
{
  "metadata": [
    {
      "reportId": 123,
      "name": "Report Name"
    }
  ]
}
```
```

--------------------------------

### Filters

Source: https://dev.jamasoftware.com/api

Endpoint to get the count of items within a filter without returning the items themselves.

```APIDOC
## GET /filters/{filterId}/count

### Description
Provides the filter result count without returning the items within a filter.

### Method
GET

### Endpoint
/filters/{filterId}/count

### Parameters
#### Path Parameters
- **filterId** (integer) - Required - The ID of the filter.

### Response
#### Success Response (200)
- **count** (integer) - The number of items matching the filter.

#### Response Example
```json
{
  "count": 150
}
```
```

--------------------------------

### Item Updates

Source: https://dev.jamasoftware.com/api

Endpoints for updating items, including asynchronous updates for an array of items and setting item location.

```APIDOC
## PATCH /items

### Description
Update an array of items with the specified ID as an asynchronous request.

### Method
PATCH

### Endpoint
/items

### Parameters
#### Request Body
- **items** (array) - Required - An array of item objects to update.
  - **id** (integer) - Required - The ID of the item.
  - **updates** (object) - Required - An object containing the fields to update.

### Request Example
```json
{
  "items": [
    {
      "id": 100,
      "updates": {
        "description": "Updated description for item 100."
      }
    }
  ]
}
```

### Response
#### Success Response (202)
- **message** (string) - Confirmation that the update request has been accepted.
- **jobId** (string) - The ID of the asynchronous job.

#### Response Example
```json
{
  "message": "Item update request accepted.",
  "jobId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```

## PUT /items/{treeLocation}

### Description
Set the location of an item by indicating its parent and the location of its peer.

### Method
PUT

### Endpoint
/items/{treeLocation}

### Parameters
#### Path Parameters
- **treeLocation** (string) - Required - The tree location identifier for the item.

#### Request Body
- **parentId** (integer) - Required - The ID of the parent item.
- **peerId** (integer) - Optional - The ID of the peer item to position relative to.
- **position** (string) - Optional - The position relative to the peer (e.g., BEFORE, AFTER).

### Request Example
```json
{
  "parentId": 50,
  "peerId": 55,
  "position": "AFTER"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the location update.

#### Response Example
```json
{
  "message": "Item location updated successfully."
}
```
```

--------------------------------

### Common Response Codes

Source: https://dev.jamasoftware.com/api

This section details the common HTTP response codes used by the API, explaining their meaning and when they are typically returned.

```APIDOC
## Common Response Codes

### Description
This section details the common HTTP response codes used by the API, explaining their meaning and when they are typically returned.

### Response Codes

- **200 – OK**: The request was processed successfully. This code gets returned after GET requests or PUT requests (if the PUT resulted in data being generated and returned).
- **201 – Created**: The POST request was processed successfully.
- **204 – No Content**: The DELETE request was processed successfully.
- **400 – Bad Request**: The request could not be parsed or the parameters were not valid. The request should be modified before resubmitting.
- **401 – Unauthorized**: Username/password is invalid or the user does not have access to the requested object.
- **404 – Not Found**: Syntax is correct on the request, but does not exist at the location specified.
- **405 – Method Not Allowed**: There is an issue with the way the request was made.
- **429 – Too Many Requests**: Only returned for API throttling or system maintenance.
```

--------------------------------

### Create Test Plan API Request

Source: https://dev.jamasoftware.com/cookbook

This snippet demonstrates how to create a new Test Plan using a POST request to the /testplans endpoint. It requires the project ID and a name for the plan. The response includes metadata and the ID of the newly created Test Plan, which is necessary for subsequent operations.

```json
{
  "project": 43,
  "fields": {
    "name": "Connect Plan 1"
  }
}

```