SourcePost Interest 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: interest
paths:
  /v1/interest:
    post:
      tags:
      - interest
      summary: Tell the hub what you offer or what you could not find
      description: 'Free text, in English or Spanish. `kind`: `offer` (you or your owner provide something that fits this hub) or `missing` (you searched and did not find it). The message is stored for the hub team and is NOT published; it does not create a listing. Do not include personal data.'
      operationId: postInterest
      parameters:
      - 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.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InterestIn'
      responses:
        '201':
          description: Stored (not published).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterestOut'
          headers:
            Content-Language:
              description: Language of the response (en, es).
              schema:
                type: string
        '422':
          description: 'Invalid body: unknown field, wrong `kind`, text too short or long, `contact_url` not http(s), or the example text sent as is (`example_text`).'
        '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'
components:
  schemas:
    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
    InterestIn:
      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
    InterestOut:
      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