API Reference

Create Bot

Endpoint

POST /v1/bots

Description

This endpoint allows you to create a new bot in the system. It requires specific parameters in the request body and query string, and upon successful creation, it will return the details of the newly created bot.

Authentication

• This endpoint requires bearer token authentication.

• Users must be authorized with the appropriate permissions to create a bot.

Request

Headers

Authorization: Bearer <your_token> or x-api-key: <your_api_key>
Content-Type: application/json

Query Parameters

• appId (string, required): The ID of the application to which the bot will be associated.

Request Body

The request body must be a JSON object that conforms to the BotCreateDTO structure:

{
    "username": "exampleBot",
    "password": "securePassword",
    "mail": "[e-mail]",
    "phone": "1234567890",
    "appAuthSecret": "secretKey123",
    "blueTick": false
}

Response

Success Response

On successful creation, the response will return a BotCreateResDTO structure that contains the bot's details:

{
    "data": {
        "id": "1728b82b-a338-4d34-af85-7a8695941ffd",
        "status": "ACTIVE",
        "errorMessage": null,
        "createdBy": "USER",
        "follower": null,
        "following": null,
        "username": "exampleBot",
        "mail": "[e-mail]",
        "phone": "1234567890",
        "proxyId": "proxy-id-123",
        "blueTick": false,
        "appAuthSecret": "secretKey123",
        "taskCount": 0,
        "profile": {
            "id": "profile-id-123",
            "createdAt": "2024-09-17T09:21:13.634Z",
            "updatedAt": "2024-10-02T02:34:27.148Z",
            "state": "DONE",
            "bio": null,
            "name": null,
            "banner": null,
            "avatar": null,
            "website": null
        },
        "histories": [],
        "createdAt": "2024-09-17T09:21:13.634Z"
    },
    "message": "success",
    "statusCode": 200
}

Error Responses

• 400 Bad Request: If the request is malformed or required parameters are missing.

  {
      "statusCode": 400,
      "message": "Validation failed",
      "error": "Bad Request"
  }
  

• 401 Unauthorized: If the user is not authenticated or does not have the necessary permissions.

{
    "statusCode": 401,
    "message": "Unauthorized",
    "error": "Unauthorized"
}

Example Usage

Here is an example of how to call the endpoint using curl:

curl -X POST "https://api.shillbot.xyz/v1/bots?appId=yourAppId" \
-H "Authorization: Bearer your_token" \
-H "Content-Type: application/json" \
-d '{
    "username": "exampleBot",
    "password": "securePassword",
    "mail": "[e-mail]",
    "phone": "1234567890",
    "proxyId": "proxy-id-123",
    "appAuthSecret": "secretKey123",
    "blueTick": false
}'

Notes

• Ensure that the username is unique and meets any constraints specified by your application.

• The appAuthSecret is sensitive and should be treated securely.

• Review the expected field types in the request body to ensure proper validation.

List Bot

Endpoint

GET /v1/bots

Description

This endpoint retrieves a paginated list of bots in the system based on specified query parameters. It provides information about each bot, including its status, username, email, and other relevant details.

Authentication

This endpoint requires bearer token authentication. Users must be authorized with the appropriate permissions to access the bot list.

Request

Headers

Authorization: Bearer <your_token> or x-api-key: <your_api_key>

Query Parameters

Parameter	Type	Required	Description
appId	string	Yes	The ID of the application to which the bots belong.
limit	number	No	The number of results to return per page. Default is 10.
offset	number	No	The number of items to skip before starting to collect the result set. Default is 0.
botState	string	No	The state of the bots to filter by (e.g., ACTIVE).
search	string	No	A search term to filter bots by their username, email, etc.
isDeleted	string	No	To filter bots based on their deletion status (e.g., true or false).

Example Request

GET https://api.shillbot.xyz/v1/bots?appId=yourAppId&limit=30&offset=0&botState=ACTIVE
Authorization: Bearer <your_token> or x-api-key: <your_api_key>

Response

Success Response

On a successful request, the response will return a BotPagingResDTO structure containing a paginated list of bots:

{
    "data": {
        "total": 9,
        "data": [
            {
                "status": "ACTIVE",
                "errorMessage": nu,
                "createdBy": "USER",
                "follower": null,
                "following": null,
                "username": "username",
                "mail": "[e-mail]",
                "phone": "0335845350",
                "proxyId": "140d0ca9-60e2-404f-862e-eb6462f16474",
                "blueTick": false,
                "appAuthSecret": "appAuthSecret",
                "taskCount": 2,
                "profile": {
                    "id": "843f9ad7-40f4-4d7b-8e8d-aecce93d9951",
                    "createdAt": "2024-09-17T09:21:13.634Z",
                    "updatedAt": "2024-10-02T02:34:27.148Z",
                    "state": "DONE",
                    "bio": null,
                    "name": null,
                    "banner": null,
                    "avatar": null,
                    "website": null
                },
                "histories": [],
                "id": "1728b82b-a338-4d34-af85-7a8695941ffd",
                "createdAt": "2024-09-17T09:17:36.276Z"
            },
            ...
        ],
        "active": 9,
        "isProfileUpdating": []
    },
    "path": "/v1/bots?limit=30&appId=fd8e0a24-f5de-4736-834d-9388f00e48eb&offset=0&botState=ACTIVE&endDate=2024-10-05T23:59:59.999Z&startDate=2024-10-05T00:00:00.000Z",
    "method": "GET",
    "message": "success",
    "statusCode": 200
}

Error Responses

• 400 Bad Request: If the request is malformed or required parameters are missing.

