socially-run Webhooks API

openapi: 3.2.0
info:
  title: 'socially.run: send a profile link, get its public data as…'
  version: 0.1.0
  description: 'One API for public data from Instagram, TikTok, YouTube, LinkedIn, X, Facebook, GitHub and any web page: profiles, posts, page text, username search, email lookup and trends. Every lookup answers **found**, **not found** or **we could not check** (`undecided`), never a guess, and a cached answer costs 0 credits. MCP tools share these operation definitions and the same `so_` key; x-mcp-tools lists the tools available over MCP. Writing TypeScript or JavaScript? `npm i socially` is one typed method per endpoint here.'
servers:
- url: https://api.socially.run/v1
tags:
- name: Webhooks
  description: 'One signed-event endpoint per account: set it, test-fire it, rotate its secret, read its delivery log.'
paths:
  /webhooks:
    get:
      operationId: get_webhook_get
      tags:
      - Webhooks
      summary: Get your webhook endpoint
      description: 'The endpoint events are being POSTed to, which ones it is subscribed to, and whether it is still healthy. `null` when none is registered. `disabledReason: "failures"` means we switched it off after 10 failed deliveries in a row. Only a final failure counts, not an attempt that will be retried. Fix the endpoint, then save it again or send a test that succeeds to switch it back on. Free.'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Get your webhook endpoint
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data: {}
        '400':
          description: 'VALIDATION_ERROR / INVALID_TARGET / SSRF_BLOCKED: the issues, never the values.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'UNAUTHORIZED / INVALID_TOKEN: the key is missing or wrong.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: 'PAYMENT_REQUIRED / PLAN_GATE: clears by upgrading or buying credits, never by waiting.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: 'RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED: Retry-After says when it clears.'
          headers:
            Retry-After:
              description: When present, how many seconds to wait before trying again.
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        default:
          description: Any other failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-sdk:
        method: webhooks.get
        returns: WebhookEndpointDto | null
      x-credits: Free
    put:
      operationId: set_webhook_put
      tags:
      - Webhooks
      summary: Register your webhook endpoint
      description: 'Point socially.run at an https URL and start receiving events there. The answer carries the signing secret ONCE, when it is minted: keep it. Every delivery is signed with it in the `x-socially-signature` header (`t=,v1=.">`), and that signature is how you know a request is really from us. Calling this again updates the URL or the subscription and keeps the same secret unless you ask to rotate it. Saving also re-enables an endpoint we had disabled. Up to 5 attempts for no answer, 5xx, 408, 425 or 429, with gaps of 30, 60, 120 and 240 seconds. A longer Retry-After extends the gap, capped at one hour. Other 4xx and all redirects are final. Free.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                url:
                  type: string
                  format: uri
                  description: Where to POST events, e.g. https://api.yourapp.com/hooks/socially.
                events:
                  description: 'Which events to receive: job.completed, job.failed. Defaults to all of them.'
                  minItems: 1
                  type: array
                  items:
                    type: string
                    enum:
                    - job.completed
                    - job.failed
                rotateSecret:
                  description: Mint a new signing secret and return it. The old one stops working.
                  type: boolean
              required:
              - url
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Register your webhook endpoint
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data: {}
        '400':
          description: 'VALIDATION_ERROR / INVALID_TARGET / SSRF_BLOCKED: the issues, never the values.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'UNAUTHORIZED / INVALID_TOKEN: the key is missing or wrong.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: 'PAYMENT_REQUIRED / PLAN_GATE: clears by upgrading or buying credits, never by waiting.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: 'RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED: Retry-After says when it clears.'
          headers:
            Retry-After:
              description: When present, how many seconds to wait before trying again.
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        default:
          description: Any other failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-sdk:
        method: webhooks.set
        returns: SavedWebhookDto
        repeatable: true
      x-credits: Free
    delete:
      operationId: delete_webhook_delete
      tags:
      - Webhooks
      summary: Remove your webhook endpoint
      description: Stop sending events and forget the endpoint, its secret and its delivery history. Registering again mints a new secret. Free.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Remove your webhook endpoint
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data: {}
        '400':
          description: 'VALIDATION_ERROR / INVALID_TARGET / SSRF_BLOCKED: the issues, never the values.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'UNAUTHORIZED / INVALID_TOKEN: the key is missing or wrong.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: 'PAYMENT_REQUIRED / PLAN_GATE: clears by upgrading or buying credits, never by waiting.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: 'RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED: Retry-After says when it clears.'
          headers:
            Retry-After:
              description: When present, how many seconds to wait before trying again.
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        default:
          description: Any other failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-sdk:
        method: webhooks.remove
        returns: DeletedWebhookDto
        repeatable: true
      x-credits: Free
  /webhooks/test:
    post:
      operationId: test_webhook_post
      tags:
      - Webhooks
      summary: Fire a test event at your endpoint
      description: 'Send a `ping` event to your registered endpoint right now and wait for the answer, so you can verify the URL and your signature check without waiting for a real job. The result is the actual outcome: `ok: false` carries the HTTP status your server answered, or why we could not reach it. A ping that lands also revives an endpoint we had auto-disabled. It never retries, and it does not count against the failure streak of a real event. Free.'
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Fire a test event at your endpoint
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data: {}
        '400':
          description: 'VALIDATION_ERROR / INVALID_TARGET / SSRF_BLOCKED: the issues, never the values.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'UNAUTHORIZED / INVALID_TOKEN: the key is missing or wrong.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: 'PAYMENT_REQUIRED / PLAN_GATE: clears by upgrading or buying credits, never by waiting.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: 'RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED: Retry-After says when it clears.'
          headers:
            Retry-After:
              description: When present, how many seconds to wait before trying again.
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        default:
          description: Any other failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-sdk:
        method: webhooks.test
        returns: WebhookTestResultDto
        repeatable: false
      x-credits: Free
  /webhooks/deliveries:
    get:
      operationId: list_webhook_deliveries_get
      tags:
      - Webhooks
      summary: Recent webhook deliveries
      description: 'The last deliveries we attempted, newest first: what we sent, what your endpoint answered, and how many attempts it took. This is the answer to “the event never arrived”. Deliveries are kept for a week. Free.'
      parameters:
      - name: limit
        in: query
        required: false
        description: How many to return, newest first. Up to 50 (the default).
        schema:
          description: How many to return, newest first. Up to 50 (the default).
          type: integer
          minimum: 1
          maximum: 50
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Recent webhook deliveries
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data: {}
        '400':
          description: 'VALIDATION_ERROR / INVALID_TARGET / SSRF_BLOCKED: the issues, never the values.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'UNAUTHORIZED / INVALID_TOKEN: the key is missing or wrong.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: 'PAYMENT_REQUIRED / PLAN_GATE: clears by upgrading or buying credits, never by waiting.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: 'RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED: Retry-After says when it clears.'
          headers:
            Retry-After:
              description: When present, how many seconds to wait before trying again.
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        default:
          description: Any other failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      x-sdk:
        method: webhooks.deliveries
        returns: WebhookDeliveryDto[]
      x-credits: Free
