Pugi

npx add-mcp 'https://api.pugi.io/api/agent/v1/mcp'

Pugi for AI agents

Pugi is an AI product team that builds, checks and publishes websites and apps. This page is for AI agents and the people who run them. It describes only what works today.

1. Get a key

curl -X POST https://api.pugi.io/api/agent/v1/keys \
  -H "content-type: application/json" \
  -d '{"name": "my-agent"}'

• With no Authorization header, Pugi creates a new agent account and its first key.
• Signed in (send your Pugi API key as Authorization: Bearer ...), the key joins your account.
• The key starts with pugi_agent_ and is shown once. Store it.
• A new key comes with $0.50 of free credit (once per signed-in account).
• Optional fields: scopes (a list of tool names this key may call) and daily_cap_usd (default 5, up to 500).
• Revoke the calling key with DELETE /api/agent/v1/keys/self. Signed-in owners can list keys with GET /api/agent/v1/keys and revoke any of them with DELETE /api/agent/v1/keys/{id}.
• Pugi creates a limited number of new keys a day. If the limit is reached, try again after midnight UTC.

2. Connect the MCP server

• Address: https://api.pugi.io/api/agent/v1/mcp
• Transport: Streamable HTTP, JSON responses.
• Auth: Authorization: Bearer pugi_agent_..., or OAuth (below).

Connecting, ping and the tool list need no key. Calling a tool does.

Connect with your Pugi account (OAuth)

Apps such as Claude and ChatGPT connect with OAuth instead of a key. Add https://api.pugi.io/api/agent/v1/mcp as a connector. The first tool call asks you to sign in to Pugi and allow the app. After that the app uses your own account: your credit, your daily cap, your published apps.

• A tool call without a token answers 401 with WWW-Authenticate: Bearer resource_metadata="https://api.pugi.io/.well-known/oauth-protected-resource/api/agent/v1/mcp".
• Authorization server: https://api.pugi.io (metadata at /.well-known/oauth-authorization-server). OAuth 2.1 authorization code with PKCE (S256), dynamic client registration, rotating refresh tokens. Scope: agent.
• Redirect URIs a client may register: the Claude and ChatGPT callbacks, and http://localhost or http://127.0.0.1 on any port (Claude Code, MCP Inspector).
• Each app you allow gets its own key on your account, named App: <app name>. It appears in GET /api/agent/v1/keys. Revoking it (DELETE /api/agent/v1/keys/{id}) disconnects the app: every token it holds stops working at once. Access tokens last an hour; the app refreshes them on its own.

Tool availability and prices are live at https://api.pugi.io/api/agent/v1/pricing. Call only tools whose available field is true. The tables below describe the tools; the live response decides what works now.

Tools available at the last documentation update:

Tool	What it does	Price
scan_url	Passive, read-only security check of a public website, graded A+ to F. 10 a day per key.	Free
get_balance	Credit balance, today's spend, the daily cap, the price list.	Free
buy_credits_link	A card checkout link a person opens to add credit. It never charges by itself.	Free
publish_status	Status and address of the apps this account has published.	Free
catalog_search	Search the public Pugi catalogue of sites and apps to start from.	Free
scan_repo	Leaked secrets, vulnerable dependencies and risky code in a public GitHub repository, with file and line.	$1, charged only when the check finishes
make_logo	Four whole logos for a business name: the name with a drawn mark, as PNG images.	Three free make_logo a day per key, then $0.25

Coming soon while available: false

Building, editing and publishing are currently unavailable. Do not call these tools until the live price list enables them.

Tool	What it does when enabled	Price
build_site	A brief becomes a built website, with a view-only preview link.	Metered by usage, never above max_usd (default $5, $1 to $25)
edit	One change to a site this account built.	Metered by usage, never above max_usd (default $2, $0.50 to $25)
job_status	Progress, cost so far and the view-only preview of a build or edit.	Free
publish	Puts a built site live on its pugi.app address, after the security check of the exact code.	Free

The same tools answer over plain HTTP: POST https://api.pugi.io/api/agent/v1/tools/{tool} with the tool's arguments as the JSON body.

Search the catalogue

curl -X POST https://api.pugi.io/api/agent/v1/tools/catalog_search \
  -H "Authorization: Bearer pugi_agent_..." \
  -H "content-type: application/json" \
  -d '{"query": "booking", "tags": ["saas"], "category": "saas", "limit": 5}'

• All arguments are optional: query (words in the title or description, up to 80 characters), tags (up to 8; a card must carry every one), category (one value; websites: portfolio, landing_page, blog, editorial, ecommerce, events, music, resume, services, lifestyle; apps: saas, dashboards, internal_tools, developer_tools, business_tools, productivity, project_management, product_management, finance, education; industries: real_estate, food, beauty_wellness, fitness, travel, health, nonprofit, agency, local_business; or other. The retired marketing, social and entertainment are still accepted), limit (1 to 20, default 10).
• Each item has title, description, tags, preview_image_url, page_url (its page on pugi.io/catalog) and start_from_this_url: the Pugi console with a brief for a new project like it. A person signs in there; it does not copy the card's code.
• Free, up to 300 searches a day per key.

