### Query Available API Versions (GET)

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

This snippet shows how to query the available API versions for a Jama instance. It involves making a GET request to the base /rest endpoint of the Jama application. The response will indicate which API versions are supported.

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

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

### Make Authenticated REST API Request (curl)

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

This snippet shows how to make a GET request to a Jama Software REST API endpoint using an access token obtained in the previous step. The Authorization header is set to 'Bearer <access_token>'. The example requests the /users/current endpoint.

```curl
$ 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"
}
}
```

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

### Picklist Option Management

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

Endpoints for managing info tips for field labels in picklists.

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

### Description
Retrieve information about a specific picklist option, including its info tip.

### Method
GET

### Endpoint
/picklistoptions/{picklistOptionId}

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

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

#### Response Example
```json
{
  "id": 10,
  "name": "High",
  "infoTip": "This is a high priority item."
}
```
```

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

### Description
Update the info tip for a field label in 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 field label.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the info tip was updated.

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

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

### Picklist Management

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

Endpoints for managing picklists and their options.

```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.
- **infoTip** (string) - Optional - The info tip for the new picklist option.

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

#### Response Example
```json
{
  "id": 15,
  "name": "Medium",
  "infoTip": "This is a medium priority item."
}
```
```

```APIDOC
## GET /picklist

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

### Method
GET

### Endpoint
/picklist

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

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

```APIDOC
## POST /picklist

### Description
Create a new picklist, specifying its type as STANDARD or LOOKUP_MATRIX.

### Method
POST

### Endpoint
/picklist

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new picklist.
- **type** (string) - Required - The type of the new picklist (e.g., "STANDARD", "LOOKUP_MATRIX").

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

#### Response Example
```json
{
  "id": 3,
  "name": "Severity",
  "type": "STANDARD"
}
```
```

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

### Item Type Management

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

Endpoints for managing info tips for item types and their fields.

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

### Description
Retrieve information about a specific item type, including info tips for its fields.

### Method
GET

### Endpoint
/itemtypes/{itemTypeId}

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

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

#### Response Example
```json
{
  "id": 5,
  "name": "User Story",
  "fields": [
    {
      "id": 101,
      "name": "Title",
      "infoTip": "The main title of the user story."
    }
  ]
}
```
```

```APIDOC
## 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 for the field.

### Response
#### Success Response (201)
- **message** (string) - A confirmation message indicating the info tip was created.

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

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

### POST for Baselines in Labs

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

Introduces the capability to create baselines within Labs using a POST request.

```APIDOC
## POST /api/labs/baselines

### Description
Creates a new baseline within the Labs feature. This endpoint allows for the programmatic creation of baselines, which can be useful for version control and tracking of lab configurations.

### Method
POST

### Endpoint
/api/labs/baselines

### Parameters
#### Request Body
- **baselineData** (object) - Required - The data required to create the baseline.
  - **name** (string) - Required - The name of the baseline.
  - **description** (string) - Optional - A description for the baseline.
  - **configuration** (object) - Required - The configuration details for the baseline.
    - **key** (string) - Required - The configuration key.
    - **value** (string) - Required - The configuration value.

### Request Example
```json
{
  "baselineData": {
    "name": "Initial Lab Setup",
    "description": "Baseline for the initial setup of the development environment.",
    "configuration": {
      "key": "environment_type",
      "value": "development"
    }
  }
}
```

### Response
#### Success Response (201)
- **baselineId** (integer) - The ID of the newly created baseline.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "baselineId": 12345,
  "message": "Baseline created successfully."
}
```
```

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

### Project Permission Management

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

Endpoints for managing project permissions for users and user groups.

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

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

### Method
GET

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

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

#### Query Parameters
- **userOrGroup** (string) - Required - The name or ID of the user or user group.

### Response
#### Success Response (200)
- **permissions** (array) - A list of permission entries.
  - **userOrGroup** (string) - The name or ID of the user or user group.
  - **permissionType** (string) - The type of permission granted.

#### Response Example
```json
{
  "permissions": [
    {
      "userOrGroup": "admin_user",
      "permissionType": "Administrator"
    }
  ]
}
```
```