components:
  schemas:
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: What went wrong, as a word a program can check.
            message:
              type: string
              description: What went wrong, as a sentence.
            messageKey:
              type: string
              description: '`message` as a key, to show it in your reader''s language, with `params` filling its blanks.'
            params:
              type: object
              additionalProperties:
                type:
                - string
                - number
              description: The values that fill `messageKey`'s blanks, such as a limit.
            details:
              description: More about this error, such as retryAfterSecs.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An `so_` API key from the console.
x-mcp-tools:
- name: resolve_target
  title: Resolve what a URL or @handle points at
  description: 'Turn a profile URL, post URL, website or @handle into what socially would read: the platform, the kind (profile, post, website), the normalized handle and the one canonical URL. No egress, no credit. Use it to validate input before a metered lookup.'
  inputSchema:
    type: object
    properties:
      input:
        type: string
        minLength: 1
        maxLength: 2048
        description: A profile URL, post URL, website or @handle.
      platform:
        description: Required when `input` is a bare handle.
        type: string
        enum:
        - instagram
        - linkedin
        - youtube
        - tiktok
        - x
        - facebook
        - github
        - website
    required:
    - input
    additionalProperties: false
- name: aggregate_intelligence
  title: Aggregate profiles into social intelligence
  description: 'Turn one or more profile reads (the six ExtractionResult keys) into the consolidated SocialIntelligence document: engagement, sentiment, content calendar, benchmark, a pt-BR knowledge-base markdown and personality hints. Pure and free. It only computes over what you send.'
  inputSchema:
    type: object
    properties:
      results:
        minItems: 1
        maxItems: 20
        type: array
        items:
          type: object
          properties:
            platform:
              type: string
              enum:
              - instagram
              - linkedin
              - youtube
              - tiktok
              - x
              - facebook
              - github
              - website
            url:
              type: string
            extractedAt:
              type: string
            profile:
              type: object
              properties:
                name:
                  type: string
                username:
                  type: string
                bio:
                  type: string
                followers:
                  type:
                  - number
                  - 'null'
                following:
                  type:
                  - number
                  - 'null'
                postsCount:
                  type:
                  - number
                  - 'null'
                profileUrl:
                  type: string
                avatarUrl:
                  type:
                  - string
                  - 'null'
                isVerified:
                  type:
                  - boolean
                  - 'null'
                isBusinessAccount:
                  type:
                  - boolean
                  - 'null'
                businessCategory:
                  type:
                  - string
                  - 'null'
                externalUrl:
                  type:
                  - string
                  - 'null'
              required:
              - name
              - username
              - bio
              - followers
              - following
              - postsCount
              - profileUrl
              - avatarUrl
            recentPosts:
              type: array
              items:
                type: object
                properties:
                  text:
                    type: string
                  date:
                    type:
                    - string
                    - 'null'
                  likes:
                    type:
                    - number
                    - 'null'
                  comments:
                    type:
                    - number
                    - 'null'
                  shares:
                    type:
                    - number
                    - 'null'
                  views:
                    type:
                    - number
                    - 'null'
                  url:
                    type:
                    - string
                    - 'null'
                  thumbnail:
                    type:
                    - string
                    - 'null'
                  duration:
                    type:
                    - string
                    - 'null'
                  hashtags:
                    type: array
                    items:
                      type: string
                  mediaType:
                    anyOf:
                    - type: string
                      enum:
                      - video
                      - image
                      - carousel
                      - article
                      - short
                      - reel
                    - type: 'null'
                required:
                - text
                - date
                - likes
                - comments
                - shares
                - views
                - url
            summary:
              type: string
          required:
          - platform
          - url
          - extractedAt
          - profile
          - recentPosts
          - summary
          additionalProperties: {}
    required:
    - results
    additionalProperties: false
