Skip to content

Tickets v4

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. Same resource as on v3; on v4 _id is a UUID and the numeric id is in _legacy_id. Both are accepted in the path and in the id filters.

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


Endpoints


GET /resource/v4/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": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44",
            "_legacy_id": 1234,
            "_version": "4.0",
            "_links": {
                "self": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44",
                "comments": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/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`, `_legacy_id`, `_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": "string",
                        "description": "UUID of the ticket, and the value to put in the path.",
                        "example": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
                    },
                    "_legacy_id": {
                        "type": "integer",
                        "description": "Numeric id of the same record, the `_id` on v3. Accepted in the path as well.",
                        "example": 1234
                    },
                    "_version": {
                        "type": "string",
                        "description": "API version.",
                        "example": "4.0"
                    },
                    "_links": {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                            "self": {
                                "type": "string",
                                "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
                            },
                            "comments": {
                                "type": "string",
                                "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/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\": \"a65e02bc-e616-11ee-a221-00505699575c\"}`;\nthe numeric id works as well. The product must belong to the caller's realm, otherwise `400 Bad Request`.\nSeveral tickets may point to the same product.\n",
                        "allOf": [
                            {
                                "type": "object",
                                "description": "Reference to product",
                                "additionalProperties": false,
                                "nullable": true,
                                "properties": {
                                    "_id": {
                                        "type": "string",
                                        "description": "Product ID",
                                        "example": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d"
                                    },
                                    "_legacy_id": {
                                        "type": "integer",
                                        "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                                    },
                                    "_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",
                                "example": {
                                    "_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
                                    "_legacy_id": 4242,
                                    "screenname": "Michael Scarn"
                                },
                                "additionalProperties": false,
                                "nullable": true,
                                "properties": {
                                    "_id": {
                                        "type": "string",
                                        "description": "Business Partner ID",
                                        "example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
                                    },
                                    "_legacy_id": {
                                        "type": "integer",
                                        "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                                    },
                                    "_links": {
                                        "type": "object"
                                    },
                                    "screenname": {
                                        "type": "string",
                                        "description": "Display name of business partner",
                                        "example": "Michael Scarn"
                                    }
                                }
                            }
                        ]
                    },
                    "assigned_business_partner": {
                        "description": "The business partner who should act on the ticket, or `null`. Write it as\n`{\"_id\": \"3f2b9c1e-5d4a-4e7b-8c6f-1a2b3c4d5e6f\"}`; the numeric id works as well. It must belong to the\ncaller's realm.\n",
                        "allOf": [
                            {
                                "type": "object",
                                "description": "Reference to business partner",
                                "example": {
                                    "_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
                                    "_legacy_id": 4242,
                                    "screenname": "Michael Scarn"
                                },
                                "additionalProperties": false,
                                "nullable": true,
                                "properties": {
                                    "_id": {
                                        "type": "string",
                                        "description": "Business Partner ID",
                                        "example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
                                    },
                                    "_legacy_id": {
                                        "type": "integer",
                                        "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                                    },
                                    "_links": {
                                        "type": "object"
                                    },
                                    "screenname": {
                                        "type": "string",
                                        "description": "Display name of business partner",
                                        "example": "Michael Scarn"
                                    }
                                }
                            }
                        ]
                    },
                    "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/v4/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": "a65e02bc-e616-11ee-a221-00505699575c"
    },
    "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`, `_legacy_id`, `_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": "string",
            "description": "UUID of the ticket, and the value to put in the path.",
            "example": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
        },
        "_legacy_id": {
            "type": "integer",
            "description": "Numeric id of the same record, the `_id` on v3. Accepted in the path as well.",
            "example": 1234
        },
        "_version": {
            "type": "string",
            "description": "API version.",
            "example": "4.0"
        },
        "_links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "self": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
                },
                "comments": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/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\": \"a65e02bc-e616-11ee-a221-00505699575c\"}`;\nthe numeric id works as well. The product must belong to the caller's realm, otherwise `400 Bad Request`.\nSeveral tickets may point to the same product.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to product",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "string",
                            "description": "Product ID",
                            "example": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d"
                        },
                        "_legacy_id": {
                            "type": "integer",
                            "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                        },
                        "_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",
                    "example": {
                        "_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
                        "_legacy_id": 4242,
                        "screenname": "Michael Scarn"
                    },
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "string",
                            "description": "Business Partner ID",
                            "example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
                        },
                        "_legacy_id": {
                            "type": "integer",
                            "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "Michael Scarn"
                        }
                    }
                }
            ]
        },
        "assigned_business_partner": {
            "description": "The business partner who should act on the ticket, or `null`. Write it as\n`{\"_id\": \"3f2b9c1e-5d4a-4e7b-8c6f-1a2b3c4d5e6f\"}`; the numeric id works as well. It must belong to the\ncaller's realm.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to business partner",
                    "example": {
                        "_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
                        "_legacy_id": 4242,
                        "screenname": "Michael Scarn"
                    },
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "string",
                            "description": "Business Partner ID",
                            "example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
                        },
                        "_legacy_id": {
                            "type": "integer",
                            "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "Michael Scarn"
                        }
                    }
                }
            ]
        },
        "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/v4/tickets/{id}

