Skip to content

Tickets v3

Dated reminders, usually for a product: a contract ends on a given day, so the product has to be taken down then. The ticket types are defined by the client.

For admins of the realm (account management) and apps acting for a realm. Also available on v4 (UUIDs as _id).

Comments are a sub-resource: /resource/v3/tickets/{id}/comments.


Endpoints


GET /resource/v3/tickets

Search tickets

Description

Returns the realm's tickets, paginated. Without sort, the next due ticket comes first and tickets without a due date come last. See Resource Queries for the filter, operator and pagination syntax.

Typical queries:

  • open reminders due up to today: ?done=false&due_date__lte=2026-11-18
  • the tickets of a product: ?product_id=1387
  • my open tickets: ?assigned_business_partner_id=128&done=false

Input parameters

Query parameters

Parameter Type Default Nullable Description
assigned_business_partner_id string No

Assigned business partner, by id or UUID. Also __isnull / __isnotnull.

created_business_partner_id string No

Business partner who created the ticket, by id or UUID. Also __isnull / __isnotnull.

done boolean No
due_date string No

Due date (YYYY-MM-DD), with the operators __lt, __lte, __gt, __gte, __range (2027-01-01,2027-03-31), __isnull and __isnotnull, e.g. due_date__gt=2027-02-08.

page integer No

Page number, starting at 1.

page_size integer No

Entries per page; defaults to 100.

product_id string No

Product id or UUID. An id that matches no product finds nothing. Also product_id__isnull / __isnotnull.

q string No

#123 finds ticket 123. A product reference finds the tickets of that product: v123, document.123 or the product's ISBN/EAN. A bare number finds the ticket or the product with that id; any other text is searched in the description.

sort string No

id, created, due_date or product_id, with an optional __asc / __desc suffix, e.g. due_date__desc.

type string No

Exact type, e.g. CONTRACT_END.

Responses

