Project API

Create and manage monitoring projects, inspect collected-content counts, and generate summaries.

Base path: /api/project

All endpoints require:

Authorization: Bearer <access_token>

Identifier and field naming

The API uses different casing between requests and responses:

create request: categoryId, startDate, endDate;
project response: categoryid, start_date, end_date, updatedAt;
related APIs: keyword_id, keywordId, and keywordID.

Endpoint overview

Method	Path	Purpose
`GET`	`/api/project`	List projects
`POST`	`/api/project`	Create a project
`DELETE`	`/api/project?id=<id>`	Delete a project
`GET`	`/api/project/content-count?id=<id>`	Count collected content
`PATCH`	`/api/project/listen-status`	Enable or disable listening
`POST`	`/api/project/generate-summary/{keywordID}`	Generate an AI summary
`GET`	`/api/project/summary/{keywordID}`	Retrieve a stored summary

List projects

`GET /api/project`

Return projects using page-based pagination.

Query parameters:

Parameter	Type	Required	Default	Description
`page`	integer	No	`1`	Page number
`limit`	integer	No	`10`	Items per page; maximum 100

Success response — 200 OK:

{
  "data": [
    {
      "id": "project_id",
      "group": "Acme July Monitoring",
      "keyword": "acme",
      "exclude": "",
      "islisten": 1,
      "updatedAt": "2026-07-20T08:35:00Z",
      "categoryid": "umum",
      "start_date": "2026-07-01",
      "end_date": "2026-07-31",
      "type": "manual"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10,
  "totalPages": 1
}

Other response: 500 for an internal server error.

curl \
  "$SOCIOVITE_API_URL/api/project?page=1&limit=10" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Create a project

`POST /api/project`

Create one monitoring project.

Request body: application/json

Field	Type	Required	Constraints
`group`	string	Yes	2–100 characters
`keyword`	string	Yes	2–255 characters
`categoryId`	string	Yes	See allowed values below
`startDate`	string	Yes	Swagger does not declare a date format
`endDate`	string	No	Optional end date; Swagger does not declare a date format
`type`	string	Yes	`manual` or `auto`
`exclude`	string	No	At most 1,000 characters

Keyword format

The keyword field can use the and and or operators. Supported formats include:

kopi and kapal api
kopi or kapal api
kopi and kapal api or kopi kapal api

Keep the operators formatted as shown so the keyword expression can be processed correctly.

Allowed categoryId values listed in the operation description:

sosial-budaya
ideologi
politik
ekonomi
pertahanan-keamanan
semua
umum
olahraga
sosial
budaya
teknologi
hiburan
kesehatan
pendidikan
agama

Example request:

{
  "categoryId": "umum",
  "endDate": "2026-07-31",
  "exclude": "acme university",
  "group": "Acme July Monitoring",
  "keyword": "acme",
  "startDate": "2026-07-01",
  "type": "manual"
}

endDate is optional:

If endDate is omitted or null, scraping continues while the project remains active.
If endDate is supplied, scraping stops after the specified date is reached.

Dates in this example use YYYY-MM-DD.

Success response — 201 Created:

{
  "message": "Group successfully added",
  "data": {
    "id": "project_id",
    "group": "Acme July Monitoring",
    "keyword": "acme",
    "exclude": "acme university",
    "islisten": 0,
    "updatedAt": "2026-07-20T08:35:00Z",
    "categoryid": "umum",
    "start_date": "2026-07-01",
    "end_date": "2026-07-31",
    "type": "manual"
  }
}

Store data.id. Project-management endpoints accept it as id; the current app flow also uses it for parameters named as keyword IDs, subject to the identifier caveat above.

Other responses:

Status	Meaning
`400`	Invalid request body or missing required fields
`500`	Internal server error

curl -X POST \
  "$SOCIOVITE_API_URL/api/project" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "categoryId": "umum",
    "endDate": "2026-07-31",
    "exclude": "acme university",
    "group": "Acme July Monitoring",
    "keyword": "acme",
    "startDate": "2026-07-01",
    "type": "manual"
  }'

Delete a project

`DELETE /api/project`

Delete a project by ID.

Query parameters:

Parameter	Type	Required
`id`	string	Yes

Success response — 200 OK:

{
  "message": "Project deleted successfully"
}

Other responses:

Status	Meaning
`400`	Required `id` is missing
`401`	User authentication is required
`404`	Project not found
`500`	Internal server error

curl -X DELETE \
  "$SOCIOVITE_API_URL/api/project?id=project_id" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Get content count

`GET /api/project/content-count`

Count collected content for a project, optionally filtered by social-media source.

Query parameters:

Parameter	Type	Required	Description
`id`	string	Yes	Project ID
`sosmedId`	string	No	Social-media source ID

Supported sosmedId values:

twitter
facebook
youtube
tiktok
instagram
news

Success response — 200 OK:

{
  "data": 4
}

Other responses:

Status	Meaning
`400`	`id` is required
`404`	Project not found
`500`	Internal server error

curl \
  "$SOCIOVITE_API_URL/api/project/content-count?id=project_id&sosmedId=social_media_id" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Update listen status

`PATCH /api/project/listen-status`

Enable or disable listening for a project.

Request body: application/json

Field	Type	Required	Constraints
`id`	string	Yes	At most 100 characters
`islisten`	integer	Yes	`1` to listen, `0` not to listen

{
  "id": "project_id",
  "islisten": 1
}

Success response — 200 OK:

{
  "id": "project_id",
  "group": "Acme July Monitoring",
  "keyword": "acme",
  "exclude": "",
  "islisten": 1,
  "updatedAt": "2026-07-20T08:35:00Z",
  "categoryid": "umum",
  "start_date": "2026-07-01",
  "end_date": "2026-07-31",
  "type": "manual"
}

Other responses:

Status	Meaning
`400`	Invalid or missing parameters
`404`	Targeted group not found
`500`	Internal server error

curl -X PATCH \
  "$SOCIOVITE_API_URL/api/project/listen-status" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "project_id",
    "islisten": 1
  }'

