Comments¶

Comments are messages attached to tickets. They can be public (visible to customers) or internal notes (visible only to agents).

Endpoints¶

Method	Endpoint	Description	Scope Required
GET	`/v1/tickets/{ticket_id}/comments`	List comments	`comments:read`
GET	`/v1/tickets/{ticket_id}/comments/{id}`	Get comment	`comments:read`
POST	`/v1/tickets/{ticket_id}/comments`	Create comment	`comments:write`
PATCH	`/v1/tickets/{ticket_id}/comments/{id}`	Update comment	`comments:write`
DELETE	`/v1/tickets/{ticket_id}/comments/{id}`	Delete comment	`comments:delete`

The Comment Object¶

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "ticket_id": "550e8400-e29b-41d4-a716-446655440000",
  "author_type": "AGENT",
  "author_user_id": "789e0123-f45b-67c8-d901-234567890abc",
  "author_customer_id": null,
  "content": "Thank you for contacting support. I'm looking into this issue.",
  "is_internal": false,
  "created_at": "2025-01-16T11:30:00Z",
  "updated_at": "2025-01-16T11:30:00Z"
}

Attributes¶

Field	Type	Description
`id`	UUID	Unique comment identifier
`ticket_id`	UUID	ID of the parent ticket
`author_type`	enum	`AGENT`, `CUSTOMER`, or `SYSTEM`
`author_user_id`	UUID	ID of agent author (nullable)
`author_customer_id`	UUID	ID of customer author (nullable)
`content`	string	Comment text content
`is_internal`	boolean	If true, not visible to customer
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last modification timestamp

List Comments¶

Retrieve all comments for a ticket.

GET /v1/tickets/{ticket_id}/comments

Path Parameters¶

Parameter	Type	Description
`ticket_id`	UUID	The ticket ID

Examples¶

cURLPython

curl -X GET "https://api.toptickets.app/v1/tickets/550e8400-e29b-41d4-a716-446655440000/comments" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

TICKET_ID = "550e8400-e29b-41d4-a716-446655440000"

response = requests.get(
    f"https://api.toptickets.app/v1/tickets/{TICKET_ID}/comments",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

Response¶

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "ticket_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2025-01-16T11:30:00Z",
    "updated_at": "2025-01-16T11:30:00Z"
  }
]

Get Comment¶

Retrieve a single comment.

GET /v1/tickets/{ticket_id}/comments/{comment_id}

Path Parameters¶

Parameter	Type	Description
`ticket_id`	UUID	The ticket ID
`comment_id`	UUID	The comment ID

Examples¶

cURLPython

curl -X GET "https://api.toptickets.app/v1/tickets/550e8400-e29b-41d4-a716-446655440000/comments/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

TICKET_ID = "550e8400-e29b-41d4-a716-446655440000"
COMMENT_ID = "123e4567-e89b-12d3-a456-426614174000"

response = requests.get(
    f"https://api.toptickets.app/v1/tickets/{TICKET_ID}/comments/{COMMENT_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

Response¶

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "ticket_id": "550e8400-e29b-41d4-a716-446655440000",
  "author_type": "AGENT",
  "author_user_id": "789e0123-f45b-67c8-d901-234567890abc",
  "author_customer_id": null,
  "content": "Thank you for contacting support. I'm looking into this issue.",
  "is_internal": false,
  "created_at": "2025-01-16T11:30:00Z",
  "updated_at": "2025-01-16T11:30:00Z"
}

Create Comment¶

Add a new comment to a ticket.

POST /v1/tickets/{ticket_id}/comments

Path Parameters¶

Parameter	Type	Description
`ticket_id`	UUID	The ticket ID

Request Body¶

Field	Type	Required	Description
`content`	string	Yes	Comment text
`is_internal`	boolean	No	Internal note (default: false)

Examples¶

cURLPython

# Public comment (visible to customer)
curl -X POST "https://api.toptickets.app/v1/tickets/550e8400-e29b-41d4-a716-446655440000/comments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Thank you for contacting support. I am looking into this issue.",
    "is_internal": false
  }'

# Internal note (agents only)
curl -X POST "https://api.toptickets.app/v1/tickets/550e8400-e29b-41d4-a716-446655440000/comments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Customer called earlier, seems frustrated. Handle with care.",
    "is_internal": true
  }'

import requests

TICKET_ID = "550e8400-e29b-41d4-a716-446655440000"

# Public comment
response = requests.post(
    f"https://api.toptickets.app/v1/tickets/{TICKET_ID}/comments",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "content": "Thank you for contacting support. I am looking into this issue.",
        "is_internal": False
    }
)

# Internal note
response = requests.post(
    f"https://api.toptickets.app/v1/tickets/{TICKET_ID}/comments",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "content": "Customer called earlier, seems frustrated. Handle with care.",
        "is_internal": True
    }
)

Response (201 Created)¶

{
  "id": "234f5678-e90c-12d3-b456-526714174111",
  "ticket_id": "550e8400-e29b-41d4-a716-446655440000",
  "author_type": "AGENT",
  "author_user_id": "789e0123-f45b-67c8-d901-234567890abc",
  "author_customer_id": null,
  "content": "Thank you for contacting support. I am looking into this issue.",
  "is_internal": false,
  "created_at": "2025-01-16T14:00:00Z",
  "updated_at": "2025-01-16T14:00:00Z"
}

Update Comment¶

Update an existing comment.

PATCH /v1/tickets/{ticket_id}/comments/{comment_id}

Path Parameters¶

Parameter	Type	Description
`ticket_id`	UUID	The ticket ID
`comment_id`	UUID	The comment ID

Request Body¶

Field	Type	Description
`content`	string	Updated comment text
`is_internal`	boolean	Updated internal status

Examples¶

cURLPython

curl -X PATCH "https://api.toptickets.app/v1/tickets/550e8400-e29b-41d4-a716-446655440000/comments/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated comment content with more details."
  }'

import requests

TICKET_ID = "550e8400-e29b-41d4-a716-446655440000"
COMMENT_ID = "123e4567-e89b-12d3-a456-426614174000"

response = requests.patch(
    f"https://api.toptickets.app/v1/tickets/{TICKET_ID}/comments/{COMMENT_ID}",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "content": "Updated comment content with more details."
    }
)

Response¶

Returns the updated comment object.

Delete Comment¶

Delete a comment.

DELETE /v1/tickets/{ticket_id}/comments/{comment_id}

Path Parameters¶

Parameter	Type	Description
`ticket_id`	UUID	The ticket ID
`comment_id`	UUID	The comment ID

Examples¶

cURLPython

curl -X DELETE "https://api.toptickets.app/v1/tickets/550e8400-e29b-41d4-a716-446655440000/comments/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

TICKET_ID = "550e8400-e29b-41d4-a716-446655440000"
COMMENT_ID = "123e4567-e89b-12d3-a456-426614174000"

response = requests.delete(
    f"https://api.toptickets.app/v1/tickets/{TICKET_ID}/comments/{COMMENT_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if response.status_code == 204:
    print("Comment deleted")

Response¶

Returns 204 No Content on success.

Author Types¶

Comments can have different author types:

Type	Description
`AGENT`	Comment from a support agent
`CUSTOMER`	Comment from the customer
`SYSTEM`	System-generated message

The author_user_id is populated for AGENT and SYSTEM comments, while author_customer_id is populated for CUSTOMER comments.