{
    "_links": {},
    "_pagination": {},
    "items": [
        {
            "_id": 1234,
            "_uuid": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44",
            "_version": "3.0",
            "_links": {
                "self": "https://api.openpublishing.com/resource/v3/tickets/1234",
                "comments": "https://api.openpublishing.com/resource/v3/tickets/1234/comments"
            },
            "type": "CONTRACT_END",
            "product": null,
            "created_business_partner": null,
            "assigned_business_partner": null,
            "created": 1763290170,
            "due_date": "2027-02-24",
            "description": "The contract ends on 2027-02-24. Take the product down.\n[x] Author informed\n[ ] Product withdrawn",
            "done": false
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "_links": {
            "type": "object"
        },
        "_pagination": {
            "type": "object"
        },
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "additionalProperties": false,
                "description": "A dated reminder, usually for a product: \"the contract of this title ends on 2027-02-24, take it down then\".\n\nOn `POST` and `PUT` only `type`, `product`, `assigned_business_partner`, `due_date`, `description` and `done`\nare written. The read-only fields (`_id`, `_uuid`, `_version`, `_links`, `created`, `created_business_partner`)\nmay be sent back unchanged and are ignored; any other key is rejected with `400 Bad Request`.\n",
                "properties": {
                    "_id": {
                        "type": "integer",
                        "description": "Numeric identifier of the ticket.",
                        "example": 1234
                    },
                    "_uuid": {
                        "type": "string",
                        "description": "UUID of the ticket.",
                        "example": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
                    },
                    "_version": {
                        "type": "string",
                        "description": "API version.",
                        "example": "3.0"
                    },
                    "_links": {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                            "self": {
                                "type": "string",
                                "example": "https://api.openpublishing.com/resource/v3/tickets/1234"
                            },
                            "comments": {
                                "type": "string",
                                "example": "https://api.openpublishing.com/resource/v3/tickets/1234/comments"
                            }
                        }
                    },
                    "type": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Kind of reminder. Free text: the API stores and returns it as given (surrounding whitespace removed) and\nattaches no meaning to it; the client defines the vocabulary. Required on create.\n",
                        "example": "CONTRACT_END"
                    },
                    "product": {
                        "description": "The product the ticket is about, or `null`. Write it as `{\"_id\": 1387}`; the product must belong to the\ncaller's realm, otherwise `400 Bad Request`. Several tickets may point to the same product.\n",
                        "allOf": [
                            {
                                "type": "object",
                                "description": "Reference to product",
                                "additionalProperties": false,
                                "nullable": true,
                                "properties": {
                                    "_id": {
                                        "type": "integer",
                                        "description": "Product ID",
                                        "example": 23
                                    },
                                    "_uuid": {
                                        "type": "string",
                                        "description": "ID of resource in V4 version of resource"
                                    },
                                    "_links": {
                                        "type": "object"
                                    },
                                    "title": {
                                        "type": "string",
                                        "description": "Title of product",
                                        "example": "Alice in Wonderland"
                                    },
                                    "eans": {
                                        "type": "array",
                                        "description": "List of the EANs of the product"
                                    },
                                    "cover_url": {
                                        "type": "string",
                                        "description": "URL of cover thumbnail"
                                    }
                                },
                                "required": [
                                    "_id"
                                ]
                            }
                        ]
                    },
                    "created_business_partner": {
                        "description": "The business partner who created the ticket; set from the login on create. Read-only.",
                        "allOf": [
                            {
                                "type": "object",
                                "description": "Reference to business partner",
                                "additionalProperties": false,
                                "nullable": true,
                                "properties": {
                                    "_id": {
                                        "type": "integer",
                                        "description": "Business Partner ID",
                                        "example": 23
                                    },
                                    "_uuid": {
                                        "type": "string",
                                        "description": "ID of resource in V4 version of resource"
                                    },
                                    "_links": {
                                        "type": "object"
                                    },
                                    "screenname": {
                                        "type": "string",
                                        "description": "Display name of business partner",
                                        "example": "John Doe"
                                    }
                                }
                            }
                        ]
                    },
                    "assigned_business_partner": {
                        "description": "The business partner who should act on the ticket, or `null`. Write it as `{\"_id\": 128}`; it must belong\nto the caller's realm.\n",
                        "allOf": [
                            {
                                "type": "object",
                                "description": "Reference to business partner",
                                "additionalProperties": false,
                                "nullable": true,
                                "properties": {
                                    "_id": {
                                        "type": "integer",
                                        "description": "Business Partner ID",
                                        "example": 23
                                    },
                                    "_uuid": {
                                        "type": "string",
                                        "description": "ID of resource in V4 version of resource"
                                    },
                                    "_links": {
                                        "type": "object"
                                    },
                                    "screenname": {
                                        "type": "string",
                                        "description": "Display name of business partner",
                                        "example": "John Doe"
                                    }
                                }
                            }
                        ]
                    },
                    "created": {
                        "type": "integer",
                        "nullable": true,
                        "readOnly": true,
                        "description": "Creation time as a Unix timestamp.",
                        "example": 1763290170
                    },
                    "due_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true,
                        "description": "When the task has to be done (`YYYY-MM-DD`).",
                        "example": "2027-02-24"
                    },
                    "description": {
                        "type": "string",
                        "nullable": true,
                        "description": "Free text: what to do. Plain text, line breaks are kept. An empty string is stored as `null`.\n",
                        "example": "The contract ends on 2027-02-24. Take the product down.\n[x] Author informed\n[ ] Product withdrawn"
                    },
                    "done": {
                        "type": "boolean",
                        "description": "Whether the reminder is dealt with. Done tickets drop off the open list (`?done=false`).",
                        "example": false
                    }
                },
                "required": []
            }
        }
    },
    "required": [
        "_links",
        "_pagination",
        "items"
    ]
}

Refer to the common response description: bad_request.


POST /resource/v3/tickets

Create a ticket

Description

type is required. created_business_partner is taken from the login, created is set by the server.

Request body

