upscrape-com Pinterest API

openapi: 3.2.0
info:
  title: Upscrape Pinterest API
  description: 'Modular scraping API with async job queue support, production-grade protections, caching, and observability.


    ## Authentication

    All `/api/v1/*` endpoints require authentication via:

    - `Authorization: Bearer ` (preferred)

    - `X-Api-Key: `


    ## Rate Limiting

    Requests are rate-limited per client (default: 20 RPS). When exceeded, returns 429 with `Retry-After` header.


    ## Monthly Quota

    Pinterest endpoints have a monthly quota based on pins returned. Check usage at `/api/v1/usage/pinterest`.

    Quota headers are included in all Pinterest responses: `X-Quota-Limit`, `X-Quota-Used`, `X-Quota-Remaining`.


    ## Async Mode

    Use `?async=true` query parameter to submit jobs asynchronously. Returns immediately with a job ID.

    Poll `/api/v1/jobs/{job_id}` for status or use SSE at `/api/v1/jobs/{job_id}/events` for real-time updates.'
  version: 1.0.0
  contact:
    name: Upscrape Support
servers:
- url: https://api.upscrape.com
  description: Production server
- url: http://localhost:8080
  description: Local development server
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Pinterest
paths:
  /api/v1/pinterest/pins:
    post:
      summary: Fetch Pinterest pins
      description: 'Fetch pin data for a batch of Pinterest URLs.


        **Sync mode (default)**: Processes all URLs and returns results in one response.


        **Async mode (`?async=true`)**: Enqueues a job and returns immediately with a job ID.

        Use the job endpoints to poll for status or stream results via SSE.'
      tags:
      - Pinterest
      parameters:
      - name: async
        in: query
        description: Set to "true" to process asynchronously
        schema:
          type: string
          enum:
          - 'true'
      - name: Idempotency-Key
        in: header
        description: Unique key for request deduplication (async mode only)
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PinsRequest'
      responses:
        '200':
          description: Sync mode - pins fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinsResponse'
        '202':
          description: Async mode - job enqueued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Server busy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: postApiV1PinterestPins
      x-operation-id-source: derived
components:
  schemas:
    PinsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              pins:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    image:
                      type: string
                    description:
                      type: string
      required:
      - results
    AsyncResponse:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - queued
          - running
      required:
      - job_id
      - status
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
      - error
      - message
    PinsRequest:
      type: object
      properties:
        urls:
          type: array
          items:
            type: string
          description: List of Pinterest URLs to fetch pins from.
      required:
      - urls