Cases

Get case details

This endpoint retrieves the specific details of a single support case (ticket) identified by its unique Case ID (name).

Request specification

Method: GET URL: https://test.api.gtt.services/apis/v1alpha/namespaces/{namespace}/case/{case_name}

Path parameters

Parameter	Type	Required	Description
namespace	String	Yes	The unique identifier for the namespace (e.g., 7).
case_name	String	Yes	The unique system identifier for the specific case (e.g., CS0071740).

Headers

Header	Value	Required	Description
Authorization	Bearer <TOKEN>	Yes	A valid OAuth2 or API Bearer token for authentication.
Content-Type	application/json	No	Specifies the media type of the resource (standard for JSON APIs).

Response Specification

The API returns a single JSON object representing the requested case.

Content-Type: application/json

Schema definitions

Field	Type	Description
kind	String	The type of resource returned (e.g., "case").
version	String	The API version used (e.g., "v1alpha").
namespace	String	The ID of the namespace the case belongs to.
name	String	The unique system identifier for the case record.
metadata	Object	A key-value map for additional custom data.
spec	Object	The specification object containing detailed case information.
number	String	The human-readable case ticket number.
state	String	The current status of the case (e.g., "Open", "New").
account_name	String	The name of the customer account associated with the case.
category	String	The high-level category of the issue (e.g., "Secure Network").
subcategory	String	A specific classification of the issue (e.g., "Service Down").
client_ticket	String	An optional reference ID provided by the client (can be null).
created_on	String	Timestamp of creation (Format: YYYY-MM-DD HH:MM:SS).
updated_on	String	Timestamp of the last update.
short_description	String	A brief summary or subject line of the issue.
description	String	The full details of the issue.

Example Usage

Request

curl --location --request GET 'https://test.api.gtt.services/apis/v1alpha/namespaces/7/case/CS0071740' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>'

Response

{
    "kind": "case",
    "version": "v1alpha",
    "namespace": "7",
    "name": "CS0071728",
    "metadata": {},
    "spec": {
        "number": "CS0071728",
        "state": "Open",
        "account_name": "Sample Customer",
        "category": "Secure Network",
        "subcategory": "Service Down",
        "client_ticket": null,
        "created_on": "2026-01-08 00:48:11",
        "updated_on": "2026-01-13 14:47:08",
        "short_description": "GTT proactively detected a service failure",
        "description": "GTT proactively detected a service failure"
    }
}

List cases

This endpoint retrieves a list of support cases (tickets) associated with a specific namespace. It allows users to view the details, status, and metadata of ongoing or past support issues within the GTT system.

Request specification

Method: GET 

URL: https://test.api.gtt.services/apis/v1alpha/namespaces/{namespace}/case

Path parameters

Parameter	Type	Required	Description
namespace	String	Yes	The unique identifier for the namespace (e.g., 7 in the example).

Headers

Header	Value	Required	Description
Authorization	Bearer <TOKEN>	Yes	A valid OAuth2 or API Bearer token for authentication.

Response specification

The API returns a JSON array where each item represents a single support case.

Content-Type: application/json

Schema definitions

Field	Type	Description
kind	String	The type of resource returned (e.g., "case").
version	String	The API version used (e.g., "v1alpha").
namespace	String	The ID of the namespace the case belongs to.
name	String	A unique system identifier for the case record.
metadata	Object	A key-value map for additional custom data (returns {} if empty).
spec	Object	The specification object containing detailed case information.
number	String	The human-readable case ticket number (e.g., "CS0071728").
state	String	The current lifecycle status of the case (e.g., "New", "Closed", "In Progress").
account_name	String	The name of the customer account associated with the case.
category	String	The high-level category of the issue (e.g., "Secure Network").
subcategory	String	A specific classification of the issue (e.g., "Service Down").
customer_ticket_reference	String	An optional reference ID provided by the customer for their internal tracking (can be null).
created_on	String	Timestamp of when the case was created (Format: YYYY-MM-DD HH:MM:SS).
updated_on	String	Timestamp of the last update to the case.
description	String	A detailed description of the issue, often including error messages, Service IDs, or hostnames.