Check a GitHub repository

curl -X POST https://api.pugi.io/api/agent/v1/tools/scan_repo \
  -H "Authorization: Bearer pugi_agent_..." \
  -H "Idempotency-Key: scan-acme-shop-0001" \
  -H "content-type: application/json" \
  -d '{"repo_url": "https://github.com/acme/shop", "ref": "main"}'

• repo_url (required): a public GitHub repository, up to 50 MB. Private repositories, other hosts, tags and commit SHAs are not supported yet. ref (optional): a branch name; default the repository's default branch.
• The check reads the committed files of the branch head: dependency advisories (including known malicious packages), secret patterns and code rules. No code is run. It is not a pentest.
• A check can take a few minutes. When the answer is "state": "running", call again with the same Idempotency-Key and repo_url after retry_after_seconds. When it is "state": "finished", it has verdict (pass or issues_found), summary, blocking (the lines that fail the check, such as a leaked key with its file and line) and findings (each with severity, rule, file and line or package, and a short fix).
• $1 from credit, charged only when a finished check is handed over. A failed check costs nothing. Collecting the same check again is never charged twice. Over MCP the key is the idempotency_key argument.
• One running check per account at a time.

Build a site (metered)

1. MCP: call build_site with {"brief":"A site for Rosa Bakery","max_usd":5,"idempotency_key":"build-rosa-0001"}.
2. HTTP: POST the same brief and max_usd to /api/agent/v1/tools/build_site with Bearer auth and Idempotency-Key: build-rosa-0001.
3. Save the returned job_id; call job_status with it until the job finishes.
4. Open preview_url and review the site; call edit with the job ID and an instruction if needed.
5. Call publish with the final job ID to put the approved site live.

curl -X POST https://api.pugi.io/api/agent/v1/tools/build_site \
  -H "Authorization: Bearer pugi_agent_..." \
  -H "Idempotency-Key: build-bakery-0001" \
  -H "content-type: application/json" \
  -d '{"brief": "A one-page site for Rosa Bakery in Porto: hours, menu with prices, map, order by phone.", "max_usd": 5}'

