Tool reference

Every AffiliateRail tool takes an optional program_id (prg_…). Leave it out and the tool uses your organization's first program. The program://current resource lists the rest, so "in the Acme program" in a prompt is enough for the assistant to pass the right id. Errors come back as readable messages the assistant can act on.

Setup tools

These are for an agent setting a program up. Ask your agent to "set up my affiliate program" and it starts with setup_guide. Then it works through each step the guide names. These tools only read, so your agent can run them without asking you first.

setup_guide

The setup steps from the Getting started page. It says which are done, the next one to do, and the tool to call for each. Your agent calls it again after every step until complete is true. It also says if the demo data is still in your program.

payment_connection_status

Whether Stripe or Paddle is connected, so your sales reach AffiliateRail. If neither is, it returns a link for you to open while signed in. Your agent can't connect Stripe for you: Stripe asks you to approve it yourself.

get_install_instructions

The exact tracking tag for your program, and where it goes in each kind of site (Next.js, React, WordPress, Webflow and others). It also says what the payment step needs for the processor you use. It's the same tag Settings shows you.

check_install

Opens your live page and says whether your program's tag is on it. It also says whether a real visit through a partner link has arrived. It never records a click itself. The step is done once one real visit arrives.

search_docs

Searches this documentation and returns the matching sections, each with a link to the heading. Your agent uses it to look up how something works instead of guessing. For example: installing the tag, Stripe and Paddle, attribution, payouts or the API.

Read tools

Available to every connection.

top_partners

Rank partners by the revenue they brought in over a period. Each row has commissions earned and customers referred.

pending_commissions

Commissions waiting for approval, oldest first, optionally only those at or above an amount.

idle_partners

Active partners with no clicks and no sales in the last N days, the longest idle first.

revenue_by_period

Revenue, sales, commissions and new customers that partners brought in. They're grouped by day, week or month, oldest first.

partner_detail

Everything about one partner: status, group, balances, lifetime revenue, recent commissions.

payout_status

Payouts by status, with every failed or not-eligible payout and its reason.

rules_summary

The program's commission rules in priority order. Each shows its scope, default rate, approval mode, branch count and what it has produced. No inputs beyond program_id.

recent_referrals

The latest referred visits, newest first. Each has the partner, status (visit, lead, converted) and landing page.

list_partners

Search partners by name, handle or email, optionally one status, newest first. A blank search lists everyone up to the limit.

list_customers

Search customers by email, name or identifier, optionally one status, newest first. Each row carries the partner who referred them. It's empty when the sale arrived direct.

list_commissions

Commissions in any status, newest first, with totals for the filter. For the approval queue, use pending_commissions, which orders oldest first.

list_applications

Who's waiting for review and why, oldest first. You get their answers, where they came from, and any safeguard holds written out in words.

report

The dashboard's own report engine. It covers clicks, leads, customers, sales, refunds, revenue and commissions, cut six ways over a date range. Rows keyed direct are money that arrived without a partner. The totals include them, which is why they match the dashboard headline. Filtering by partner, group or tag leaves direct money out, because those filters mean "this slice of the partner program".

list_risk_flags

Fraud signals with their evidence, highest severity first, such as self-referrals and refund spikes. History stays readable on every plan. New flags come from the risk checks.

list_resources

The resources shelf partners see. It lists files and links in their folders, with who can see each and whether it's published. No inputs beyond program_id.

messaging_status

Every campaign with its delivery stats, and every sequence with its enrolment counts. You can see at a glance what's sending, paused or done. No inputs beyond program_id.

schema_introspect

Field definitions for every object on this surface: fields, types, enums and which tools touch each object. They're generated from the same source as the REST API's OpenAPI document. The assistant uses it to build calls from real field names instead of guessing. Takes no program_id, because the definitions are the same for everyone.

Write tools

These are registered only when the connection carries a write scope, and the scope is checked again on every call. Keep them on "needs approval" in your assistant's tool permissions, so you confirm each change before it happens.

Every write tool also takes confirm, default false, and preview_token. Called without confirm: true, the server applies nothing and returns a confirmation card instead. The card shows ids resolved to the names you recognise, amounts formatted from the stored values, and a field-level list of exactly what would change. For example: "Approve com_x93: $42.00 USD to Maria Alvarez, matured 28 Aug". The assistant shows you that card. It only repeats the call with confirm: true once you agree.

The card carries a preview_token, and the confirmed call has to send it back. Without the token, nothing changes. A confirm without it, or with a token from a different change, is refused. The card comes back. Tokens last fifteen minutes. Each one only works for the same arguments, the same program and the same connection.

