scrapefield-com Catalogue API

openapi: 3.2.0
info:
  title: ScrapeField Catalogue API
  version: 1.0.0
  summary: One API for Google Maps, LinkedIn, Instagram, TikTok and X.
  description: 'One key, one invoice, five platforms — and each platform''s data in its own shape. A Google Maps place is named the way Google''s Places API names it, an Instagram post the way the Graph API does, a TikTok video the way TikTok''s own APIs do, an X post the way X''s API v2 does; LinkedIn, which has no official data API, uses the words it prints.


    **Conventions.** The same everywhere: the `{ data, meta }` envelope, snake_case, ISO 8601 UTC timestamps, the platform''s own ids as strings, and every documented key present on every object.


    **Pricing.** Every endpoint has a published credit cost, carried here as `x-credits`. Multiply by your volume to get your bill — there are no plans and no tiers, just credits. A call we fail is refunded automatically and the reversal appears in your usage ledger.


    **Pagination.** Cursor only. Pass `meta.next_cursor` back as `cursor`; `null` means the last page. A page holds at most `limit` rows, sometimes fewer; an endpoint without `limit` has a fixed page size, given in its description. A cursor lasts as long as the answer is cached (hours); after that it is refused with `invalid_cursor`.


    **Demo.** Any data endpoint answers with no key when you add `?demo=true`: a fixed answer in the same shape, charged nothing.


    **Nulls.** A field is `null` when the platform does not expose it — never 0 and never a guess.'
  contact:
    name: Support
    url: https://scrapefield.com/contact
    email: support@scrapefield.com
servers:
- url: https://api.scrapefield.com/v1
security:
- bearerAuth: []
tags:
- name: Catalogue
paths:
  /endpoints:
    get:
      operationId: listEndpoints
      tags:
      - Catalogue
      summary: 'Every endpoint: its price, parameters and what it returns'
      security:
      - {}
      responses:
        '200':
          description: The endpoint table.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        endpoint:
                          type: string
                        surface:
                          type: string
                        summary:
                          type: string
                        available:
                          type: boolean
                          description: 'Whether a call can be served now: false for an endpoint not offered yet, and for one that cannot be served this minute, as `/v1/status` shows.'
                        unavailable_because:
                          type: string
                          description: Why it is not available, when it is not.
                        credits:
                          type: integer
                        credits_by:
                          type: object
                          properties:
                            parameter:
                              type: string
                            credits:
                              type: object
                              additionalProperties:
                                type: integer
                        returns:
                          type: string
                        list:
                          type: boolean
                        cache_ttl_seconds:
                          type: integer
                        parameters:
                          type: array
                          items:
                            type: object
  /errors:
    get:
      operationId: listErrors
      tags:
      - Catalogue
      summary: 'Every error code: when it happens and what to do'
      security:
      - {}
      responses:
        '200':
          description: The error catalogue.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        type:
                          type: string
                          enum:
                          - invalid_request
                          - authentication_error
                          - method_not_allowed
                          - permission_error
                          - not_found
                          - rate_limit
                          - upstream_error
                          - not_available
                          - internal_error
                        when:
                          type: string
                        fix:
                          type: string
  /status:
    get:
      operationId: getStatus
      tags:
      - Catalogue
      summary: Whether each endpoint is working now
      security:
      - {}
      responses:
        '200':
          description: The state of the API.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    properties:
                      state:
                        type: string
                        enum:
                        - operational
                        - degraded
                        - unavailable
                      checked_at:
                        type: string
                        format: date-time
                      measured_at:
                        type: string
                        format: date-time
                        description: 'When the 30-day numbers were read: at most a minute before `checked_at`.'
                      surfaces:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: object
                            properties:
                              endpoint:
                                type: string
                              state:
                                type: string
                                enum:
                                - operational
                                - degraded
                                - unavailable
                              credits:
                                type: integer
                              success_rate:
                                type:
                                - number
                                - 'null'
                                description: Answered calls of all counted, in percent, the last 30 days. Null below 50 calls.
                              p50_ms:
                                type:
                                - integer
                                - 'null'
                                description: The median answer time, the last 30 days. Null below 50 calls.
                              p95_ms:
                                type:
                                - integer
                                - 'null'
                                description: 95 of 100 answers came in this time or less, the last 30 days. Null below 50 calls.
                              calls_30d:
                                type: integer
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key: `Authorization: Bearer sf_live_…`'