Defici Public Browse API

openapi: 3.2.0
info:
  title: Defici Com Public Browse API
  version: live
  description: 'Operations tagged Public Browse across 2 of this provider''s published API definitions: defici-com-openapi.json, defici-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://defici.com
security:
- bearerAuth: []
tags:
- name: Public Browse
  description: Read-only public endpoints — no authentication required.
paths:
  /api/ads:
    get:
      tags:
      - Public Browse
      summary: Contact fields (phone, email, whatsapp, website) are omitted from anonymous…
      description: 'Contact fields (phone, email, whatsapp, website) are omitted from anonymous responses. Every listing price is in USD (converted at ingest from the seller''s currency via daily FX rates), so priceMin/priceMax are USD too. An empty `ads` array on a 200 means the catalogue really has no match — a server-side read failure is a 503, and a search query the backend rejects (e.g. text blocked at the edge) is a 400 invalid_query; neither is ever an empty 200. Do not treat `total: null` as zero: it means the count is unavailable while the rows are real.


        Rate limit: No per-endpoint limit on this public browse route — no 429 and no RateLimit-* headers are emitted here; throttling is edge/cluster-level only (≈60 req/min across the 2-instance cluster). The plan-dependent 30 req/min figure in the preamble applies to authenticated agent-API endpoints, not this route.


        Auth: public'
      operationId: get_ads
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                ads:
                - id: uuid
                  title: string
                  description: string
                  category: string
                  price: number|null — USD
                  currency: '''USD'''
                  city: string|null
                  market: string
                  is_promo: false
                  created_at: ISO8601
                  currency_original: string — the currency the seller priced in (provenance)
                  price_original: number|null — the seller's original amount
                total: number|null (null = count unavailable, NOT zero)
                page: number
                totalPages: number|null (null whenever total is null)
                limit: number — the page size actually applied
                limitRequested: number — present ONLY when your `limit` exceeded the max and was capped; the short page is not the end of the results
      security: []
      parameters:
      - name: optional
        in: query
        required: false
        schema:
          type: string
        description: '["q","category","market","priceMin","priceMax","page","limit"]'
      - name: types
        in: query
        required: false
        schema:
          type: string
        description: '{"q":"string — full-text search (PostgreSQL websearch syntax)","category":"string — category slug or alias","market":"string","priceMin":"number — minimum price, in USD (every listing price is stored in USD)","priceMax":"number — maximum price, in USD","page":"number (default 1)","limit":"number (default 30, max 30)"}'
    servers:
    - url: https://defici.com
  /api/ads/{id}:
    get:
      tags:
      - Public Browse
      summary: GET /api/ads/{id}
      description: 'The endpoint itself is keyless; contact fields are omitted from the response unless the caller is signed in. A keyless call succeeds — it simply returns fewer fields.


        Auth: public (contact fields gated behind login)'
      operationId: get_ads_id
      responses:
        '200':
          description: Success
          content:
            application/json:
              example: '{ full listing row minus private contact fields for anonymous requests }'
      security: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: uuid
    servers:
    - url: https://defici.com
  /api/public/metrics:
    get:
      tags:
      - Public Browse
      summary: Live DB-grounded platform proof metrics
      description: 'Live DB-grounded platform proof metrics. Each metric is an object with its own value and query timestamp — there is no single top-level query time for the whole response. A metric with no real data behind it is absent rather than shown as zero or guessed, so do not read a missing key as a zero.


        Auth: public'
      operationId: get_public_metrics
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                available: true
                total_listings:
                  value: number
                  computed_at: ISO8601
                  source: string (plain-language description of what this value represents)
                active_listings:
                  value: number
                  computed_at: ISO8601
                  source: string (plain-language description of what this value represents)
                markets_count:
                  value: number (count of actively served/pickable markets — PICKABLE_MARKET_COUNT)
                  computed_at: ISO8601
                  source: string (plain-language description of what this value represents)
                active_contests:
                  value: number
                  computed_at: ISO8601
                  source: string (plain-language description of what this value represents)
      security: []
    servers:
    - url: https://defici.com
  /api/mcp:
    get:
      tags:
      - Public Browse
      summary: Model Context Protocol 2025-03-26 SSE endpoint advertisement for HTTP+SSE…
      description: 'Model Context Protocol 2025-03-26 SSE endpoint advertisement for HTTP+SSE clients.


        Auth: public'
      operationId: get_mcp
      responses:
        '200':
          description: Success
          content:
            application/json:
              example: SSE stream advertising MCP tools.
      security: []
    post:
      tags:
      - Public Browse
      summary: MCP Streamable HTTP — JSON-RPC 2.0 request
      description: 'MCP Streamable HTTP — JSON-RPC 2.0 request. Tools: search_listings, get_listing, list_categories, get_regions.


        Auth: public'
      operationId: post_mcp
      responses:
        '200':
          description: Success
          content:
            application/json:
              example: '{ jsonrpc: "2.0", id: 1, result: { content: [...] } }'
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
            example:
              example:
                jsonrpc: '2.0'
                id: 1
                method: tools/call
                params:
                  name: search_listings
                  arguments:
                    q: laptop
                    limit: 5
    servers:
    - url: https://defici.com
  /api/news:
    get:
      tags:
      - Public Browse
      summary: ai_generated = true means the article text was produced by Defici's AI…
      description: 'ai_generated = true means the article text was produced by Defici''s AI editorial system (EU AI Act Art.50 machine-readable disclosure). Read this field, not the author name, to determine authorship type.


        Auth: public'
      operationId: get_news
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                articles:
                - id: uuid
                  slug: string
                  title: string
                  excerpt: string
                  category: string
                  market: string
                  author: string
                  published_at: ISO8601
                  is_archived: boolean
                  ai_generated: boolean
                count: number
                limit: number
                archived: boolean
      security: []
      parameters:
      - name: optional
        in: query
        required: false
        schema:
          type: string
        description: '["n","limit","category","archived"]'
      - name: types
        in: query
        required: false
        schema:
          type: string
        description: '{"n":"number (default 10, max 50)","category":"string","archived":"true|false"}'
    servers:
    - url: https://defici.com
  /api/news/latest:
    get:
      tags:
      - Public Browse
      summary: GET /api/news/latest
      description: 'Auth: public'
      operationId: get_news_latest
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                status: ok|stalled|no_articles
                latest:
                  id: uuid
                  title: string
                  created_at: ISO8601
                  published_at: ISO8601
                  ai_generated: boolean
                hours_since_latest: number
      security: []
    servers:
    - url: https://defici.com
  /feed.json:
    get:
      tags:
      - Public Browse
      summary: Machine-readable feed of OUR OWN active listings, refreshed every 6 h by cron
      description: 'Machine-readable feed of OUR OWN active listings, refreshed every 6 h by cron. NOT the full catalogue and NOT a bulk download of it: scraped third-party listings are excluded by design. The envelope declares population, record_count, total and partial, and the same statement is repeated in X-Feed-* response headers. Listing fields: id, title, price, currency, region, country, images, seller_type, availability, updated_at, category.


        Auth: public'
      operationId: get__feed_json
      responses:
        '200':
          description: Success
          content:
            application/json:
              example: 'JSON object: { generated_at, record_count, total, partial, pagination, population, source, feed_url, csv_url, listings: [...] }.'
        '503':
          description: Feed not yet generated - the generator runs every 6 hours
      security: []
    servers:
    - url: https://defici.com
  /feed.csv:
    get:
      tags:
      - Public Browse
      summary: The CSV twin of /feed.json, RFC 4180
      description: 'The CSV twin of /feed.json, RFC 4180. Same data, same 6 h cron. This is NOT a bulk-read surface for the full ads catalogue - there is no such surface; use the search endpoints to reach the catalogue. A CSV carries no envelope, so population, record_count, total and partial arrive in the X-Feed-* response headers. Columns (double-quoted): id, title, price, currency, region, country, images (JSON-encoded array), seller_type, availability, updated_at, category.


        Auth: public'
      operationId: get__feed_csv
      responses:
        '200':
          description: Success
          content:
            application/json:
              example: text/csv stream with headers, plus X-Feed-Population / X-Feed-Record-Count / X-Feed-Total / X-Feed-Partial / X-Feed-Pagination / X-Feed-Generated-At.
        '503':
          description: Feed not yet generated - the generator runs every 6 hours
      security: []
    servers:
    - url: https://defici.com
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: ak_ key from POST /api/v1/agent/challenge → /verify. Also accepted as X-API-Key.
x-refined-from:
- defici-com-openapi.json
- defici-com-openapi.yml