{
    "type": "CONTRACT_END",
    "product": {
        "_id": 1387
    },
    "due_date": "2027-02-24",
    "description": "The contract ends on 2027-02-24. Take the product down."
}
Schema of the request body
{
    "type": "object",
    "additionalProperties": false,
    "description": "A dated reminder, usually for a product: \"the contract of this title ends on 2027-02-24, take it down then\".\n\nOn `POST` and `PUT` only `type`, `product`, `assigned_business_partner`, `due_date`, `description` and `done`\nare written. The read-only fields (`_id`, `_uuid`, `_version`, `_links`, `created`, `created_business_partner`)\nmay be sent back unchanged and are ignored; any other key is rejected with `400 Bad Request`.\n",
    "properties": {
        "_id": {
            "type": "integer",
            "description": "Numeric identifier of the ticket.",
            "example": 1234
        },
        "_uuid": {
            "type": "string",
            "description": "UUID of the ticket.",
            "example": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
        },
        "_version": {
            "type": "string",
            "description": "API version.",
            "example": "3.0"
        },
        "_links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "self": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v3/tickets/1234"
                },
                "comments": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v3/tickets/1234/comments"
                }
            }
        },
        "type": {
            "type": "string",
            "maxLength": 255,
            "description": "Kind of reminder. Free text: the API stores and returns it as given (surrounding whitespace removed) and\nattaches no meaning to it; the client defines the vocabulary. Required on create.\n",
            "example": "CONTRACT_END"
        },
        "product": {
            "description": "The product the ticket is about, or `null`. Write it as `{\"_id\": 1387}`; the product must belong to the\ncaller's realm, otherwise `400 Bad Request`. Several tickets may point to the same product.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to product",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "integer",
                            "description": "Product ID",
                            "example": 23
                        },
                        "_uuid": {
                            "type": "string",
                            "description": "ID of resource in V4 version of resource"
                        },
                        "_links": {
                            "type": "object"
                        },
                        "title": {
                            "type": "string",
                            "description": "Title of product",
                            "example": "Alice in Wonderland"
                        },
                        "eans": {
                            "type": "array",
                            "description": "List of the EANs of the product"
                        },
                        "cover_url": {
                            "type": "string",
                            "description": "URL of cover thumbnail"
                        }
                    },
                    "required": [
                        "_id"
                    ]
                }
            ]
        },
        "created_business_partner": {
            "description": "The business partner who created the ticket; set from the login on create. Read-only.",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to business partner",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "integer",
                            "description": "Business Partner ID",
                            "example": 23
                        },
                        "_uuid": {
                            "type": "string",
                            "description": "ID of resource in V4 version of resource"
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "John Doe"
                        }
                    }
                }
            ]
        },
        "assigned_business_partner": {
            "description": "The business partner who should act on the ticket, or `null`. Write it as `{\"_id\": 128}`; it must belong\nto the caller's realm.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to business partner",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "integer",
                            "description": "Business Partner ID",
                            "example": 23
                        },
                        "_uuid": {
                            "type": "string",
                            "description": "ID of resource in V4 version of resource"
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "John Doe"
                        }
                    }
                }
            ]
        },
        "created": {
            "type": "integer",
            "nullable": true,
            "readOnly": true,
            "description": "Creation time as a Unix timestamp.",
            "example": 1763290170
        },
        "due_date": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "When the task has to be done (`YYYY-MM-DD`).",
            "example": "2027-02-24"
        },
        "description": {
            "type": "string",
            "nullable": true,
            "description": "Free text: what to do. Plain text, line breaks are kept. An empty string is stored as `null`.\n",
            "example": "The contract ends on 2027-02-24. Take the product down.\n[x] Author informed\n[ ] Product withdrawn"
        },
        "done": {
            "type": "boolean",
            "description": "Whether the reminder is dealt with. Done tickets drop off the open list (`?done=false`).",
            "example": false
        }
    },
    "required": []
}

Responses

Refer to the common response description: ticket.

Refer to the common response description: bad_request.


GET /resource/v3/tickets/{id}

Retrieve a ticket

Input parameters

Path parameters

Parameter Type Default Nullable Description
id integer No

Ticket id.

Responses

Refer to the common response description: ticket.

Refer to the common response description: not_found.


PUT /resource/v3/tickets/{id}

Update a ticket

Description

A partial update: only the keys present in the body are applied. Send null to clear product, assigned_business_partner, due_date or description.

Input parameters

Path parameters

