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 |
|
created_business_partner_id |
string | No |
Business partner who created the ticket, by id or UUID. Also |
|
done |
boolean | No | ||
due_date |
string | No |
Due date ( |
|
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 |
|
q |
string | No |
|
|
sort |
string | No |
|
|
type |
string | No |
Exact type, e.g. |
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
}
]
}
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
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."
}
]
}
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. |
||
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 |
||
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 |
||
items[].created |
integer| null |
Creation time as a Unix timestamp. |
1763290170 |
items[].due_date |
string(date)| null |
When the task has to be done ( |
2027-02-24 |
items[].description |
string| null |
Free text: what to do. Plain text, line breaks are kept. An empty string is stored as |
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 ( |
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
}
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."
}
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": {}
}
]
}
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": {}
}
]
}
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 |