Application flow

This page shows how the documented endpoints fit together. It focuses on dependencies between calls: which value to save and where to use it next.

Flow at a glance

Login
  │
  ├─► Validate session / read profile
  │
  └─► Check quota
         │
         ▼
     Create project
         │
         └─ save response.data.id
                    │
                    ▼
              Enable listening
              (`islisten = 1`)
                    │
                    ▼
              Start scraping
                    │
                    ├─► Read mentions / content count
                    ├─► Change listening status
                    │      └─ when re-enabled,
                    │         start scraping again
                    └─► Delete project

Finish: logout current session or logout all devices

1. Log in

Call POST /api/auth/login with username and password.

Save these response values:

Value	Used for
token	Authorization: Bearer <token> on protected endpoints
expires_at	Deciding when the client must renew or end the session
user and roles	Client-side identity and authorization display

You can validate the token with GET /api/auth/session or read the current profile with GET /api/auth/me.

2. Optionally check quota

Call GET /api/user-quota when the client needs to display or inspect remaining quota. The endpoint returns the authenticated user's id and kuota.

3. Create a project

Call POST /api/project with all six required fields:

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

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

Save data.id from the 201 response. Project-management endpoints use it as a project ID.

Use GET /api/project?page=1&limit=10 to retrieve existing projects.

4. Start data collection

Data collection requires two API calls in sequence.

4.1 Enable listening

Call PATCH /api/project/listen-status with islisten set to 1:

{
  "id": "<data.id from project creation>",
  "islisten": 1
}

4.2 Start scraping

After listening is active, call POST /api/ai-service/scrap-project-keywords:

{
  "keyword_id": "<data.id from project creation>"
}

Call sequence

Setting islisten to 1 only enables listening status. Scraping must still be triggered by calling POST /api/ai-service/scrap-project-keywords.

The Swagger response contains success and an untyped result, but does not clarify dispatch versus completion and does not define a job ID or status endpoint. Do not build polling against an undocumented /status route.

5. Read results

Use the saved ID in these calls:

Goal	Request
Read mentions	GET /api/mentions?keywordId=<id>&page=1&limit=10
Count all collected content	GET /api/project/content-count?id=<id>
Count content for one source	GET /api/project/content-count?id=<id>&sosmedId=<source>

keywordId is required for mentions. sentimen and sosmedId are optional filters.

Supported sosmedId values:

• twitter
• facebook
• youtube
• tiktok
• instagram
• news

6. Generate an AI summary

After mentions are available:

1. Call POST /api/project/generate-summary/<id> to generate a summary.
2. Call GET /api/project/summary/<id> to retrieve the saved summary later.

The generate endpoint returns a structured sentiment_distribution. The retrieve endpoint returns sentiment_distribution as a string; parse it as JSON only when the runtime value is valid serialized JSON.

7. Manage or remove the project

• Set listening status with PATCH /api/project/listen-status:
  • use islisten: 1 to enable listening;
  • use islisten: 0 to disable listening.
• When listening is re-enabled from 0 to 1, call POST /api/ai-service/scrap-project-keywords again to start scraping.
• Delete the project with DELETE /api/project?id=<id>.

Deletion is permanent from the API consumer's perspective. Confirm the ID before sending the request.

8. End the session

Choose the endpoint based on scope:

Goal	Authentication	Payload
End the supplied/current session	POST /api/auth/logout	JSON body containing token
Revoke every session for the user	POST /api/auth/logout-all	Bearer token, no body