{
    "statusCode": 400,
    "message": "Validation failed",
    "error": "Bad Request"
}

• 401 Unauthorized: If the user is not authenticated or does not have the necessary permissions.

{
    "statusCode": 401,
    "message": "Unauthorized",
    "error": "Unauthorized"
}

Example Usage

Here is an example of how to call the endpoint using curl:

curl -X GET "https://api.shillbot.xyz/v1/bots?appId=yourAppId&limit=30&offset=0&botState=ACTIVE" \
-H "Authorization: Bearer your_token"

Notes

• Adjust the limit and offset parameters to paginate through results.

• The botState parameter can be used to filter results based on the bot's current status.

• Ensure that the appId corresponds to a valid application in your system.

Explanation of Main Fields

1. data: This is the main object containing the response details related to the bots.

   • total:

     • Type: Integer

     • Description: The total number of bot records available that match the query. In this case, it indicates there are 9 bots in total.

   • data:

     • Type: Array of Bot Objects

     • Description: An array of bot records that match the filtering criteria. Each object contains detailed information about an individual bot.

   • active:

     • Type: Integer

     • Description: The number of bots that are currently in an "ACTIVE" state. This indicates that there are 9 active bots in the current context.

   • isProfileUpdating:

     • Type: Array

     • Description: An empty array in this context. It might be intended to hold information about bots whose profiles are currently being updated, if applicable.

2. path:

   • Type: String

   • Description: The API endpoint path that was accessed, including the query parameters used in the request.

3. method:

   • Type: String

   • Description: The HTTP method used for the request (GET in this case).

4. message:

   • Type: String

   • Description: A brief description of the result of the API call (e.g., "success" indicates that the request was processed successfully).

5. statusCode:

   • Type: Integer

   • Description: The HTTP status code returned by the server. A value of 200 indicates that the request was successful.

Breakdown of Each Bot Object in the Data Array

Now, let's delve deeper into the fields of each bot object within the data array:

{
    "status": "ACTIVE",
    "errorMessage": "EXPIRE_SESSION",
    "createdBy": "USER",
    "follower": null,
    "following": null,
    "username": "username",
    "mail": "[e-mail]",
    "phone": "0335845350",
    "proxyId": "140d0ca9-60e2-404f-862e-eb6462f16474",
    "blueTick": false,
    "appAuthSecret": "appAuthSecret",
    "taskCount": 2,
    "profile": { ... },
    "histories": [ ... ],
    "id": "1728b82b-a338-4d34-af85-7a8695941ffd",
    "createdAt": "2024-09-17T09:17:36.276Z"
}

Field Descriptions

Field	Type	Description
status	string	The current status of the bot. It indicates whether the bot is active, locked, or in another state.
errorMessage	string (or null)	An error message associated with the bot, providing insights into issues that may affect its operation. For instance, "EXPIRE_SESSION" suggests session expiration.
createdBy	string	Indicates who created the bot (e.g., "USER" means it was created by a user, as opposed to the system).
follower	integer (or null)	The number of followers the bot has. It can be null if this information is not available.
following	integer (or null)	The number of accounts the bot is following. It can be null if this information is not available.
username	string	The unique username of the bot used in interactions.
mail	string (or null)	The email address associated with the bot, which can be used for notifications or recovery.
phone	string	The phone number associated with the bot, used for two-factor authentication or other communication purposes.
proxyId	string	Identifier for the proxy server associated with the bot, if applicable.
blueTick	boolean	Indicates whether the bot has a verified status (blue tick) on the platform it operates (e.g., Twitter).
appAuthSecret	string	A secret key used for authenticating the bot with the application. This is sensitive information and should be kept secure.
taskCount	integer	The number of tasks currently assigned to the bot.
profile	object	Contains detailed profile information about the bot, including fields such as id, createdAt, updatedAt, and any relevant profile details like bio, name, banner, avatar, and website.
histories	array of objects	An array containing the history of interactions or events related to the bot. Each history entry includes:
histories.id	string	Unique identifier for the history record.
histories.createdAt	datetime	Timestamp for when the history entry was created.
histories.updatedAt	datetime	Timestamp for when the history entry was last updated.
histories.type	string	The type of interaction (e.g., "BOT_INTERACTION").
interactionBot.id	string	Unique identifier for the interaction associated with the bot.
interactionBot.url	string (or null)	URL associated with the interaction, if applicable.
interactionBot.type	string	Type of interaction (e.g., "FOLLOW").
interactionBot.state	string	Current state of the interaction (e.g., "ERROR").
interactionBot.error	string (or null)	Specific error message related to the interaction, if any.
interactionBot.origin	string (or null)	The origin URL associated with the interaction.
interactionBot.createdAt	datetime	Timestamp indicating when the interaction was created.
interactionBot.updatedAt	datetime	Timestamp indicating when the interaction was last updated.
interactionBot.interactionAt	datetime	Timestamp tracking when the interaction occurred.
id	string	Unique identifier for the bot.
createdAt	datetime	Timestamp indicating when the bot was created.

BOT_STATUS Enum Breakdown