Generate a summary

`POST /api/project/generate-summary/{keywordID}`

Ask the AI service to generate a summary for a keyword ID.

Path parameters:

Parameter	Type	Required
`keywordID`	string	Yes

Request body: None

Success response — 200 OK:

{
  "status": "success",
  "keyword_id": "keyword_id",
  "result": {
    "summary": "Summary of the collected mentions.",
    "metrics": {
      "sentiment_distribution": {
        "negative": 2,
        "neutral": 4,
        "positive": 8
      }
    }
  }
}

The keys inside sentiment_distribution are dynamic strings with integer counts.

Other responses:

Status	Meaning
`400`	Keyword ID is missing
`500`	Internal server error

curl -X POST \
  "$SOCIOVITE_API_URL/api/project/generate-summary/keyword_id" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Retrieve a summary

`GET /api/project/summary/{keywordID}`

Retrieve a previously generated summary.

Path parameters:

Parameter	Type	Required
`keywordID`	string	Yes

Success response — 200 OK:

{
  "id": "summary_id",
  "ai_summary": "Summary of the collected mentions.",
  "sentiment_distribution": "{\"neutral\":4,\"negative\":2,\"positive\":8}",
  "created_at": "2026-07-20T09:00:00Z",
  "keyword_id": "keyword_id"
}

Other responses:

Status	Meaning
`400`	Keyword ID is missing
`404`	Summary not found
`500`	Internal server error

curl \
  "$SOCIOVITE_API_URL/api/project/summary/keyword_id" \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <access_token>'

Error shape

Project errors use the shared model:

{
  "success": false,
  "error": "Invalid request",
  "message": "A required parameter is missing"
}

Identifier and field naming​

Endpoint overview​

List projects​

GET /api/project​

Create a project​

POST /api/project​

Delete a project​

DELETE /api/project​

Get content count​

GET /api/project/content-count​

Update listen status​

PATCH /api/project/listen-status​

Generate a summary​

POST /api/project/generate-summary/{keywordID}​

Retrieve a summary​

GET /api/project/summary/{keywordID}​

Error shape​

Identifier and field naming

Endpoint overview

List projects

`GET /api/project`

Create a project

`POST /api/project`

Delete a project

`DELETE /api/project`

Get content count

`GET /api/project/content-count`

Update listen status

`PATCH /api/project/listen-status`

Generate a summary

`POST /api/project/generate-summary/{keywordID}`

Retrieve a summary

`GET /api/project/summary/{keywordID}`

Error shape