Retrieve a ticket

Input parameters

Path parameters

Parameter Type Default Nullable Description
id string No

Ticket UUID (or its _legacy_id).

Responses

Refer to the common response description: ticket.

Refer to the common response description: not_found.


PUT /resource/v4/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 string No

Ticket UUID (or its _legacy_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`, `_legacy_id`, `_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": "string",
            "description": "UUID of the ticket, and the value to put in the path.",
            "example": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
        },
        "_legacy_id": {
            "type": "integer",
            "description": "Numeric id of the same record, the `_id` on v3. Accepted in the path as well.",
            "example": 1234
        },
        "_version": {
            "type": "string",
            "description": "API version.",
            "example": "4.0"
        },
        "_links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "self": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
                },
                "comments": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/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\": \"a65e02bc-e616-11ee-a221-00505699575c\"}`;\nthe numeric id works as well. The product must belong to the caller's realm, otherwise `400 Bad Request`.\nSeveral tickets may point to the same product.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to product",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "string",
                            "description": "Product ID",
                            "example": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d"
                        },
                        "_legacy_id": {
                            "type": "integer",
                            "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                        },
                        "_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",
                    "example": {
                        "_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
                        "_legacy_id": 4242,
                        "screenname": "Michael Scarn"
                    },
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "string",
                            "description": "Business Partner ID",
                            "example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
                        },
                        "_legacy_id": {
                            "type": "integer",
                            "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "Michael Scarn"
                        }
                    }
                }
            ]
        },
        "assigned_business_partner": {
            "description": "The business partner who should act on the ticket, or `null`. Write it as\n`{\"_id\": \"3f2b9c1e-5d4a-4e7b-8c6f-1a2b3c4d5e6f\"}`; the numeric id works as well. It must belong to the\ncaller's realm.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to business partner",
                    "example": {
                        "_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
                        "_legacy_id": 4242,
                        "screenname": "Michael Scarn"
                    },
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "string",
                            "description": "Business Partner ID",
                            "example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
                        },
                        "_legacy_id": {
                            "type": "integer",
                            "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "Michael Scarn"
                        }
                    }
                }
            ]
        },
        "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/v4/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 string No

Ticket UUID (or its _legacy_id).

Responses

Refer to the common response description: not_found.


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

Retrieve the comments of a ticket

Description

Oldest first. No filters.

Input parameters

Path parameters

Parameter Type Default Nullable Description
id string No

Ticket UUID (or its _legacy_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": "0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93",
            "_legacy_id": 5678,
            "_version": "4.0",
            "_links": {
                "self": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/comments/0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93",
                "parent": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
            },
            "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": "string",
                        "description": "UUID of the comment, and the value to put in the path.",
                        "example": "0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93"
                    },
                    "_legacy_id": {
                        "type": "integer",
                        "description": "Numeric id of the same record, the `_id` on v3. Accepted in the path as well.",
                        "example": 5678
                    },
                    "_version": {
                        "type": "string",
                        "example": "4.0"
                    },
                    "_links": {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                            "self": {
                                "type": "string",
                                "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/comments/0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93"
                            },
                            "parent": {
                                "type": "string",
                                "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
                            }
                        }
                    },
                    "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",
                                "example": {
                                    "_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
                                    "_legacy_id": 4242,
                                    "screenname": "Michael Scarn"
                                },
                                "additionalProperties": false,
                                "nullable": true,
                                "properties": {
                                    "_id": {
                                        "type": "string",
                                        "description": "Business Partner ID",
                                        "example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
                                    },
                                    "_legacy_id": {
                                        "type": "integer",
                                        "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                                    },
                                    "_links": {
                                        "type": "object"
                                    },
                                    "screenname": {
                                        "type": "string",
                                        "description": "Display name of business partner",
                                        "example": "Michael Scarn"
                                    }
                                }
                            }
                        ]
                    },
                    "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/v4/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 string No

Ticket UUID (or its _legacy_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": "string",
            "description": "UUID of the comment, and the value to put in the path.",
            "example": "0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93"
        },
        "_legacy_id": {
            "type": "integer",
            "description": "Numeric id of the same record, the `_id` on v3. Accepted in the path as well.",
            "example": 5678
        },
        "_version": {
            "type": "string",
            "example": "4.0"
        },
        "_links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "self": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/comments/0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93"
                },
                "parent": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
                }
            }
        },
        "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",
                    "example": {
                        "_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
                        "_legacy_id": 4242,
                        "screenname": "Michael Scarn"
                    },
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "string",
                            "description": "Business Partner ID",
                            "example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
                        },
                        "_legacy_id": {
                            "type": "integer",
                            "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "Michael Scarn"
                        }
                    }
                }
            ]
        },
        "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/v4/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 string No

Comment UUID (or its _legacy_id).

id string No

Ticket UUID (or its _legacy_id).

Responses

Refer to the common response description: ticket_comment.

Refer to the common response description: not_found.


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

Delete a comment

Input parameters

Path parameters