- name: list_platforms
  title: List the platforms and how each one is answering
  description: List supported capabilities separately from source health. `capabilities` reports profile/post lookup, topic video search, indexed topic search, hashtag search and country trend boards. YouTube and TikTok support topic video search; only YouTube has a country board. Only Instagram has indexed topic search, the reels on its public popular page for a word, which exists for some words only. TikTok and Instagram support hashtag search. Google Trends is a separate `/trending` source. `status` and `strategies` describe profile reads; `postStatus` and `postStrategies` describe post reads, with verification dates and the last 24 hours of results. A supported capability can still have no working source here. Free.
  inputSchema:
    type: object
    properties: {}
    additionalProperties: false
- name: lookup_profile
  title: Look up a public profile
  description: 'Read a public profile on Instagram, TikTok, YouTube, LinkedIn, X, Facebook, GitHub or a website. A `found` answer includes the profile, recent posts and platform details when available: account ids, links, creation dates and public counts. Instagram''s `userId` and `graphId` name different ids; neither grants permission. Missing fields are null; unsupported blocks are absent. Data outcomes answer 200: `found`, `notFound` (confirmed by the platform, cached an hour) or `undecided` (refunded, never cached). 1 credit on a miss, 0 on a hit. `extractedAt` is the original read time, including cache and snapshot hits.'
  inputSchema:
    type: object
    properties:
      input:
        type: string
        minLength: 1
        maxLength: 2048
        description: A profile URL, post URL, website or @handle.
      platform:
        description: Required when `input` is a bare handle.
        type: string
        enum:
        - instagram
        - linkedin
        - youtube
        - tiktok
        - x
        - facebook
        - github
        - website
      posts:
        description: Recent posts to return (0–15). Default 10. This limits the answer, not the source read.
        type: integer
        minimum: 0
        maximum: 15
      refresh:
        description: Bypass the cache and the snapshot; costs a credit even when fresh.
        type: boolean
    required:
    - input
    additionalProperties: false
