---
name: alternative.tools
description: Submit a software tool or website to Alternative.tools using the JSON API, and complete the free backlink path or review the paid listing options.
---
# Submit a tool to Alternative.tools
Use this skill when your requester wants their product listed on Alternative.tools.
Confirm that they authorize you to submit the website and to use their contact
email. A submission saves a request and screens the site. It is not immediate
publication: every listing is reviewed by a person. Read `statusUrl` from the
response for the current state and the next step.
## Choose a listing path
- **Free listing** — available to agents through this API. Requires an Ahrefs
Domain Rating of 25+ (checked server-side at submission time), 1,000+ monthly
visitors, and a visible "Featured on Alternative.tools" badge kept permanently on
the submitted domain. Reviewed within 2 weeks. Not every submission is approved.
- **Premium Listing — 19 USD, one-time.** Send `plan: "basic"`. No badge
and no Domain Rating requirement, 3 permanent dofollow backlinks, AI-written
listing page. The response carries a Creem `checkoutUrl`: the listing stays an
unpaid draft until a person opens it and pays, then it publishes automatically.
- **Premium Listing + Review Article — 49 USD, one-time.** Send
`plan: "pro"`. Everything in Premium plus an AI-written in-depth review article
published on the blog with dofollow links, generated after the payment
completes. Same checkout flow as above.
- **Affiliate referrals** — Alternative.tools pays 30% on referred paid listings.
See https://alternative.tools/affiliate.
**Never pay, and never try to.** The API creates the checkout session; it does
not charge a card, and no endpoint or browser tool here completes a payment.
Hand the `checkoutUrl` to your requester and let them decide. Only submit on a
paid plan, publish a backlink, or recommend a purchase when the requester has
authorized that action — a budget brief is not permission to buy anything.
## Gather the submission
Required fields:
| Field | What to provide |
| --- | --- |
| name | Actual software or product name; up to 32 characters. |
| websiteUrl | Public product website on a custom domain; up to 2048 characters. Bare domains and HTTP URLs are normalized to HTTPS. Development and preview hosting domains are rejected. |
| submitterName | Requester or representative name; up to 120 characters. |
| submitterEmail | Real contact email the requester has authorized you to use; up to 254 characters. It is prefilled in the checkout for paid plans. |
Optional fields:
| Field | Limit and purpose |
| --- | --- |
| plan | `"free"` (default), `"basic"` (19 USD) or `"pro"` (49 USD). Paid plans return a checkout URL; they skip the Domain Rating gate and the badge. |
| description | Capped by plan: 160 free, 200 basic, 300 pro. Omit it and AI writes one from the website. |
| introduction | Markdown, capped by plan: 1000 free, 3000 basic, 10000 pro. Omit it and AI writes one from the website. |
| submitterNote | Up to 200 characters about the submission. |
| botBudget | Up to 200 characters: amount, currency, and whether paid options are allowed. |
| botGoals | Up to 1000 characters: audience, discoverability goals, priorities. |
| botListingPlans | Up to 1000 characters: other directories being considered. |
| botInstructions | Up to 2000 characters: context stored with the submission. It is not sent to a model. |
| newsletterOptIn | Defaults to false. Set true only if the requester explicitly wants marketing email. |
| dryRun | Set true to validate without saving a request or sending email. Defaults to false. |
Submissions through this API are always recorded as bots. You may send
`isBot: true` for clarity. In the browser form at https://alternative.tools/submit, check
"Are you a bot?" on the first step. Bots are welcome. Never invent brief
answers — include only what the requester told you. Briefs are stored for human
review and are not sent to a model.
Contact and brief fields are private intake information. The response exposes
only listing navigation fields.
## Validate first
No API key is required. Fetch the current requirements and JSON Schema:
```sh
curl --fail-with-body 'https://alternative.tools/api/agent/submissions'
```
Replace the example product, website, name, and email below with values your
requester authorized. The .example addresses are placeholders.
```sh
curl --fail-with-body 'https://alternative.tools/api/agent/submissions' \
-H 'Content-Type: application/json' \
--data '{
"dryRun": true,
"isBot": true,
"name": "Your Product",
"websiteUrl": "https://your-product.example",
"submitterName": "Authorized Requester",
"submitterEmail": "requester@your-product.example",
"newsletterOptIn": false,
"botBudget": "Free listing only; no purchases authorized",
"botGoals": "Help people find our software",
"botInstructions": "Free listing only. Do not buy anything."
}'
```
A successful preview returns `success=true` and `dryRun=true`. It does not check
for an existing listing, look up the Domain Rating, screen the content, test
email deliverability, verify the backlink, or reserve a listing. Fix validation
issues before submitting.
## Submit once
After a successful preview and the requester's authorization, send the same
values with `dryRun: false`. Success returns HTTP 201 with `listing`, a
`payment` object, `nextActionUrl`, `statusUrl` and any `warnings`.
On the **free** plan: `listing.status` is `pending_review`, `payment.required`
is false, and `backlink` carries the exact badge snippet to publish.
On a **paid** plan: `listing.status` is `awaiting_payment`, nothing is public,
and `payment` carries `checkoutUrl` (the Creem hosted checkout), `payUrl` (a
page on this site listing the plans for that submission), `amount` and
`currency`. Give the requester the `checkoutUrl` — do not attempt to pay. The
listing publishes by itself once Creem confirms the payment; poll `statusUrl`
if you need to confirm, and expect `awaiting_payment` until someone pays.
Do not repeat a successful submission: each real call records a new request. If
the network response is lost, read `statusUrl` or open `nextActionUrl` before
retrying. Respect 429 rate limits (5 submissions per hour per IP) rather than
changing identities or flooding requests.
The endpoint accepts `application/json` only and limits the body to 16 KiB.
Errors return `success=false` and an `error` object with `code`/`message`, plus
`issues` when validation failed. Codes include `validation_error` (422),
`not_eligible` (422, e.g. Domain Rating below 25),
`duplicate_listing` (409), `prohibited_content` (422), `generation_failed` (502),
`invalid_json` (400), `unsupported_media_type` (415), `payload_too_large` (413),
`rate_limited` (429), and `submission_failed` (500).
A domain may hold one regular listing and one review article — never two of the
same kind. Listings for cryptocurrency, adult content, gambling, drugs, and
illegal services are not accepted.
## Request a paid listing
```sh
curl --fail-with-body 'https://alternative.tools/api/agent/submissions' \
-H 'Content-Type: application/json' \
--data '{
"dryRun": false,
"isBot": true,
"plan": "basic",
"name": "Your Product",
"websiteUrl": "https://your-product.example",
"submitterName": "Authorized Requester",
"submitterEmail": "requester@your-product.example"
}'
```
Paid plans skip the Domain Rating gate and need no badge. Do this only when the
requester has authorized the spend; report the price and the `checkoutUrl` back
to them rather than acting on the payment yourself.
## Complete the free listing
With permission to edit the product website, add the badge snippet returned in
`backlink.snippet` and publish the page. It looks like this:
```html
```
The badge can live in a footer, an About page, or a "Listed on" section. The page
must be on the submitted domain, public without sign-in, and indexable. Links
hidden in comments, invisible markup, or scripts, and links marked
nofollow/sponsored/ugc, do not qualify.
Then verify it:
```sh
curl --fail-with-body 'https://alternative.tools/api/agent/backlink' \
-H 'Content-Type: application/json' \
--data '{"listingId":"","backlinkUrl":"https://your-product.example/about"}'
```
A successful check confirms the backlink and moves the listing to
`backlink_verified_pending_review`; it is not a publication. Keep the badge in
place — a removed badge leads to delisting. An unreadable page does not count as
a missing link.
## Check status
```sh
curl --fail-with-body 'https://alternative.tools/api/agent/submissions/'
```
`status` is one of `pending_backlink`, `backlink_verified_pending_review`,
`approved_pending_publish`, `live`, `rejected`, `awaiting_payment`,
`paid_pending_publish`. Only `live` means the listing is public;
`listingUrl` is null until then.
## Discovery
- Requirements and JSON Schema: https://alternative.tools/api/agent/submissions
- OpenAPI description: https://alternative.tools/api/agent/openapi.json
- Machine-readable site summary: https://alternative.tools/llms.txt
- Browser form: https://alternative.tools/submit
- Pricing: https://alternative.tools/pricing
- Contact: hello@alternative.tools