{
  "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 same three inclusion paths offered on /request-inclusion (SayAbout.Us wall, Altimateguide badge, or a one-time paid listing). Authenticate with an account API token created at /account (Agent & API access)."
  },
  "servers": [
    {
      "url": "https://altimateguide.com"
    }
  ],
  "paths": {
    "/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.",
            "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"
                }
              }
            }
          }
        }
      }
    }
  },
  "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": {
      "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": [
              "none",
              "sayabout",
              "badge",
              "paid"
            ],
            "default": "none",
            "description": "Inclusion path. none = standard listing (nofollow, always allowed). sayabout = free, verified by a live SayAbout.Us Wall of Love URL. badge = free, verified by the Altimateguide badge being live on the tool's site. paid = one-time paid listing (dofollow, labeled), requires payment_ref."
          },
          "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",
          "categories"
        ],
        "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": 1,
            "items": {
              "type": "string",
              "enum": [
                "ai-tools",
                "analytics-tools",
                "audio-editing",
                "design-tools",
                "documentation-tools",
                "feedback-tools",
                "productivity",
                "scheduling-tools",
                "seo-tools",
                "social-media-tools",
                "testimonial-tools",
                "transcription",
                "video-editing",
                "writing-tools"
              ]
            },
            "description": "One or more category slugs."
          },
          "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"
          }
        }
      },
      "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."
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "details": {}
        }
      }
    }
  },
  "x-listing-programs": {
    "none": {
      "free": true,
      "proof": "none",
      "link_tier": "nofollow"
    },
    "sayabout": {
      "free": true,
      "proof": "live SayAbout.Us Wall of Love URL",
      "link_tier": "dofollow (once verified)"
    },
    "badge": {
      "free": true,
      "proof": "Altimateguide badge live on the tool's site",
      "link_tier": "dofollow (once verified)"
    },
    "paid": {
      "price_usd": 15,
      "proof": "payment reference from the checkout redirect",
      "link_tier": "dofollow (labeled)"
    }
  },
  "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."
}