Parameter Type Default Nullable Description
id integer No

Ticket id.

Request body

{
    "done": true
}
Schema of the request body
{
    "type": "object",
    "additionalProperties": false,
    "description": "A dated reminder, usually for a product: \"the contract of this title ends on 2027-02-24, take it down then\".\n\nOn `POST` and `PUT` only `type`, `product`, `assigned_business_partner`, `due_date`, `description` and `done`\nare written. The read-only fields (`_id`, `_uuid`, `_version`, `_links`, `created`, `created_business_partner`)\nmay be sent back unchanged and are ignored; any other key is rejected with `400 Bad Request`.\n",
    "properties": {
        "_id": {
            "type": "integer",
            "description": "Numeric identifier of the ticket.",
            "example": 1234
        },
        "_uuid": {
            "type": "string",
            "description": "UUID of the ticket.",
            "example": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
        },
        "_version": {
            "type": "string",
            "description": "API version.",
            "example": "3.0"
        },
        "_links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "self": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v3/tickets/1234"
                },
                "comments": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v3/tickets/1234/comments"
                }
            }
        },
        "type": {
            "type": "string",
            "maxLength": 255,
            "description": "Kind of reminder. Free text: the API stores and returns it as given (surrounding whitespace removed) and\nattaches no meaning to it; the client defines the vocabulary. Required on create.\n",
            "example": "CONTRACT_END"
        },
        "product": {
            "description": "The product the ticket is about, or `null`. Write it as `{\"_id\": 1387}`; the product must belong to the\ncaller's realm, otherwise `400 Bad Request`. Several tickets may point to the same product.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to product",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "integer",
                            "description": "Product ID",
                            "example": 23
                        },
                        "_uuid": {
                            "type": "string",
                            "description": "ID of resource in V4 version of resource"
                        },
                        "_links": {
                            "type": "object"
                        },
                        "title": {
                            "type": "string",
                            "description": "Title of product",
                            "example": "Alice in Wonderland"
                        },
                        "eans": {
                            "type": "array",
                            "description": "List of the EANs of the product"
                        },
                        "cover_url": {
                            "type": "string",
                            "description": "URL of cover thumbnail"
                        }
                    },
                    "required": [
                        "_id"
                    ]
                }
            ]
        },
        "created_business_partner": {
            "description": "The business partner who created the ticket; set from the login on create. Read-only.",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to business partner",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "integer",
                            "description": "Business Partner ID",
                            "example": 23
                        },
                        "_uuid": {
                            "type": "string",
                            "description": "ID of resource in V4 version of resource"
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "John Doe"
                        }
                    }
                }
            ]
        },
        "assigned_business_partner": {
            "description": "The business partner who should act on the ticket, or `null`. Write it as `{\"_id\": 128}`; it must belong\nto the caller's realm.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to business partner",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "integer",
                            "description": "Business Partner ID",
                            "example": 23
                        },
                        "_uuid": {
                            "type": "string",
                            "description": "ID of resource in V4 version of resource"
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "John Doe"
                        }
                    }
                }
            ]
        },
        "created": {
            "type": "integer",
            "nullable": true,
            "readOnly": true,
            "description": "Creation time as a Unix timestamp.",
            "example": 1763290170
        },
        "due_date": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "When the task has to be done (`YYYY-MM-DD`).",
            "example": "2027-02-24"
        },
        "description": {
            "type": "string",
            "nullable": true,
            "description": "Free text: what to do. Plain text, line breaks are kept. An empty string is stored as `null`.\n",
            "example": "The contract ends on 2027-02-24. Take the product down.\n[x] Author informed\n[ ] Product withdrawn"
        },
        "done": {
            "type": "boolean",
            "description": "Whether the reminder is dealt with. Done tickets drop off the open list (`?done=false`).",
            "example": false
        }
    },
    "required": []
}

Responses

Refer to the common response description: ticket.

Refer to the common response description: bad_request.

Refer to the common response description: not_found.


DELETE /resource/v3/tickets/{id}

Delete a ticket

Description

Deletes the ticket and its comments permanently. To close a reminder, set done instead.

Input parameters

Path parameters

