Integration Notes

Audience: Engineers wiring Adros into their stack - whether via MCP, REST, webhooks, or the dashboard.

This page covers behaviors and constraints that are easy to miss if you only read the OpenAPI surface.

1. What Adros is

Adros is a hybrid marketing OS: FastAPI on Railway, React dashboard on Vercel, Supabase Postgres, Cloudflare R2 for scoped files, plus MCP (Streamable HTTP). It includes patterns, memory, creative generation, monitoring, and first-class operator workflows on app.adros.ai (opens in a new tab): Command Center, Strategy Workspace, Files, Campaigns, and Adros CEO.

If you run a custom conductor on top, Adros remains the marketing capability + data plane; your layer can own cross-tool sequencing, human assignment, or policies Adros does not encode.

Research stack direction: product direction is Perplexity + DataForSEO + Firecrawl + platform-native account data. Verify exact deployment support before documenting a specific environment as fully live-native.

2. Auth is the same everywhere

One token, one user, one permission model.

3. MCP connection: the #1 support issue

Checklist:

1. Token is lyr_...
2. X-User-Token header, not Authorization: Bearer
3. URL is https://api.adros.ai/mcp
4. Transport is Streamable HTTP
5. Restart the MCP client fully after config change

4. Memory is append-only (mostly)

• business_context and personas can be overwritten
• weekly_logs should be appended, not replaced
• Memory is scoped by (user_id, client_id)

5. Multi-tenant scoping

Every data access should be scoped to user_id. Where client context matters, also scope by client_id.

Common examples:

• approve/reject flows
• file access
• campaign data

6. Webhook delivery is fire-and-forget

• No retries
• Signature: HMAC-SHA256 using your webhook secret
• Deduping: use dedupe_key
• Design your receiver to be idempotent

7. Contract layer - important details

• recommended_specialist values are runtime actor IDs: adros_ceo, adros_research, adros_cmo, adros_cd, adros_deployer
• Branch on those IDs, not display names
• next_stage in the contract is advisory; the orchestrator owns task lifecycle

8. Creative generation guardrails

• Always use the documented generator/mode defaults for your deployment
• generate_creative has an idempotency window
• Creative generation is rate-limited
• Pattern blueprints anchor generation quality

9. File upload flow

1. Client calls POST /files/upload
2. Backend validates scope
3. Object is written to R2 under a scoped prefix
4. Metadata is stored in task artifacts
5. Browse/download/delete via corresponding endpoints

10. Task event timeline

• Events are append-only
• Query latest activity with ORDER BY created_at DESC
• WebSocket at /ws/events/{task_id}?token=lyr_... streams new events
• Task status is broader than file upload. A task can still be in review, paused, or failed after artifacts appear if package completion, approvals, or revisions are still pending.

11. Campaign scope and fallback

• Google/Meta campaign data depends on the accounts the user has connected and selected
• If the selected account is unavailable, the system may fall back to another accessible account
• Fallback behavior should be surfaced in the UI or API consumer

12. Quality track prerequisites

Before scorecards, guardrails, or audit artifact persistence work:

1. Migration 025_audit_quality_track must be applied
2. AUDIT_QUALITY_TRACK_ENABLED must be enabled in the target environment
3. The task must be an audit-type task that completed the quality path

13. What NOT to do

• Do not hardcode specialist display names
• Do not assume all tasks share the same lifecycle
• Do not skip ownership checks in custom orchestration
• Do not replace weekly logs
• Do not expect webhook retries