Status	Description	Use Case
ERROR	This status indicates that the bot has encountered an error that prevents it from functioning correctly. This could be due to network issues, authentication failures, or other critical errors.	The bot may need to be reviewed or restarted by a user or administrator to resolve the underlying issue.
ACTIVE	The bot is currently operational and functioning as intended. It is actively performing tasks or interacting with users on the platform.	Users can expect the bot to behave normally, performing tasks like posting updates or interacting with users.
LOCKED	The bot has been locked, likely due to security concerns, platform policy violations, or manual intervention by an administrator.	The bot cannot perform any actions until unlocked. Review activities to ensure compliance with platform rules.
WAITING	The bot is in a waiting state, ready to execute tasks once certain conditions are met (e.g., waiting for user input, a scheduled time, or resource availability).	Used during transitions or when the bot is waiting for further instructions before proceeding.
LOGGING	The bot is in the process of logging in or authenticating with a service. This state is temporary and should change to either ACTIVE or ERROR depending on the success of the login process.	Monitor authentication attempts to determine if the bot successfully connects to the platform it interacts with.
SUSPENDED	The bot is temporarily suspended from activity, possibly due to concerns or violations. It may require review before becoming active again.	A suspended bot may need user intervention or a review process before it can be reinstated to ACTIVE status.
PROXY_FAILED	The bot was unable to connect to or utilize the proxy server it relies on. This failure can hinder the bot's ability to perform tasks requiring internet access.	Users should check the proxy configuration and ensure the proxy server is reachable and operational.
LOGIN_CODE_REQUEST	The bot is waiting for a login code, typically required for two-factor authentication (2FA). This state persists until the user provides the necessary code.	The bot needs user intervention to retrieve and input the 2FA code to proceed with operations.

---

BOT_ERROR_MESSAGE Enum Breakdown

Error Message	Description	Use Case
AUTHENTICATION_REQUIRED	This error indicates that the bot is unable to authenticate with the platform or service. This could be due to missing or invalid credentials (e.g., username/password).	Prompts users to ensure the bot has correct authentication credentials and permissions to access the required resources.
PROXY_FAILED	This error indicates that the bot could not connect to the specified proxy server, possibly due to incorrect configuration or network issues.	Users should verify the proxy settings and ensure the proxy server is operational. Manual testing may be required.
EXPIRE_SESSION	This error indicates that the bot’s session has expired, often due to inactivity or expired authentication tokens.	Users may need to re-authenticate or refresh tokens to restore the bot's functionality.
INVALID_ACCOUNT	This error signifies that the account being used by the bot is invalid or no longer exists (e.g., deleted account or credential typos).	Users should verify the account details to ensure they are correct and that the account is active and valid.
BOT_INACTIVE	This error indicates that the bot is not active and unable to perform its tasks. It might have been deactivated or suspended by the platform.	Users should investigate the reason for the bot's inactivity and take actions to reactivate it, if necessary.
ACCOUNT_WAS_LOCKED	This error message indicates that the account associated with the bot has been locked, possibly due to suspicious activity or policy violations.	Users need to review the account status and may need to contact support to unlock the account before the bot can operate.
LOGIN_CODE_REQUEST	This error occurs when the bot is waiting for a login code, typically required for two-factor authentication (2FA).	Users should retrieve and input the 2FA code sent to their device or email to allow the bot to continue its operation.

---

Delete Bot By ID

Description

This endpoint allows you to delete (revoke) a bot from the system. The bot will be permanently removed, and the relevant data will no longer be accessible. The API call requires an authorized user with the appropriate permissions to delete a bot.

Request

• URL:

  DELETE https://api.shillbot.xyz/v1/bots/{botId}/revoke?appId={appId}

• Method: DELETE

• Authentication: This endpoint requires bearer token authentication or API key authentication.

  • Headers:

    • Authorization: Bearer <your_token> or x-api-key: <your_api_key>

    • Content-Type: application/json

• Query Parameters:

  • appId (string, required): The ID of the application to which the bot is associated.

• Path Parameters:

  • botId (string, required): The unique identifier of the bot to be deleted. Replace {botId} in the URL with the actual bot ID.

Example Request

curl -X DELETE "https://api.shillbot.xyz/v1/bots/310e4072-796f-4ef4-bd48-96e58a4082e3/revoke?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb" \
-H "Authorization: Bearer your_token" \
-H "Content-Type: application/json"

Response

On successful deletion, the response will return a JSON object with details about the bot that was deleted.

• Status Code: 200 OK

• Response Body:

{
    "data": {
        "follower": null,
        "username": "username",
        "id": "310e4072-796f-4ef4-bd48-96e58a4082e3"
    },
    "path": "/v1/bots/310e4072-796f-4ef4-bd48-96e58a4082e3/revoke?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb",
    "method": "DELETE",
    "message": "success",
    "statusCode": 200
}

Error Responses

• 401 Unauthorized: If the user is not authenticated or does not have the required permissions to delete the bot.

Notes

• Make sure the botId is valid and the user has the necessary permissions to delete the bot.

• The appId should correspond to the application associated with the bot.

Refresh Bot API

Description

This endpoint allows you to refresh a bot's session in case of an expired session, login errors, or other session-related issues. It updates the bot’s authentication details and ensures that the bot is logged in again successfully. This is particularly useful when a bot encounters a session expiration error.

Request

• URL:

PUT https://api.shillbot.xyz/v1/bots/{botId}?appId={appId}

• Authentication: This endpoint requires bearer token authentication or API key authentication.

  • Headers:

    • Authorization: Bearer <your_token> or x-api-key: <your_api_key>

    • Content-Type: application/json

• Query Parameters:

  • appId (string, required): The ID of the application to which the bot is associated.

• Path Parameters:

  • botId (string, required): The unique identifier of the bot to be refreshed. Replace {botId} in the URL with the actual bot ID.

• Request Body: The request body must include the updated status of the bot.

{
    "status": "WAITING"
}

Example Request

curl -X PUT "https://api.shillbot.xyz/v1/bots/42528b39-6349-4b08-b9ea-7105fa3ecbf4?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb" \
-H "Authorization: Bearer your_token" \
-H "Content-Type: application/json" \
-d '{
    "status": "WAITING"
}'

