Cases

Path parameters

Headers

Response Specification

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

Schema definitions

Example 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>'

Example 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"
    }
}

Path parameters

Headers

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

Response specification

Example request

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

Example 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"
        }
    }
]

Path parameters

Headers

Request body

Response highlights (200 OK)

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

• 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.

Path parameters

Headers

Request body

This transaction will indicate in the GTT system, that you would like to close a case.

Response highlights (200 OK)

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

• 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.

Path parameters

Headers

Request body schema

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

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.

Path parameters

Headers

Response schema

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

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.

Path parameters

Body parameters (Form-Data)

Headers

Response schema

The response returns a JSON object representing the metadata of the successfully uploaded attachment.

Example implementation

cURL request

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"'

Successful response (201 created)

{
    "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"
    }
}

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.

Path parameters

Headers

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.

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"
        }
    }
]