Contents API

Manage contents of your Knowledge Bases.

The Content model

Properties

_id String - The unique identifier for the contents which is given by Pingstreams.
name String - The content name.
id_project String - The unique identifier of the project
type String - The type of the content. Supported types: url, text, pdf, docx, faq
source String - The content source.
content String - The textual content of a source. Is empty if the type is not text
namespace String - The namespace id to which the content belongs
status Number - The content status. Admissible status: -1 (not in queue), 100 (in queue), 200 (in indexing), 300 (indexed), 400 (error)

Get all contents of a knowledge base

GET https://api.pingstreams.com/v3/:project_id/kb/

Allows to list all the content of a knowledge base

Path Parameters

project_id string - The Project Id is a unique code assigned to your project when you create it in Pingstreams.

Query Parameters

namespace string - The Namespace Id is a unique code assigned to your knowledge base when you create it in Pingstreams.
status number - (Optional) To list all content in a determined indexing status.
type string - (Optional) To list all content of a determined status.
limit number - (Optional) Determines the number of contents returned (used for pagination).
page number - (Optional) Determines the number of the page (used for pagination).
sortField string - (Optional) Determines the field on which to sort.
direction number - (Optional) Determines the sorting direction. -1 (descending order), 1 (ascending order)
search string - (Optional) The text to search for in the source field

Headers

Authorization string - Authorization token. Basic Auth or JWT

Response

{
  "count": 2,
  "query": {
    "limit": 20,
    "sortField": "updatedAt",
    "direction": -1
  },
  "kbs": [
    {
      "_id": "667941c90d6bac990eb908da",
      "id_project": "63ad512e70d5ed0012ad6286",
      "source": "Return an item",
      "type": "text",
      "__v": 0,
      "content": "Return an item content sample",
      "createdAt": "2024-06-24T09:52:09.613Z",
      "name": "Return an item",
      "namespace": "63ad512e70d5ed0012ad6286",
      "status": 300,
      "updatedAt": "2024-06-24T09:52:11.698Z"
    },
    {
      "_id": "6679419c0d6bac990eb8452f",
      "id_project": "63ad512e70d5ed0012ad6286",
      "source": "Shipping information",
      "type": "text",
      "__v": 0,
      "content": "Shipping informazione content sample.",
      "createdAt": "2024-06-24T09:51:24.835Z",
      "name": "Shipping information",
      "namespace": "63ad512e70d5ed0012ad6286",
      "status": 300,
      "updatedAt": "2024-06-24T09:51:26.278Z"
    }
  ]
}

Example

curl -v -X GET -u user@example.com:password \
  "https://api.pingstreams.com/v3/63ad512e70d5ed0012ad6286/kb?direction=-1&sortField=updatedAt&namespace=63ad512e70d5ed0012ad6286&limit=20"

Get content detail

GET https://api.pingstreams.com/v3/:project_id/kb/:content_id

Allows to get the content detail

Path Parameters

project_id string - The Project Id is a unique code assigned to your project when you create it in Pingstreams.
content_id string - The content Id is a unique code assigned to your content.

Headers

Authorization string - Authorization token. Basic Auth or JWT

Response

{
  "_id": "66794d310d6bac990ef72ed3",
  "id_project": "63ad512e70d5ed0012ad6286",
  "source": "Shipping information",
  "type": "text",
  "__v": 0,
  "content": "Shipping information content sample.",
  "createdAt": "2024-06-24T09:51:24.835Z",
  "name": "Shipping information",
  "namespace": "63ad512e70d5ed0012ad6286",
  "status": 300,
  "updatedAt": "2024-06-24T09:51:26.278Z"
}

Example

curl -v -X GET -u user@example.com:password \
  https://api.pingstreams.com/v3/63ad512e70d5ed0012ad6286/kb/66794d310d6bac990ef72ed3

Add a content to a knowledge base

POST https://api.pingstreams.com/v3/:project_id/kb/

Allows to create and add a content to a specific knwoledge base

Path Parameters

project_id string - The Project Id is a unique code assigned to your project when you create it in Pingstreams.

Headers

Authorization string - Authorization token. Basic Auth or JWT

Request Body

name string - The name of the content
type string - The type of the content. It can be text, url, pdf, docx or faq.
source string - The source name of a content. If the content type is url, pdf or docx the source field must be the resource’s url.
content string - The content field of the content entity. Is empty if the type is url, pdf or docx. If the type is faq the content should be Question\nAnswer.
namespace string - The namespace id to which the content belongs.

Response

{
  "lastErrorObject": {
    "n": 1,
    "updatedExisting": false,
    "upserted": "6679502d0d6bac990e06c2fb"
  },
  "value": {
    "_id": "6679502d0d6bac990e06c2fb",
    "id_project": "63ad512e70d5ed0012ad6286",
    "source": "https://eu.rtmv3.pingstreams.com/api/files?path=uploads/users/63ad512170d5ed0012ad6279/files/09d40382-3755-4d87-8cb5-e345b7fcf418/my_awesome_file.pdf",
    "type": "pdf",
    "__v": 0,
    "content": "",
    "createdAt": "2024-06-24T10:53:33.368Z",
    "name": "my_awesome_file.pdf",
    "namespace": "63ad512e70d5ed0012ad6286",
    "status": -1,
    "updatedAt": "2024-06-24T10:53:33.368Z"
  }
}