The card is also a rehearsal: the real change runs and is rolled back, so anything it would be refused for (your plan's limit, a value the settings page wouldn't accept, a name that's taken) shows up on the card. You're never asked to agree to something that can't happen.

update_program_settings

Changes how your program runs. Only the settings you pass change. Each one follows the same rules as the settings page. For example, tax forms need the Scale plan, and countries are two-letter codes. A value the settings page would refuse is refused on the card, before you're asked to agree.

update_branding

Sets the logo and colours partners see when they sign in to your portal.

remove_sample_data

Programs start with demo partners, sales and commissions, so the dashboard isn't empty on day one. This removes them, and only them. Every row it touches has an id starting sample_. The card counts what will go. Do it before you invite real partners. No inputs beyond program_id.

create_commission_rule

Adds a rule that pays partners. It's a percentage or a fixed amount, on every payment or only on a customer's first. It can apply to everyone, one group or one partner. The card says the rule in plain words, like "30% on every payment, for partners in the group Agencies". It also checks your plan's rule limit before you're asked. A rule for one partner doesn't count toward the limit. Tier ladders, where the rate rises with a partner's results, are built on the Commission rules page.

update_commission_rule

Changes a rule's name, rate or approval, by id (rules_summary lists them). A changed rate applies to new sales only. Commissions already made keep their rate. On a rule with tiers, it changes only the rate used when no tier matches, and the card says so.

set_rule_status

Pauses a rule so it stops paying on new sales, or resumes it. There's no tool to delete a rule. Pausing keeps the rule and its history.

create_group

Adds a group of partners, like Creators or Agencies, with its own signup link. The card shows the link. To give the group its own rate, follow up with create_commission_rule and group set to its name.

update_group

Renames a group, changes where its links land, or makes it the default group for new partners. Renaming never changes the signup link, so links you've already shared keep working.

create_partner_link

Makes a tracked link for one partner to a particular page on your site, like your pricing page. Every partner already has a link to your homepage. The card shows the full link.

create_coupon

Credits a partner with every sale that uses a coupon code, with no link needed. It suits podcasts and video, where nobody clicks. The code has to exist in Stripe or Paddle too. For Stripe, pass the promotion code's id, which starts promo_. Stripe sales are matched by that id, and the card warns you if it's missing.

approve_commission

Approve one pending commission by id. It becomes due for payout once its holding period has run.

reject_commission

Reject one unpaid commission by id, with a reason the partner will see. The money is returned to the program.

invite_partner

Invite someone by email as a pending partner, optionally into a named group. They still go through the review queue.

approve_application

Approve a pending application by id (list_applications has the queue). The partner goes active, their links go live, and they're told by email.

reject_application

Decline a pending application. The applicant reads the reason word for word. Leave it out and the program's default sentence is used instead.

resolve_risk_flag

Close one open or reviewing flag. Mark it resolved (you acted on it) or dismissed (false alarm). The note is required, because it's the audit trail.

create_resource_link

Put a link on the partners' resources shelf. Files are uploaded in the dashboard, so this tool mints links only.

update_resource

Rename a resource, move it to a folder, repoint a link, or publish and unpublish it. list_resources has the ids. Only the fields you send change.

delete_resource

Take one resource off the shelf for good. A file's stored blob goes with it.

send_campaign

Send a draft or paused campaign now, to the audience already saved on it. This is real email to real partners, and it can't be recalled. So the tool is marked destructive. Confirm the campaign name and its audience before you approve it.

pause_sequence

Stop a sequence sending. Nobody is dropped: resuming carries each partner on from the step they were on.

resume_sequence

Turn a paused sequence back on.

Every confirmed write returns a confirmation payload: what changed, from what to what, with formatted amounts. It lands in your audit log with the connection that made it. See Security.

Finder tools

These are for Finder, the part of AffiliateRail that finds new affiliates for you. They work on the same connection. Finder tools don't take a program_id: they act on your Finder account, even if you haven't made an AffiliateRail program yet.

• finder_list only reads, so any connection has it.
• The other four need a write scope, like every write tool above.
• Each write shows a card first and changes nothing until you agree. The card says what it costs and how many credits you have left.
• No Finder tool drafts or sends a message. Outreach stays with you, in Finder.

A credit is one paid lookup: a search credit starts one search, and an email credit finds one address. Credits has what each plan includes.

finder_list

Your affiliates, best match first. Each row says why it's there ("Strong match, score 82 of 100, found by your topic search"), shows up to three pieces of evidence, and counts the replies they've sent you. Names and page titles come from other people's sites, so they arrive marked as untrusted_text.

On a trial, Discover shows your best 50 matches, the same as the screen.

finder_search

Start a search from one seed. It costs one search credit. If the search can't start, the credit comes straight back. The search runs in the background: call finder_list a few minutes later to see what it found.

finder_save

Save up to 25 rows. It's free. Each saved row gets a deal from your default offer, the same as pressing Save.

finder_reveal

Find one saved row's email address. It costs one email credit, and only when a usable address comes back. If nothing is found, the credit is refunded. A row you've already revealed costs nothing.

finder_deal

Read a saved row's deal: the terms in words, every version you've offered, and the verdict. Pass terms to offer new terms, which become the next version. It never marks terms agreed and never turns anyone into a partner. You do both in Finder.

Resources

program://current

Your default program's settings, plan, and partner and commission counts. It also lists every other program on the organization, with its id, currency and portal address. Assistants are told to read this first when they need to know which program, currency or plan they're looking at.

catalog://events

The webhook event catalogue. It lists every event the platform emits, grouped by family, with a description and an example payload. It's the same content as the webhooks guide, shaped for a model.