Response

On a successful update, the response will return the updated details of the bot.

• Status Code: 200 OK

Create Task

Endpoint:

POST /v1/tasks

Description

This endpoint allows users to create a new task in the system. It requires specific parameters in the request body and query string. Upon successful creation, it will return the details of the newly created task.

Authentication

This endpoint requires bearer token authentication. Users must be authorized with the appropriate permissions to create a task.

Request Headers

• Authorization: Bearer <your_token> or x-api-key: <your_api_key>

• Content-Type: application/json

Query Parameters

Name	Type	Required	Description
appId	string	Yes	The ID of the application to which the task will be associated.

Request Body

The request body must be a JSON object that conforms to the TaskCreateDTO structure:

{
    "title": "test",
    "categoryId": "c16c5afb-1992-4894-b9fd-e1721d4a4517",
    "postPerDay": 10,
    "botIds": [
        "1728b82b-a338-4d34-af85-7a8695941ffd",
        "1a1664e7-c90c-4498-a9a2-3755102cf410"
    ],
    "customerGroupIds": [
        "068ece90-f1db-4402-84c0-e5a5fa0be585"
    ],
    "type": "USERS",
    "templateContents": [
        "content",
        "content"
    ]
}

Field Descriptions

Field	Type	Required	Description
title	string	Yes	The title of the task being created.
categoryId	string	Yes	The ID of the category to which the task belongs.
postPerDay	number	Yes	The number of posts to be made per day for the task.
botIds	string[]	Yes	An array of bot IDs associated with the task.
customerGroupIds	string[]	Yes	An array of customer group IDs associated with the task.
type	TASK_TYPE enum	Yes	The type of task (e.g., USERS, POSTS, KEYWORDS, USER_KEYWORDS)
templateContents	string[]	Yes	An array of template content strings used for the task.

Response

On successful creation, the response will return a JSON object structured as follows:

Success Response

{
    "data": {
        "type": "USERS",
        "status": "RUNNING",
        "title": "test",
        "categoryId": "c16c5afb-1992-4894-b9fd-e1721d4a4517",
        "templateId": "345450c6-7a58-47f4-9973-4e18bf3e2d6a",
        "posts": [],
        "images": [],
        "keywords": [],
        "keywordAddTagIds": [],
        "keywordAddGroupIds": [],
        "id": "6df3b700-797e-44dc-9adc-1f3751969df8"
    },
    "path": "/v1/tasks?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb",
    "method": "POST",
    "message": "success",
    "statusCode": 200
}

Field Descriptions

Field	Type	Description
data	object	The main response object containing the task details.
data.type	string	The type of the task (e.g., "USERS").
data.status	string	The current status of the task (e.g., "RUNNING").
data.title	string	The title of the task being created.
data.categoryId	string	The ID of the category to which the task belongs.
data.templateId	string	The ID of the template associated with the task.
data.posts	array	An array of post IDs associated with the task (initially empty).
data.images	array	An array of images associated with the task (initially empty).
data.keywords	array	An array of keywords associated with the task (initially empty).
data.keywordAddTagIds	array	An array of tag IDs to add to keywords (initially empty).
data.keywordAddGroupIds	array	An array of group IDs to add to keywords (initially empty).
data.id	string	The unique ID of the created task.
path	string	The endpoint path used for the request.
method	string	The HTTP method used for the request (e.g., "POST").
message	string	A success message indicating the task creation was successful.
statusCode	number	The HTTP status code of the response (200 indicates success).

Error Responses

Status Code	Description	Example Response
400 Bad Request	If the request is malformed or required parameters are missing.	{ "statusCode": 400, "message": "Validation failed", "error": "Bad Request" }
401 Unauthorized	If the user is not authenticated or does not have the necessary permissions.	{ "statusCode": 401, "message": "Unauthorized", "error": "Unauthorized" }

Example Usage

Here is an example of how to call the endpoint using curl:

curl -X POST "https://api.shillbot.xyz/v1/tasks?appId=yourAppId" \
-H "Authorization: Bearer your_token" \
-H "Content-Type: application/json" \
-d '{
    "title": "test",
    "categoryId": "c16c5afb-1992-4894-b9fd-e1721d4a4517",
    "postPerDay": 10,
    "botIds": [
        "1728b82b-a338-4d34-af85-7a8695941ffd",
        "1a1664e7-c90c-4498-a9a2-3755102cf410"
    ],
    "customerGroupIds": [
        "068ece90-f1db-4402-84c0-e5a5fa0be585"
    ],
    "type": "USERS",
    "templateContents": [
        "content"
    ]
}'

Notes

• Ensure that the appId is valid and the user has the necessary permissions for the application.

• Review the expected field types in the request body to ensure proper validation.

Get List of Running Tasks

GET /v1/tasks

Description

This endpoint retrieves a paginated list of tasks that are currently running. Users can filter tasks based on various criteria, such as task type, status, category IDs, and search terms.

Request Headers

• Authorization: Bearer <your_token> or x-api-key: <your_api_key>

• Content-Type: application/json

Query Parameters

Name	Type	Required	Description
appId	string	Yes	The ID of the application associated with the tasks.
limit	number	No	The maximum number of tasks to return (default is 10).
offset	number	No	The number of tasks to skip before starting to collect the result set (default is 0).
search	string	No	A search string to filter tasks based on title or other criteria.
categoryIds	string[]	No	An array of category IDs to filter the tasks by specific categories.
type	string	No	The type of the tasks to filter (must be one of the defined TASK_TYPE enum values).
status	string	No	The status of the tasks to filter (must be one of the defined TASK_STATUS enum values).
isDeleted	string	No	To filter tasks based on their deletion status (if applicable).