Parameter Type Default Nullable Description
id integer No

Ticket id.

Responses

Refer to the common response description: not_found.


GET /resource/v3/tickets/{id}/comments

Retrieve the comments of a ticket

Description

Oldest first. No filters.

Input parameters

Path parameters

Parameter Type Default Nullable Description
id integer No

Ticket id.

Query parameters

Parameter Type Default Nullable Description
page integer No

Page number, starting at 1.

page_size integer No

Entries per page; defaults to 100.

Responses

{
    "_links": {},
    "_pagination": {},
    "items": [
        {
            "_id": 5678,
            "_uuid": "0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93",
            "_version": "3.0",
            "_links": {
                "self": "https://api.openpublishing.com/resource/v3/tickets/1234/comments/5678",
                "parent": "https://api.openpublishing.com/resource/v3/tickets/1234"
            },
            "created_business_partner": null,
            "created": 1763291370,
            "comment": "Author contacted twice."
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "type": "object",
    "additionalProperties": false,
    "properties": {
        "_links": {
            "type": "object"
        },
        "_pagination": {
            "type": "object"
        },
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "additionalProperties": false,
                "description": "A note on a ticket. Comments cannot be edited; delete and re-add instead.\nOn `POST` only `comment` is written; the read-only fields may be sent back and are ignored, any other key\nis rejected with `400 Bad Request`.\n",
                "properties": {
                    "_id": {
                        "type": "integer",
                        "example": 5678
                    },
                    "_uuid": {
                        "type": "string",
                        "example": "0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93"
                    },
                    "_version": {
                        "type": "string",
                        "example": "3.0"
                    },
                    "_links": {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                            "self": {
                                "type": "string",
                                "example": "https://api.openpublishing.com/resource/v3/tickets/1234/comments/5678"
                            },
                            "parent": {
                                "type": "string",
                                "example": "https://api.openpublishing.com/resource/v3/tickets/1234"
                            }
                        }
                    },
                    "created_business_partner": {
                        "description": "Author; set from the login. `null` for old comments without a recorded author. Read-only.",
                        "allOf": [
                            {
                                "type": "object",
                                "description": "Reference to business partner",
                                "additionalProperties": false,
                                "nullable": true,
                                "properties": {
                                    "_id": {
                                        "type": "integer",
                                        "description": "Business Partner ID",
                                        "example": 23
                                    },
                                    "_uuid": {
                                        "type": "string",
                                        "description": "ID of resource in V4 version of resource"
                                    },
                                    "_links": {
                                        "type": "object"
                                    },
                                    "screenname": {
                                        "type": "string",
                                        "description": "Display name of business partner",
                                        "example": "John Doe"
                                    }
                                }
                            }
                        ]
                    },
                    "created": {
                        "type": "integer",
                        "nullable": true,
                        "readOnly": true,
                        "description": "Creation time as a Unix timestamp.",
                        "example": 1763291370
                    },
                    "comment": {
                        "type": "string",
                        "description": "Plain text. Required and must not be blank; surrounding whitespace is removed.",
                        "example": "Author contacted twice."
                    }
                },
                "required": []
            }
        }
    },
    "required": [
        "_links",
        "_pagination",
        "items"
    ]
}

Refer to the common response description: bad_request.

Refer to the common response description: not_found.


POST /resource/v3/tickets/{id}/comments

Add a comment

Description

The author is taken from the login. A ticket holds at most 127 comments; one more returns 400 Bad Request (ticket_comment::too_many_comments). Deleting a comment frees its place.

Input parameters

Path parameters

Parameter Type Default Nullable Description
id integer No

Ticket id.

Request body