Example usage

Request

curl --location 'https://test.api.gtt.services/apis/v1alpha/namespaces/7/case' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Response

[
    {
        "kind": "case",
        "version": "v1alpha",
        "namespace": "7",
        "name": "CS0071728",
        "metadata": {},
        "spec": {
            "number": "CS0071728",
            "state": "New",
            "account_name": "Sample Customer",
            "category": "Secure Network",
            "subcategory": "Service Down",
            "customer_ticket_reference": null,
            "created_on": "2026-01-08 00:48:11",
            "updated_on": "2026-01-13 14:47:08",
            "description": "GTT proactively detected a service failure"
        }
    },
    {
        "kind": "case",
        "version": "v1alpha",
        "namespace": "7",
        "name": "CS0071726",
        "metadata": {},
        "spec": {
            "number": "CS0071726",
            "state": "New",
            "account_name": "Sample Customer",
            "category": "Secure Network",
            "subcategory": "Service Down",
            "customer_ticket_reference": null,
            "created_on": "2026-01-08 00:48:05",
            "updated_on": "2026-01-08 00:48:09",
            "description": "GTT proactively detected a service failure"
        }
    }
]

Update/Close case

This endpoint facilitates the update of an existing support Case. In this specific implementation, it is used to transition a case state to Closed by providing the required resolution metadata.

Request details

• Endpoint: https://test.api.gtt.services/apis/v1alpha/namespaces/{namespace}/case/{case_number}
• Method: PUT
• Auth Required: Yes (Bearer <TOKEN>)
• Content-Type: application/json

URL parameters

Parameter	Type	Description
namespace	String	The unique identifier for the environment (e.g., 7).
case_number	String	The human-readable ID of the case to update (e.g., CS0074187).

Request body schema

The PUT request requires the full resource representation. When closing a case, specific resolution fields in the spec object become mandatory.

Field	Type	Required	Description
kind	String	Yes	Must be case.
spec.state	String	Yes	The target state (e.g., close).
spec.resolution_code	String	Conditionally*	Required when closing (e.g., Cause Undetermined).
spec.responsible_party	String	Conditionally*	Required when closing (e.g., Unknown).
spec.comment	String	No	Notes regarding the update or resolution.
spec.updated_on	String	Yes	The timestamp of the last known update to prevent mid-air collisions.

Key workflow: Closing a case

To successfully move a case to a Closed state, the payload must include the resolution context. Unlike a simple PATCH request, this PUT request expects the existing descriptive fields (short description, category, etc.) to be re-submitted alongside the new state.

Response highlights (200 OK)

A successful update returns the updated object. Note the system’s normalization of data:

• State Normalization: Even if “close” (lowercase) is sent, the system returns the formal state “Closed“.
• Audit Timestamps: The updated_on field will reflect the current system time of the modification ( in the sample).

Common error scenarios

• 404 Not Found: The case_number does not exist within the specified namespace.
• 409 Conflict: Occurs if the updated_on timestamp in your request is older than the one currently stored in the database (indicating another user updated the ticket first).
• 422 Unprocessable Entity: Required resolution fields are missing while attempting to set the state to close.

Add note to case

This endpoint allows users to append a comment or work note to an existing Case. It is primarily used for communication between the requester and the support team without modifying the core attributes of the case (like priority or category).

Request details

• Endpoint: https://test.api.gtt.services/apis/v1alpha/namespaces/{namespace}/case/{case_number}/note
• Method: POST
• Auth Required: Yes (Bearer <TOKEN>)
• Content-Type: application/json

URL parameters

Parameter	Type	Description
namespace	String	The unique identifier for the environment (e.g., 7).
case_number	String	The human-readable ID of the target case (e.g., CS0074187).