• OAuth-connected apps spend the customer’s existing compute credit, including funded plan credit. Builds currently require enough credit to reserve max_usd, including on plans whose console builds are exempt from the ledger gate.
• You pay by usage, rounded up to the cent, and never more than max_usd. A build that produces nothing costs nothing.
• max_usd is reserved from your credit (and from the key's daily cap) before the build starts; the unused part is released when it ends. Without enough credit the answer is HTTP 402 with buy_credits_url (and, where open, a payment challenge for a credit pack).
• The answer has job_id, state and estimate_usd_range (from recent builds). A build takes several minutes: the call waits up to 50 seconds and then answers "state": "running".
• Poll job_status with {"job_id": "..."} (free) every 30 seconds or so. It shows stage, charged_usd so far and, once built, preview_url: a link that only shows the site and expires in 15 minutes (call again for a fresh one). It cannot be used for anything else.
• At the spending limit the build stops and keeps what was built ("state": "stopped"). It is charged at the limit at most.
• edit takes job_id (or project_id), instruction, max_usd and an idempotency key, and runs the same way.
• publish takes job_id (or project_id) and answers the live url, or status: "building" while the address comes up (then publish_status). It is free; the account's hosting rules apply.
• One build or edit at a time per account (HTTP 409 build_in_progress). When Pugi runs its maximum of agent builds at once the answer is HTTP 429 builds_busy with retry_after_seconds. Nothing is charged for a refused call.

Make four logos

curl -X POST https://api.pugi.io/api/agent/v1/tools/make_logo \
  -H "Authorization: Bearer pugi_agent_..." \
  -H "Idempotency-Key: logo-forno-nove-0001" \
  -H "content-type: application/json" \
  -d '{"business_name": "Forno Nove", "industry": "pizza restaurant", "colours": {"primary": "#b91c1c", "secondary": "#f59e0b"}}'

• business_name (required): 1 to 32 letters, digits, spaces or & ' . -. Names of well-known brands are refused.
• industry, description (optional, up to 300 characters): only choose the kind of imagery; they are never drawn as text.
• colours (optional): {"primary", "secondary", "text"} as hex colours, or a list of one to three of them. style (optional): minimal, tech, corporate, modern (default), playful, abstract or flashy.
• The answer has four logos (a lockup, a wordmark, an emblem and a second lockup). Over HTTP each is in logos[].png_base64, a PNG on white: 512 px on a free call (the four are drawn together as one picture), 1024 px on a paid call (each drawn on its own); over MCP each comes as an image content block, and the call takes idempotency_key as an argument instead of the header.
• New logo choices include a stable logos[].logo_id, scoped to the account that generated them. Keep the handle to identify the chosen image. The agent brand-kit tool is not open yet.
• Three free make_logo a day per key (UTC day), then $0.25 a call, charged only when at least one logo comes out. If none does, the answer says why, nothing is charged, and an unused free call stays available. A retry with the same key and the same arguments is never charged twice.
• For vector files, palette, fonts and a brand book, open https://logo.pugi.io

3. Prices

One credit balance pays for every tool. Prices are per call, in US dollars, before tax. The live list is at https://api.pugi.io/api/agent/v1/pricing.

Tool	Price	Open to agents
scan_url	Free	Yes
scan_deep	$0.50	Not yet
scan_repo	$1	Yes
catalog_search	Free	Yes
build_site	Metered from credit, never above your max_usd; usually $1.50 to $5	Yes, when available in the live price list
edit	Metered from credit, never above your max_usd; usually $0.25 to $1.50	Yes, when available in the live price list
job_status	Free	Yes, when available in the live price list
publish	Free	Yes, when available in the live price list
build_app	Metered, never above your max_usd; usual minimum estimate $8	Yes, when available in the live price list
make_logo (four logos)	3 free a day per key (one 2x2 preview grid), then $0.25 for four separate logos	Yes
brand_kit	$29 full kit, $69 Pro	Not yet

A tool marked "Not yet" answers HTTP 501 and charges nothing. brand_kit and scan_deep are still closed.

build_app takes brief, max_usd (default $5, $1–$25) and an idempotency key, like build_site. It uses the same Vite app scaffold and metered runner. Use job_status for progress and a view-only preview, edit for changes and publish to put it live. The $8 figure is an estimate, never a fixed debit or a charge above max_usd. A signed security check of the pushed commit must pass the same gate as the console’s Ready state before an app or an edit to it is delivered. If it does not pass, no preview is returned and the prepaid build settles at $0 (OAuth plan builds retain normal plan usage accounting). Availability follows the existing build switch and runtime readiness.

4. When credit runs out

A paid call without enough credit answers HTTP 402:

{
  "error": "insufficient_credit",
  "required_usd": 1.5,
  "balance_usd": 0.2,
  "buy_credits_url": "https://api.pugi.io/api/agent/v1/checkout?t=...",
  "buy_credits_amount_usd": 5
}

Show buy_credits_url to a person. They open it and pay by card on a hosted checkout page; the credit lands on the account in the link. Paid calls need an Idempotency-Key header, so a retry is never charged twice. Each key also has a daily spend cap. An agent can also pay the 402 itself, without a person, as a business purchase: see section 5.

5. Payments

• Card top-ups through a hosted card checkout. Tax, where it applies, is added at checkout.
• No tool takes a payment by itself. Agents spend credit a person has already added, or credit the agent's own wallet paid for (below).

Paying without a person (a business purchase)

Agent payments are business purchases. Buyers in the EU and the UK need a valid VAT number; anyone else can pay as a person on our checkout page. Pugi Inc. is the seller.

1. Your country decides whether a declaration is needed. It is the country you declared, else the country Cloudflare sees for the request, else unknown. If the two disagree, the stricter rule applies.

   • Outside the EU and the UK, or when the country is unknown: nothing to declare. The account is a business by default, and the first payment records that, with the country and where it came from.
   • In the EU or the UK: declare the business once with its VAT number. Pugi checks it in the EU (VIES) or UK (HMRC) VAT register. Without a valid number, a person adds credit by card at buy_credits_url instead, and VAT is handled there.

curl -X POST https://api.pugi.io/api/agent/v1/business \
  -H "Authorization: Bearer pugi_agent_..." \
  -H "content-type: application/json" \
  -d '{"business_name": "Acme GmbH", "country": "DE", "vat_id": "DE123456789", "business_use": true}'

• Anyone may declare, to put the business name on the record. An account declared outside the EU and the UK still needs a VAT number when its requests come from the EU or the UK.
• Prices are before tax. EU and UK businesses account for VAT under the reverse charge.

2. A paid call without enough credit answers HTTP 402 with two ways to pay. Pick one, pay, and retry the same request with the same Idempotency-Key:

Way to pay	What the 402 carries	How the agent answers	What it buys
Card, through an agent wallet (for example Link)	WWW-Authenticate: Payment ... method="stripe" (Machine Payments Protocol)	A Shared Payment Token, sent as Payment-Authorization: Payment <credential>	A credit pack: $5, or the smallest pack that covers the call
USDC on Base	PAYMENT-REQUIRED (x402 v2, exact)	A signed transfer, sent as PAYMENT-SIGNATURE	Exactly this call, from $0.01

• A paid answer carries a receipt: Payment-Receipt for a card, PAYMENT-RESPONSE for USDC.
• Sending the same credential twice never charges twice.
• A card issued in the EU or UK needs a confirmed VAT number on the account.

3. To add credit without making a call, use POST https://api.pugi.io/api/agent/v1/credits with {"amount_usd": 5}. It answers 402 with the same options. Over MCP, the add_credit tool does the same with the MCP payment binding: error -32042 carries the challenge, and the wallet retries with the credential in _meta.

Refunds go back to the card or wallet that paid, and take back the credit they bought, as far as it is still unused.

6. Limits and rules

• Each key has a request rate limit and a daily spend cap.
• The site check reads only what a browser receives. It is not a pentest and does not prove a site is secure.
• Publishing stays under the person's control: review the preview before calling publish. Build tools require the build flag and configured runtime; check the live price list for availability.

Questions: https://pugi.io/support