- name: lookup_profiles_batch
  title: Look up up to ten profiles in one call
  description: 'Read up to ten profiles at once (five in flight, 30 s each, 120 s total). Answers 200 with `results` (the found ones), `failures` (the ones not found and the ones we could not check, which are refunded) and, with `aggregate: true`, the consolidated social intelligence the siblings persist. `partial` says whether anything failed.'
  inputSchema:
    type: object
    properties:
      targets:
        minItems: 1
        maxItems: 10
        type: array
        items:
          type: object
          properties:
            input:
              type: string
              minLength: 1
              maxLength: 2048
              description: A profile URL, post URL, website or @handle.
            platform:
              description: Required when `input` is a bare handle.
              type: string
              enum:
              - instagram
              - linkedin
              - youtube
              - tiktok
              - x
              - facebook
              - github
              - website
          required:
          - input
          additionalProperties: false
        description: 1–10 profiles to read in parallel.
      posts:
        description: Recent posts to return (0–15). Default 10. This limits the answer, not the source read.
        type: integer
        minimum: 0
        maximum: 15
      aggregate:
        description: Run the aggregator over the profiles that were found (0 credits).
        type: boolean
      perTargetTimeoutMs:
        description: Per-profile timeout in milliseconds (1,000–30,000). Default 30,000.
        type: integer
        minimum: 1000
        maximum: 30000
    required:
    - targets
    additionalProperties: false
- name: lookup_post
  title: Look up a public post
  description: 'Read one public Instagram, TikTok, YouTube, X, LinkedIn or Facebook post or GitHub repository by URL. Returns its caption, author id, date, media and public counts when available. X, LinkedIn and Facebook posts are read only through a paid reader, with exact counts, and a deployment with no reader configured answers 503 before it charges. A LinkedIn post''s `author.profileUrl` is the person''s or the company''s own page, and a Facebook post''s `likes` counts every reaction. A full Instagram read adds source ids and ordered `frames` with image/video URLs, dimensions, duration and alt text; missing fields are null. YouTube adds video/channel ids, title and description, not a playable stream. GitHub adds repository details (language, license, default branch, topics, stars, forks, open issues and watchers). Every read says its `detailLevel` (`detailed` from the post''s own page or API, `embed` from a thin public card that leaves what it does not show null) and its `confidence`; a cached answer keeps both. CDN URLs can expire: download the files. Answers `found` or `undecided` (refunded), never `notFound`. 1 credit on a miss, 0 on a hit. Cached answers keep the original `extractedAt`.'
  inputSchema:
    type: object
    properties:
      url:
        type: string
        minLength: 1
        maxLength: 2048
        description: An http(s) URL.
      refresh:
        description: Bypass the cache and the snapshot; costs a credit even when fresh.
        type: boolean
    required:
    - url
    additionalProperties: false
