captapi-com Linkbio API

openapi: 3.2.0
info:
  title: Captapi Linkbio API
  version: 0.1.0
  summary: Structured public data from social platforms through one REST API.
  description: 'Captapi returns public data (profiles, posts, comments, transcripts, search, ads, commerce) from social platforms as JSON.


    Auth: send your key as `Authorization: Bearer capt_live_...` or `X-API-Key: capt_live_...`. Keys are created by a human at https://captapi.com/dashboard/api-keys.


    Billing: each operation states its cost in `x-credit-cost`. The `X-Captapi-Credits` response header shows what was charged. Failed requests (4xx/5xx) are not billed. `cache=true` serves from the 24h cache, free on a hit where `billedOnCacheHit` is false. Where the price depends on which path served the call, `x-credit-cost.note` gives the full rule and the range we have observed.


    Empty results: on many list and search endpoints a call that ran but found nothing is charged 0 credits (for example an ad-library or profile search with no matches). Where an empty result is still billed, the endpoint description says so; Google Maps business search, for instance, bills its one page because the lookup ran. The `X-Captapi-Credits` header always shows the actual charge.


    Errors: every non-2xx response uses the same envelope, `{ success: false, error: { code, message, retryable } }`. Retry only when `retryable` is true, honouring `Retry-After`.


    Timing: every response carries `Server-Timing: total;dur=`, the total time the request took. Deprecated: the `timings` object some endpoints still return in `data` will be removed from response bodies on 2026-12-17; use the header instead. It is not part of the response schemas below.


    Response schemas are inferred from real captured responses and list the fields seen there plus documented top-level fields. Fields can be null when a platform does not expose them.


    Endpoint list: https://captapi.com/llms-endpoints.txt · Guide for agents: https://captapi.com/llms.txt · MCP: https://captapi.com/mcp.json'
  contact:
    name: Captapi support
    email: support@captapi.com
    url: https://captapi.com
  termsOfService: https://captapi.com/legal/terms
  license:
    name: Captapi Terms of Service
    url: https://captapi.com/legal/terms
servers:
- url: https://api.captapi.com
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Linkbio
  description: Public data from Linkbio.