{
    "comment": "Author contacted twice."
}
Schema of the request body
{
    "type": "object",
    "additionalProperties": false,
    "description": "A note on a ticket. Comments cannot be edited; delete and re-add instead.\nOn `POST` only `comment` is written; the read-only fields may be sent back and are ignored, any other key\nis rejected with `400 Bad Request`.\n",
    "properties": {
        "_id": {
            "type": "integer",
            "example": 5678
        },
        "_uuid": {
            "type": "string",
            "example": "0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93"
        },
        "_version": {
            "type": "string",
            "example": "3.0"
        },
        "_links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "self": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v3/tickets/1234/comments/5678"
                },
                "parent": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v3/tickets/1234"
                }
            }
        },
        "created_business_partner": {
            "description": "Author; set from the login. `null` for old comments without a recorded author. Read-only.",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to business partner",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "integer",
                            "description": "Business Partner ID",
                            "example": 23
                        },
                        "_uuid": {
                            "type": "string",
                            "description": "ID of resource in V4 version of resource"
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "John Doe"
                        }
                    }
                }
            ]
        },
        "created": {
            "type": "integer",
            "nullable": true,
            "readOnly": true,
            "description": "Creation time as a Unix timestamp.",
            "example": 1763291370
        },
        "comment": {
            "type": "string",
            "description": "Plain text. Required and must not be blank; surrounding whitespace is removed.",
            "example": "Author contacted twice."
        }
    },
    "required": []
}

Responses

Refer to the common response description: ticket_comment.

Refer to the common response description: bad_request.

Refer to the common response description: not_found.


GET /resource/v3/tickets/{id}/comments/{comment_id}

Retrieve a comment

Description

A comment of another ticket returns 403, an unknown id 404.

Input parameters

Path parameters

Parameter Type Default Nullable Description
comment_id integer No

Comment id.

id integer No

Ticket id.

Responses

Refer to the common response description: ticket_comment.

Refer to the common response description: not_found.


DELETE /resource/v3/tickets/{id}/comments/{comment_id}

Delete a comment

Input parameters

Path parameters

Parameter Type Default Nullable Description
comment_id integer No

Comment id.

id integer No

Ticket id.

Responses

Refer to the common response description: not_found.


Schemas

ticket_comment_list

Name Type Description Example
_links object
_pagination object
items Array<Properties: _id, _uuid, _version, _links, created_business_partner, created, comment>
items[]._id integer 5678
items[]._uuid string 0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93
items[]._version string 3.0
items[]._links Properties: self, parent
items[]._links.self string https://api.openpublishing.com/resource/v3/tickets/1234/comments/5678
items[]._links.parent string https://api.openpublishing.com/resource/v3/tickets/1234
items[].created_business_partner

Author; set from the login. null for old comments without a recorded author. Read-only.

items[].created integer| null

Creation time as a Unix timestamp.

1763291370
items[].comment string

Plain text. Required and must not be blank; surrounding whitespace is removed.

Author contacted twice.

ticket_list

Name Type Description Example
_links object
_pagination object
items Array<Properties: _id, _uuid, _version, _links, type, product, created_business_partner, assigned_business_partner, created, due_date, description, done>
items[]._id integer

Numeric identifier of the ticket.

1234
items[]._uuid string

UUID of the ticket.

6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44
items[]._version string

API version.

3.0
items[]._links Properties: self, comments
items[]._links.self string https://api.openpublishing.com/resource/v3/tickets/1234
items[]._links.comments string https://api.openpublishing.com/resource/v3/tickets/1234/comments
items[].type string

Kind of reminder. Free text: the API stores and returns it as given (surrounding whitespace removed) and attaches no meaning to it; the client defines the vocabulary. Required on create.

CONTRACT_END
items[].product

The product the ticket is about, or null. Write it as {"_id": 1387}; the product must belong to the caller's realm, otherwise 400 Bad Request. Several tickets may point to the same product.

items[].created_business_partner

The business partner who created the ticket; set from the login on create. Read-only.

items[].assigned_business_partner

The business partner who should act on the ticket, or null. Write it as {"_id": 128}; it must belong to the caller's realm.

items[].created integer| null

Creation time as a Unix timestamp.

1763290170
items[].due_date string(date)| null

When the task has to be done (YYYY-MM-DD).

2027-02-24
items[].description string| null

Free text: what to do. Plain text, line breaks are kept. An empty string is stored as null.

The contract ends on 2027-02-24. Take the product down. [x] Author informed [ ] Product withdrawn
items[].done boolean

Whether the reminder is dealt with. Done tickets drop off the open list (?done=false).

false

Common responses

