SocialCrawl Github API

openapi: 3.2.0
info:
  title: SocialCrawl Github API
  version: 1.0.0
  description: 'Unified social media data API - one API key, one consistent response format, 50 platforms, 400 endpoints. Power AI agents with clean social data.


    Slim variant: inline examples removed and the shared error responses hoisted into components. The full annotated spec is at https://www.socialcrawl.dev/openapi.json.'
  contact:
    name: SocialCrawl
    url: https://www.socialcrawl.dev
    email: support@socialcrawl.dev
servers:
- url: https://www.socialcrawl.dev/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: github
  description: Github endpoints
paths:
  /github/profile:
    get:
      summary: Get a GitHub user profile
      description: Returns public profile information for a GitHub user (login, name, avatar, bio, follower / following / public-repos counts, and account-creation date) mapped to the unified Author schema. `author.likes_count` surfaces `public_gists` (a creation-count analog); `author.verified` surfaces the rare `site_admin` flag (true only for GitHub staff accounts).
      tags:
      - github
      operationId: get_github_profile
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      parameters:
      - name: handle
        in: query
        required: true
        description: 'GitHub username: 1-39 chars, alphanumeric + non-consecutive hyphens, no leading/trailing hyphen.'
        schema:
          type: string
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      id:
                        type: string
                        description: Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)
                      username:
                        type:
                        - string
                        - 'null'
                        description: User handle or username
                      display_name:
                        type:
                        - string
                        - 'null'
                        description: Display name or full name
                      avatar_url:
                        type:
                        - string
                        - 'null'
                        description: URL to profile picture
                      bio:
                        type:
                        - string
                        - 'null'
                        description: Profile biography or description
                      verified:
                        type:
                        - boolean
                        - 'null'
                        description: Whether the account is verified
                      followers:
                        type:
                        - integer
                        - 'null'
                        description: Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true.
                      following:
                        type:
                        - integer
                        - 'null'
                        description: Number of accounts followed
                      posts_count:
                        type:
                        - integer
                        - 'null'
                        description: Total number of posts / videos / tracks / episodes
                      likes_count:
                        type:
                        - integer
                        - 'null'
                        description: Total likes received across the author's content (when surfaced)
                      url:
                        type:
                        - string
                        - 'null'
                        description: Direct URL to the profile page
                      location:
                        type:
                        - string
                        - 'null'
                        description: ISO region code (e.g. `US`) or freeform location string when surfaced
                      external_url:
                        type:
                        - string
                        - 'null'
                        description: Bio link / external website URL when surfaced by the platform
                      private:
                        type:
                        - boolean
                        - 'null'
                        description: Boolean at author.private
                      joined_at:
                        type:
                        - string
                        - 'null'
                        description: String at author.joined_at
                      ext:
                        type:
                        - object
                        - 'null'
                        description: 'Nested object: author.ext'
                        properties:
                          social_context:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.social_context
                          account_created:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.account_created
                          country:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.country
                          former_usernames:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.former_usernames
                            items:
                              type: string
                              description: String at author.ext.former_usernames
                          public_email:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.public_email
                          public_phone:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.public_phone
                          business_category:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.business_category
                          hd_avatar_url:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.hd_avatar_url
                          website:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.website
                          cover_url:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.cover_url
                          page_active:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.page_active
                          employee_count:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.employee_count
                          employee_count_range:
                            type:
                            - object
                            - 'null'
                            description: 'Nested object: author.ext.employee_count_range'
                            properties:
                              start:
                                type:
                                - integer
                                - 'null'
                                description: Numeric at author.ext.employee_count_range.start
                              end:
                                type:
                                - integer
                                - 'null'
                                description: Numeric at author.ext.employee_count_range.end
                          founded_year:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.founded_year
                          specialities:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.specialities
                            items:
                              type: string
                              description: String at author.ext.specialities
                          industries:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.industries
                            items:
                              type: string
                              description: String at author.ext.industries
                          headquarters:
                            type:
                            - string
                            - 'null'
                            description: Leaf at author.ext.headquarters
                          locations:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.locations
                            items:
                              type: string
                              description: Leaf at author.ext.locations
                          hashtags:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.hashtags
                            items:
                              type: string
                              description: Leaf at author.ext.hashtags
                          funding:
                            type:
                            - string
                            - 'null'
                            description: Leaf at author.ext.funding
                          address:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.address
                          price_range:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.price_range
                          rating:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.rating
                          rating_count:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.rating_count
                          talking_about_count:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.talking_about_count
                          business_hours:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.business_hours
                            items:
                              type: string
                              description: Leaf at author.ext.business_hours
                          links:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.links
                            items:
                              type: string
                              description: Leaf at author.ext.links
                          ad_library_page_id:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.ad_library_page_id
                          ad_library_status:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.ad_library_status
                          urn:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.urn
                          is_top_voice:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.is_top_voice
                          is_premium:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.is_premium
                          followers_approximate:
                            type:
                            - boolean
                            - 'null'
                            description: 'True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts.'
                          keywords:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.keywords
                          topicCategories:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.topicCategories
                            items:
                              type: string
                              description: String at author.ext.topicCategories
                          bannerExternalUrl:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.bannerExternalUrl
                          madeForKids:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.madeForKids
                          hiddenSubscriberCount:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.hiddenSubscriberCount
                          related_playlists:
                            type:
                            - string
                            - 'null'
                            description: Leaf at author.ext.related_playlists
                          topic_ids:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.topic_ids
                            items:
                              type: string
                              description: String at author.ext.topic_ids
                          unsubscribed_trailer:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.unsubscribed_trailer
                          monthly_listeners:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.monthly_listeners
                          total_ratings:
                            type:
                            - integer
                            - 'null'
                            description: 'Spotify podcasts only: how many listeners have rated the show. Cumulative over the show''s whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)'
                          average_rating:
                            type:
                            - integer
                            - 'null'
                            description: 'Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf'
                          creator_username:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.creator_username
                          join_policy:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.join_policy
                          is_nsfw:
                            type:
                            - boolean
                            - 'null'
                            description: Boolean at author.ext.is_nsfw
                          weekly_active_users:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.weekly_active_users
                          weekly_contributions:
                            type:
                            - integer
                            - 'null'
                            description: Numeric at author.ext.weekly_contributions
                          bio_link:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.bio_link
                          group:
                            type:
                            - string
                            - 'null'
                            description: Leaf at author.ext.group
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
  /github/repo:
    get:
      summary: Get a GitHub repository
      description: 'Returns repository metadata (full_name, description, stars, forks, open issues, watchers, language, and creation date) mapped to the unified Author schema. A repo is a follow-able creator-like entity in this API: stars map to `author.followers`, watchers (subscribers) to `author.likes_count`, forks to `author.following`. Use `/v1/github/repo/readme`, `/v1/github/repo/releases`, and `/v1/github/repo/issues` for richer per-repo data.'
      tags:
      - github
      operationId: get_github_repo
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      parameters:
      - name: url
        in: query
        required: true
        description: 'GitHub repo URL: `https://github.com/{owner}/{repo}`.'
        schema:
          type: string
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      id:
                        type: string
                        description: Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)
                      username:
                        type:
                        - string
                        - 'null'
                        description: User handle or username
                      display_name:
                        type:
                        - string
                        - 'null'
                        description: Display name or full name
                      avatar_url:
                        type:
                        - string
                        - 'null'
                        description: URL to profile picture
                      bio:
                        type:
                        - string
                        - 'null'
                        description: Profile biography or description
                      verified:
                        type:
                        - boolean
                        - 'null'
                        description: Whether the account is verified
                      followers:
                        type:
                        - integer
                        - 'null'
                        description: Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true.
                      following:
                        type:
                        - integer
                        - 'null'
                        description: Number of accounts followed
                      posts_count:
                        type:
                        - integer
                        - 'null'
                        description: Total number of posts / videos / tracks / episodes
                      likes_count:
                        type:
                        - integer
                        - 'null'
                        description: Total likes received across the author's content (when surfaced)
                      url:
                        type:
                        - string
                        - 'null'
                        description: Direct URL to the profile page
                      location:
                        type:
                        - string
                        - 'null'
                        description: ISO region code (e.g. `US`) or freeform location string when surfaced
                      external_url:
                        type:
                        - string
                        - 'null'
                        description: Bio link / external website URL when surfaced by the platform
                      private:
                        type:
                        - boolean
                        - 'null'
                        description: Boolean at author.private
                      joined_at:
                        type:
                        - string
                        - 'null'
                        description: String at author.joined_at
                      ext:
                        type:
                        - object
                        - 'null'
                        description: 'Nested object: author.ext'
                        properties:
                          social_context:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.social_context
                          account_created:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.account_created
                          country:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.country
                          former_usernames:
                            type:
                            - array
                            - 'null'
                            description: Array at author.ext.former_usernames
                            items:
                              type: string
                              description: String at author.ext.former_usernames
                          public_email:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.public_email
                          public_phone:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.public_phone
                          business_category:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.business_category
                          hd_avatar_url:
                            type:
                            - string
                            - 'null'
                            description: String at author.ext.hd_avatar_url
                          website:
                            type:
            

# --- truncated at 32 KB (317 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socialcrawl/refs/heads/main/openapi/socialcrawl-github-api-openapi.yml