Subjects v3
CRUD operations subjects. Subjects are customer/publisher specific classifications of products. For academic publishers these are typically academic subjects (e.g. economic science or MINT).
Endpoints
GET /resource/v3/subjects
Retrieve a list of subjects
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
identifier |
query | string | No | Filter by identifier. Supports equal-operator (exact match) only. | |
name |
query | string | No | Filter by subject name. Supports equal-operator (exact match) only. | |
q |
query | string | No | Perform a full-text search across multiple fields. |
Response 200 OK
{
"_links": {},
"_pagination": {},
"items": [
{
"_id": 23,
"_version": "3.0",
"_uuid": "string",
"_links": {},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"bisac": [
"SOC026000"
],
"description": "Test description",
"identifier": null,
"labels": [
"Society"
],
"name": [
{
"language": "ger",
"text": "Soziologie"
}
],
"vlb": [
"720"
]
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_links": {
"type": "object"
},
"_pagination": {
"type": "object"
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the subject",
"example": 23
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"bisac": {
"type": "array",
"description": "BISAC codes associated with the subject.",
"items": {
"type": "string"
},
"example": [
"SOC026000"
]
},
"description": {
"type": "string",
"description": "A brief description of the subject.",
"example": "Test description",
"nullable": true
},
"identifier": {
"type": "string",
"description": "External identifier for the subject.",
"nullable": true,
"example": null
},
"labels": {
"type": "array",
"description": "List of labels categorizing the subject.",
"items": {
"type": "string"
},
"example": [
"Society"
]
},
"name": {
"type": "array",
"description": "Multi-language representation of the subject (s. [Multi-language Representation Format](../structured-fields/#multi-language-representation-format)).",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"language": {
"type": "string",
"example": "ger"
},
"text": {
"type": "string",
"example": "Soziologie"
}
}
}
},
"vlb": {
"type": "array",
"description": "VLB (German book trade) subject codes.",
"items": {
"type": "string"
},
"example": [
"720"
]
}
}
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
Response 403 Forbidden
POST /resource/v3/subjects
Create a new subject
Request body
{
"_id": 23,
"_version": "3.0",
"_uuid": "string",
"_links": {},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"bisac": [
"SOC026000"
],
"description": "Test description",
"identifier": null,
"labels": [
"Society"
],
"name": [
{
"language": "ger",
"text": "Soziologie"
}
],
"vlb": [
"720"
]
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the subject",
"example": 23
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"bisac": {
"type": "array",
"description": "BISAC codes associated with the subject.",
"items": {
"type": "string"
},
"example": [
"SOC026000"
]
},
"description": {
"type": "string",
"description": "A brief description of the subject.",
"example": "Test description",
"nullable": true
},
"identifier": {
"type": "string",
"description": "External identifier for the subject.",
"nullable": true,
"example": null
},
"labels": {
"type": "array",
"description": "List of labels categorizing the subject.",
"items": {
"type": "string"
},
"example": [
"Society"
]
},
"name": {
"type": "array",
"description": "Multi-language representation of the subject (s. [Multi-language Representation Format](../structured-fields/#multi-language-representation-format)).",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"language": {
"type": "string",
"example": "ger"
},
"text": {
"type": "string",
"example": "Soziologie"
}
}
}
},
"vlb": {
"type": "array",
"description": "VLB (German book trade) subject codes.",
"items": {
"type": "string"
},
"example": [
"720"
]
}
}
}
Response 201 Created
{
"_id": 23,
"_version": "3.0",
"_uuid": "string",
"_links": {},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"bisac": [
"SOC026000"
],
"description": "Test description",
"identifier": null,
"labels": [
"Society"
],
"name": [
{
"language": "ger",
"text": "Soziologie"
}
],
"vlb": [
"720"
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the subject",
"example": 23
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"bisac": {
"type": "array",
"description": "BISAC codes associated with the subject.",
"items": {
"type": "string"
},
"example": [
"SOC026000"
]
},
"description": {
"type": "string",
"description": "A brief description of the subject.",
"example": "Test description",
"nullable": true
},
"identifier": {
"type": "string",
"description": "External identifier for the subject.",
"nullable": true,
"example": null
},
"labels": {
"type": "array",
"description": "List of labels categorizing the subject.",
"items": {
"type": "string"
},
"example": [
"Society"
]
},
"name": {
"type": "array",
"description": "Multi-language representation of the subject (s. [Multi-language Representation Format](../structured-fields/#multi-language-representation-format)).",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"language": {
"type": "string",
"example": "ger"
},
"text": {
"type": "string",
"example": "Soziologie"
}
}
}
},
"vlb": {
"type": "array",
"description": "VLB (German book trade) subject codes.",
"items": {
"type": "string"
},
"example": [
"720"
]
}
}
}
Response 400 Bad Request
{
"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."
}
}
}
}
}
}
Response 403 Forbidden
GET /resource/v3/subjects/{id}
Retrieve a single subject by ID
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | string | No | The unique identifier of the subject |
Response 200 OK
{
"_id": 23,
"_version": "3.0",
"_uuid": "string",
"_links": {},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"bisac": [
"SOC026000"
],
"description": "Test description",
"identifier": null,
"labels": [
"Society"
],
"name": [
{
"language": "ger",
"text": "Soziologie"
}
],
"vlb": [
"720"
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the subject",
"example": 23
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"bisac": {
"type": "array",
"description": "BISAC codes associated with the subject.",
"items": {
"type": "string"
},
"example": [
"SOC026000"
]
},
"description": {
"type": "string",
"description": "A brief description of the subject.",
"example": "Test description",
"nullable": true
},
"identifier": {
"type": "string",
"description": "External identifier for the subject.",
"nullable": true,
"example": null
},
"labels": {
"type": "array",
"description": "List of labels categorizing the subject.",
"items": {
"type": "string"
},
"example": [
"Society"
]
},
"name": {
"type": "array",
"description": "Multi-language representation of the subject (s. [Multi-language Representation Format](../structured-fields/#multi-language-representation-format)).",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"language": {
"type": "string",
"example": "ger"
},
"text": {
"type": "string",
"example": "Soziologie"
}
}
}
},
"vlb": {
"type": "array",
"description": "VLB (German book trade) subject codes.",
"items": {
"type": "string"
},
"example": [
"720"
]
}
}
}
Response 403 Forbidden
PUT /resource/v3/subjects/{id}
Update subject
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | string | No | The unique identifier of the subject |
Request body
{
"_id": 23,
"_version": "3.0",
"_uuid": "string",
"_links": {},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"bisac": [
"SOC026000"
],
"description": "Test description",
"identifier": null,
"labels": [
"Society"
],
"name": [
{
"language": "ger",
"text": "Soziologie"
}
],
"vlb": [
"720"
]
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the subject",
"example": 23
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"bisac": {
"type": "array",
"description": "BISAC codes associated with the subject.",
"items": {
"type": "string"
},
"example": [
"SOC026000"
]
},
"description": {
"type": "string",
"description": "A brief description of the subject.",
"example": "Test description",
"nullable": true
},
"identifier": {
"type": "string",
"description": "External identifier for the subject.",
"nullable": true,
"example": null
},
"labels": {
"type": "array",
"description": "List of labels categorizing the subject.",
"items": {
"type": "string"
},
"example": [
"Society"
]
},
"name": {
"type": "array",
"description": "Multi-language representation of the subject (s. [Multi-language Representation Format](../structured-fields/#multi-language-representation-format)).",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"language": {
"type": "string",
"example": "ger"
},
"text": {
"type": "string",
"example": "Soziologie"
}
}
}
},
"vlb": {
"type": "array",
"description": "VLB (German book trade) subject codes.",
"items": {
"type": "string"
},
"example": [
"720"
]
}
}
}
Response 200 OK
{
"_id": 23,
"_version": "3.0",
"_uuid": "string",
"_links": {},
"realm": {
"_id": 23,
"_uuid": "string",
"_links": {},
"name": "xyzpublishing",
"screenname": "XYZ Publishing"
},
"bisac": [
"SOC026000"
],
"description": "Test description",
"identifier": null,
"labels": [
"Society"
],
"name": [
{
"language": "ger",
"text": "Soziologie"
}
],
"vlb": [
"720"
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Unique identifier for the subject",
"example": 23
},
"_version": {
"type": "string",
"description": "API Version",
"example": "3.0"
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"realm": {
"type": "object",
"description": "Reference to realm which owns this object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "integer",
"description": "Realm ID",
"example": 23
},
"_uuid": {
"type": "string",
"description": "ID of resource in V4 version of resource"
},
"_links": {
"type": "object"
},
"name": {
"type": "string",
"description": "Name of the realm",
"example": "xyzpublishing"
},
"screenname": {
"type": "string",
"description": "Screenname of the realm",
"example": "XYZ Publishing"
}
},
"required": [
"_id"
]
},
"bisac": {
"type": "array",
"description": "BISAC codes associated with the subject.",
"items": {
"type": "string"
},
"example": [
"SOC026000"
]
},
"description": {
"type": "string",
"description": "A brief description of the subject.",
"example": "Test description",
"nullable": true
},
"identifier": {
"type": "string",
"description": "External identifier for the subject.",
"nullable": true,
"example": null
},
"labels": {
"type": "array",
"description": "List of labels categorizing the subject.",
"items": {
"type": "string"
},
"example": [
"Society"
]
},
"name": {
"type": "array",
"description": "Multi-language representation of the subject (s. [Multi-language Representation Format](../structured-fields/#multi-language-representation-format)).",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"language": {
"type": "string",
"example": "ger"
},
"text": {
"type": "string",
"example": "Soziologie"
}
}
}
},
"vlb": {
"type": "array",
"description": "VLB (German book trade) subject codes.",
"items": {
"type": "string"
},
"example": [
"720"
]
}
}
}
Response 400 Bad Request
{
"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."
}
}
}
}
}
}
Response 403 Forbidden
DELETE /resource/v3/subjects/{id}
Delete subject
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | string | No | The unique identifier of the subject |
Response 204 No Content
Response 400 Bad Request
{
"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."
}
}
}
}
}
}
Response 403 Forbidden
GET /resource/v3/subjects/{subject_id}/texts
Retrieve a list of subject texts of subject
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
subject_id |
path | string | No | The unique identifier of the subject |
Response 200 OK
{
"_links": {},
"_pagination": {},
"items": [
{
"_id": "4cb7d96c-6f72-470e-884c-6b96bb99a22e",
"_links": {
"self": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"language": "eng",
"mime_type": "text/plain",
"text": "long-text-lorem-ipsom",
"timestamp": 1743391587,
"type": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
]
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_links": {
"type": "object"
},
"_pagination": {
"type": "object"
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the subject text",
"example": "4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"example": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
}
}
},
"language": {
"type": "string",
"description": "Language code in ISO 639-2 format indicating the language of the text.",
"example": "eng"
},
"mime_type": {
"type": "string",
"description": "MIME type of the text content.",
"example": "text/plain"
},
"text": {
"type": "string",
"example": "long-text-lorem-ipsom",
"description": "The actual text content."
},
"timestamp": {
"type": "integer",
"description": "Unix timestamp representing creation or modification time.",
"example": 1743391587
},
"type": {
"type": "string",
"description": "The type of text, such as a description or title.",
"example": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
}
}
}
},
"required": [
"_links",
"_pagination",
"items"
]
}
Response 403 Forbidden
POST /resource/v3/subjects/{subject_id}/texts
Create a new subject text
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
subject_id |
path | string | No | The unique identifier of the subject |
Request body
{
"_id": "4cb7d96c-6f72-470e-884c-6b96bb99a22e",
"_links": {
"self": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"language": "eng",
"mime_type": "text/plain",
"text": "long-text-lorem-ipsom",
"timestamp": 1743391587,
"type": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the subject text",
"example": "4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"example": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
}
}
},
"language": {
"type": "string",
"description": "Language code in ISO 639-2 format indicating the language of the text.",
"example": "eng"
},
"mime_type": {
"type": "string",
"description": "MIME type of the text content.",
"example": "text/plain"
},
"text": {
"type": "string",
"example": "long-text-lorem-ipsom",
"description": "The actual text content."
},
"timestamp": {
"type": "integer",
"description": "Unix timestamp representing creation or modification time.",
"example": 1743391587
},
"type": {
"type": "string",
"description": "The type of text, such as a description or title.",
"example": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
}
}
Response 201 Created
{
"_id": "4cb7d96c-6f72-470e-884c-6b96bb99a22e",
"_links": {
"self": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"language": "eng",
"mime_type": "text/plain",
"text": "long-text-lorem-ipsom",
"timestamp": 1743391587,
"type": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the subject text",
"example": "4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"example": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
}
}
},
"language": {
"type": "string",
"description": "Language code in ISO 639-2 format indicating the language of the text.",
"example": "eng"
},
"mime_type": {
"type": "string",
"description": "MIME type of the text content.",
"example": "text/plain"
},
"text": {
"type": "string",
"example": "long-text-lorem-ipsom",
"description": "The actual text content."
},
"timestamp": {
"type": "integer",
"description": "Unix timestamp representing creation or modification time.",
"example": 1743391587
},
"type": {
"type": "string",
"description": "The type of text, such as a description or title.",
"example": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
}
}
Response 400 Bad Request
{
"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."
}
}
}
}
}
}
Response 403 Forbidden
GET /resource/v3/subjects/{subject_id}/texts/{id}
Retrieve a single subject text by ID
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | string | No | The unique identifier of the subject text | |
subject_id |
path | string | No | The unique identifier of the subject |
Response 200 OK
{
"_id": "4cb7d96c-6f72-470e-884c-6b96bb99a22e",
"_links": {
"self": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"language": "eng",
"mime_type": "text/plain",
"text": "long-text-lorem-ipsom",
"timestamp": 1743391587,
"type": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the subject text",
"example": "4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"example": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
}
}
},
"language": {
"type": "string",
"description": "Language code in ISO 639-2 format indicating the language of the text.",
"example": "eng"
},
"mime_type": {
"type": "string",
"description": "MIME type of the text content.",
"example": "text/plain"
},
"text": {
"type": "string",
"example": "long-text-lorem-ipsom",
"description": "The actual text content."
},
"timestamp": {
"type": "integer",
"description": "Unix timestamp representing creation or modification time.",
"example": 1743391587
},
"type": {
"type": "string",
"description": "The type of text, such as a description or title.",
"example": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
}
}
Response 403 Forbidden
PUT /resource/v3/subjects/{subject_id}/texts/{id}
Update subject text
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | string | No | The unique identifier of the subject text | |
subject_id |
path | string | No | The unique identifier of the subject |
Request body
{
"_id": "4cb7d96c-6f72-470e-884c-6b96bb99a22e",
"_links": {
"self": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"language": "eng",
"mime_type": "text/plain",
"text": "long-text-lorem-ipsom",
"timestamp": 1743391587,
"type": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
Schema of the request body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the subject text",
"example": "4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"example": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
}
}
},
"language": {
"type": "string",
"description": "Language code in ISO 639-2 format indicating the language of the text.",
"example": "eng"
},
"mime_type": {
"type": "string",
"description": "MIME type of the text content.",
"example": "text/plain"
},
"text": {
"type": "string",
"example": "long-text-lorem-ipsom",
"description": "The actual text content."
},
"timestamp": {
"type": "integer",
"description": "Unix timestamp representing creation or modification time.",
"example": 1743391587
},
"type": {
"type": "string",
"description": "The type of text, such as a description or title.",
"example": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
}
}
Response 200 OK
{
"_id": "4cb7d96c-6f72-470e-884c-6b96bb99a22e",
"_links": {
"self": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"language": "eng",
"mime_type": "text/plain",
"text": "long-text-lorem-ipsom",
"timestamp": 1743391587,
"type": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
Schema of the response body
{
"type": "object",
"additionalProperties": false,
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the subject text",
"example": "4cb7d96c-6f72-470e-884c-6b96bb99a22e"
},
"_links": {
"type": "object",
"additionalProperties": false,
"properties": {
"self": {
"type": "string",
"example": "https://api.openpublishing.com/resource/v3/subjects/ed7eaaa5-699a-491b-a5da-29e2d49caa46/texts/4cb7d96c-6f72-470e-884c-6b96bb99a22e"
}
}
},
"language": {
"type": "string",
"description": "Language code in ISO 639-2 format indicating the language of the text.",
"example": "eng"
},
"mime_type": {
"type": "string",
"description": "MIME type of the text content.",
"example": "text/plain"
},
"text": {
"type": "string",
"example": "long-text-lorem-ipsom",
"description": "The actual text content."
},
"timestamp": {
"type": "integer",
"description": "Unix timestamp representing creation or modification time.",
"example": 1743391587
},
"type": {
"type": "string",
"description": "The type of text, such as a description or title.",
"example": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua."
}
}
}
Response 400 Bad Request
{
"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."
}
}
}
}
}
}
Response 403 Forbidden
DELETE /resource/v3/subjects/{subject_id}/texts/{id}
Delete subject text
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
id |
path | string | No | The unique identifier of the subject text | |
subject_id |
path | string | No | The unique identifier of the subject |
Response 204 No Content
Response 400 Bad Request
{
"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."
}
}
}
}
}
}
Response 403 Forbidden
Schemas
Subject
| Name | Type |
|---|---|
_id |
integer Unique identifier for the subject
Example: |
_links |
|
_uuid |
string ID of resource in V4 version of resource |
_version |
string API Version
Example: |
bisac |
Array<string> |
description |
string| null A brief description of the subject.
Example: |
identifier |
string| null External identifier for the subject. |
labels |
Array<string> |
name |
Array<Properties: language, text> |
realm |
Properties: _id, _uuid, _links, name, screennameReference to realm which owns this object |
vlb |
Array<string> |
Subject Text
| Name | Type |
|---|---|
_id |
string Unique identifier for the subject text
Example: |
_links |
Properties: self |
language |
string Language code in ISO 639-2 format indicating the language of the text.
Example: |
mime_type |
string MIME type of the text content.
Example: |
text |
string The actual text content.
Example: |
timestamp |
integer Unix timestamp representing creation or modification time.
Example: |
type |
string The type of text, such as a description or title.
Example: |