SourcePost Listings API

openapi: 3.2.0
info:
  title: SourcePost — directory of suppliers and services for AI…
  description: 'SourcePost is a directory where AI agents find suppliers, services and data sources for their task.


    **Current niche:** Resale sourcing — Suppliers, wholesale marketplaces, price data and automation tools for agents that look for products to resell.


    How to use it:

    1. `GET /v1/listings` to search (free text in English or Spanish, plus filters).

    2. `GET /v1/listings/{id}` for one listing.

    3. If you offer something that fits, or did not find what you needed, tell us with

    `POST /v1/interest`. Every search response carries an `invitation` with the exact URL.

    Messages are stored for the SourcePost team and are not published.


    Rules you can rely on:

    - **Sponsored** listings appear only in `sponsored_results` (at most 3, `sponsored: true`),

    never in `results`.

    - **Languages:** `en` (default) and `es`. Use `?lang=` or `Accept-Language`; the response says

    which one it used (`Content-Language`, `lang`). Listings without a translation fall back to

    English.

    - **Prices:** price information as free text (`pricing_info`), with its source

    (`price_source`: the provider''s own site or a third party) and the date SourcePost last checked

    it (`price_checked_at`).

    - **Links:** each listing''s `url` carries `utm_source=sourcepost.dev` and `utm_medium=agent-directory`, so the provider can see that the visit came from SourcePost; they never contain data about you. `url_original` is the same link without tags.

    - **Rate limits:** 60 requests per minute per client, and 10 messages

    per hour to `POST /v1/interest`. Over the limit you get `429` with `Retry-After` (seconds).

    - SourcePost does not store your IP address in its request records (see `/privacy`).'
  version: 0.1.0
servers:
- url: https://sourcepost.dev
tags:
- name: Listings
paths:
  /v1/listings:
    get:
      tags:
      - Listings
      summary: Search listings
      description: 'Search active listings of the hub. Free text matches English and Spanish content. Paid placements come only in `sponsored_results` (at most 3, `sponsored: true`) and never in `results`. Every response carries an `invitation` to tell the hub what you offer or what you could not find.'
      operationId: searchListings
      parameters:
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          description: Free text, any language.
          title: Q
        description: Free text, any language.
      - name: category
        in: query
        required: false
        schema:
          type: string
          enum:
          - automation_tool
          - dropshipping_supplier
          - price_data
          - print_on_demand
          - sourcing_agent
          - supplier_directory
          - wholesale_marketplace
        description: Category id of the active niche (see the allowed values).
      - name: offer_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/OfferType'
          - type: 'null'
          description: Only this kind of offer.
          title: Offer Type
        description: Only this kind of offer.
      - name: verified_only
        in: query
        required: false
        schema:
          type: boolean
          description: Only listings verified by the hub.
          default: false
          title: Verified Only
        description: Only listings verified by the hub.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          description: Results per page (1–50).
          default: 20
          title: Limit
        description: Results per page (1–50).
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 0
          description: Results to skip, for the next pages.
          default: 0
          title: Offset
        description: Results to skip, for the next pages.
      - name: lang
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Response language (en, es). Overrides Accept-Language. Default: en.'
          title: Lang
        description: 'Response language (en, es). Overrides Accept-Language. Default: en.'
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
          headers:
            Content-Language:
              description: Language of the response (en or es).
              schema:
                type: string
        '422':
          description: Invalid parameter, or unknown category (`unknown_category` lists the allowed ones).
        '429':
          description: Too many requests from this client. Wait `Retry-After` seconds.
          headers:
            Retry-After:
              description: Seconds to wait before the next request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedOut'
  /v1/listings/{listing_id}:
    get:
      tags:
      - Listings
      summary: Get one listing
      description: One active listing by id, in the requested language (falls back to English, the `lang` field says which one was served). Listings that are not public return 404.
      operationId: getListing
      parameters:
      - name: listing_id
        in: path
        required: true
        schema:
          type: string
          description: Listing id, as returned by the search.
          title: Listing Id
        description: Listing id, as returned by the search.
      - name: lang
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Response language (en, es). Overrides Accept-Language. Default: en.'
          title: Lang
        description: 'Response language (en, es). Overrides Accept-Language. Default: en.'
      responses:
        '200':
          description: The listing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingOut'
          headers:
            Content-Language:
              description: Language of the response (en, es).
              schema:
                type: string
        '404':
          description: No public listing with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '429':
          description: Too many requests from this client. Wait `Retry-After` seconds.
          headers:
            Retry-After:
              description: Seconds to wait before the next request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ErrorOut:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    RateLimitedOut:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    OfferType:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    SearchResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    ListingOut:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    HTTPValidationError:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true