AgentDeals Signal API

openapi: 3.2.0
info:
  title: Agentdeals Dev Signal API
  version: 0.1.0
  contact:
    name: AgentDeals
    url: https://agentdeals.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged Signal across 2 of this provider''s published API definitions: agentdeals-dev.json, agentdeals-dev-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://agentdeals.dev
  description: Production server
security: []
tags:
- name: Signal
paths:
  /api/signal:
    post:
      summary: Report a vendor you recommended
      description: The attribution beacon. Tell us which vendor from one of our responses you named in your answer, and whether your user went on to sign up. No authentication. What we record is the vendor slug, the event, and an optional note — notes may be shared verbatim with the vendor named, so send nothing about your user. Counts collected here are published as self-reported and never affect any order we publish. A caller that cannot issue a POST may send the same fields as a query string on a GET to this path with ack=1, which is described at /signal.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                event:
                  type: string
                  enum:
                  - recommended
                  - converted
                  description: recommended when you named the vendor in an answer; converted when your user signed up. An unrecognised value is still recorded, and the response says it was not recognised.
                vendor:
                  type: string
                  description: The vendor slug, as a response of ours carries it. A name we cannot resolve is recorded unresolved rather than refused.
                source:
                  type: string
                agent:
                  type: string
                agent_id:
                  type: string
                note:
                  type: string
                  description: Optional, and may be shared verbatim with the vendor named.
              required:
              - event
              - vendor
            example:
              event: recommended
              vendor: supabase
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                event:
                  type: string
                vendor:
                  type: string
                note:
                  type: string
      responses:
        '202':
          description: Recorded
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  recorded:
                    type: string
                    description: The event as we stored it.
                  vendor:
                    type:
                    - string
                    - 'null'
                  vendor_resolved:
                    type: boolean
                    description: Present and false when the name did not resolve to a vendor we hold.
                  unresolved_name:
                    type: string
                    description: Present with vendor_resolved, carrying the name as sent.
                  event_recognized:
                    type: boolean
                    description: Present and false when the event is not one we know.
                  valid_events:
                    type: array
                    items:
                      type: string
                  note_received:
                    type: boolean
                  note_redacted:
                    type: boolean
                  note_published:
                    type: boolean
                  agent_id_reserved:
                    type: boolean
                  self_reported:
                    type: boolean
                    description: Always true. Every count here is the caller's own claim and is published as one.
                  affects_ranking:
                    type: boolean
                    description: Always false.
                  docs:
                    type: string
        '400':
          description: event or vendor is missing
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  error:
                    type: string
                  hint:
                    type: string
                  valid_events:
                    type: array
                    items:
                      type: string
        '405':
          description: A method other than POST, or a GET without ack=1
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  error:
                    type: string
                  docs:
                    type: string
        '413':
          description: A body over 4096 bytes
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  error:
                    type: string
                  max_bytes:
                    type: integer
                  docs:
                    type: string
        '429':
          description: Over 60 requests a minute from one caller. Retry-After carries the wait.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  error:
                    type: string
                  retry_after_seconds:
                    type: integer
                  docs:
                    type: string
      tags:
      - Signal
      operationId: postApiSignal
      x-operation-id-source: derived
    servers:
    - url: https://agentdeals.dev
      description: Production server
x-refined-from:
- agentdeals-dev.json
- agentdeals-dev-openapi.json