Tools reference.
Every tool your agent can call on Pagehive, sorted by topic. Each one has its plans, its parameters and an example call.
Topic 01 · 6 tools
Getting started
- whoamiAccountWho this key is and what it can reach. bot is the bot behind it; rename_bot renames it. credential is account_key, site_key, or oauth. scope is full, read_on...All plans
- get_accountAccountRead this API key's account, tier, effective limits, rights, and usage. A null limit is unlimited. quotas shows each capped quota with used, limit, remaining...All plans
- list_tiersAccountList the tiers this account can see, with their rights and limits: the public tiers and the account's own. A null limit is unlimited. warning_percent is a us...All plans
- request_owner_sign_in_linkAccountCreate a one-time owner sign-in link that lasts 15 minutes by default (sign_in_link_lifetime_minutes). Requires a full key on a claimed account whose owner h...All plans
- rename_botAccountRename the agent behind this key or connected app (leave bot_id out, or pass its own id from whoami). Works at every level, None included, and for an agent t...All plans
- get_guideGuideThe Pagehive bot guide, one topic at a time. Without topic it returns the list of topics with their sizes. topic "tools" lists the tool groups this key can c...All plans
Topic 03 · 43 tools
Sites and pages
- list_sitesSitesList sites on this account. shared_sites lists sites other people shared with this account and let its agents work on, with role, member_id and allowed_tools.All plans
- get_siteSitesGet one site and the files in its draft. current_version_id is the version visitors see. published_at is the first publish time and does not change. last_pub...All plans
- get_site_statsSitesVisitor analytics of one site, in UTC days: page views, visitors, visits, bounce rate, average visit length, visitor action events and bot hits (AI crawlers ...All plans
- create_siteSitesCreate a site. The key issued at sign-up can create one site and is then limited to it. A site key that already belongs to a site cannot create another. Crea...All plans
- update_siteSitesUpdate a site's title, theme, settings, visibility (private or public), status (live or offline), subdomain, agent_guide, time_zone or page_access. This does...All plans
- delete_siteSitesOnly the owner can delete a site. This tool always fails with validation_failed and reason owner_only. The owner deletes it in /hive by typing the subdomain....All plans
- read_pageDraft contentRead one page from the draft. By default it returns source only: the template, page CSS, global CSS, the partials the template includes and the scripts it re...All plans
- read_pagesDraft contentRead the source of up to 10 draft pages in one call: for each page its template, page CSS, global CSS, the partials it includes and the scripts it references...All plans
- read_redirectsDraft contentRead the site's redirect list: source as stored and rules with line, from, to and status. version is draft (default) or live. source is null when the site ha...All plans
- put_pageDraft contentCreate or replace one page in the draft. Visitors do not see it until publish_site. Omit source to leave the template. Omit page_css to leave that page's sty...All plans
- patch_pageDraft contentFind-and-replace in the draft. Edits apply in order, each to one file: template, page_css, css, global_css, script or partial. If any edit fails, nothing is ...All plans
- write_filesDraft contentWrite several draft files in one call: up to 20 pages, partials, stylesheets, scripts, robots.txt, sitemap.xml and the redirect list together, stored as one ...All plans
- put_partialDraft contentCreate or replace one partial. Pages include it with {% include 'name' %}.All plans
- put_stylesheetDraft contentCreate or replace the one global stylesheet.All plans
- put_page_cssDraft contentCreate or replace one page stylesheet. It loads after the global stylesheet. Page and template reference: https://pagehive.io/docs/bot-guide.md (section Page...All plans
- put_scriptDraft contentCreate or replace one script file in the draft. It is not parsed as Liquid and is not visible until publish_site. The page keeps the script tag the bot wrote...All plans
- upload_fileDraft contentUpload one file to the draft: an image (png, jpg, jpeg, gif, webp, avif, svg, ico), a PDF, a font (woff2, woff, ttf, otf) or a short video (mp4, webm). Send ...All plans
- upload_filesDraft contentUpload up to 20 files to the draft as one draft version. Each item in files has name and one of source_url (a public https link Pagehive downloads) or conten...All plans
- create_upload_urlDraft contentUpload a file from your own disk without its bytes passing through a tool call. Returns a single-use upload_url for curl -sS -X PUT --data-binary @<file> "<u...All plans
- create_upload_urlsDraft contentUpload up to 20 files from your own disk as one draft version, without their bytes passing through a tool call. files lists each { name, sha256? } (same name...All plans
- commit_uploadsDraft contentWrite every file staged through one create_upload_urls batch as one draft version. Refused, writing nothing, when a file of the batch was not sent (validatio...All plans
- put_robotsDraft contentPublish robots.txt on this site. A private, offline, unpublished, or unreviewed site still serves Disallow: / and ignores this file.All plans
- put_sitemapDraft contentPublish sitemap.xml. Private, offline, and unpublished sites do not serve it.All plans
- put_redirectsDraft contentReplace the site's redirect list in the draft, for old addresses of a site moved to Pagehive. Visitors get it with the next publish_site; rollback_site resto...All plans
- delete_pageDraft contentDelete one page and its page stylesheet. Page and template reference: https://pagehive.io/docs/bot-guide.md (section Pages and partials).All plans
- delete_partialDraft contentDelete one partial.All plans
- delete_stylesheetDraft contentDelete the global stylesheet.All plans
- delete_page_cssDraft contentDelete one page stylesheet. Page and template reference: https://pagehive.io/docs/bot-guide.md (section Pages and partials).All plans
- delete_scriptDraft contentDelete one script file.All plans
- delete_fileDraft contentDelete one uploaded file from the draft. Pages that still link /files/name get a 404 for it after publish.All plans
- delete_robotsDraft contentRemove a published robots.txt. A public reviewed site then serves the default Allow file.All plans
- delete_sitemapDraft contentRemove a published sitemap.xml.All plans
- delete_redirectsDraft contentRemove the site's redirect list from the draft. Old addresses show not found again after the next publish_site.All plans
- list_site_versionsPublish and versionsList site versions, newest first. limit defaults to 200 and cannot exceed 200. before, a version number, reads the next older page. next_before is set when a...All plans
- get_site_versionPublish and versionsGet one version and its file list.All plans
- diff_site_versionsPublish and versionsDiff two versions. added, removed and changed list files; changed text files include a unified diff. pages lists pages whose title or settings (og image, des...All plans
- publish_sitePublish and versionsPublish the draft atomically. Visitors see every file in that version together. A new site stays offline until this call, which sets it live and queues the f...All plans
- rollback_sitePublish and versionsCopy an older version into a new version. History stays linear.All plans
- list_templatesTemplatesList site templates with an approved version, each at its latest approved version with the outside_hosts its pages reach. Pagehive staff review every version...All plans
- get_templateTemplatesRead one site template: its approved versions with notes and preview path, the latest agent guide, and each version's review (status, reviewed_at, and the re...All plans
- get_template_changesTemplatesReturn the version notes from from_version through to_version, including both. The copied site does not update itself. The notes describe changes to apply by...All plans
- create_site_from_templateTemplatesCopy a published site template into this account in one call. Uses the snapshot, never the live source. Requires an account-wide full key, the same as create...All plans
- clear_sample_dataTemplatesDelete every sample row on this site. Rows that are not marked sample stay. A site key can clear its own site.All plans
Topic 04 · 26 tools
Data
- list_valuesValuesList values on this account, including read_access and site_id: the site that owns the value, or null for an account value that every site reads. A secret va...All plans
- get_valueValuesGet one value by key, including read_access. This is the only call that returns a secret value's content. read_access: public = pages, page scripts (bp.value...All plans
- get_valuesValuesGet up to 100 values by key in one call, in the order asked, including read_access. Like get_value, it returns a secret value's content. missing lists the ke...All plans
- upsert_valueValuesCreate or replace a value by key. site_id on create puts it on that site; without it an account key puts it on the account, which every site reads, and a sit...All plans
- upsert_valuesValuesCreate or replace up to 100 values in one call and one transaction. Each item has the fields of upsert_value. If any item fails, nothing is written and detai...All plans
- move_valueValuesMove a value between the account and a site, or from one site to another. Full account keys only. to_site_id is a site id from list_sites, or null for the ac...All plans
- delete_valueValuesDelete a value.All plans
- list_tablesTablesList tables on this account, or with site_id, the tables of a site shared with you. Each table has site_id: the site that owns it, or null for an account tab...All plans
- get_tableTablesGet one table, including its columns.All plans
- list_rowsTablesQuery rows in a table. query takes where, any (AND-ed with where when both are set), search, sort, page, limit, group_by, or include, fields to return only s...All plans
- get_rowTablesGet one row by id, with revision (goes up by one each time its values change) and created_by / updated_by as stored. _created_by and _updated_by say who wrot...All plans
- query_tableTablesRun a data query: where, any (AND-ed with where when both are set), search, sort, paging, group_by, include, fields, and visibility. The SQL runs in Postgres...All plans
- list_table_changesTablesList recent row changes for a table, newest first.All plans
- create_tableTablesCreate a typed table. Columns are stored as JSON and do not change the Postgres schema. site_id makes it a site table of that site; without it an account key...All plans
- update_tableTablesUpdate a table's columns, read access, last-updated stamp, or name. Column changes bump schema_version. Set read_access public before a page calls bp.query, ...All plans
- move_tableTablesMove a table between the account and a site, or from one site to another, keeping its rows, ids and history. Full account keys only. to_site_id is a site id ...All plans
- create_rowTablesInsert one row. A client-supplied id is ignored. This does not create a page version. Set sample true for a row a site template should copy. clear_sample_dat...All plans
- update_rowTablesUpdate part of a row. Null clears a column. This does not create a page version. The row's revision goes up when its values change, so a visitor edit drawn f...All plans
- set_row_memberTablesGive a row to a member of the site that owns the table (member_id from list_members), or take it back with member_id null. A row a member added through a mem...All plans
- bulk_upsert_rowsTablesUpsert many rows in one transaction, by id or by a key column. A row that matches an existing id or key is merged like update_row: only the columns sent chan...All plans
- delete_tableTablesDelete a table and its rows. The change log is kept.All plans
- delete_rowTablesDelete one row. A member's agent or site agent deletes rows of an own_and_shared table: the shared ones and its own, never another member's.All plans
- bulk_delete_rowsTablesDelete many rows by id in one transaction. A missing id writes nothing. The response has deleted_count and ids, the rows removed. The error message counts er...All plans
- list_data_sharesData sharesList shares of tables and values. An account key sees every share. A site key sees shares of data it owns and shares granted to its site.All plans
- create_data_shareData sharesShare one table or one value from its owning site to another site. Only an agent that works as the owner on the whole hive, with no sites left out, may call ...All plans
- revoke_data_shareData sharesRevoke a share. Only an agent that works as the owner on the whole hive, with no sites left out, may call this; site keys and agents limited to some sites ar...All plans
Topic 05 · 17 tools
Visitors and members
- list_membersMembersList a site's members: id, email, status (invited or active), role (view, edit, build or publish), agents (whether their own agent may work on the site), and...All plans
- list_site_pinsMembersList a site's PINs: id (the member id rows carry as _member), label, role, created_at and last_used_at. Never the PIN itself. A PIN lets people open a site b...All plans
- invite_memberMembersInvite an email address to a site, public or private. On a public site everyone else stays a visitor; the member signs in to get their role. role is view (de...All plans
- update_memberMembersChange a member's role (view, edit, build, publish) and/or agents (whether their own agent may work on the site, within the role). Send at least one. It appl...All plans
- create_site_pinMembersCreate a PIN for a site. pin: 6 to 12 digits as a string, not a run like 123456 and not the same as another PIN of the site. role view (default) or edit, lab...All plans
- update_site_pinMembersChange a PIN's role, label (null clears it), or the PIN itself (pin). A new PIN signs out everyone who used the old one.All plans
- revoke_memberMembersRemove a member from a site. Their invite link and any open visit stop working at once.All plans
- remove_site_pinMembersRemove a PIN. Everyone who opened the site with it loses access at once; other PINs keep working.All plans
- read_site_dataShared sitesOn a site shared with you (whoami lists them): read what you, as its member, can read on the site. With table: that table's rows, the same as bp.query on the...All plans
- run_actionShared sitesOn a site shared with you with role edit or higher: run one of the site's visitor actions as its member, exactly as a click on the page would. Only actions w...All plans
- list_agentsSite agentsList the agents that work on a site as themselves (its own member there): member_id (the _member of the rows they keep private), agent_id (the same agent on ...All plans
- list_actionsVisitor actionsList visitor actions on a site, with kind, access and spec (column, allowed, when, set, params, fields). access off means the action refuses every caller, in...All plans
- action_logVisitor actionsRead the visitor action log, newest first. Each entry has op (insert for an add, delete for a delete, update otherwise), the actor, member_id, agent ({ agent...All plans
- action_eventsVisitor actionsVisitor actions since an exclusive timestamp, oldest first. since, and since_id from next when a page is full, page through the events, for mirroring calls i...All plans
- define_actionVisitor actionsDefine a visitor action on one table this site owns. kind toggle flips a checkbox. kind set writes a text or select column to one of at least two allowed val...All plans
- update_actionVisitor actionsUpdate a visitor action. Send the fields that change. Changing kind starts the spec over from the fields you send. An action that is already public can be ed...All plans
- delete_actionVisitor actionsDelete a visitor action. Logged calls stay in the action log. Rows the action wrote or added stay.All plans
Topic 06 · 10 tools
Sharing
- list_site_domainsCustom domainsList a site's custom domains: hostname, role (primary serves the site, redirect sends to it), status (pending, active, dns_lost, disabled, off with off_by ow...Basic and up
- add_site_domainCustom domainsConnect a custom domain (such as www.example.com or example.com) to a site. It stays pending until verify_site_domain passes. domain.dns.records holds the DN...Basic and up
- verify_site_domainCustom domainsCheck a domain's DNS after the owner created the records: the TXT record, and that every A and AAAA answer is Pagehive. Passing makes it active and the site ...Basic and up
- update_site_domainCustom domainsChange a domain: role primary or redirect (making one primary turns the site's current primary into a redirect), and/or on false to turn it off or on true to...Basic and up
- remove_site_domainCustom domainsDisconnect a custom domain from a site. Removing the primary makes the next domain primary (a live one first, reported as promoted); with none left, the site...Basic and up
- list_site_linksSharing and keysList share links for a site with expires_at and expired. Tokens are not included.All plans
- list_site_keysSharing and keysList site keys for one site. Each item includes label, prefix, and dates. Secrets are never returned. Requires an account key. A site key cannot list keys. O...All plans
- create_site_linkSharing and keysCreate a view link for a site. The URL is shown once. The link does nothing while the site is offline. Review links are paused. It expires after 30 days; exp...All plans
- revoke_site_linkSharing and keysRevoke a share link.All plans
- seo_scanSEOSEO and sharing report for one site: what search engines and link previews (X, LinkedIn, WhatsApp, Slack) get from each page, and what to improve. It renders...All plans
Topic 07 · 1 tools
Your Hive and security
Topic 08 · 9 tools
Agent commands
- list_commandsAgent commandsList agent commands on a site, and agent: whether the owner set the site's Webhook (connected, kind claude, chatgpt, grok_bot, or generic), which events it g...All plans
- command_queueAgent commandsRead a site's command queue. status pending (default) lists commands waiting for the agent, oldest first, including claims whose lease ran out. in_progress, ...All plans
- define_commandAgent commandsDefine an agent command a page can send with data-bp-command or bp.command. kind fixed (default) needs instruction, up to 2000 characters; put {input} where ...All plans
- update_commandAgent commandsUpdate an agent command. Send the fields that change. name renames it.All plans
- claim_commandAgent commandsClaim a queued command so another run skips it while this one works on it. The lease lasts lease_seconds (60 to 3600, default 600); after that the command is...All plans
- complete_commandAgent commandsClose a queued command as done or failed, with an optional note of up to 1000 characters that the page can show the sender. Completing a connection test mark...All plans
- complete_commandsAgent commandsClose up to 50 queued commands in one call, each as done or failed with an optional note, with the same rules as complete_command. A bad argument refuses the...All plans
- delete_commandAgent commandsDelete an agent command. Calls already queued stay in the queue.All plans
- list_messagesMessagesMessages from Pagehive to this account, newest first: notices about the account or one of its sites (such as a site taken offline, with the reason and what t...All plans
Topic 09 · 4 tools
Troubleshooting
- list_my_ticketsSupportList this account's support tickets, newest first, each with status (new, accepted, declined, done), waiting_on (whose turn: support, customer, or nobody), a...All plans
- get_ticketSupportRead one support ticket with its conversation. It is read afterwards: unread false, and support messages you had not seen carry new: true.All plans
- open_ticketSupportOpen a Pagehive support ticket. kind is bug, feedback, request, question, account (about this account, tier, or keys), or abuse (a site or account breaking t...All plans
- reply_to_ticketSupportReply on a support ticket, up to 4,000 characters, when you have something new: an answer to support's question, what you found, or that a fix did not work. ...All plans