This section describes common responses that are reused across operations.

ticket

A single ticket

{
    "_id": 1234,
    "_uuid": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44",
    "_version": "3.0",
    "_links": {
        "self": "https://api.openpublishing.com/resource/v3/tickets/1234",
        "comments": "https://api.openpublishing.com/resource/v3/tickets/1234/comments"
    },
    "type": "CONTRACT_END",
    "product": null,
    "created_business_partner": null,
    "assigned_business_partner": null,
    "created": 1763290170,
    "due_date": "2027-02-24",
    "description": "The contract ends on 2027-02-24. Take the product down.\n[x] Author informed\n[ ] Product withdrawn",
    "done": false
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "type": "object",
    "additionalProperties": false,
    "description": "A dated reminder, usually for a product: \"the contract of this title ends on 2027-02-24, take it down then\".\n\nOn `POST` and `PUT` only `type`, `product`, `assigned_business_partner`, `due_date`, `description` and `done`\nare written. The read-only fields (`_id`, `_uuid`, `_version`, `_links`, `created`, `created_business_partner`)\nmay be sent back unchanged and are ignored; any other key is rejected with `400 Bad Request`.\n",
    "properties": {
        "_id": {
            "type": "integer",
            "description": "Numeric identifier of the ticket.",
            "example": 1234
        },
        "_uuid": {
            "type": "string",
            "description": "UUID of the ticket.",
            "example": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
        },
        "_version": {
            "type": "string",
            "description": "API version.",
            "example": "3.0"
        },
        "_links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "self": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v3/tickets/1234"
                },
                "comments": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v3/tickets/1234/comments"
                }
            }
        },
        "type": {
            "type": "string",
            "maxLength": 255,
            "description": "Kind of reminder. Free text: the API stores and returns it as given (surrounding whitespace removed) and\nattaches no meaning to it; the client defines the vocabulary. Required on create.\n",
            "example": "CONTRACT_END"
        },
        "product": {
            "description": "The product the ticket is about, or `null`. Write it as `{\"_id\": 1387}`; the product must belong to the\ncaller's realm, otherwise `400 Bad Request`. Several tickets may point to the same product.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to product",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "integer",
                            "description": "Product ID",
                            "example": 23
                        },
                        "_uuid": {
                            "type": "string",
                            "description": "ID of resource in V4 version of resource"
                        },
                        "_links": {
                            "type": "object"
                        },
                        "title": {
                            "type": "string",
                            "description": "Title of product",
                            "example": "Alice in Wonderland"
                        },
                        "eans": {
                            "type": "array",
                            "description": "List of the EANs of the product"
                        },
                        "cover_url": {
                            "type": "string",
                            "description": "URL of cover thumbnail"
                        }
                    },
                    "required": [
                        "_id"
                    ]
                }
            ]
        },
        "created_business_partner": {
            "description": "The business partner who created the ticket; set from the login on create. Read-only.",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to business partner",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "integer",
                            "description": "Business Partner ID",
                            "example": 23
                        },
                        "_uuid": {
                            "type": "string",
                            "description": "ID of resource in V4 version of resource"
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "John Doe"
                        }
                    }
                }
            ]
        },
        "assigned_business_partner": {
            "description": "The business partner who should act on the ticket, or `null`. Write it as `{\"_id\": 128}`; it must belong\nto the caller's realm.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to business partner",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "integer",
                            "description": "Business Partner ID",
                            "example": 23
                        },
                        "_uuid": {
                            "type": "string",
                            "description": "ID of resource in V4 version of resource"
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "John Doe"
                        }
                    }
                }
            ]
        },
        "created": {
            "type": "integer",
            "nullable": true,
            "readOnly": true,
            "description": "Creation time as a Unix timestamp.",
            "example": 1763290170
        },
        "due_date": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "description": "When the task has to be done (`YYYY-MM-DD`).",
            "example": "2027-02-24"
        },
        "description": {
            "type": "string",
            "nullable": true,
            "description": "Free text: what to do. Plain text, line breaks are kept. An empty string is stored as `null`.\n",
            "example": "The contract ends on 2027-02-24. Take the product down.\n[x] Author informed\n[ ] Product withdrawn"
        },
        "done": {
            "type": "boolean",
            "description": "Whether the reminder is dealt with. Done tickets drop off the open list (`?done=false`).",
            "example": false
        }
    },
    "required": []
}