```APIDOC
## 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
- **userOrGroup** (string) - Required - The name or ID of the user or user group.
- **permissionType** (string) - Required - The type of permission to grant.

### Response
#### Success Response (201)
- **message** (string) - A confirmation message indicating the permission was created or overridden.

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

```APIDOC
## 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
- **userOrGroup** (string) - Required - The name or ID of the user or user group.
- **permissionType** (string) - Required - The new type of permission to set.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the permission was updated.

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

```APIDOC
## 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
- **userOrGroup** (string) - Required - The name or ID of the user or user group whose permission should be removed.

### Response
#### Success Response (204)
No content is returned on successful deletion.

#### Response Example
(No content)
```

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

### API Versioning

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

Information on how the Jama Software REST API is versioned and how to access different versions.

```APIDOC
## API Versioning

### Description
Jama Software's REST API is versioned separately from product releases to ensure backward compatibility and manage updates.

### Supported Versions
- **v0**: Pre-beta version (may be in use by older Self Hosted clients).
- **v1**: Current supported version of the REST API.
- **latest**: Designated for Sunset (refer to Sunset details).
- **labs**: Introduces new endpoints for feedback; not officially supported and may change.

### Accessing API Documentation
To access documentation for different versions, update the swagger URL.

### Querying Available API Versions
To determine which API versions are available for your instance, issue a request to the base REST endpoint.

#### Method
GET

#### Endpoint
`/rest`

#### Example Request
```bash
https://your-instance.jamacloud.com/rest
```

### Specifying Version in Requests
It is recommended to state the REST version in all requests. For example, to use version 1:

#### Endpoint Example
`/rest/v1/your-endpoint`
```

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

### Baseline Management

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

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

```APIDOC
## POST /baselines

### Description
Create a new baseline. In Jama Connect 8.86 and later, this allows creation without a source.

### Method
POST

### Endpoint
/baselines

### Parameters
#### Request Body
- **name** (string) - Required - The name of the baseline.
- **description** (string) - Optional - A description for the baseline.
- **sourceItemId** (integer) - Optional - The ID of the item to use as a source for the baseline (required in versions prior to 8.86 if not creating from scratch).

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

#### Response Example
```json
{
  "id": 100,
  "name": "Baseline v1.0"
}
```
```

```APIDOC
## GET /baselines

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

### Method
GET

### Endpoint
/baselines

### Response
#### Success Response (200)
- **baselines** (array) - A list of baseline objects.
  - **id** (integer) - The baseline ID.
  - **name** (string) - The baseline name.
  - **baselineOption** (string) - The baseline pick list option (available from 8.75 onwards).

#### Response Example
```json
{
  "baselines": [
    {
      "id": 100,
      "name": "Baseline v1.0",
      "baselineOption": "Option A"
    }
  ]
}
```
```

```APIDOC
## GET /baselines/{baselineId}

### Description
Retrieve details of a specific baseline. In Jama Connect 8.75 and later, this endpoint also 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 baseline ID.
- **name** (string) - The baseline name.
- **baselineOption** (string) - The baseline pick list option (available from 8.75 onwards).

#### Response Example
```json
{
  "id": 100,
  "name": "Baseline v1.0",
  "baselineOption": "Option A"
}
```
```

```APIDOC
## PUT /baselines/{baselineId}

### Description
Update the baseline pick list option for a specific baseline.

### Method
PUT

### Endpoint
/baselines/{baselineId}

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

#### Request Body
- **baselineOption** (string) - Required - The new baseline pick list option.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the update was successful.

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

```APIDOC
## GET /baselines/{baselineId}/versioneditems

### Description
Retrieve items within a baseline, including 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 items within the baseline.
  - **itemId** (integer) - The ID of the item.
  - **appliedCategory** (object) - Information about the category applied at baseline time.
    - **id** (integer) - The category ID.
    - **name** (string) - The category name.