Request body schema

The payload follows the standard resource structure but focuses on the comment field within the spec object.

Field	Type	Required	Description
kind	String	Yes	Must be set to note.
version	String	Yes	The API version (e.g., v1alpha).
namespace	String	Yes	Must match the namespace in the URL.
name	String	Yes	Must match the case_number in the URL.
spec.comment	String	Yes	The text content to be added to the case history.

Data relationship

Adding a note creates a child record associated with the parent Case. This allows for a chronological audit trail of all interactions.

Success response (200 OK / 201 Created)

The response confirms the action and provides the current state of the parent case.

Key Output Fields:

• spec.action: Confirms the operation performed (e.g., add_comment).
• spec.state: Displays the current state of the case (Note: Comments can often be added even if the state is Closed).
• spec.message: A short status message (e.g., Case updated).

Important notes

• Immutability: Once a note is posted via this endpoint, it typically cannot be edited or deleted through the API to maintain a reliable audit log.
• Notifications: Depending on the system configuration, adding a note may trigger automated email notifications to the contact_email associated with the case.

List case notes

This endpoint retrieves a chronological list of all notes, comments, and work logs associated with a specific Case. It is essential for synchronizing conversation histories between GTT and external ticketing systems.

Request details

• Endpoint: https://test.api.gtt.services/apis/v1alpha/namespaces/{namespace}/case/{case_number}/note
• Method: GET
• Auth Required: Yes (Bearer <TOKEN>)
• Content-Type: application/json

URL parameters

Parameter	Type	Description
namespace	String	The unique identifier for the environment (e.g., 7).
case_number	String	The human-readable ID of the parent case (e.g., CS0074187).

Response schema

The response returns a JSON Array of note objects. Each object represents a single entry in the case’s activity log.

Field	Type	Description
kind	String	Identifies the resource type (always note).
name	String	The unique system identifier (sys_id) for this specific note entry.
spec.author	String	The username or system account that created the note.
spec.field	String	The internal field type (e.g., comments for public notes).
spec.note	String	The actual text content of the message.
spec.created_on	String	Timestamp of when the note was posted ().

Understanding the data structure

Notes are returned as discrete resources linked to a parent case. This structure supports a “thread” view where multiple updates can be tracked over the lifecycle of an incident.

Implementation details

• Sorting: By default, notes are usually returned in chronological order (oldest to newest), though it is recommended to sort by the created_on timestamp in your application logic to ensure accuracy.
• Permissions: Access to notes is governed by the same permissions as the parent case. If you can view the case, you can generally view its notes.
• Empty States: If a case exists but has no notes, the API will return an empty array [] with a 200 OK status.

Common use cases

• Audit Logs: Reviewing the timeline of an incident resolution.
• System Integration: Pulling updates from GTT into a local ITSM tool (like ServiceNow or Jira) to keep local users informed.
• Verification: Confirming that a POST request to create a note was successfully committed to the database.

curl --location 'https://test.api.gtt.services/apis/v1alpha/namespaces/7/case/CS0074930/attachment' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--form 'files=@"/path/to/your/file.png"'

{
    "kind": "attachment",
    "version": "v1alpha",
    "namespace": "7",
    "name": "beec57eafffa72104fb6fb91e34fd935",
    "spec": {
        "file_name": "Screenshot.png",
        "size_bytes": "218445",
        "download_link": "https://gttdev.service-now.com/api/now/attachment/beec57.../file",
        "content_type": "image/png",
        "state": "available"
    }
}

List case attachments

This endpoint retrieves a collection of all attachments associated with a specific case record. It provides detailed metadata for each file, including the file size, type, and a direct link for download.

Request information

• HTTP Method: GET
• URL: https://test.api.gtt.services/apis/v1alpha/namespaces/{namespace}/case/{case_id}/attachment
• Authentication: Bearer Token

Path parameters

