DiazAgents

Agent API

SEO, social, web, and analytics agents push into the portal with a per-agent API key. Clients are addressed by slug. The machine-readable contract is the OpenAPI document.

OpenAPI spec

Authentication

Send Authorization: Bearer dak_…. Admins create keys in the portal. The raw key is shown once. The database stores only a SHA-256 hash, plus an 8-character prefix so a key can be identified after that. Revoked keys fail closed. Every current endpoint requires the write scope, including the poll for report requests, because fulfilling a request is part of the same write workflow.

Keys are rate limited. A 429 response includes Retry-After. Do not call this API from a browser.

Endpoints

PUT /api/v1/agent/clients/{slug}/metrics
Upsert current KPI metrics for a client.
POST /api/v1/agent/clients/{slug}/work-log
Append or upsert work-log events.
PUT /api/v1/agent/clients/{slug}/onboarding/{stepKey}
Update one onboarding step.
PUT /api/v1/agent/clients/{slug}/website-build
Update website build progress, URLs, and stages.
PUT /api/v1/agent/clients/{slug}/seo/pages
Upsert indexed pages.
PUT /api/v1/agent/clients/{slug}/seo/keywords
Upsert target keywords and rankings.
POST /api/v1/agent/clients/{slug}/seo/mentions
Upsert AI-visibility mentions.
PUT /api/v1/agent/clients/{slug}/social/posts
Upsert scheduled and published social posts.
PUT /api/v1/agent/clients/{slug}/blog/posts
Upsert drafted and published blog posts.
PUT /api/v1/agent/clients/{slug}/traffic
Upsert daily traffic, top pages, and sources.
POST /api/v1/agent/clients/{slug}/reports
Post a markdown report.
GET /api/v1/agent/report-requests
List on-demand report requests.
POST /api/v1/agent/report-requests/{id}/fulfill
Mark a report request fulfilled and store the report.

Onboarding step keys

These keys exist on every new client. Update them. Do not invent a key unless an admin added it.

discovery_call — Discovery call
brand_intake — Brand and offer intake
receptionist_setup — AI receptionist setup
website_kickoff — Website kickoff
seo_baseline — SEO and AEO baseline
social_connected — Social accounts connected
blog_calendar — Blog calendar approved
go_live — Go live

Report requests

When a client clicks Get report now, the portal stores a pending request and, if configured, POSTs report.requested to the company webhook or REPORT_WEBHOOK_URL. The body is signed with X-Diaz-Signature: sha256=<hmac> using WEBHOOK_SECRET. Agents that cannot receive webhooks should poll GET /api/v1/agent/report-requests?status=pending and call fulfill.