#### Response Example
```json
{
  "versionedItems": [
    {
      "itemId": 123,
      "appliedCategory": {
        "id": 1,
        "name": "Requirement"
      }
    }
  ]
}
```
```

```APIDOC
## GET /baselines/{baselineId}/reviewlink

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

### Method
GET

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

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

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

#### Response Example
```json
{
  "reviewId": "rev-abc123xyz"
}
```
```

```APIDOC
## 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 folder ID.
  - **name** (string) - The folder name.

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

```APIDOC
## 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.

### 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": "Project Beta Baselines"
}
```
```

```APIDOC
## 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 folder to move the baseline source to.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the move was successful.

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

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

### User and User Group Permissions

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

Updates to permissions for retrieving users and user groups. Access now requires specific admin roles or project association.

```APIDOC
## GET /api/users and GET /api/usergroups

### Description
Retrieves a list of users or user groups. Access to these endpoints now requires organization or user admin roles. Project admins can use these endpoints but must provide a project ID where they are administrators.

### Method
GET

### Endpoint
/api/users
/api/usergroups

### Parameters
#### Query Parameters
- **projectId** (integer) - Optional - The ID of the project to filter users/user groups by. Required for project admins.

### Response
#### Success Response (200)
- **users** (array) - A list of user objects.
- **userGroups** (array) - A list of user group objects.

#### Response Example (Users)
```json
{
  "users": [
    {
      "id": 1,
      "username": "johndoe",
      "firstName": "John",
      "lastName": "Doe"
    }
  ]
}
```

#### Response Example (User Groups)
```json
{
  "userGroups": [
    {
      "id": 10,
      "name": "Developers"
    }
  ]
}
```
```

```APIDOC
## GET /api/users/{userId} and GET /api/usergroups/{id}

### Description
Retrieves details for a specific user or user group. A permissions check is performed to ensure the requesting user has access to the same project as the requested user or user group.

### Method
GET

### Endpoint
/api/users/{userId}
/api/usergroups/{id}

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

### Response
#### Success Response (200)
- **user** (object) - Details of the requested user.
- **userGroup** (object) - Details of the requested user group.

#### Response Example (User)
```json
{
  "user": {
    "id": 1,
    "username": "johndoe",
    "firstName": "John",
    "lastName": "Doe",
    "projectId": 5
  }
}
```

#### Response Example (User Group)
```json
{
  "userGroup": {
    "id": 10,
    "name": "Developers",
    "projectId": 5
  }
}
```
```

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

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

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

Introduces a new API header to enable full ISO-8601 formatting for dates within the fields section of requests.

```APIDOC
## Request Header: x-jama-date-fields-with-time

### Description
This header, when set to `true`, enables the API to accept and process date fields using the full ISO-8601 format (e.g., `YYYY-MM-DDTHH:mm:ss.sssZ`). This provides more precise date and time handling in API requests.

### Usage
Include the following header in your API requests:

`x-jama-date-fields-with-time: true`

### Example
When this header is present, you can send date values like this in your request body:

```json
{
  "startDate": "2023-10-27T10:00:00.000Z",
  "completionDate": "2023-10-27T15:30:00.000Z"
}
```

If the header is not present or set to `false`, date fields may be expected in a different format (e.g., `YYYY-MM-DD`).
```

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

### Common Response Codes

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

This section details the common HTTP response codes used by the Jamasoftware API, explaining the meaning of each code and when it is typically returned.

```APIDOC
## Common Response Codes

### Description
Provides a reference for standard HTTP response codes returned by the API, indicating the outcome of a request.

### Response Codes

- **200 – OK**: The request was processed successfully. Returned after successful GET requests or PUT requests that generate and return data.
- **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 contained invalid parameters. The request should be modified before resubmitting.
- **401 – Unauthorized**: The provided username/password is invalid, or the user lacks access to the requested object.
- **404 – Not Found**: The syntax of the request is correct, but the requested resource does not exist.
- **405 – Method Not Allowed**: There is an issue with the HTTP method used for the request.
- **429 – Too Many Requests**: Indicates API throttling or system maintenance.
```

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