paths:
  /v1/linkbio/page:
    get:
      operationId: linkbio_page
      tags:
      - Linkbio
      summary: Linkbio Page API
      description: 'lnk.bio → id, socials{}, titled links[], website/email/whatsapp, other[].


        Paste an lnk.bio URL and get the public page as clean JSON. Identity: id (lnk.bio numeric string, e.g. "-1344625"), handle/username, url, avatar. displayName/name are emitted only when lnk.bio publishes a real display name — @handle OG titles are not synthesised (null/omitted). socials{} is derived from data-network icon rows and username CTAs (facebook/twitter/instagram/tiktok/youtube/snapchat/triller/website/whatsapp/…) other[] holds typed social networks we could not map to a known key so nothing disappears. Top-level website / email / whatsapp when published. links[] includes content buttons (pb-linkbox) plus primary social icons with titles from icon labels (Facebook, Instagram, Triller, …) — not null. lnk.bio does not expose follower counts or a verified badge. Flat 1 credit. Pass cache=true or cacheMaxAge (1d/3d/7d/14d/30d).


        Docs: https://captapi.com/apis/linkbio-page'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      parameters:
      - name: url
        in: query
        required: true
        description: Linkbio (lnk.bio) page URL or username, e.g. https://lnk.bio/charlidamelio. The URL platform must match this endpoint's platform. Do not pass cross-platform URLs, e.g. YouTube to TikTok, Instagram to Facebook, LinkedIn to X/Twitter, or Pinterest to Rumble.
        schema:
          type: string
        example: https://lnk.bio/charlidamelio
      - name: cache
        in: query
        required: false
        description: Set true to serve from the response cache (default TTL). Default false — always fetch fresh. Prefer cacheMaxAge when you need 1d–30d freshness control.
        schema:
          type: boolean
          default: false
        example: false
      - name: cacheMaxAge
        in: query
        required: false
        description: 'Max age of a cached response: 1d, 3d, 7d, 14d, or 30d. When set, enables caching with that TTL.'
        schema:
          enum:
          - 1d
          - 3d
          - 7d
          - 14d
          - 30d
          type: string
      x-credit-cost:
        credits: 1
        label: 1 credit
        billedOnCacheHit: false
      x-one-liner: lnk.bio → id, socials{}, titled links[], website/email/whatsapp, other[].
      responses:
        '200':
          description: Success. The data object for this endpoint.
          headers:
            X-Captapi-Credits:
              $ref: '#/components/headers/Credits'
            X-Captapi-Cache:
              $ref: '#/components/headers/Cache'
            X-Captapi-Request-Id:
              $ref: '#/components/headers/RequestId'
            Server-Timing:
              $ref: '#/components/headers/ServerTiming'
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    const: true
                  data:
                    type: object
                    properties:
                      platform:
                        type: string
                        description: Platform identifier for this response (matches the endpoint's platform).
                      id:
                        type: string
                        description: lnk.bio numeric profile id as a string (e.g. "-1344625"). From data-uid / avatar path.
                      url:
                        type: string
                        description: 'On the page: https://lnk.bio/{username}. On a link row: outbound destination.'
                      username:
                        type: string
                        description: Account username / handle.
                      handle:
                        type: string
                        description: lnk.bio path slug. Canonical alongside username.
                      avatar:
                        type: string
                        description: Avatar / profile picture URL. Canonical across profile endpoints.
                      website:
                        type: string
                        description: Official website URL when published (hero TYPE_BUTTON / official-website CTA or SOCIAL_WEB). Null when unset.
                      linkCount:
                        type: integer
                        description: Content buttons + primary social icon rows (family deep-link dupes excluded).
                      socials:
                        type: object
                        properties:
                          facebook:
                            type: string
                            description: Facebook URL.
                          twitter:
                            type: string
                            description: Twitter URL.
                          instagram:
                            type: string
                            description: Instagram URL.
                          triller:
                            type: string
                            description: Triller URL.
                          tiktok:
                            type: string
                            description: Tiktok URL.
                          youtube:
                            type: string
                            description: Youtube URL.
                          snapchat:
                            type: string
                            description: Snapchat URL.
                          website:
                            type: string
                            description: Official website URL when published (hero TYPE_BUTTON / official-website CTA or SOCIAL_WEB). Null when unset.
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              description: 'On the page: https://lnk.bio/{username}. On a link row: outbound destination.'
                            title:
                              type: string
                              description: Title of this links item.
                            id:
                              type: string
                              description: Id of this links item.
                            type:
                              type: string
                              description: Content type of the item.
                      other:
                        type: array
                        items: {}
                        description: Typed social networks that did not map into socials{} [{url, title?, type?}]. Empty when every icon mapped.
              example:
                success: true
                data:
                  platform: linkbio
                  id: '-1344625'
                  url: https://lnk.bio/charlidamelio
                  username: charlidamelio
                  handle: charlidamelio
                  avatar: https://s3.us-west-2.amazonaws.com/cdn.lnk.bio/profilepics/-1344625_20220123667.jpg
                  website: https://www.charlidamelio.com
                  linkCount: 15
                  socials:
                    facebook: https://facebook.com/thecharlidamelio
                    twitter: https://twitter.com/charlidamelio
                    instagram: https://instagram.com/charlidamelio
                    triller: https://triller.co/m/@charlidamelio
                    tiktok: https://tiktok.com/@charlidamelio
                    youtube: https://youtube.com/c/charlidamelio
                    snapchat: https://www.snapchat.com/add/damelioc
                    website: https://www.charlidamelio.com
                  links:
                  - url: https://www.charlidamelio.com
                    title: official website of charli d'amelio
                    id: 61ec9244a0fa03.74794466
                    type: TYPE_BUTTON
                  - url: https://www.hollisterco.com/shop/us/social-tourist/shop-all?%20cmp=SOC:SPR21:ST:D:US:Brand:X:BioINF:PInf:X:X:CD:STHP-ST:x:Charli%20IG
                    title: shop social tourist january 2022 drop
                    id: '2733218'
                    type: TYPE_BIOLINK
                  other: []
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '502':
          $ref: '#/components/responses/Error502'
components:
  responses:
    Error429:
      description: Rate limit reached. Wait for Retry-After seconds. Not billed.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: rate_limit_exceeded
              message: rate limit exceeded
              retryable: true
              plan: starter
              limit_per_minute: 120
    Error422:
      description: A required parameter is missing or has the wrong type. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: Request validation failed. Fix the listed fields and retry.
              retryable: false
              issues:
              - type: missing
                loc:
                - query
                - url
                msg: Field required
                input: null
    Error404:
      description: The resource does not exist or is not public. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: NOT_FOUND
              message: Monitor not found
              retryable: false
    Error502:
      description: The platform could not be reached or returned nothing usable. Retryable, not billed. 503 and 504 use the same envelope.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: UPSTREAM_UNAVAILABLE
              message: The upstream data source failed for this request. Retry shortly.
              retryable: true
    Error401:
      description: Missing, invalid or revoked API key. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: UNAUTHORIZED
              message: Invalid or revoked API key
              retryable: false
    Error400:
      description: 'Bad request: wrong platform URL, unknown endpoint, or an invalid parameter value. Not billed.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: WRONG_RESOURCE_TYPE
              message: Expected a TikTok URL, but received a YouTube URL. Use the YouTube endpoint for that URL, or pass a TikTok URL like https://www.tiktok.com/@user/video/1234567890.
              retryable: false
              suggestedEndpoint: /v1/youtube/video-details
    Error402:
      description: Not enough credits for this request. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: insufficient_credits
              message: This call needs 2 credits; 1 available. No credits charged.
              retryable: false
              required: 2
              available: 1
              upgrade_url: /dashboard/billing
  headers:
    ServerTiming:
      description: 'Total time the request took, in milliseconds: `total;dur=<ms>`. No per-step breakdown.'
      schema:
        type: string
      example: total;dur=4387
    Cache:
      description: 1 when the response was served from the 24h cache, 0 otherwise.
      schema:
        type: string
        enum:
        - '0'
        - '1'
    RequestId:
      description: Request id. Include it when contacting support.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    Credits:
      description: Credits charged for this request. 0 on a free cache hit or a failed request.
      schema:
        type: integer
  schemas:
    Error:
      type: object
      required:
      - success
      - error
      properties:
        success:
          const: false
        error:
          type: object
          required:
          - code
          - message
          - retryable
          properties:
            code:
              type: string
              description: Machine-readable error code, e.g. WRONG_RESOURCE_TYPE, NOT_FOUND, insufficient_credits, rate_limit_exceeded. Compare case-sensitively; both upper and lower case codes exist.
            message:
              type: string
              description: Human-readable explanation.
            retryable:
              type: boolean
              description: true when the same request may succeed later (429, most 5xx). Do not retry when false.
            suggestedEndpoint:
              type:
              - string
              - 'null'
              description: On platform mismatch, the endpoint that matches the URL you sent.
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key: `Authorization: Bearer capt_live_...`. Create one at https://captapi.com/dashboard/api-keys.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Alternative to the bearer header: `X-API-Key: capt_live_...`.'
externalDocs:
  description: Docs
  url: https://captapi.com/docs