captapi-com Status API

openapi: 3.2.0
info:
  title: Captapi Status 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: Status
  description: Live API health per platform.
paths:
  /v1/status:
    get:
      operationId: api_status
      tags:
      - Status
      summary: Public API health (live, based on latest requests, no auth required)
      description: Per-platform health from the most recent requests in the last 24 hours. Only 5xx responses count against health; 4xx responses are caller errors. A platform is degraded after 1 trailing 5xx and in outage after 3. Cached for 120 seconds. No API key needed. Free. Example values are illustrative.
      security: []
      x-credit-cost:
        label: 0 credits
        credits: 0
      x-one-liner: Per-platform health from the most recent requests in the last 24 hours.
      responses:
        '200':
          description: Success.
          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:
                      overall:
                        type: object
                        properties:
                          status:
                            type: string
                          requests_24h:
                            type: integer
                      platforms:
                        type: array
                        items:
                          type: object
                          properties:
                            platform:
                              type: string
                            status:
                              type: string
                            success_rate:
                              type: integer
                            requests_24h:
                              type: integer
                            avg_response_ms:
                              type: integer
                      window_hours:
                        type: integer
                      generated_at:
                        type: string
              example:
                success: true
                data:
                  overall:
                    status: operational
                    requests_24h: 1200
                  platforms:
                  - platform: youtube
                    status: operational
                    success_rate: 100
                    requests_24h: 200
                    avg_response_ms: 2000
                  window_hours: 24
                  generated_at: '2026-10-10T18:12:49.049323+00:00'
        '429':
          $ref: '#/components/responses/Error429'
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
  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