- name: read_website
  title: Read a public web page
  description: 'Fetch a public page through the proxy and return its readable text, title, description, images and ld+json. Pages that render with JavaScript are rendered when the budget allows (`render: auto`). Private and internal addresses answer 400 SSRF_BLOCKED. 1 credit on a miss, 0 on a hit (24 h).'
  inputSchema:
    type: object
    properties:
      url:
        type: string
        minLength: 1
        maxLength: 2048
        description: An http(s) URL.
      maxChars:
        description: Cap on the readable text. Default 8,000.
        type: integer
        minimum: 500
        maximum: 50000
      render:
        description: '`always` renders every time and never falls back to a plain fetch. It spends render budget and fails closed at RENDER_BUDGET_EXHAUSTED; a deployment with no renderer answers SIDECAR_UNAVAILABLE.'
        type: string
        enum:
        - auto
        - never
        - always
      refresh:
        description: Bypass the cache and the snapshot; costs a credit even when fresh.
        type: boolean
    required:
    - url
    additionalProperties: false
- name: fetch_og
  title: Fetch a page's Open Graph card
  description: 'The Open Graph card a page publishes: title, description, image, site name, type, locale, canonical URL. 1 credit on a miss, 0 on a hit (24 h).'
  inputSchema:
    type: object
    properties:
      url:
        type: string
        minLength: 1
        maxLength: 2048
        description: An http(s) URL.
      refresh:
        description: Bypass the cache and the snapshot; costs a credit even when fresh.
        type: boolean
    required:
    - url
    additionalProperties: false
- name: get_job
  title: Get a job
  description: 'Read a job: its status, progress and credits, plus its hits once it has finished (found and undecided by default, capped at 500; page the rest with list_job_hits) and its summary. Poll this, or attach to the stream, until status is succeeded, partial, failed or cancelled.'
  inputSchema:
    type: object
    properties:
      id:
        type: string
        format: uuid
        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        description: The job id from the 202 that created it.
      include:
        description: Also embed the notFound hits (found and undecided come by default).
        type: string
        enum:
        - notFound
      wait:
        description: Wait up to this many seconds (0–25) for the job to settle before returning.
        type: integer
        minimum: 0
        maximum: 25
    required:
    - id
    additionalProperties: false
- name: list_job_hits
  title: List a job's hits
  description: Page through every site a job answered. It works while it is still running. Filter by outcome (found, notFound, undecided) or site category.
  inputSchema:
    type: object
    properties:
      id:
        type: string
        format: uuid
        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        description: The job id from the 202 that created it.
      outcome:
        description: Only hits with this outcome.
        type: string
        enum:
        - found
        - notFound
        - undecided
      category:
        description: Only sites in this category.
        type: string
        enum:
        - archived
        - art
        - blog
        - business
        - coding
        - dating
        - finance
        - gaming
        - health
        - hobby
        - images
        - misc
        - music
        - news
        - political
        - search
        - shopping
        - social
        - tech
        - video
        - xx NSFW xx
      limit:
        default: 50
        description: Hits per page (1–200). Default 50.
        type: integer
        minimum: 1
        maximum: 200
      offset:
        default: 0
        description: Rows to skip before this page. Default 0.
        type: integer
        minimum: 0
        maximum: 9007199254740991
    required:
    - id
    additionalProperties: false
- name: cancel_job
  title: Cancel a job
  description: Stop a job. A queued job is cancelled at once and fully refunded; a running one is asked to stop and lands within seconds. The hits it already has are kept and nothing is refunded. A finished job answers 409.
  inputSchema:
    type: object
    properties:
      id:
        type: string
        format: uuid
        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        description: The job id from the 202 that created it.
    required:
    - id
    additionalProperties: false


# --- truncated at 32 KB (53 KB total) ---
# Full source: https://artifacts.apis.io/socially-run/openapi/socially-run-webhooks-api-openapi.yml