The purpose of this article is to describe API endpoints for user needs tagging of provided articles.
API is designed to work asynchronously, schedule user needs tagging using URLs endpoint, which returns request id. Using that request, you check the status of tagging using the status endpoint and fetch results of tagging, if the request is successful using the user_needs endpoint.
Authentication
For authentication, api_key GET parameter should be set. Customer support should provide you with a valid key for authentication.
Example:
/api/brands/:brandId/user_needs/urls?api_key=xxxxxxxx
Endpoints
Content analysis
This way of usage implies the issuing an API call to /content endpoint, which in turn responds with detection results.
Content endpoint
This is a JSON POST endpoint
Endpoint path:
/api/brands/:brandId/user_needs/content
:brandId parameter is the id of your brand
JSON request payload example:
{
"content": "article full text"
}
URL object properties used to create request:
**content** - mandatory value
JSON response example:
{
"request_id": 2,
"request_status": "COMPLETED",
"user_needs": {
"action_driven": true,
"context_driven": true,
"emotion_driven": false,
"fact_driven": true
}
}
URL analysis
This way of usage follows a three-step process:
- Call /urls endpoint and pass URL/s to be analyzed. This call would return request_id which you would use in subsequent API calls
- Call /status endpoint on a periodic base (ex. every ten seconds) passing the request_id to check the status of the request until you receive a COMPLETED status for you request
- Once the status of your request is completed, call a /user_needs endpoint passing the original request_id to fetch results
Urls endpoint
This is a JSON POST endpoint
Endpoint path:
/api/brands/:brandId/user_needs/urls
:brandId parameter is the id of your brand
JSON request payload example:
URL object properties used to create request:
**url** - mandatory value, url of article to be fetched (please make sure domain matches the domain configured for specified brandid)
JSON response example:
Example 1
{
"request_id": 1,
"request_status": "PENDING"
}
Example 2
{
"request_id": 1,
"request_status": "COMPLETED",
"user_needs": [
{
"success": true,
"article_url": "www.test.com/article/123456",
"user_needs": {
"action_driven": true,
"context_driven": true,
"emotion_driven": false,
"fact_driven": true
},
{
"success": false,
"article_url": "www.test.com/4567"
}
]
}
**user_needs** - is returned only if request is in status COMPLETED
List of possible statuses:
- PENDING
- COMPLETED
- FAILED
Status endpoint
This is a GET endpoint
Endpoint path:
/api/brands/:brandId/user_needs/status/:request_id
:brandId parameter is the id of your brand
:request_id parameter is the id of request received in response of urls endpoint call
JSON response example:
{
"request_id": 1,
"request_status": "PENDING"
}
User needs endpoint
This is a GET endpoint
Endpoint path:
/api/brands/:brandId/user_needs/:request_id
:brandId parameter is the id of your brand
:request_id parameter is the id of request received in response of urls endpoint call
JSON response example:
{
"request_id": 1,
"request_status": "COMPLETED",
"user_needs": [
{
"success": true,
"article_url": "www.test.com/article/123456",
"user_needs": {
"action_driven": true,
"context_driven": true,
"emotion_driven": false,
"fact_driven": true
},
{
"success": false,
"article_url": "www.test.com/4567"
}
]
}
In case of errors you would get error HTTP code and JSON payload
Example:
Request:
GET /api/brands/:brandId/user_needs/1
Response:
HTTP code 404
Payload:
{
"message": "Request with id 1 not found"
}