Create a project

This guide explains how to create a monitoring project and save the ID needed in subsequent steps.

Prerequisites

• A Sociovite account with a valid username and password

1. Log in

curl -X POST \
  "$SOCIOVITE_API_URL/api/auth/login" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

The 200 response contains a top-level token:

{
  "token": "eyJhbGciOi...",
  "expires_at": "2026-07-29T23:26:03.041292+07:00",
  "roles": [
    "user"
  ],
  "user": {
    "id": "user_id",
    "userId": "user_id",
    "name": "Example User",
    "email": "user@example.com",
    "username": "your_username"
  }
}

Use this value as <access_token> in subsequent requests. See the login reference for error details and response fields.

2. Prepare the project

All of these fields are required:

Field	Purpose
group	An easily recognizable project name
keyword	The keyword to monitor
categoryId	Project category
startDate	Start of the collection period
endDate	End of the collection period
type	manual or auto

exclude is optional.

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.

This example uses the YYYY-MM-DD date format, but Swagger does not explicitly prescribe a date format. Confirm the format accepted by the target environment.

3. Create the project

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"
  }'

On success, the API returns 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"
  }
}

Save data.id.

Identifier terminology

Swagger calls this value a project ID on project-management operations but uses keyword-ID names on scraping, mentions, and summary operations. This guide follows the current app-flow assumption that data.id is the value to pass to those operations. Confirm the mapping if the deployed backend returns a separate keyword ID.

Next steps

1. Review how the keyword field is represented.
2. Start collection and read mentions.
3. See every field and category in the POST /api/project reference.

Troubleshooting

Symptom	Check
400 Bad Request	Include all six required fields and use manual or auto for type.
401 Unauthorized	Send the login token as Authorization: Bearer <access_token>.
Date rejected	Swagger types dates as strings but does not define the required format; confirm backend expectations.