### Make REST API Request with Access Token

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

This section describes how to make authenticated requests to the Jama Software REST API using an access token obtained from the previous step.

```APIDOC
## Authenticated REST API Requests

### Description
Make requests to the Jama Software REST API using an access token for authentication.

### Method
[HTTP Method: GET, POST, PUT, DELETE, etc.]

### Endpoint
[Full endpoint path, e.g., `/rest/v1/users/current`]

### Parameters
#### Query Parameters
[List any relevant query parameters for the specific endpoint]

#### Request Body
[Describe the request body if applicable for the specific endpoint]

### Authentication
- **Header Name**: `Authorization`
- **Header Value**: `Bearer <access_token>`
  (Replace `<access_token>` with the token obtained from the `/rest/oauth/token` endpoint.)

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

### Response
#### Success Response (200)
[Describe the structure of a successful response for the specific endpoint. The example below is for `/users/current`.]
- **meta** (object) - Metadata about the response.
- **links** (object) - Links to related resources.
- **data** (object) - The requested data.

#### Response Example (for `/users/current`)
```json
{
  "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"
  }
}
```
```

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

### Category Management

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

Endpoints for managing categories, including retrieving, creating, and updating their 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 categories by name.
- **projectId** (integer) - Optional - Filter categories by project ID.

### Response
#### Success Response (200)
- **categories** (array) - A list of category objects.
  - **id** (integer) - The category ID.
  - **name** (string) - The category name.
  - **projectId** (integer) - The project ID.
  - **visibility** (string) - The category visibility setting.

#### Response Example
```json
{
  "categories": [
    {
      "id": 1,
      "name": "General",
      "projectId": 101,
      "visibility": "public"
    }
  ]
}
```
```

```APIDOC
## POST /categories

### Description
Create a new CategoryPath.

### Method
POST

### Endpoint
/categories

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

### Response
#### Success Response (201)
- **id** (integer) - The ID of the newly created category.
- **name** (string) - The name of the new category.
- **projectId** (integer) - The project ID.
- **visibility** (string) - The category visibility setting.

#### Response Example
```json
{
  "id": 2,
  "name": "New Feature",
  "projectId": 101,
  "visibility": "private"
}
```
```

```APIDOC
## 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
- **visibility** (string) - Required - The new visibility setting for the category (e.g., "public", "private").

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the visibility was updated.

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

```APIDOC
## 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 is returned on successful deletion.

#### Response Example
(No content)
```

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

### Exchange Client Credentials for Access Token

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

This endpoint allows you to exchange client credentials (client ID and client secret) for an access token, which is required for subsequent API requests.

```APIDOC
## POST /rest/oauth/token

### Description
Exchanges client credentials (client ID and client secret) for an access token.

### Method
POST

### Endpoint
`/rest/oauth/token`

### Parameters
#### Query Parameters
- **grant_type** (string) - Required - Must be `client_credentials`.

#### Request Body
This endpoint does not use a request body. Authentication is handled via HTTP Basic Authentication or an `Authorization` header.

### Authentication
**HTTP Basic Authentication:**
- Username: Client ID
- Password: Client Secret

**Alternatively, using `Authorization` header:**
- Name: `Authorization`
- Value: `Basic <base64_encoded_client_id:client_secret>`

### Request Example
```bash
curl --request POST https://your-instance.jamacloud.com/rest/oauth/token \
     --header "Authorization: Basic <base64_encoded_client_id:client_secret>" \
     --data "grant_type=client_credentials"
