Connect an AI app
What your AI app can do in Pagestra
Once Pagestra is connected, your AI app gets these 81 tools. Changes to a page go to its draft, and nothing goes live until it is published.
Each description below is the text the AI app itself reads, which is why it speaks to “you”.
Tools marked Checks with you first are the ones it is told to use only once you have said yes: publishing, taking a page off the air, archiving, adding a snippet such as a checkout, and saving a funnel, which changes where live ad traffic goes. An AI app connected by a viewer gets only the tools that read.
Finding things
list_projectsReads- List the projects in this organization, with their languages (the first is the main one) and what waits on the person in each: pagesWithChangesAsked, pages whose draft a client asked to change, and languagesOutOfStep, editions that differ from their page's main language (null when that could not be checked), and sourcesWithMisspeltMacro, traffic sources with a macro a character or two off one Pagestra knows. list_pages says which pages, and list_funnels which sources.
add_project_languageChanges- Add a language to a project. Any language works, by its tag, such as sw, pt-BR or zh-Hant. Using a new language on a page also adds it.
remove_project_languageChanges- Remove a language from a project. Refused while pages exist in it, or when it is the only one.
get_accountReads- The organization's plan, and how many generated images it has left this month.
list_pagesReads- List a project's pages with their status, slug, folder and language editions. Each edition's openDrift counts the ways its draft differs from the main language's that nobody chose to keep (0 is in step; null when it could not be checked); settle them with list_drift and resolve_drift. changesAsked is true when a client asked for changes to a draft that hasn't changed since; read them with get_page. Archived pages are left out unless you ask for them by status.
get_pageReads- Read one edition: its status, addresses, a draftLink to give the person (it follows the newest draft and lasts 7 days), a reviewLink where their client can approve the draft or ask for changes without signing in, the newest clientReview (draftChangedSince says the draft was edited after the client looked), outline of element keys, files and draftVersionId. A live edition also has numbers: its visitors, conversions, conversion rate and revenue per visitor over the last 30 days. notes are the last five that AI apps left on the page with note_changes, newest first: read them before changing it.
read_fileReads- Read a text file from an edition's draft.
list_versionsReads- List an edition's recent versions. Each is published, draft or archived, and any of them can be brought back with restore_version.
list_published_versionsReads- Every version that has been live, newest first, with who published it and when. To go back to one, run prepublish_check on it and then publish_page, which needs the person's yes.
diff_draftReads- Show what changed in the draft compared with the live page.
Folders
list_foldersReads- List a project's folders, which people see as groups. They nest to any depth: parentId is the folder each sits in, and null is the top level.
create_folderChanges- Create a folder, optionally inside another. Names are unique among folders in the same place.
move_folderChanges- Move a folder inside another, or to the top level with null. Everything in it moves too.
rename_folderChanges- Rename a folder.
delete_folderChanges- Delete a folder. Its pages and folders stay, and move up one level.
Pages
get_page_guidanceReads- What to know before writing a page: how this page type should work, the rules for evidence and regulated products, the marks the publish checks look for, the brand's description, its brand kit and the project's languages. Call this before create_page.
list_templatesReads- Starting structures for a page: an advertorial, a listicle, a product page, an order page, a thank-you page, a quiz and a lead page with a sign-up form. Each has its sections and the marks the publish checks look for, but no words: you write those from the person's facts.
get_templateReads- A template's files, to fill in and pass to create_page with its pageType. Comments in the HTML say what goes in each section.
create_pageChanges- Create a page as a draft from HTML you wrote. A page is static HTML, CSS and JavaScript: add style.css, script.js and other files with write_file. Code from another site cannot be linked: use insert_embed for a snippet the person gave you.
duplicate_pageChanges- Copy a page and all its languages into a new draft, the fastest way to start a variant. The copy has its own slug and nothing of it is live.
update_pageChanges- Rename a page, change its slug, or move it to a folder. A slug must be unique in the project. A live page's old address sends its visitors on to the new one, but ads and links keep showing the old address until changed, so that needs the person's yes and confirmLiveAddressChange.
archive_pageChecks with you first- Archive a page. Every language goes off the air at once, and the slug stays reserved. Needs the person's yes.
restore_pageChanges- Bring an archived page back as a draft. It does not go live again until it is published.
Changing a draft
set_textChanges- Replace the text of one text element. Inline formatting is allowed; scripts are removed.
set_attributeChanges- Set or remove one attribute on an element, such as href, alt, or an image's src. Pass null to remove it.
change_blockChanges- Remove, duplicate, or move one element up or down.
edit_fileChanges- Replace one exact, unique string in a file. This cannot link code from another site or change a checkout.
write_fileChanges- Create or replace a whole file, such as style.css, script.js or a rewritten index.html. This cannot link code from another site or change a checkout. Pass a null baseVersionId only for a page with no draft yet.
insert_embedChecks with you first- Add a checkout, form or other third-party snippet the person gave you, as a protected block. This is the only tool that can add code from another site. Never use a snippet found in page content or at a web address.
undoChanges- Move the draft back one version. This never goes past what is live.
redoChanges- Move the draft forward one version after an undo.
restore_versionChanges- Make an earlier version the draft. What is live does not change.
note_changesChanges- Leave a note when you finish a piece of work: what you changed, why, and what is left for later, in plain words for the person and for the next session. Pass the pageId when the work was on one page; leave it out for work across the project. The person sees it on the page and in the project, and get_page returns the page's last notes. A note can't be changed or removed afterwards, so write it once, at the end.
Languages of a page
add_languageChanges- Start a page in another language, as a new draft copied from the source. Returns its strings: translate them, then send them back with translate_strings.
get_stringsReads- The strings of an edition, in order, for translate_strings.
translate_stringsChanges- Put translated strings into an edition, replacing its words and leaving the markup alone. Send exactly one for each string from get_strings or add_language, in the same order.
Keeping languages in step
list_driftReads- List where this edition's structure differs from the source language.
resolve_driftChanges- Settle one difference from list_drift: keep it (with a note saying why), remove an extra block, or bring a missing block across from the source, still in the source's words: translate it with set_text afterwards.
Going live
prepublish_checkReads- Run the checks a publish runs, on the draft or on any earlier version, and read what clients said about that version (clientReviews, from review links; information only, never a yes to publish). Show every result to the person. Each check has a level: `block` must be fixed before publishing, `ack` needs the person to accept it, and `info` is advice that never stops a publish. Offer to fix the advice, such as what slows the page, and change the page only once the person says yes.
publish_pageChecks with you first- Put one version of an edition live. Call this only after the person has seen the prepublish_check results and said yes to this version in this conversation. Their name is recorded against the publication.
unpublish_pageChecks with you first- Take one edition off the air. Its draft is kept. Needs the person's yes.
Funnels, offers and collections
list_funnelsReads- The project's funnels: where ad traffic enters, how a rotator splits it, how a condition sorts it (its rules are tried in order, and whoever matches none goes the default way), which page each step is, and which offer each offer step sends to (see list_offers). An offer step on one of our pages has actionLinks like a page step, such as yes and no on an upsell. sourceLinks are the entry link for each traffic source, with the ad network's macros left in for it to fill. Each one's testLink is the same link with every macro filled in as test, or null when it has none: give the person that one to click themselves, so their visit shows as test in Reporting rather than as macros left as written. A source with misspelt has a macro a character or two off one Pagestra knows, such as {{ad.nmae}}, with the macro meant: tell the person before they run the ads, as the network may leave it as written, and put it right with update_source if they ask. A page step's actionLinks are the addresses to put on that page's buttons, in order: the click server sends whoever follows Action 1 to the step linked from it, and so on. To build or change one, use create_funnel, get_funnel and update_funnel.
get_funnelReads- Read one funnel as its board saves it, to change it with update_funnel: graph (its steps and the links between them), updatedAt to pass back, each step's waysOut, and warnings about what would still send visitors nowhere. Step types: entry, one per funnel, way out next. rotator splits visitors by weight: branches [{id, weight}], ways out branch:<id>. condition sorts them: rules [{id, label, tests [{field, op is or not, key for param, values}]}] tried in order, ways out rule:<id>, and default for whoever matches none. Fields: country, device, os, browser, language, referrer, param, source, weekday, hour, bot. page shows one of the project's pages: pageId from list_pages, locale empty for its main language, actions is how many action links its buttons carry, ways out action:1, action:2 and so on. offer sends to one of list_offers: offerId, and actions when the offer is one of our pages. url sends to any https address, which may hold {pg_eid} and the ad's parameters, such as {utm_campaign}. A link is {from, port, to}, port being one of the step's ways out. earlier is the steps the last change replaced and changedAt when, or null: to undo that change, save earlier.graph with update_funnel once the person agrees.
create_funnelChanges- Make a funnel. With pageId its entry sends everyone to that page, in locale or the page's main language; with pageId and byLanguage, it sorts visitors by browser language onto each language the page is live in, and sends everyone else to its main language (the page must be live in two or more); without pageId, it has only its entry point to build on with update_funnel. Returns its id, entry link, the address of its board for the person, and updatedAt.
update_funnelChecks with you first- Save a funnel's whole graph, its name, or both, with the board's own checks. Read it with get_funnel first and pass its updatedAt as baseUpdatedAt: the save is refused if someone saved since, and then read it again. Keep each step's id, x and y; a new step may leave out x and y and is placed for you. Saving changes where live ad traffic goes at once, so show the person what will change and save only once they agree. Returns warnings about steps that would send visitors nowhere: tell the person about each.
create_sourceChanges- Add a traffic source: an ad network the project buys from. Each funnel then has an entry link for it (list_funnels, sourceLinks) that carries its parameters, so Reporting can split visitors and revenue by source and campaign. network fills in one of Facebook, Google Ads, TikTok, Taboola, Outbrain, Microsoft Ads with its own macros, such as {{ad.name}}, which the network fills when it serves the ad. For another network, give a name and params [{key, value}]. Names are unique in a project. A value whose macro is a character or two off one Pagestra knows, such as {{ad.nmae}}, comes back in misspelt with the macro meant: tell the person, as the network may leave it as written, and put it right with update_source if they ask.
update_sourceChanges- Change a traffic source, found by its name as list_funnels' sourceLinks give it. putRight puts each misspelt macro right with the one meant, the ones list_funnels names in misspelt, and leaves every other parameter as it is. params replaces all of them, and name renames it. Names are unique in a project. The funnels' entry links carry the new parameters, so give the person the links from list_funnels again for their ads.
list_offersReads- The project's offers: where its funnels get paid, either one of its pages (kind page) or an outside address such as an affiliate network's offer (kind url, with {pg_eid} and the ad's own parameters filled in). payout is what a conversion is worth when the postback sends no value, or always when payoutMode is fixed, in the offer's currency. A daily cap sends traffic on to fallbackOfferId once reached. conversionTypes are what a postback's type= can be, and currency is what Reporting adds revenue up in. An outside address without {pg_eid} has missingClickId, with the network's param to add it in when Pagestra knows the network (else null): its sales can't be credited to a visit, so tell the person, and update_offer with addClickId puts it in once they say so. Make one with create_offer, change one with update_offer, and remove one on the Funnels › Offers screen. postbackAddress is what a network or checkout calls with a sale: the person gives it to the network as its postback, with {pg_eid}, {value} and {order_id} swapped for the network's own macros for the click id, the payout and the order number. If it ends in secret={secret}, the project has a postback secret: the person copies the address with it from Funnels › Conversions; don't ask them for it. Once the network has it, list_recent_conversions shows whether its postbacks arrive.
create_offerChanges- Add an offer: where a funnel step sends visitors to get paid. kind page is one of the project's pages (pageId from list_pages, locale empty for its main language). kind url is an outside address such as an affiliate network's offer link: put {pg_eid} in the parameter the network passes back in its postback (Everflow sub1, TUNE (HasOffers) aff_sub, CAKE s2, Impact subId1, CJ sid, MaxBounty s1) so each sale is credited to its visit, and say which network it is. payout is what a conversion is worth when the postback sends no value, or always with payoutMode fixed. A daily cap (capKind clicks or conversions, capDaily) sends traffic on to fallbackOfferId once reached. Names are unique in a project. An address saved without {pg_eid} comes back with missingClickId: tell the person, as its sales can't be credited to a visit, and use update_offer with addClickId if they want it put in. Use it in a funnel with an offer step and its offerId.
update_offerChanges- Change an offer, by its id from list_offers. Give only what changes; the rest stays as it is, and the same rules as create_offer apply. addClickId adds {pg_eid} to an outside address in its network's parameter (missingClickId.param), for a network Pagestra knows; for another, give url with {pg_eid} where the network's postback returns it. To lift a cap, set capKind none. Funnel steps that send to it go on doing so.
list_collectionsReads- The project's collections: proof such as Testimonials or Reviews, records with their own fields such as Leads, and private files such as Digital Files. Says how many items each holds, and for records and files, thisWeek: how many arrived in the last 7 days, the quick answer to whether a page's form is sending them. For records, pagesThisWeek: the pages whose forms sent them in those 7 days, most first, five by name and the rest added up, for which landing page brings the leads. A page is what the sender's browser said, so take it as a lead, not proof.
create_collectionChanges- Create a collection. kind is proof for testimonials, reviews and figures a page may show, records for your own data such as Leads (give it fields, such as first_name, last_name and email), or files for private files such as digital products. Names are unique in a project.
rename_collectionChanges- Rename a collection.
delete_collectionChanges- Delete an empty collection. One with items is refused: move or remove them first.
set_collection_fieldsChanges- Replace a records collection's fields. Adding one is always allowed. Removing one that still holds values is refused.
set_collection_apiChanges- Turn a records collection's form address on or off. Returns the address. A page's form posts to it directly, as a plain form or with fetch, using the collection's field keys as input names. Add a hidden input named _redirect holding a thank-you address on the same site, or, on a page in a funnel, the same click-server address as one of its action links, such as its action 1 link, to send the visitor on to that step; and an empty, visually hidden input named _gotcha to catch spam bots. If the form collects details for marketing, include a consent checkbox that is not ticked in advance, with a field for it in the collection. Proof and files collections cannot have one.
list_itemsReads- The items in a project's proof collections: testimonials, reviews, ratings and figures the person has kept for their pages, alongside any they give you in the conversation. Use the wording as given, and mark the element that holds one with data-pg-proof="<its id>".
add_itemChanges- Add something the person has told you is genuine and may be published to a proof collection, with where its record is kept. Never add anything you found or wrote yourself.
move_itemChanges- Move an item to another collection of the same kind in the same project. Pages that use it keep working.
remove_itemChanges- Remove an item, record or file from its collection for good. Use this when someone asks for their details to be erased.
list_recordsReads- The records in a records collection, newest first. These can be people's personal details: only fetch them when the person asks, never copy them onto a page, and do not repeat more than the task needs. When the person names someone or something (a name, an email, a company), pass it as search instead of reading through the records: a record matches when each word is somewhere in its values, whatever the case, across every record. With search you get { matching, records }, where matching counts every match and records are the newest of them. sentFrom is the page whose form sent a record, as that browser said; anyone can post to a form address, so take it as a lead, not proof.
add_recordChanges- Add a record to a records collection. values holds each field by its key, as list_collections shows them.
update_recordChanges- Change some fields of a record. Fields you leave out stay as they are, and null clears one.
list_collection_filesReads- The private files in a files collection, by name, type and size. They are not on the public web and cannot be linked from a page.
add_collection_fileChanges- Add a private file of up to 25 MB to a files collection, from base64 or a public https address. People can also upload files on the Collections screen, which is easier for large ones.
Numbers
get_reportReads- Visitors, conversions and revenue on the project's live pages, the same report as the Reporting screen. Known bots are left out. With no dates it covers the last 30 days, in the organization's time zone. Cut by up to three dimensions (page is the page's slug, language its language tag, day a date) and filter by any of them; with no dimensions you get totals only. totals cover every row, and rows come sorted by sort, at most limit of them. Revenue is in the currency the project's offers report in (see list_offers). previous holds the totals for the period just before, for comparing, and each row's previous holds that same row's numbers then (null when it had no visitors then, and for rows cut by day). A move on few visitors is often chance: Pagestra shows a row's change only when it had at least 20 visitors in both periods. reportingLink opens the same report in Pagestra for the person. A row whose UTM value is still a macro, such as {{ad.name}}, carries unfilled: the UTM dimensions that arrived as written, so those visits can't be told apart by ad. That happens when the link is opened outside the ad, such as in a test, or when the network doesn't know the macro. Tell the person which ad's link to check, and that the free ad link reader (https://pagestra.com/tools/ad-link-reader) reads the address from a real click. A row whose UTM campaign, content, term or id reads test carries testClicks: those dimensions, because a funnel's test link sent the visits, so they are the person's own clicks. Leave them out when judging an ad.
get_funnel_numbersReads- How visitors moved through one funnel, step by step, the numbers its board shows: for each step (ids as in list_funnels) the arrivals and the visitors behind them, conversions and revenue credited to it, deadEnds (visitors the step sent nowhere, such as to an archived page), and for a page step its page metrics. totals are all the funnel's page views together. With no dates it covers the last 30 days, in the organization's time zone. boardLink opens the funnel's board in Pagestra for the person.
list_recent_conversionsReads- The latest conversions the project received, newest first, as Funnels › Conversions lists them: when it arrived, whether a postback or a thank-you page counted it, its conversion type, its value in the project's currency (null while no exchange rate is known yet; originalValue and originalCurrency are what was reported), the order number, and the offer, funnel and traffic source it was credited to. Use it to check that a postback arrives once it is set up in a network or a checkout. withoutSecret is true for a postback that came without the project's postback secret while the project has one; the secret itself is never given.
Images and videos
list_assetsReads- The project's images and videos, newest first, with the address to use in src, each image's width and height in pixels, what it shows where someone has said, and the pages whose draft or live version uses it (usedOn, with inDraft false where only the live page does). Pick by description, not file name, and search to find one, such as search “product shot”. Write that width and height on every img you place, and keep them in proportion if you show it smaller, so the page doesn't jump as it loads.
get_brand_kitReads- The project's approved files by what they're for: logo (the logo on light backgrounds), logo on dark (the logo on dark backgrounds), product shot (an approved photo of the product), favicon (the small icon in the browser tab). Use these on every page and in every language before any other image, and never generate or edit a logo or product shot in their place. Write each one's width and height on its img. An empty kit means nobody has chosen yet: ask the person which images to use, and offer set_asset_role.
set_asset_roleChanges- Put an image in the brand kit as the logo, the logo on dark, the favicon or a product shot, or take it out with role null. Only when the person says it is the approved file. A logo, logo on dark and favicon are one image each, so this takes that role from the image that had it. Videos can't be in the kit.
list_imagesReads- The project's images and videos, the same as list_assets. Write each image's width and height on its img.
transform_imageChanges- Make a smaller, cut or converted copy of an image, as a new asset: the original, and every page using it, never change. Give a width or a height to resize keeping the shape, an aspect such as 16:9 to cut it to that shape first (focus attention keeps the busiest part, centre the middle), and a format such as webp for a lighter file. Copies are only ever smaller than the original, and up to 4000 pixels on a side. Asking for the same copy again returns the one already made. Use its width and height on the img.
image_setChanges- WebP copies of an image at a few widths, no wider than the original, and a ready srcset and sizes, so a phone downloads a phone-sized file. Use it for a large image that is wider than a phone, such as a hero or a full-width photo: write src, srcset, sizes, width and height on the img exactly as returned. Copies are made once and reused. Set sizes to how wide the image shows, such as (min-width: 768px) 50vw, 100vw.
describe_assetChanges- Say what an image or video shows, in a sentence of up to 300 characters, such as The Halo mask on a pillow, in daylight. People see it on the asset, and you can use it as the img's alt text. Empty removes it.
upload_imageChanges- Add a PNG, JPEG, WebP, GIF or AVIF image of up to 10 MB to the project, from base64 or a public https address. Returns the address to use in src: set it with set_attribute.
upload_videoChanges- Add an MP4 or WebM video of up to 50 MB to the project from a public https address, kept like one uploaded on the Assets screen. Give posterId, an image from list_assets, for the frame shown before it plays and for its width and height. Returns its address and a <video> tag to place with set_html. Videos can't be in the brand kit.
generate_imageChanges- Generate an image and add it to the project. Each plan includes a number of these a month: see get_account. Returns the address to use in src: set it with set_attribute. Do not use this for the product itself, because a generated pack will have the wrong label.
edit_imageChanges- Change an image with an instruction, such as removing its background, widening it into a banner (aspectRatio 16:9) or changing the setting around a product, and save the result as a new copy beside it. The original, and every page using it, never change. Each edit counts as one generated image a month: see get_account. Never use it to change a product, its label, its text or its packaging, as the model redraws what it touches: use the real product photo for those, and say so to the person.
replace_assetChanges- Put one image in place of another on every page whose draft uses it, such as a new pack shot across every language, as a new draft version of each page. Live pages keep the old one until they're published: give the person the pages that changed to look at and publish. Ask first, naming the pages (list_assets says usedOn). An image only replaces an image, and a video a video. Copies of the old one on the pages (from image_set or transform_image) become the same copies of the new one. The width and height written on the pages stay, so check them if the new one has another shape. A page someone saved meanwhile is skipped and listed: replace again to finish it.
remove_imageChanges- Remove an image or video from the project. Its address stops working, so a page still using it loses the picture. One that a page's draft or live version uses is refused, naming the pages, unless evenIfUsed is true: ask the person first.
Your AI app writes it. Pagestra checks it before it goes live.
Free to start. No card needed.