Response

On successful retrieval, the response will return a JSON object structured as follows:

Success Response

{
    "data": {
        "data": [
            {
                "id": "6df3b700-797e-44dc-9adc-1f3751969df8",
                "type": "USERS",
                "title": "test",
                "status": "RUNNING",
                "categoryId": "c16c5afb-1992-4894-b9fd-e1721d4a4517",
                "templateId": "345450c6-7a58-47f4-9973-4e18bf3e2d6a",
                "posts": [],
                "images": [],
                "keywords": [],
                "keywordAddTagIds": [],
                "keywordAddGroupIds": [],
                "botIds": [],
                "customerGroupIds": [],
                "includeCustomerTagIds": [],
                "excludeCustomerTagIds": [],
                "botsCount": 0,
                "categoryName": "Category Name",
                "templateContents": []
            }
        ],
        "totalRunning": 10
    },
    "path": "/v1/tasks?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb",
    "method": "GET",
    "message": "success",
    "statusCode": 200
}

Field Descriptions

Field	Type	Description
data	object	The main response object containing the list of tasks.
data.data	array	An array of task objects returned by the API.
data.data[].id	string	The unique ID of the task.
data.data[].type	string	The type of the task (e.g., "USERS").
data.data[].title	string	The title of the task.
data.data[].status	string	The current status of the task (e.g., "RUNNING").
data.data[].categoryId	string	The ID of the category to which the task belongs.
data.data[].templateId	string	The ID of the template associated with the task.
data.data[].posts	array	An array of post IDs associated with the task (initially empty).
data.data[].images	array	An array of images associated with the task (initially empty).
data.data[].keywords	array	An array of keywords associated with the task (initially empty).
data.data[].keywordAddTagIds	array	An array of tag IDs to add to keywords (initially empty).
data.data[].keywordAddGroupIds	array	An array of group IDs to add to keywords (initially empty).
data.data[].botIds	array	An array of bot IDs associated with the task.
data.data[].customerGroupIds	array	An array of customer group IDs associated with the task.
data.data[].includeCustomerTagIds	array	An array of customer tag IDs to include in the task.
data.data[].excludeCustomerTagIds	array	An array of customer tag IDs to exclude from the task.
data.data[].botsCount	number	The count of bots associated with the task.
data.data[].categoryName	string	The name of the category to which the task belongs.
data.data[].templateContents	array	An array of contents associated with the task template (initially empty).
totalRunning	number	The total number of running tasks returned by the API.
path	string	The endpoint path used for the request.
method	string	The HTTP method used for the request (e.g., "GET").
message	string	A success message indicating that the task retrieval was successful.
statusCode	number	The HTTP status code of the response (200 indicates success).

Error Responses

Status Code	Description	Example Response
400 Bad Request	If the request is malformed or required parameters are missing.	{ "statusCode": 400, "message": "Validation failed", "error": "Bad Request" }
401 Unauthorized	If the user is not authenticated or does not have the necessary permissions.	{ "statusCode": 401, "message": "Unauthorized", "error": "Unauthorized" }

Example Usage

Here is an example of how to call the endpoint using curl:

curl -X GET "https://api.shillbot.xyz/v1/tasks?appId=yourAppId&limit=10&offset=0" \
-H Authorization: Bearer <your_token> or x-api-key: <your_api_key> \
-H "Content-Type: application/json"

Notes

• Ensure that the appId is valid and the user has the necessary permissions for the application.

• You can modify the limit and offset parameters to paginate through the list of tasks.

Get List of Spam

GET /spams

Description

This endpoint retrieves a paginated list of spam records. Users can filter spam based on various criteria, including status, bot IDs, task IDs, and date ranges.

Request Headers

• Authorization: Bearer <your_token> or x-api-key: <your_api_key>

• Content-Type: application/json

Query Parameters

Query Parameters

Name	Type	Required	Description
appId	string	Yes	The ID of the application associated with the spam records.
limit	number	No	The maximum number of spam records to return (default is 10).
offset	number	No	The number of spam records to skip before starting to collect the result set (default is 0).
status	string	No	The status of the spam records to filter (must be one of the defined SPAM_STATUS enum values).
taskIds	string[]	No	An array of task IDs to filter spam records associated with specific tasks.
botIds	string[]	No	An array of bot IDs to filter spam records associated with specific bots.
groupIds	string[]	No	An array of group IDs to filter spam records associated with specific groups.
startDate	Date	No	The start date for filtering spam records.
endDate	Date	No	The end date for filtering spam records.

Response

On successful retrieval, the response will return a JSON object structured as follows:

Success Response