Parameter Type Default Nullable Description
comment_id string No

Comment UUID (or its _legacy_id).

id string No

Ticket UUID (or its _legacy_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, _legacy_id, _version, _links, created_business_partner, created, comment>
items[]._id string

UUID of the comment, and the value to put in the path.

0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93
items[]._legacy_id integer

Numeric id of the same record, the _id on v3. Accepted in the path as well.

5678
items[]._version string 4.0
items[]._links Properties: self, parent
items[]._links.self string https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/comments/0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93
items[]._links.parent string https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44
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, _legacy_id, _version, _links, type, product, created_business_partner, assigned_business_partner, created, due_date, description, done>
items[]._id string

UUID of the ticket, and the value to put in the path.

6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44
items[]._legacy_id integer

Numeric id of the same record, the _id on v3. Accepted in the path as well.

1234
items[]._version string

API version.

4.0
items[]._links Properties: self, comments
items[]._links.self string https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44
items[]._links.comments string https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/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": "a65e02bc-e616-11ee-a221-00505699575c"}; the numeric id works as well. 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": "3f2b9c1e-5d4a-4e7b-8c6f-1a2b3c4d5e6f"}; the numeric id works as well. 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": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44",
    "_legacy_id": 1234,
    "_version": "4.0",
    "_links": {
        "self": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44",
        "comments": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/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`, `_legacy_id`, `_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": "string",
            "description": "UUID of the ticket, and the value to put in the path.",
            "example": "6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
        },
        "_legacy_id": {
            "type": "integer",
            "description": "Numeric id of the same record, the `_id` on v3. Accepted in the path as well.",
            "example": 1234
        },
        "_version": {
            "type": "string",
            "description": "API version.",
            "example": "4.0"
        },
        "_links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "self": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
                },
                "comments": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/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\": \"a65e02bc-e616-11ee-a221-00505699575c\"}`;\nthe numeric id works as well. The product must belong to the caller's realm, otherwise `400 Bad Request`.\nSeveral tickets may point to the same product.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to product",
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "string",
                            "description": "Product ID",
                            "example": "5d2223ea-57bf-4f79-a06e-e1222ab81a5d"
                        },
                        "_legacy_id": {
                            "type": "integer",
                            "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                        },
                        "_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",
                    "example": {
                        "_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
                        "_legacy_id": 4242,
                        "screenname": "Michael Scarn"
                    },
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "string",
                            "description": "Business Partner ID",
                            "example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
                        },
                        "_legacy_id": {
                            "type": "integer",
                            "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "Michael Scarn"
                        }
                    }
                }
            ]
        },
        "assigned_business_partner": {
            "description": "The business partner who should act on the ticket, or `null`. Write it as\n`{\"_id\": \"3f2b9c1e-5d4a-4e7b-8c6f-1a2b3c4d5e6f\"}`; the numeric id works as well. It must belong to the\ncaller's realm.\n",
            "allOf": [
                {
                    "type": "object",
                    "description": "Reference to business partner",
                    "example": {
                        "_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
                        "_legacy_id": 4242,
                        "screenname": "Michael Scarn"
                    },
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "string",
                            "description": "Business Partner ID",
                            "example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
                        },
                        "_legacy_id": {
                            "type": "integer",
                            "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "Michael Scarn"
                        }
                    }
                }
            ]
        },
        "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": "0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93",
    "_legacy_id": 5678,
    "_version": "4.0",
    "_links": {
        "self": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/comments/0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93",
        "parent": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
    },
    "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": "string",
            "description": "UUID of the comment, and the value to put in the path.",
            "example": "0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93"
        },
        "_legacy_id": {
            "type": "integer",
            "description": "Numeric id of the same record, the `_id` on v3. Accepted in the path as well.",
            "example": 5678
        },
        "_version": {
            "type": "string",
            "example": "4.0"
        },
        "_links": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "self": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44/comments/0b8e4d2a-1f3c-4e6a-9d7b-2c5a8e1f0d93"
                },
                "parent": {
                    "type": "string",
                    "example": "https://api.openpublishing.com/resource/v4/tickets/6f1c2d0e-8a51-4c43-9f0b-3c2e1d7a9b44"
                }
            }
        },
        "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",
                    "example": {
                        "_id": "eeee04ea-2752-40f5-a29d-3d67a77ba82c",
                        "_legacy_id": 4242,
                        "screenname": "Michael Scarn"
                    },
                    "additionalProperties": false,
                    "nullable": true,
                    "properties": {
                        "_id": {
                            "type": "string",
                            "description": "Business Partner ID",
                            "example": "eeee04ea-2752-40f5-a29d-3d67a77ba82c"
                        },
                        "_legacy_id": {
                            "type": "integer",
                            "description": "Legacy integer identifier of this resource, kept so existing integrations can correlate their own records."
                        },
                        "_links": {
                            "type": "object"
                        },
                        "screenname": {
                            "type": "string",
                            "description": "Display name of business partner",
                            "example": "Michael Scarn"
                        }
                    }
                }
            ]
        },
        "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 string No

comment_id

Name In Type Default Nullable Description
comment_id path string 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