ticket_comment

A single comment

{
    "_id": 5678,
    "_uuid": "0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93",
    "_version": "3.0",
    "_links": {
        "self": "https://api.openpublishing.com/resource/v3/tickets/1234/comments/5678",
        "parent": "https://api.openpublishing.com/resource/v3/tickets/1234"
    },
    "created_business_partner": null,
    "created": 1763291370,
    "comment": "Author contacted twice."
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "type": "object",
    "additionalProperties": false,
    "description": "A note on a ticket. Comments cannot be edited; delete and re-add instead.\nOn `POST` only `comment` is written; the read-only fields may be sent back and are ignored, any other key\nis rejected with `400 Bad Request`.\n",
    "properties": {
        "_id": {
            "type": "integer",
            "example": 5678
        },
        "_uuid": {
            "type": "string",
            "example": "0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93"
        },
        "_version": {
            "type": "string",
            "example": "3.0"
        },
        "_links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "self": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v3/tickets/1234/comments/5678"
                },
                "parent": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v3/tickets/1234"
                }
            }
        },
        "created_business_partner": {
            "description": "Author; set from the login. `null` for old comments without a recorded author. Read-only.",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to business partner",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "integer",
                            "description": "Business Partner ID",
                            "example": 23
                        },
                        "_uuid": {
                            "type": "string",
                            "description": "ID of resource in V4 version of resource"
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "John Doe"
                        }
                    }
                }
            ]
        },
        "created": {
            "type": "integer",
            "nullable": true,
            "readOnly": true,
            "description": "Creation time as a Unix timestamp.",
            "example": 1763291370
        },
        "comment": {
            "type": "string",
            "description": "Plain text. Required and must not be blank; surrounding whitespace is removed.",
            "example": "Author contacted twice."
        }
    },
    "required": []
}

bad_request

Bad Request. Common causes: type missing or empty; an unknown field; a product or business partner outside the realm; an unknown filter or sort field; a blank comment.

{
    "errors": [
        {
            "_id": "string",
            "stack_trace": [
                "string"
            ],
            "message": "string",
            "vars": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "errors"
    ],
    "properties": {
        "errors": {
            "type": "array",
            "description": "List of errors occurred",
            "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "_id",
                    "message",
                    "stack_trace",
                    "vars"
                ],
                "properties": {
                    "_id": {
                        "type": "string",
                        "description": "The identifier of the error"
                    },
                    "stack_trace": {
                        "type": "array",
                        "description": "A stacktrace of the error occurred. Only for testing systems.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "message": {
                        "type": "string",
                        "description": "A translated message of the error"
                    },
                    "vars": {
                        "type": "object",
                        "description": "A dict containing additional values of the context of the error."
                    }
                }
            }
        }
    }
}

not_found

Resource not found

{
    "errors": [
        {
            "_id": "string",
            "stack_trace": [
                "string"
            ],
            "message": "string",
            "vars": {}
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body
{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "errors"
    ],
    "properties": {
        "errors": {
            "type": "array",
            "description": "List of errors occurred",
            "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                    "_id",
                    "message",
                    "stack_trace",
                    "vars"
                ],
                "properties": {
                    "_id": {
                        "type": "string",
                        "description": "The identifier of the error"
                    },
                    "stack_trace": {
                        "type": "array",
                        "description": "A stacktrace of the error occurred. Only for testing systems.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "message": {
                        "type": "string",
                        "description": "A translated message of the error"
                    },
                    "vars": {
                        "type": "object",
                        "description": "A dict containing additional values of the context of the error."
                    }
                }
            }
        }
    }
}

Common parameters

This section describes common parameters that are reused across operations.

id

Name In Type Default Nullable Description
id path integer No

comment_id

Name In Type Default Nullable Description
comment_id path integer No

page

Name In Type Default Nullable Description
page query integer No

page_size

Name In Type Default Nullable Description
page_size query integer No