socialdata-tools SocialData Account Management API

openapi: 3.2.0
info:
  title: SocialData API Reference SocialData Account Management API
  description: SocialData API is a scalable and reliable API that simplifies the process of fetching data from Twitter/X. With SocialData API, you can easily retrieve tweets, user profiles, user followers/following and other information without the need for proxies or parsing Twitter responses.
  termsOfService: https://socialdata.tools/legal/terms-and-conditions
  contact:
    email: support@socialdata.tools
  version: 1.0.0
servers:
- url: https://api.socialdata.tools
security:
- bearerAuth: []
tags:
- name: SocialData Account Management
  description: Endpoints for managing your SocialData account
paths:
  /user/balance:
    get:
      tags:
      - SocialData Account Management
      summary: Get Remaining Balance
      description: Returns remaining SocialData balance in USD
      operationId: getBalance
      responses:
        '200':
          description: Returns remaining balance (USD)
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance_usd:
                    type: number
                    format: float
                    example: '123.45'
        '500':
          description: API internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /user/webhook:
    post:
      tags:
      - SocialData Account Management
      summary: Set Global Webhook URL
      description: Used to set webhook URL that will be used for all monitors that don't have a monitor-specific webhook_url set.
      operationId: setGlobalWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type:
                  - string
                  - 'null'
                  description: New webhook URL that will be used for all monitors that don't have an individual webhook_url set
                  format: uri
              required:
              - url
            example:
              url: https://my-website.com/webhook
      responses:
        '200':
          description: Webhook URL successfully set
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Webhook URL updated
        '422':
          description: Validation failed (e.g. invalid URL format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: API internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/set-global-webhook-url/
  /user/webhook/secret:
    post:
      tags:
      - SocialData Account Management
      summary: Set Webhook Secret
      description: Sets the shared secret used to sign every webhook we send you. Your server uses the same value to confirm a request is authentic. You choose the value; there is no generate-a-secret endpoint. Calling this endpoint again replaces the previous secret. The account has one secret, shared by every monitor and every webhook URL. There is no endpoint that returns the current secret - it can only be overwritten.
      operationId: setWebhookSecret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                secret:
                  type: string
                  maxLength: 256
                  description: The shared secret used to sign webhook requests. Maximum 256 characters. Store it somewhere your webhook handler can read it, and treat it like a password.
              required:
              - secret
            example:
              secret: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
      responses:
        '200':
          description: Webhook secret successfully set
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Webhook secret updated
        '422':
          description: Validation failed (e.g. the secret field was not provided)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/set-webhook-secret/
components:
  schemas:
    ValidationErrorResponse:
      type: object
      description: Laravel-style validation error, returned by endpoints that validate individual fields
      properties:
        message:
          type: string
          example: The secret field is required.
        errors:
          type: object
          description: One entry per rejected field, each holding an array of messages
          additionalProperties:
            type: array
            items:
              type: string
          example:
            secret:
            - The secret field is required.
      required:
      - message
      - errors
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - error
        message:
          type: string
      required:
      - status
      - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Each request to SocialData API needs to contain your API key in the Authorization header.

        Example: `Authorization: Bearer YOUR_API_KEY`'
externalDocs:
  description: SocialData API Reference
  url: https://docs.socialdata.tools