Parameter	Type	Description
namespace	String	The environment or tenant identifier (e.g., 7).
case_id	String	The unique identifier of the case (e.g., CS0074930).

Headers

Header	Value	Description
Authorization	Bearer <TOKEN>	Required. Your valid access token.

Data model and relationships

The attachment system acts as a bridge between the Case Management layer and the Binary Storage layer. When you query this endpoint, the API resolves the relationships as shown below:

Response fields

The response returns an Array of attachment objects.

Root object

Field	Type	Description
kind	String	Resource type (e.g., attachment).
version	String	API version used for the response.
name	String	The unique system name for the file entry.
spec	Object	The container for specific file metadata.

Spec object details

Field	Type	Description
sys_id	String	The unique internal ID of the attachment record.
file_name	String	The original name of the file (e.g., Screenshot.png).
content_type	String	The MIME type of the file.
size_bytes	String	The total file size in bytes.
download_url	String	The authenticated URL used to download the file content.

Example usage

cURL request

curl --location 'https://test.api.gtt.services/apis/v1alpha/namespaces/7/case/CS0074930/attachment' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

JSON response

[
    {
        "kind": "attachment",
        "version": "v1alpha",
        "namespace": "7",
        "name": "beec57eafffa72104fb6fb91e34fd935",
        "spec": {
            "file_name": "Screenshot 2026-02-04 at 10.03.07 AM.png",
            "content_type": "image/png",
            "size_bytes": "218445",
            "download_url": "https://gttdev.service-now.com/api/now/attachment/beec57eafffa72104fb6fb91e34fd935/file"
        }
    }
]

[
    {
        "kind": "casecategory",
        "version": "v1alpha",
        "name": "410",
        "spec": {
            "serviceType": "410",
            "categories": [
                {
                    "caseType": "Incident",
                    "name": "Cloud Solutions",
                    "subcategories": [
                        { "name": "Application - Slow Response" },
                        { "name": "Database Major Issue" }
                    ]
                }
            ]
        }
    }
]

Case category detail

This endpoint retrieves the specific classification schema for a single Case Category. It is primarily used to fetch the hierarchical relationship between a Service Type, its parent Categories, and granular Subcategories—essential for building dynamic incident forms or automated routing logic.

Request overview

Method	Endpoint Path
GET	/apis/v1alpha/namespaces/gtt/casecategory/{name}

Path parameters

• name (string): The unique identifier for the category resource (e.g., 410). This typically corresponds to a specific service ID.

Headers

• Authorization: Bearer <TOKEN> (Required)

Response schema

The response returns a single JSON object. The data is organized into a standard Kubernetes-style resource format (kind, version, metadata, spec).

Resource identifiers

• kind: Resource type (casecategory).
• version: API version (v1alpha).
• namespace: The logical grouping (gtt).
• name: The resource name.

Metadata object

Contains system-generated timestamps.

• dateCreated: Unix timestamp (ms) of resource creation.
• dateUpdated: Unix timestamp (ms) of the last modification.

Spec object (the core data)

The spec object defines the ticketing hierarchy:

• serviceType: The ID of the service this category set applies to.
• categories: An array of objects defining high-level ticket types.
• caseType: The classification of the work (e.g., Incident).
• name: The functional category (e.g., Cloud Solutions).
• subcategories: An array of specific issues used for detailed reporting and triage.

Data example: Cloud solutions (ID 410)

For the resource 410, the classification follows this logic:

Level	Value
Service ID	410
Category	Cloud Solutions
Incident Type	Incident
Subcategories	Connectivity, Host Down, Storage, Database Critical Issue, etc.

Usage implementation

When implementing this API in a frontend application, the response should be used to drive a nested selection UI.

1. Level 1: Identify the serviceType from the user’s context.
2. Level 2: Map spec.categories[].name to a “Category” dropdown.
3. Level 3: Once a category is selected, populate a “Subcategory” dropdown using spec.categories[].subcategories[].name.