{
  "openapi": "3.1.0",
  "info": {
    "title": "Altimateguide agent submission API",
    "version": "1.0.0",
    "description": "Submit a tool listing (with structured features) to Altimateguide for editorial review. Submissions are queued as pending: an editor reviews and publishes them. Proof modes map to the four inclusion paths offered on /request-inclusion (SayAbout.Us wall, Altimateguide badge, a one-time paid listing, or the free no-verification request). Review turnaround: paid and sayabout within 2 business days, badge in 5–7 business days, none within 30 days (nofollow); verified and paid submissions are reviewed first. Authenticate with an account API token created at /account (Agent & API access). The anonymous /api/public/* endpoints need no auth and back the MCP server's research tools. A first-party MCP server (`altimateguide-agent-mcp`) wraps both — run it over stdio or connect to the hosted endpoint at /api/mcp (see x-agent-mcp)."
  },
  "servers": [
    {
      "url": "https://altimateguide.com"
    }
  ],
  "paths": {
    "/api/public/search": {
      "get": {
        "operationId": "searchTools",
        "summary": "Search the directory (no auth)",
        "description": "Anonymous search over published tools. Backs the MCP search_tools tool.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "free_plan",
            "in": "query",
            "description": "1 to keep only tools with a free plan",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching tools with canonical /tools/{slug} URLs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/tools/{slug}": {
      "get": {
        "operationId": "getTool",
        "summary": "Read one tool profile (no auth)",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Definition, value proposition, categories, pricing, free plan/trial, pros, cons, features, rating and engagement. Backs the MCP get_tool tool.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Unknown slug."
          }
        }
      }
    },
    "/api/public/compare": {
      "get": {
        "operationId": "compareTools",
        "summary": "Compare two tools (no auth)",
        "description": "Returns both profiles, their shared categories and the canonical /vs/ page when one exists. Backs the MCP compare_tools tool.",
        "parameters": [
          {
            "name": "a",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "b",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Both profiles plus the comparison page URL."
          },
          "404": {
            "description": "One or both slugs are unknown."
          }
        }
      }
    },
    "/api/public/alternatives/{slug}": {
      "get": {
        "operationId": "findAlternatives",
        "summary": "Find alternatives to a tool (no auth)",
        "description": "Returns the curated /alternatives/ page when present, then same-category tools. Backs the MCP find_alternatives tool.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Curated alternatives followed by related tools."
          },
          "404": {
            "description": "Neither a tool nor an alternatives page exists."
          }
        }
      }
    },
    "/api/public/deals": {
      "get": {
        "operationId": "listDeals",
        "summary": "List live deals (no auth)",
        "description": "Time-boxed offers (lifetime deal, sale, launch) that are live right now. Backs the MCP list_deals tool.",
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ltd",
                "sale",
                "launch"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Live offers with their canonical tool page URLs."
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "Hosted MCP endpoint (streamable HTTP)",
        "description": "JSON-RPC endpoint for MCP clients. Stateless: no session id, JSON responses. Exposes the credential-free research tools only; submission tools run on the local stdio server (`npx -y altimateguide-agent-mcp`) until OAuth sign-in lands.",
        "responses": {
          "200": {
            "description": "JSON-RPC response."
          },
          "429": {
            "description": "Per-client rate limit; see Retry-After."
          }
        }
      }
    },
    "/api/agent/submit": {
      "post": {
        "operationId": "submitListing",
        "summary": "Submit a tool listing for editorial review",
        "description": "Creates a pending submission. Idempotent on (source, external_id): replaying the same pair returns the original submission instead of creating a duplicate.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmissionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent replay — the submission already existed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmissionAccepted"
                }
              }
            }
          },
          "202": {
            "description": "Queued for editorial review. Turnaround depends on proof: paid and sayabout within 2 business days, badge in 5–7 business days, none within 30 days (nofollow).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmissionAccepted"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "Duplicate — the tool is already listed or already awaiting review.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Editorial gate — the copy contains promotional language.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/token": {
      "post": {
        "operationId": "createAgentToken",
        "summary": "Mint an account API token from an email OTP (browserless)",
        "description": "The browserless counterpart to /account's token UI: request a code with POST /api/auth/request-code, then exchange it here for an `atg_…` bearer token. The token is bound to the resolved account and can be revoked at /account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "email",
                  "code"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "code": {
                    "type": "string",
                    "pattern": "^[0-9]{6}$"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 60,
                    "description": "Token label."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Token created (returned once).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentToken"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Invalid or expired code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "List the valid category slugs",
        "description": "The valid set for listing.categories / x-category-slugs. Categories are optional on submit — unrecognised ones are recorded for the reviewer.",
        "responses": {
          "200": {
            "description": "Category slugs and titles.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoryList"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/whoami": {
      "get": {
        "operationId": "whoami",
        "summary": "Report the account behind a bearer token",
        "description": "Confirms the token is live and returns the account it resolves to. Returns 401 for a missing, unknown, or revoked token — so an agent can verify its credential without spending a write.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The authenticated account.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer"
                        },
                        "email": {
                          "type": "string",
                          "format": "email"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/agent/check": {
      "get": {
        "operationId": "checkDuplicate",
        "summary": "Preflight a name/URL against published tools and the pending queue",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "url",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Whether a duplicate exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DuplicateCheck"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/agent/submissions/{id}": {
      "get": {
        "operationId": "getSubmission",
        "summary": "Poll a submission's status",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Submission status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmissionStatus"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/listing": {
      "post": {
        "operationId": "chooseListingPath",
        "summary": "Choose an inclusion path (sayabout/badge/paid) for an owned listing",
        "description": "Records the chosen path on a submission for review. `paid` returns a Dodo checkout URL whose metadata carries the submission id — verified server-side by the Dodo webhook. Never publishes and never self-grants dofollow.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "path"
                ],
                "properties": {
                  "path": {
                    "type": "string",
                    "enum": [
                      "sayabout",
                      "badge",
                      "paid"
                    ]
                  },
                  "submissionId": {
                    "type": "integer"
                  },
                  "slug": {
                    "type": "string",
                    "description": "A published tool slug you own (for upgrades)."
                  },
                  "verificationUrl": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Path recorded (and a checkoutUrl for paid).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListingActionResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "You don't own that listing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/listing/{slug}": {
      "patch": {
        "operationId": "updateListing",
        "summary": "Edit the facts of a listing you own",
        "description": "Updates the listing facts (website, description, features, pros/cons, pricing, plan flags, categories). Only the fields you send change. Slug, outbound link tier and paid status are admin-managed. Publishes within the ISR window; copy is run through the neutral-language gate.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListingFactsPatch"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListingEditResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "You don't own that listing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Editorial gate — the copy contains promotional language.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/stats": {
      "get": {
        "operationId": "getListingStats",
        "summary": "Engagement analytics for the listings you own",
        "description": "Visits, upvotes, saves and reviews with lifetime totals plus 7- and 30-day windows. Pass ?slug= to limit to one owned listing.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Per-listing analytics.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListingStatsList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "description": "You don't own that listing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/agentid/start": {
      "post": {
        "operationId": "startAgentIdLogin",
        "summary": "Begin an AgentID sign-in (no email inbox needed)",
        "description": "Returns an authorizeUrl and a flowId. Complete the sign-in at the URL, then poll /api/agent/agentid/poll for an account API token. 503 if AgentID is not configured.",
        "responses": {
          "201": {
            "description": "Flow created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentIdFlow"
                }
              }
            }
          },
          "503": {
            "description": "AgentID is not configured on this server.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/agentid/poll": {
      "get": {
        "operationId": "completeAgentIdLogin",
        "summary": "Poll an AgentID sign-in for its account API token",
        "description": "Returns { status: 'pending' } until the sign-in completes, then the token once (the flow is single-use).",
        "parameters": [
          {
            "name": "flow",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pending or complete.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentIdPollResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "description": "Unknown, expired, or already-used flow.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/deals": {
      "post": {
        "operationId": "submitDeal",
        "summary": "Submit a time-boxed deal for editorial review",
        "description": "Queues a deal (lifetime deal, sale, or launch offer) against a tool. Reviewed in the deal lane: free within 7 days, paid within 2 business days. On approval the offer is written onto the listing and appears on /deals. A deal never changes the listing's link tier. Idempotent on (source, external_id).",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DealRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent replay — the deal already existed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DealAccepted"
                }
              }
            }
          },
          "202": {
            "description": "Deal queued. `review_eta` states the lane's turnaround; `needs_listing` is true when the product is not listed yet (the deal publishes after the listing does).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DealAccepted"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "A deal for this product is already awaiting review.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Account API token. Sign in at /account with email OTP, create a token under \"Agent & API access\", then send it as `Authorization: Bearer <token>`. The submission is owned by that account (it appears on /account) and is attributed to the `source` sent in the body. Tokens can be revoked at any time."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request body.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid bearer token.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "DealRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "toolName",
          "toolUrl",
          "dealUrl",
          "price",
          "kind"
        ],
        "properties": {
          "toolName": {
            "type": "string",
            "description": "Product name"
          },
          "toolUrl": {
            "type": "string",
            "format": "uri",
            "description": "Canonical product URL (matched to a listing by domain)"
          },
          "dealUrl": {
            "type": "string",
            "format": "uri",
            "description": "Page documenting the offer. Required — review verifies the price and dates against it."
          },
          "source": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9:_-]{1,63}$",
            "default": "agent:mcp"
          },
          "external_id": {
            "type": "string",
            "description": "The caller's own id for this deal. With source, makes the call idempotent."
          },
          "agent": {
            "$ref": "#/components/schemas/AgentInfo"
          },
          "kind": {
            "type": "string",
            "enum": [
              "ltd",
              "sale",
              "launch"
            ],
            "description": "ltd = lifetime deal, sale = discount, launch = launch offer"
          },
          "billing": {
            "type": "string",
            "enum": [
              "one-time",
              "month",
              "year"
            ],
            "default": "one-time",
            "description": "How the offer is charged (not the product's normal pricing)"
          },
          "price": {
            "type": "number",
            "minimum": 0
          },
          "wasPrice": {
            "type": "number",
            "minimum": 0,
            "description": "Pre-deal price; shown as the struck-through reference"
          },
          "endsAt": {
            "type": "string",
            "description": "YYYY-MM-DD. Optional — omit for an open-ended offer (it then stays live while the last verification is under 30 days old)."
          },
          "tiers": {
            "type": "array",
            "description": "AppSumo-style code tiers",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "name"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "codes": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          },
          "description": {
            "type": "string",
            "description": "What the deal includes"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional listing categories (real slugs)"
          },
          "payment_ref": {
            "type": "string",
            "maxLength": 200,
            "description": "Optional. Presence puts the deal in the paid lane (within 2 business days) instead of free (within 7 days)."
          }
        }
      },
      "DealAccepted": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "submission_id": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected"
            ]
          },
          "kind": {
            "type": "string",
            "const": "deal"
          },
          "tool_slug": {
            "type": "string",
            "nullable": true
          },
          "needs_listing": {
            "type": "boolean",
            "description": "True when the product is not listed yet — the deal publishes after the listing does."
          },
          "link_tier": {
            "type": "string",
            "const": "unchanged",
            "description": "A deal never changes the listing's outbound link tier."
          },
          "offer": {
            "type": "object",
            "description": "The staged offer"
          },
          "review_eta": {
            "type": "object",
            "properties": {
              "min_days": {
                "type": "integer"
              },
              "max_days": {
                "type": "integer"
              },
              "unit": {
                "type": "string",
                "enum": [
                  "business_days",
                  "calendar_days"
                ]
              }
            }
          },
          "upgrade": {
            "type": "object",
            "description": "Present on the free lane: how to get priority review."
          },
          "message": {
            "type": "string"
          }
        }
      },
      "SubmissionRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "listing",
          "proof"
        ],
        "properties": {
          "source": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9:_-]{1,63}$",
            "description": "Origin identifier for the caller, e.g. agent:claude. Used to filter and rate-limit the source.",
            "examples": [
              "agent:claude",
              "agent:cursor"
            ]
          },
          "external_id": {
            "type": "string",
            "description": "The caller's own id for this listing. With source, makes the call idempotent."
          },
          "agent": {
            "$ref": "#/components/schemas/AgentInfo"
          },
          "listing": {
            "$ref": "#/components/schemas/Listing"
          },
          "proof": {
            "type": "string",
            "enum": [
              "paid",
              "sayabout",
              "badge",
              "none"
            ],
            "default": "none",
            "description": "Inclusion path. paid = one-time dofollow listing (labeled, reviewed within 2 business days) and the fastest route; requires payment_ref. sayabout = free, verified by a live SayAbout.Us Wall of Love URL (reviewed within 2 business days). badge = free, verified by the Altimateguide badge being live on the tool's site (reviewed in 5–7 business days). none = free no-verification listing (nofollow, reviewed within 30 days)."
          },
          "verification_url": {
            "type": "string",
            "format": "uri",
            "description": "Required when proof is sayabout or badge."
          },
          "payment_ref": {
            "type": "string",
            "maxLength": 200,
            "description": "Required when proof is paid. Opaque correlation id from the checkout redirect."
          },
          "human": {
            "type": "object",
            "description": "Optional operator contact used during review.",
            "additionalProperties": false,
            "properties": {
              "email": {
                "type": "string",
                "format": "email"
              }
            }
          }
        },
        "allOf": [
          {
            "if": {
              "required": [
                "proof"
              ],
              "properties": {
                "proof": {
                  "enum": [
                    "sayabout",
                    "badge"
                  ]
                }
              }
            },
            "then": {
              "required": [
                "verification_url"
              ]
            }
          },
          {
            "if": {
              "required": [
                "proof"
              ],
              "properties": {
                "proof": {
                  "const": "paid"
                }
              }
            },
            "then": {
              "required": [
                "payment_ref"
              ]
            }
          }
        ]
      },
      "Listing": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical https URL of the tool."
          },
          "description": {
            "type": "string",
            "minLength": 20,
            "description": "Neutral listing copy. Promotional words (best, top, leading, winner, recommended, must-have, ultimate) are rejected by the editorial gate."
          },
          "categories": {
            "type": "array",
            "minItems": 0,
            "items": {
              "type": "string"
            },
            "description": "Category slugs (see x-category-slugs / GET /api/agent/categories). Optional: a missing or unrecognised category never blocks the submission — unknown slugs are recorded for the reviewer. Put free-text guesses in category_suggestions instead."
          },
          "category_suggestions": {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 60
            },
            "description": "Optional free-text category hints when none of x-category-slugs fit. Recorded for the reviewer; never auto-created."
          },
          "features": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Feature"
            },
            "description": "Structured feature list — what the tool does, as data rather than prose."
          },
          "pros": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pricing": {
            "$ref": "#/components/schemas/Pricing"
          },
          "free_plan": {
            "type": "boolean"
          },
          "free_trial": {
            "type": "boolean"
          }
        }
      },
      "Feature": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "label"
        ],
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "description": {
            "type": "string",
            "maxLength": 300
          }
        }
      },
      "Pricing": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "amount",
          "currency",
          "period"
        ],
        "properties": {
          "amount": {
            "type": "number",
            "exclusiveMinimum": 0
          },
          "currency": {
            "type": "string",
            "enum": [
              "USD"
            ]
          },
          "period": {
            "type": "string",
            "enum": [
              "month",
              "year",
              "one-time"
            ]
          }
        }
      },
      "AgentInfo": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "contact_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ReviewEta": {
        "type": "object",
        "description": "Expected review turnaround for the submitted proof.",
        "properties": {
          "min_days": {
            "type": "integer"
          },
          "max_days": {
            "type": "integer"
          },
          "unit": {
            "type": "string",
            "enum": [
              "business_days",
              "calendar_days"
            ]
          }
        }
      },
      "SubmissionAccepted": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "submission_id": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending"
            ]
          },
          "proof": {
            "type": "string",
            "enum": [
              "none",
              "sayabout",
              "badge",
              "paid"
            ]
          },
          "link_tier": {
            "type": "string",
            "enum": [
              "nofollow",
              "dofollow"
            ],
            "description": "Resulting outbound link tier once published. Verified/paid proofs are dofollow candidates; none stays nofollow."
          },
          "review_eta": {
            "$ref": "#/components/schemas/ReviewEta"
          },
          "upgrade": {
            "type": "object",
            "description": "Present when proof is none — how to earn dofollow and a faster review.",
            "properties": {
              "endpoint": {
                "type": "string"
              },
              "body": {
                "type": "object"
              },
              "recommended": {
                "type": "string",
                "enum": [
                  "paid"
                ],
                "description": "The fastest dofollow path."
              },
              "price_usd": {
                "type": "number",
                "description": "One-time price of the recommended paid listing."
              },
              "review_times": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            }
          },
          "message": {
            "type": "string"
          },
          "category_suggestions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Category slugs/free text that didn't match an existing category; the reviewer files them."
          }
        }
      },
      "AgentToken": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string"
          },
          "account": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "email": {
                "type": "string",
                "format": "email"
              }
            }
          }
        }
      },
      "CategoryList": {
        "type": "object",
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "DuplicateCheck": {
        "type": "object",
        "properties": {
          "duplicate": {
            "type": "boolean"
          },
          "existingTool": {
            "type": "object",
            "nullable": true,
            "properties": {
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "website": {
                "type": "string"
              }
            }
          },
          "pending": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "matchedBy": {
                "type": "string",
                "enum": [
                  "name",
                  "url",
                  "host"
                ]
              }
            }
          }
        }
      },
      "SubmissionStatus": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected"
            ]
          },
          "proof": {
            "type": "string",
            "enum": [
              "none",
              "sayabout",
              "badge",
              "paid"
            ]
          },
          "link_tier": {
            "type": "string",
            "enum": [
              "nofollow",
              "dofollow"
            ]
          },
          "review_eta": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ReviewEta"
              }
            ],
            "nullable": true,
            "description": "Null once the submission is reviewed."
          },
          "review_time": {
            "type": "string",
            "nullable": true
          },
          "paymentVerified": {
            "type": "boolean"
          },
          "note": {
            "type": "string",
            "nullable": true
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "category_suggestions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "createdAt": {
            "type": "string"
          },
          "reviewedAt": {
            "type": "string",
            "nullable": true
          },
          "upgrade": {
            "type": "object",
            "description": "Present only for the free no-verification lane while it is nofollow — the fastest way to earn dofollow (paid), plus the free alternatives.",
            "properties": {
              "endpoint": {
                "type": "string"
              },
              "recommended": {
                "type": "string",
                "enum": [
                  "paid"
                ]
              },
              "price_usd": {
                "type": "number"
              },
              "body": {
                "type": "object"
              },
              "alternatives": {
                "type": "object"
              },
              "review_times": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ListingActionResult": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "submissionId": {
            "type": "integer"
          },
          "path": {
            "type": "string",
            "enum": [
              "sayabout",
              "badge",
              "paid"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending"
            ]
          },
          "checkoutUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "ListingFactsPatch": {
        "type": "object",
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "website": {
            "type": "string",
            "format": "uri"
          },
          "definition": {
            "type": "string",
            "maxLength": 5000
          },
          "valueProposition": {
            "type": "string",
            "maxLength": 500
          },
          "features": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Feature"
            }
          },
          "pros": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "startingPrice": {
            "$ref": "#/components/schemas/Pricing"
          },
          "freePlan": {
            "type": "boolean"
          },
          "freeTrial": {
            "type": "boolean"
          },
          "categories": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ListingEditResult": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "slug": {
            "type": "string"
          },
          "linkRelReset": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "StatWindow": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "last7": {
            "type": "integer"
          },
          "last30": {
            "type": "integer"
          }
        }
      },
      "ListingStats": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "visits": {
            "$ref": "#/components/schemas/StatWindow"
          },
          "upvotes": {
            "$ref": "#/components/schemas/StatWindow"
          },
          "saves": {
            "$ref": "#/components/schemas/StatWindow"
          },
          "reviews": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "last30": {
                "type": "integer"
              }
            }
          },
          "ratingAvg": {
            "type": "number"
          },
          "ratingCount": {
            "type": "integer"
          }
        }
      },
      "ListingStatsList": {
        "type": "object",
        "properties": {
          "listings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListingStats"
            }
          }
        }
      },
      "AgentIdFlow": {
        "type": "object",
        "properties": {
          "flowId": {
            "type": "string"
          },
          "authorizeUrl": {
            "type": "string",
            "format": "uri"
          },
          "expiresAt": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "AgentIdPollResult": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "complete",
              "expired"
            ]
          },
          "token": {
            "type": "string",
            "description": "Present only on the first 'complete' poll; store it securely."
          },
          "account": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "email": {
                "type": "string"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "details": {}
        }
      }
    }
  },
  "x-category-slugs": [
    "ai-tools",
    "analytics-tools",
    "audio-editing",
    "automation",
    "competitive-intelligence",
    "creator-tools",
    "customer-support",
    "design-tools",
    "developer-tools",
    "documentation-tools",
    "education",
    "events-webinars",
    "feedback-tools",
    "forms-surveys",
    "job-boards",
    "knowledge-management",
    "meeting-assistants",
    "mobile-apps",
    "pets",
    "privacy-security",
    "product-directory",
    "productivity",
    "project-management",
    "sales-marketing",
    "scheduling-tools",
    "seo-tools",
    "social-media-tools",
    "testimonial-tools",
    "transcription",
    "video-editing",
    "writing-tools"
  ],
  "x-recommended-path": "paid",
  "x-listing-programs": {
    "paid": {
      "price_usd": 14.99,
      "proof": "payment reference from the checkout redirect",
      "link_tier": "dofollow (labeled)",
      "review_time": "within 2 business days",
      "recommended": true,
      "note": "Fastest route to dofollow — nothing to install or verify."
    },
    "sayabout": {
      "free": true,
      "proof": "live SayAbout.Us Wall of Love URL",
      "link_tier": "dofollow (once verified)",
      "review_time": "within 2 business days"
    },
    "badge": {
      "free": true,
      "proof": "Altimateguide badge live on the tool's site",
      "link_tier": "dofollow (once verified)",
      "review_time": "in 5–7 business days"
    },
    "none": {
      "free": true,
      "proof": "none",
      "link_tier": "nofollow",
      "review_time": "within 30 days"
    }
  },
  "x-agent-mcp": {
    "registry_name": "io.github.imharikumaran/altimateguide",
    "remotes": [
      {
        "transport": "streamable-http",
        "url": "https://altimateguide.com/api/mcp"
      }
    ],
    "package": {
      "registry": "npm",
      "name": "altimateguide-agent-mcp",
      "transport": "stdio"
    },
    "install": "npx -y altimateguide-agent-mcp",
    "hosted_tools": [
      "search_tools",
      "get_tool",
      "compare_tools",
      "find_alternatives",
      "list_deals",
      "list_categories"
    ],
    "env": {
      "ALTIMATEGUIDE_AGENT_TOKEN": "account API token — create at /account, or mint one browserlessly via POST /api/agent/token. Only the write tools need it; the research tools work anonymously.",
      "ALTIMATEGUIDE_API_URL": "optional; defaults to https://altimateguide.com"
    },
    "tools": [
      "search_tools (GET /api/public/search) — no auth",
      "get_tool (GET /api/public/tools/{slug}) — no auth",
      "compare_tools (GET /api/public/compare) — no auth",
      "find_alternatives (GET /api/public/alternatives/{slug}) — no auth",
      "list_deals (GET /api/public/deals) — no auth",
      "login (start_login / complete_login -> POST /api/auth/request-code, POST /api/agent/token)",
      "start_agentid_login / complete_agentid_login (POST /api/agent/agentid/start, GET /api/agent/agentid/poll — no email inbox needed)",
      "whoami (GET /api/agent/whoami)",
      "list_categories (GET /api/agent/categories)",
      "check_duplicate (GET /api/agent/check)",
      "submit_tool (POST /api/agent/submit)",
      "submit_deal (POST /api/agent/deals)",
      "get_submission (GET /api/agent/submissions/{id})",
      "update_listing (PATCH /api/agent/listing/{slug})",
      "get_listing_stats (GET /api/agent/stats)",
      "upgrade_listing (POST /api/agent/listing)"
    ],
    "note": "First-party MCP server. Research tools read published directory data and need no account; every result carries its canonical altimateguide.com URL. Write tools queue for editorial review like any other submission; nothing publishes automatically, and a paid listing only becomes a dofollow candidate once its payment is verified server-side."
  },
  "x-editorial-policy": "Submissions are never published automatically. Premium placements (comparisons, best-for, homepage, ordering) are editorially curated and are not sold or agent-submittable."
}