AI agent integration

AI agents and server automations integrate a Webtools project with a secret project key — no dashboard login. Instead of a raw OpenAPI dump, an agent fetches a feature-filtered documentation pack that describes only the modules the project has enabled, then seeds or writes content incrementally.

Secret key scopes

Agent routes require a Secret key (wt_sk_…). Issue it in the dashboard under Project settings → API keys.

Scope	Purpose
`storefront.docs`	Download the agent documentation pack.
`storefront.seed`	Run a batch seed (each section also needs its write scope).
`storefront.write.catalogue`	Products and product categories.
`storefront.write.content`	Posts, authors and blog categories.
`storefront.write.media`	Media uploads.
`storefront.write.services`	Service catalogue.
`storefront.write.past_works`	Past works portfolio.
`storefront.write.crm`	CRM contacts, companies and opportunities.
`storefront.write.landing_pages`	Landing page types and entries.

A key with * satisfies any scope; storefront.* satisfies any storefront.<action> scope.
Send the key as Authorization: Bearer wt_sk_… or X-Project-Key: wt_sk_…. Never from a browser.
Publishable keys cannot be issued with agent scopes and cannot call docs, seed or write routes.

Endpoints

Method	Path	Scope	Notes
`GET`	`/api/v1/storefront/projects/{project_slug}/agent-docs`	`storefront.docs`	Query format=markdown (default) or format=json. Returns only sections for enabled project features.
`POST`	`/api/v1/storefront/projects/{project_slug}/seed`	`storefront.seed`	Optional Idempotency-Key header. Supports dry_run. Maximum 100 items per list in each seed section.

Write routes

Each granular write route requires the matching storefront.write.* scope and the project feature listed. Paths are relative to /api/v1/storefront/projects/{project_slug}.

Method	Path	Scope	Feature
`POST / PATCH`	`…/products, …/products/{product_slug}`	`storefront.write.catalogue`	commerce
`POST / PATCH`	`…/product-categories, …/product-categories/{category_slug}`	`storefront.write.catalogue`	commerce
`POST / PATCH`	`…/posts, …/authors, …/blog-categories (and their /{slug} forms)`	`storefront.write.content`	blog
`POST`	`…/media (multipart)`	`storefront.write.media`	blog, commerce, past_works, services, or landing_pages
`POST / PATCH`	`…/services, …/services/{service_slug}`	`storefront.write.services`	services
`POST / PATCH`	`…/past-works, …/past-works/{past_work_slug}`	`storefront.write.past_works`	past_works
`POST / PATCH`	`…/crm/contacts, …/crm/companies, …/crm/opportunities`	`storefront.write.crm`	crm
`POST / PATCH`	`…/landing-pages, …/landing-pages/{page_slug}, …/entries, …/entries/{entry_slug}`	`storefront.write.landing_pages`	landing_pages

Integration sequence

Issue a secret key with storefront.docs plus the write scopes you need (dashboard → Project settings → API keys).
GET …/agent-docs?format=json and load only the returned sections into the agent context.
Optionally POST …/seed with dry_run=true to validate payloads.
Run a live seed, or use the granular write routes for incremental updates.
Use publishable keys only for public reads, carts and checkout in the browser.

Fetch the docs pack

curl "https://api.webtools.ng/api/v1/storefront/projects/your-project/agent-docs?format=json" \
  -H "Authorization: Bearer wt_sk_your_secret_key"

Dry-run a seed

curl -X POST "https://api.webtools.ng/api/v1/storefront/projects/your-project/seed" \
  -H "Authorization: Bearer wt_sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seed-v1" \
  -d '{"dry_run":true,"catalogue":{"products":[{"name":"Demo","slug":"demo","default_variant":{"price_minor":1000}}]}}'

Behaviour notes

Disabled project features return 404 and are omitted from the docs pack entirely.
Missing scope returns 403; missing key returns 401.
Write and seed routes are rate limited to 30 requests per minute per key fingerprint and client IP.
Writes are attributed to the account that issued the API key.
Seed idempotency within a batch uses the entity slug (contact email when present). An existing slug is skipped.

For public reads, carts and checkout in the browser, use a publishable key — see Authentication.