```

### Response
#### Success Response (200)
- **access_token** (string) - The obtained access token.
- **token_type** (string) - The type of token (e.g., "bearer").
- **expires_in** (integer) - The time in seconds until the token expires.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NDQ5MjI4OTcsInNjb3BlIjpbInJlYWQiXSwianRpIjoiNTQ3N2...",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "token_information",
  "application_data": {
    "JAMA_CORE": "sample"
  },
  "tenant": "default",
  "jti": "d480b154-4e5e-446b-beec-2f1b7cdc0e35"
}
```
```

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

### Exchange Client Credentials for Access Token (curl)

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

This snippet demonstrates how to exchange client ID and client secret for an access token using HTTP Basic Authentication. The request is a POST to the /rest/oauth/token endpoint with grant_type=client_credentials. The response contains the access_token, token_type, and expires_in.

```curl
$ curl --request POST http://test123:EC231BA29695BF2CBAB6@basepath/rest/oauth/token \
	--data grant_type=client_credentials \
{
"access_token":"eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NDQ5MjI4OTcsInNjb3BlIjpbInJlYWQiXSwianRpIjoiNTQ3N2... (et cetera)",
"token_type":"bearer",
"expires_in":3599,
"scope":"token_information",
"application_data":{
"JAMA_CORE":"sample"
},
"tenant":"default",
"jti":"d480b154-4e5e-446b-beec-2f1b7cdc0e35"
}
```

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

### Item Category Management

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

Endpoints for managing categories associated with items.

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

### Description
Retrieve all categories applied to 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 applied to the item.
  - **id** (integer) - The category ID.
  - **name** (string) - The category name.

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

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

### Description
Apply a category to a specific 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.

### Response
#### Success Response (201)
- **message** (string) - A confirmation message indicating the category was applied.

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

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

### Report Management

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

Endpoints for managing reports, including creation and metadata retrieval.

```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** (string) - Required - The ID of the report to create.

### Response
#### Success Response (202)
- **workId** (string) - The identifier for the asynchronous report generation task.

#### Response Example
```json
{
  "workId": "work-12345abcde"
}
```
```

```APIDOC
## 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.
  - **id** (string) - The report metadata ID.
  - **name** (string) - The name of the report.
  - **description** (string) - A description of the report.

#### Response Example
```json
{
  "metadata": [
    {
      "id": "report-type-1",
      "name": "Requirements Traceability Matrix",
      "description": "Shows the traceability of requirements."
    }
  ]
}
```
```

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

### Item Updates

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

Endpoints for updating items.

```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 to update.
  - **fields** (object) - Optional - An object containing fields to update.

### Response
#### Success Response (202)
- **workId** (string) - The identifier for the asynchronous update task.

#### Response Example
```json
{
  "workId": "work-abcdef12345"
}

```

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

### Update Custom Fields

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

Custom fields in test runs can now be updated via the API, mirroring the behavior of the execution UI. Only fields editable in the UI are updatable.

```APIDOC
## PUT /api/testruns/{testRunId}/customfields

### Description
Updates custom fields for a specific test run. This endpoint mirrors the UI behavior for updating custom fields, allowing only fields that are editable in the execution interface to be modified.

### Method
PUT

### Endpoint
/api/testruns/{testRunId}/customfields

### Parameters
#### Path Parameters
- **testRunId** (integer) - Required - The ID of the test run whose custom fields are to be updated.

#### Request Body
- **customFields** (object) - Required - A key-value map where keys are the names of the custom fields and values are their new values.
  - **fieldName** (string) - Required - The name of the custom field.
  - **fieldValue** (any) - Required - The new value for the custom field.

### Request Example
```json
{
  "customFields": [
    {
      "fieldName": "Environment",
      "fieldValue": "Production"
    },
    {
      "fieldName": "Build Number",
      "fieldValue": "1.2.3"
    }
  ]
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the custom fields were updated.

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

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

### /latest API Endpoint Sunset

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

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

```APIDOC
## /latest API Endpoint Sunset

### Description
Details the sunsetting of the '/latest' API endpoint, including key dates and a reference to community posts for more information.

### Endpoint
`/latest`

### Sunset Information
- **Announcement Date**: 2019-11-22
- **End-of-Life (EOL) Date**: 2020-05-22
- **Details**: See community post for more details.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.