Example

curl -v -X POST -u user@example.com:password \
  -d '{"type":"pdf","source":"https://eu.rtmv3.pingstreams.com/api/files?path=uploads/users/63ad512170d5ed0012ad6279/files/09d40382-3755-4d87-8cb5-e345b7fcf418/my_awesome_file.pdf","content":"","name":"my_awesome_file.pdf","namespace":"63ad512e70d5ed0012ad6286"}' \
  https://api.pingstreams.com/v3/63ad512e70d5ed0012ad6286/kb/

Add multiple URL contents to a knowledge base

POST https://api.pingstreams.com/v3/:project_id/kb/multi

Allows to add more than one content of type url to a specific knwoledge base in a single operation.

Path Parameters

project_id string - The Project Id is a unique code assigned to your project when you create it in Pingstreams.

Query Parameters

namespace string - The Namespace Id is a unique code assigned to your knowledge base when you create it in Pingstreams.

Headers

Authorization string - Authorization token. Basic Auth or JWT

Request Body

list array - The array of URLs to be added to the knwoledge base.

Response

[
  {
    "_id": "667954840d6bac990e1dc383",
    "id_project": "63ad512e70d5ed0012ad6286",
    "source": "https://mysite.com/content_1",
    "type": "url",
    "content": "",
    "createdAt": "2024-06-24T11:12:04.080Z",
    "name": "https://mysite.com/content_1",
    "namespace": "63ad512e70d5ed0012ad6286",
    "status": -1,
    "updatedAt": "2024-06-24T11:12:04.080Z"
  },
  {
    "_id": "667954840d6bac990e1dc399",
    "id_project": "63ad512e70d5ed0012ad6286",
    "source": "https://mysite.com/content_2",
    "type": "url",
    "content": "",
    "createdAt": "2024-06-24T11:12:04.080Z",
    "name": "https://mysite.com/content_2",
    "namespace": "63ad512e70d5ed0012ad6286",
    "status": -1,
    "updatedAt": "2024-06-24T11:12:04.080Z"
  },
  {
    "_id": "667954840d6bac990e1dc3be",
    "id_project": "63ad512e70d5ed0012ad6286",
    "source": "https://mysite.com/content_3",
    "type": "url",
    "content": "",
    "createdAt": "2024-06-24T11:12:04.080Z",
    "name": "https://mysite.com/content_3",
    "namespace": "63ad512e70d5ed0012ad6286",
    "status": -1,
    "updatedAt": "2024-06-24T11:12:04.080Z"
  }
]

Example

curl -v -X POST -u user@example.com:password \
  -d '{"list": ["https://mysite.com/content_1", "https://mysite.com/content_2", "https://mysite.com/content_3"]}' \
  "https://api.pingstreams.com/v3/63ad512e70d5ed0012ad6286/kb/multi?namespace=63ad512e70d5ed0012ad6286"

Convert a sitemap in a list of URLs

POST https://api.pingstreams.com/v3/:project_id/kb/sitemap

Allows to convert a sitemap into a list of urls to be uploaded later in a single operation.

Path Parameters

project_id string - The Project Id is a unique code assigned to your project when you create it in Pingstreams.

Headers

Authorization string - Authorization token. Basic Auth or JWT

Request Body

list array - The array of URLs to be added to the knwoledge base.

Response

{
  "url": "https://gethelp.pingstreams.com/sitemap.xml",
  "sites": [
    "https://gethelp.pingstreams.com/articles/activities-log/",
    "https://gethelp.pingstreams.com/articles/define-the-operating-hours/",
    "https://gethelp.pingstreams.com/articles/how-do-invite-a-teammate/",
    "https://gethelp.pingstreams.com/articles/understanding-default-roles/"
  ],
  "errors": []
}

Example

curl -v -X POST -u user@example.com:password \
  -d '{"sitemap": "https://gethelp.pingstreams.com/sitemap.xml"}' \
  https://api.pingstreams.com/v3/63ad512e70d5ed0012ad6286/kb/sitemap

Delete a content from the knowledge base

DELETE https://api.pingstreams.com/v3/:project_id/kb/:content_id

Allows to delete a single content from the knowledge base.

Path Parameters

project_id string - The Project Id is a unique code assigned to your project when you create it in Pingstreams.
content_id string - The Content Id is a unique code assigned to your contnet when you create it.

Headers

Authorization string - Authorization token. Basic Auth or JWT

Response

{
  "_id": "66794d950d6bac990ef90e3d",
  "id_project": "63ad512e70d5ed0012ad6286",
  "source": "Use a Voucher",
  "type": "text",
  "__v": 0,
  "content": "Use a Voucher content sample",
  "createdAt": "2024-06-24T10:42:29.798Z",
  "name": "Use a Voucher",
  "namespace": "63ad512e70d5ed0012ad6286",
  "status": 300,
  "updatedAt": "2024-06-24T10:42:31.202Z"
}

Example

curl -v -X DELETE -u user@example.com:password \
  https://api.pingstreams.com/v3/63ad512e70d5ed0012ad6286/kb/66794d950d6bac990ef90e3d