openapi: 3.2.0
info:
  title: Social Fetch Public System API
  version: 1.0.0
  description: 'REST API for Social Fetch. Versioned routes under `/v1` accept `x-api-key` credits or x402 USDC on Base (walk-up, no key). OpenAPI: https://api.socialfetch.dev/openapi.json. x402 discovery: https://api.socialfetch.dev/.well-known/x402. MCP: https://api.socialfetch.dev/mcp (POST). Docs and agent guide: https://www.socialfetch.dev/docs and https://www.socialfetch.dev/llms.txt.'
servers:
- url: https://api.socialfetch.dev
  description: API origin
tags:
- name: System
paths:
  /v1/ask:
    post:
      tags:
      - System
      summary: Ask in natural language
      description: Route a natural-language social-data question to the right lookup when you do not yet know the typed tool — prefer typed tools once the operation is known.
      security:
      - ApiKeyAuth: []
      x-socialfetch-pricing:
        version: 1
        baseCredits: 0
        surcharges: []
        maxCredits: 0
        normalizationFailureCredits: 0
      x-socialfetch-credits-pricing: Routing is free. The nested lookup bills at that endpoint's normal credit rate — see meta.creditsCharged.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  minLength: 1
                  maxLength: 500
                  description: Natural-language question to route to a public API lookup.
              required:
              - query
              description: Request body for POST /v1/ask.
            example:
              query: How many TikTok followers does MrBeast have?
      responses:
        '200':
          description: Routed lookup result with the underlying public API response nested in `data.lookup`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      query:
                        type: string
                        description: Echo of the submitted natural-language question.
                      routedOperation:
                        type: object
                        properties:
                          operationId:
                            type: string
                            description: Resolved public API operation id, e.g. youtube.channel.get.
                          method:
                            type: string
                            description: HTTP method for the routed lookup.
                          path:
                            type: string
                            description: OpenAPI path template for the routed lookup.
                          params:
                            type: object
                            additionalProperties: {}
                            description: Path and query parameters for the routed lookup.
                        required:
                        - operationId
                        - method
                        - path
                        - params
                        description: Resolved public API operation for the natural-language request.
                      lookup:
                        type: object
                        properties:
                          data:
                            description: Success payload from the routed lookup. Shape depends on the resolved operation.
                          meta:
                            type: object
                            properties:
                              requestId:
                                type: string
                                description: Request id for the nested lookup response.
                              creditsCharged:
                                type: number
                                description: Credits charged for the routed lookup.
                              version:
                                type: string
                                enum:
                                - v1
                            required:
                            - requestId
                            - creditsCharged
                            - version
                        required:
                        - meta
                        description: Nested lookup response from the routed public API operation.
                    required:
                    - query
                    - routedOperation
                    - lookup
                    description: Endpoint-specific response payload.
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                        minLength: 1
                        description: Unique request identifier for tracing this API call.
                      creditsCharged:
                        type: integer
                        minimum: 0
                        description: Credits charged for this request.
                      version:
                        type: string
                        enum:
                        - v1
                        description: Public API version that served the response.
                      cached:
                        type: boolean
                        description: True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.
                    required:
                    - requestId
                    - creditsCharged
                    - version
                    description: Metadata describing the request and billing outcome.
                required:
                - data
                - meta
                description: Standard success response envelope.
              example:
                data:
                  query: How many TikTok followers does MrBeast have?
                  routedOperation:
                    operationId: tiktok.profile.get
                    method: GET
                    path: /v1/tiktok/profiles/{handle}
                    params:
                      handle: MrBeast
                  lookup:
                    data:
                      lookupStatus: found
                    meta:
                      requestId: req_example
                      creditsCharged: 1
                      version: v1
                meta:
                  requestId: req_example
                  creditsCharged: 1
                  version: v1
        '400':
          description: Invalid query or routing failure
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - bad_request
                        description: Machine-readable error code for the failed request.
                      message:
                        type: string
                        description: Human-readable error message. May change over time; do not parse it. Use `error.code` and the HTTP status for programmatic handling.
                      requestId:
                        type: string
                        description: Unique request identifier for tracing the failed API call.
                      checkoutUrl:
                        type: string
                        format: uri
                        description: Optional one-click checkout URL when credits are exhausted and a conversion offer is available.
                    required:
                    - code
                    - message
                    - requestId
                    description: Error details for the failed request.
                required:
                - error
                description: Standard error response envelope.
              example:
                error:
                  code: bad_request
                  message: Example message.
                  requestId: req_01example
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - unauthorized
                        description: Machine-readable error code for the failed request.
                      message:
                        type: string
                        description: Human-readable error message. May change over time; do not parse it. Use `error.code` and the HTTP status for programmatic handling.
                      requestId:
                        type: string
                        description: Unique request identifier for tracing the failed API call.
                      checkoutUrl:
                        type: string
                        format: uri
                        description: Optional one-click checkout URL when credits are exhausted and a conversion offer is available.
                    required:
                    - code
                    - message
                    - requestId
                    description: Error details for the failed request.
                required:
                - error
                description: Standard error response envelope.
              example:
                error:
                  code: unauthorized
                  message: Example message.
                  requestId: req_01example
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - insufficient_credits
                        description: Machine-readable error code for the failed request.
                      message:
                        type: string
                        description: Human-readable error message. May change over time; do not parse it. Use `error.code` and the HTTP status for programmatic handling.
                      requestId:
                        type: string
                        description: Unique request identifier for tracing the failed API call.
                      checkoutUrl:
                        type: string
                        format: uri
                        description: Optional one-click checkout URL when credits are exhausted and a conversion offer is available.
                    required:
                    - code
                    - message
                    - requestId
                    description: Error details for the failed request.
                required:
                - error
                description: Standard error response envelope.
              example:
                error:
                  code: insufficient_credits
                  message: Example message.
                  requestId: req_01example
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - internal_error
                        description: Machine-readable error code for the failed request.
                      message:
                        type: string
                        description: Human-readable error message. May change over time; do not parse it. Use `error.code` and the HTTP status for programmatic handling.
                      requestId:
                        type: string
                        description: Unique request identifier for tracing the failed API call.
                      checkoutUrl:
                        type: string
                        format: uri
                        description: Optional one-click checkout URL when credits are exhausted and a conversion offer is available.
                    required:
                    - code
                    - message
                    - requestId
                    description: Error details for the failed request.
                required:
                - error
                description: Standard error response envelope.
              example:
                error:
                  code: internal_error
                  message: Example message.
                  requestId: req_01example
        '502':
          description: Lookup failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - lookup_failed
                        description: Machine-readable error code for the failed request.
                      message:
                        type: string
                        description: Human-readable error message. May change over time; do not parse it. Use `error.code` and the HTTP status for programmatic handling.
                      requestId:
                        type: string
                        description: Unique request identifier for tracing the failed API call.
                      checkoutUrl:
                        type: string
                        format: uri
                        description: Optional one-click checkout URL when credits are exhausted and a conversion offer is available.
                    required:
                    - code
                    - message
                    - requestId
                    description: Error details for the failed request.
                required:
                - error
                description: Standard error response envelope.
              example:
                error:
                  code: lookup_failed
                  message: Example message.
                  requestId: req_01example
        '503':
          description: Temporarily unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - temporarily_unavailable
                        description: Machine-readable error code for the failed request.
                      message:
                        type: string
                        description: Human-readable error message. May change over time; do not parse it. Use `error.code` and the HTTP status for programmatic handling.
                      requestId:
                        type: string
                        description: Unique request identifier for tracing the failed API call.
                      checkoutUrl:
                        type: string
                        format: uri
                        description: Optional one-click checkout URL when credits are exhausted and a conversion offer is available.
                    required:
                    - code
                    - message
                    - requestId
                    description: Error details for the failed request.
                required:
                - error
                description: Standard error response envelope.
              example:
                error:
                  code: temporarily_unavailable
                  message: Example message.
                  requestId: req_01example
      operationId: postV1Ask
      x-operation-id-source: derived
  /health:
    get:
      tags:
      - System
      summary: Health check
      description: Check API availability.
      responses:
        '200':
          description: Service is running
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                    description: Health status for the service.
                required:
                - status
                description: Simple health check response.
        '429':
          description: Health endpoint rate limited
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - temporarily_unavailable
                        description: Machine-readable error code for the failed request.
                      message:
                        type: string
                        description: Human-readable error message. May change over time; do not parse it. Use `error.code` and the HTTP status for programmatic handling.
                      requestId:
                        type: string
                        description: Unique request identifier for tracing the failed API call.
                      checkoutUrl:
                        type: string
                        format: uri
                        description: Optional one-click checkout URL when credits are exhausted and a conversion offer is available.
                    required:
                    - code
                    - message
                    - requestId
                    description: Error details for the failed request.
                required:
                - error
                description: Standard error response envelope.
              example:
                error:
                  code: temporarily_unavailable
                  message: Example message.
                  requestId: req_01example
      operationId: getHealth
      x-operation-id-source: derived
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key (`sfk_...`)