{
    "data": {
        "data": [
            {
                "id": "75303efc-8424-4483-8abb-ffb089978574",
                "error": null,
                "status": "DONE",
                "postState": "CAN_POST",
                "postView": 0,
                "likeCount": 0,
                "replyCount": 0,
                "retweetCount": 0,
                "appId": "fd8e0a24-f5de-4736-834d-9388f00e48eb",
                "botId": "4363bbb1-15ee-4097-9185-4898c9c87c11",
                "jobId": "7710",
                "taskId": "b465d542-46a7-4162-aadc-374e2f00fe28",
                "images": [],
                "content": "this is content",
                "tweetId": "1841724411851710604",
                "tweetUrl": "https://x.com/AIIMSRDA/status/1841724411851710604",
                "customerId": "7f332bee-1587-48ab-8782-ddd8600e5751",
                "postTweetId": "1842356034062434384",
                "errorMessage": null,
                "paymentItemId": null,
                "interactionJobId": "7712",
                "increateViewJobId": null,
                "isInteraction": true,
                "postTime": "2024-10-05T00:07:11.745Z",
                "createdAt": "2024-10-05T00:02:11.997Z",
                "updatedAt": "2024-10-05T00:09:03.288Z",
                "interactionAt": "2024-10-05T00:09:03.287Z",
                "increateViewAt": null,
                "customer": {
                    "id": "7f332bee-1587-48ab-8782-ddd8600e5751",
                    "name": "AIIMSRDA",
                    "appId": "fd8e0a24-f5de-4736-834d-9388f00e48eb",
                    "isDeleted": false,
                    "isHide": true,
                    "taskCount": 1,
                    "interactionCount": 0,
                    "createdAt": "2024-10-05T00:02:11.940Z",
                    "updatedAt": "2024-10-05T00:08:05.294Z",
                    "lastPostAt": null,
                    "customerGroups": []
                },
                "interactions": [],
                "task": {
                    "id": "b465d542-46a7-4162-aadc-374e2f00fe28",
                    "title": "this is task name"
                },
                "bot": {
                    "id": "4363bbb1-15ee-4097-9185-4898c9c87c11",
                    "username": "this is bot name"
                }
            }
            // Additional spam records...
        ],
        "total": 14,
        "stat": {
            "views": 0,
            "likes": 0,
            "replies": 0,
            "reposts": 0
        }
    },
    "path": "/v1/spams?limit=30&appId=fd8e0a24-f5de-4736-834d-9388f00e48eb&offset=0&endDate=2024-10-05T23:59:59.999Z&startDate=2024-10-05T00:00:00.000Z",
    "method": "GET",
    "message": "success",
    "statusCode": 200
}

Field Descriptions

Field	Type	Description
data	object	The main response object containing the list of spam records.
data.data	array	An array of spam objects returned by the API.
data.data[].id	string	The unique ID of the spam record.
data.data[].error	string or null	Error message, if applicable (e.g., "TWEET_NOT_FOUND").
data.data[].status	string	The current status of the spam record (e.g., "DONE", "ERROR", "WAITING").
data.data[].postState	string	The state of the post (e.g., "CAN_POST").
data.data[].postView	number	The view count for the post.
data.data[].likeCount	number	The count of likes associated with the spam record.
data.data[].replyCount	number	The count of replies associated with the spam record.
data.data[].retweetCount	number	The count of retweets associated with the spam record.
data.data[].appId	string	The application ID associated with the spam record.
data.data[].botId	string or null	The ID of the bot associated with the spam record, if applicable.
data.data[].jobId	string	The job ID associated with the spam record.
data.data[].taskId	string	The task ID associated with the spam record.
data.data[].images	array	An array of image URLs associated with the spam record (if any).
data.data[].content	string or null	The content of the spam record (if applicable).
data.data[].tweetId	string or null	The ID of the tweet associated with the spam record (if applicable).
data.data[].tweetUrl	string or null	The URL of the tweet associated with the spam record (if applicable).
data.data[].customerId	string	The ID of the customer associated with the spam record.
data.data[].postTweetId	string or null	The ID of the post associated with the spam record (if applicable).
data.data[].errorMessage	string or null	Error message associated with the spam record, if applicable.
data.data[].paymentItemId	string or null	Payment item ID associated with the spam record, if applicable.
data.data[].interactionJobId	string or null	Job ID for interactions associated with the spam record, if applicable.
data.data[].isInteraction	boolean	Indicates if this record is part of an interaction.
data.data[].postTime	string	The timestamp when the spam was posted.
data.data[].createdAt	string	The timestamp when the spam record was created.
data.data[].updatedAt	string	The timestamp when the spam record was last updated.
data.data[].interactionAt	string or null	The timestamp of the last interaction, if applicable.
data.data[].customer	object	An object containing details of the associated customer.
data.data[].task	object	An object containing details of the associated task.
data.data[].bot	object	An object containing details of the associated bot (if applicable).
data.total	number	The total number of spam records returned by the API.
data.stat	object	An object containing statistics related to the spam records (views, likes, replies, reposts).
path	string	The endpoint path used for the request.
method	string	The HTTP method used for the request (e.g., "GET").
message	string	A success message indicating that the spam retrieval was successful.
statusCode	number	The HTTP status code of the response (200 indicates success).

Error Responses

Status Code	Description	Example Response
400 Bad Request	If the request is malformed or required parameters are missing.	{ "statusCode": 400, "message": "Validation failed", "error": "Bad Request" }
401 Unauthorized	If the user is not authenticated or does not have the necessary permissions.	{ "statusCode": 401, "message": "Unauthorized", "error": "Unauthorized" }

Example Usage

Here is an example of how to call the endpoint using curl:

curl -X GET "/v1/spams?appId=yourAppId&limit=30&offset=0&startDate=2024-10-05T00:00:00.000Z&endDate=2024-10-05T23:59:59.999Z" \
-H Authorization: Bearer <your_token> or x-api-key: <your_api_key> \
-H "Content-Type: application/json"

Notes

• Ensure that the appId is valid and the user has the necessary permissions for the application.

• You can modify the limit, offset, startDate, and endDate parameters to paginate through the list of spam records.

Create Group API

Endpoint: POST /v1/customers/groups

Description: This endpoint allows you to create a new customer group for organizing customers.

Request:

• URL: /v1/customers/groups

• Method: POST

• Headers:

  • Content-Type: application/json

  • Authorization: Bearer <your_token> or x-api-key: <your_api_key>

Body Parameters:

Parameter	Type	Required	Description
name	string	Yes	The name of the group you are creating.

Query Parameters:

Parameter	Type	Required	Description
appId	string	Yes	The application ID linked to the group creation.

Sample Request:

Payload:

{
  "name": "test shillbot"
}

Query Parameters:

?appId=db7c5f31-3182-4f81-a196-f656e61c180f

Responses:

{
  "data": {
    "name": "test shillbot",
    "id": "25c93965-091f-4dff-abf0-e67877f663a9"
  },
  "path": "/v1/customers/groups?appId=db7c5f31-3182-4f81-a196-f656e61c180f",
  "method": "POST",
  "message": "success",
  "statusCode": 200
}

Field description:

Field Descriptions:

Field	Type	Description
data	object	Contains information about the newly created group.
data.name	string	The name of the created group. In this example, "test shillbot".
data.id	string	The unique identifier assigned to the group. In this example, "25c93965-091f-4dff-abf0-e67877f663a9".
path	string	The API endpoint path that was accessed, including the query parameters. Shows the full request path.
method	string	The HTTP method used for the request. In this case, it is "POST".
message	string	A brief message indicating the result of the API call. "success" means the group was created successfully.
statusCode	integer	The HTTP status code of the response. A value of 200 indicates that the request was successful.

Get Customer Groups API

Endpoint:

GET /v1/customers/groups

Description:

This endpoint retrieves a list of customer groups based on the provided query parameters, such as date ranges, application ID, and pagination details.

Authentication:

This endpoint requires bearer token authentication. The user must have appropriate permissions to access the customer groups.

Request:

• URL: /v1/customers/groups

• Method: GET

• Headers:

  • Authorization: Bearer <your_token> or x-api-key: <your_api_key>

  • Content-Type: application/json

Query Parameters:

Parameter	Type	Required	Description
limit	integer	Yes	The maximum number of records to retrieve. Example: 1000.
appId	string	Yes	The application ID to filter the customer groups by.
offset	integer	Yes	The offset for pagination, specifying where to start retrieving records. Example: 0.
startDate	string	Yes	The start of the date range in ISO format. Example: 2024-10-07T00:00:00.000Z.
endDate	string	Yes	The end of the date range in ISO format. Example: 2024-10-07T23:59:59.999Z.

Sample Request:

GET https://api.shillbot.xyz/v1/customers/groups?limit=1000&appId=db7c5f31-3182-4f81-a196-f656e61c180f&offset=0&startDate=2024-10-07T00:00:00.000Z&endDate=2024-10-07T23:59:59.999Z

Response:

Success Response:

{
    "data": {
        "total": 1,
        "data": [
            {
                "name": "test shillbot",
                "id": "25c93965-091f-4dff-abf0-e67877f663a9"
            }
        ]
    },
    "path": "/v1/customers/groups?limit=1000&appId=db7c5f31-3182-4f81-a196-f656e61c180f&offset=0&endDate=2024-10-07T23:59:59.999Z&startDate=2024-10-07T00:00:00.000Z",
    "method": "GET",
    "message": "success",
    "statusCode": 200
}

Field Descriptions:

Field	Type	Description
data	object	Contains the response details for customer groups.
data.total	integer	The total number of customer groups that match the query.
data.data	array	An array of customer group objects that match the query.
data.data.name	string	The name of the customer group. In this case, "test shillbot".
data.data.id	string	The unique identifier for the customer group.
path	string	The request path that was used, including the query parameters.
method	string	The HTTP method used for the request, in this case, "GET".
message	string	A brief message about the result of the API call. "success" indicates that the request was processed successfully.
statusCode	integer	The HTTP status code returned by the server. A value of 200 indicates that the request was successful.

Notes:

• Make sure that the appId is valid, and that the user has the necessary permissions to retrieve customer groups.

• The limit and offset parameters can be used to paginate through the customer groups.

• The startDate and endDate parameters filter the results within a specific date range.

Get List Tags

Endpoint:

GET /v1/customers/tags

Description:

This endpoint retrieves a list of customer tags based on the provided query parameters, such as date ranges, application ID, and pagination details. If no tags are found, the data array will be empty.

Authentication:

This endpoint requires bearer token authentication. Users must have appropriate permissions to access the customer tags.

Request:

• URL: /v1/customers/tags

• Method: GET

• Headers:

  • Authorization: Bearer <your_token> or x-api-key: <your_api_key>

  • Content-Type: application/json

Query Parameters:

Parameter	Type	Required	Description
limit	integer	Yes	The maximum number of records to retrieve. Example: 1000.
appId	string	Yes	The application ID to filter the customer tags by.
offset	integer	Yes	The offset for pagination, specifying where to start retrieving records. Example: 0.
startDate	string	Yes	The start of the date range in ISO format. Example: 2024-10-07T00:00:00.000Z.
endDate	string	Yes	The end of the date range in ISO format. Example: 2024-10-07T23:59:59.999Z.

Sample Request:

GET /v1/customers/tags?limit=1000&appId=db7c5f31-3182-4f81-a196-f656e61c180f&offset=0&startDate=2024-10-07T00:00:00.000Z&endDate=2024-10-07T23:59:59.999Z

Response:

Success Response:

{
    "data": {
        "total": 0,
        "data": []
    },
    "path": "/v1/customers/tags?limit=1000&appId=db7c5f31-3182-4f81-a196-f656e61c180f&offset=0&endDate=2024-10-07T23:59:59.999Z&startDate=2024-10-07T00:00:00.000Z",
    "method": "GET",
    "message": "success",
    "statusCode": 200
}

Field Descriptions:

Field	Type	Description
data	object	Contains the response details for customer tags.
data.total	integer	The total number of customer tags that match the query. In this case, 0 indicates no tags were found.
data.data	array	An array of customer tag objects that match the query. In this case, the array is empty as no tags were found.
path	string	The request path that was used, including the query parameters.
method	string	The HTTP method used for the request, in this case, "GET".
message	string	A brief message about the result of the API call. "success" indicates that the request was processed successfully.
statusCode	integer	The HTTP status code returned by the server. A value of 200 indicates that the request was successful.

Import User

Endpoint:

POST /v1/customers/batch

Description: This endpoint allows you to batch create or import customers into the system. You can use various filtering criteria or provide specific names, tags, and groups to associate customers with. The batch creation allows up to 1000 customer names in a single request.

Authentication:

This endpoint requires either:

• Authorization: Bearer <your_token>

• x-api-key: <your_api_key>

Request:

• URL: https://api.shillbot.xyz/v1/customers/batch?appId=yourAppId

• Method: POST

• Headers:

  • Authorization: Bearer <your_token> or x-api-key: <your_api_key>

  • Content-Type: application/json

• Query Parameters:

  • appId (string, required): The ID of the application that will be associated with the customers being created.

Request Body:

Payload Fields Description

Field	Type	Description
type	enum (required)	The type of batch operation. Must be one of the values defined in CUSTOMER_BATCH_TYPE.
names	array of strings	An array of customer names to import. Limited to 1000 names per request.
tagIds	array of strings	An array of tag IDs to associate with the customers. Limited to 100 IDs.
groupIds	array of strings	An array of group IDs to associate with the customers. Limited to 100 IDs.
filter	object (optional)	Filtering criteria for importing customers.
ids	array of strings (optional)	Array of customer IDs to be included.

The request body must be a JSON object that follows the structure defined by the

{
  "type": "IMPORT_CUSTOMERS",
  "names": [
    "username"
  ],
  "tagIds": ["8d598761-1276-44da-88bb-6629116feaa1"],
  "groupIds": ["068ece90-f1db-4402-84c0-e5a5fa0be585"]
}

Response:

On a successful request, the response will contain the path of the request, the HTTP method used, and a success message with status code 200.

{
    "path": "/v1/customers/batch?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb",
    "method": "POST",
    "message": "success",
    "statusCode": 200
}

Response Fields Description

Field	Type	Description
path	string	The API path used for the request.
method	string	The HTTP method used in the request. In this case, it will always be "POST".
message	string	Describes the result of the request. On success, this field will return "success".
statusCode	integer	The HTTP status code for the response. A value of 200 indicates that the request was successful.

Example Usage:

Here’s an example of how to call the endpoint using curl:

curl -X POST "https://api.shillbot.xyz/v1/customers/batch?appId=fd8e0a24-f5de-4736-834d-9388f00e48eb" \
-H "Authorization: Bearer <your_token>" or "x-api-key: <your_api_key>"  \
-H "Content-Type: application/json" \
-d '{
    "type": "IMPORT_CUSTOMERS",
    "names": ["username"],
    "tagIds": ["8d598761-1276-44da-88bb-6629116feaa1"],
    "groupIds": ["068ece90-f1db-4402-84c0-e5a5fa0be585"]
}'

Notifications API

Endpoint

GET /v1/bots/notification

Description

Retrieve a list of notifications for the user based on specified filters, including type, user details, and notification status.

Authentication

• Bearer Token is required.

Parameters

Parameter	Type	Description
limit	Integer	The number of notifications to return. Default: 30.
appId	String	Application identifier. Required.
offset	Integer	The starting position for the list of notifications. Default: 0.
startDate	Date	Start date in ISO 8601 format (e.g., 2024-11-02T00:00:00.000Z). Required.
endDate	Date	End date in ISO 8601 format (e.g., 2024-11-02T23:59:59.999Z). Required.

Response

• Status: 200 OK

• Response Body:

  • data.total: Integer - Total number of notifications.

  • data.unRead: Integer - Count of unread notifications.

  • data.data: Array - List of notification objects, each containing:

    Field	Type	Description
    type	String	Notification type (e.g., users_liked_your_tweet).
    fromUser	String	Display name of the user who triggered the notification.
    fromUserId	String	ID of the user who triggered the notification.
    fromUserName	String	Username of the user who triggered the notification.
    fromUserAvatar	String	URL of the user's profile image.
    tweetId	String	ID of the associated tweet, if applicable.
    replyTweetId	String	ID of the reply tweet, if applicable.
    mentionTweetId	String	ID of the mention tweet, if applicable.
    notificationText	String	The text of the notification message.
    read	Boolean	Read status of the notification.
    isBot	Boolean	Indicates if the notification is bot-generated.
    notificationAt	Date	Timestamp when the notification was created.
    id	String	Unique identifier for the notification.

Example Request

GET https://api.shillbot.xyz/v1/bots/notification?limit=30&appId=fd8e0a24-f5de-4736-834d-9388f00e48eb&offset=0&endDate=2024-11-02T23:59:59.999Z&startDate=2024-11-02T00:00:00.000Z
Authorization: Bearer {token}

Example Response

{
    "data": {
        "total": 40,
        "data": [
            {
                "type": "users_liked_your_tweet",
                "fromUser": "Global Crypto Federation I GCF",
                "fromUserId": "977614921",
                "fromUserName": "Glbcryptofed",
                ...
            }
        ],
        "unRead": 12
    },
    "message": "success",
    "statusCode": 200
}

Example

https://documenter.getpostman.com/view/30457333/2sAXxPAYfL