Sociovite API

The Sociovite API lets an authenticated client create monitoring projects, collect social-media mentions, inspect quota, and generate AI summaries.

This documentation follows Sociovite Swagger 2.0, API version 1.2. It adds task-oriented guides and application flow without inventing endpoints that are not present in that contract.

What you can do

Capability	Endpoint
Sign in and manage sessions	/api/auth/*
Create, list, change listen status, and delete projects	/api/project*
Start keyword scraping	/api/ai-service/scrap-project-keywords
Read collected mentions	/api/mentions
Generate and retrieve AI summaries	/api/project/*summary*
Check the authenticated user's quota	/api/user-quota

Authentication

Most endpoints use a bearer access token:

Authorization: Bearer <access_token>

Start by calling POST /api/auth/login. Its response contains token; use that value as the bearer token for protected endpoints.

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

See Authentication API for login, token refresh, session validation, and logout details.

Identifier terminology

In this documentation:

• Project ID means the returned data.id when a project endpoint asks for id.
• Keyword ID means a value requested by a field named keywordID, keywordId, or keyword_id.
• Parameter names remain exactly as defined by the API because their casing is significant.

The existing application flow assumes data.id is also the keyword ID used by scraping, mentions, and summaries. Confirm that inference if the deployed backend exposes a separate keyword identifier. For example, the mentions endpoint requires keywordId, while the scraping request body requires keyword_id.

Typical request flow

1. Log in and store the bearer token.
2. Optionally check quota.
3. Create a project and store data.id.
4. Start scraping with that ID.
5. Retrieve mentions using that ID as keywordId.
6. Generate and retrieve a summary.
7. Log out the current session or all devices.

Continue with the Application flow for an endpoint-by-endpoint walkthrough.