AI Agent API

A dedicated API for AI agents to create links, update profiles, and complete purchases on behalf of an EdgeURL user. Separate auth tier, explicit permissions, full audit trail.

Why a separate API?

Sharing a session cookie or API key with an agent is risky: you give up scope control, rate limits apply to you instead of the agent, and there's no attribution for agent-initiated actions.

/api/ai/v1 fixes all three:

• Scoped tokens — each agent gets its own ai_* token with explicit permissions (read-only analytics, create-links, make-purchases).
• Per-agent rate limits — one misbehaving agent can't exhaust your session's quota.
• Usage attribution — every call emits a row in ai_usage_events. You see what each agent did, when, and how much AI cost it incurred.
• Instant revocation — revoke a token from the dashboard and the agent is locked out within one request cycle.

Auth flow

Agents don't register themselves. A human EdgeURL user grants an agent token through the authorization flow.

1. Agent calls POST /api/ai/v1/request-access with its identity (name, description, requested permissions). Returns a request_id and the user is emailed an authorization link.
2. User clicks the approval link (GET /api/ai/v1/authorize?token=<token>&action=approve) from their email. Signed-in users can also POST to the same route programmatically. The request moves toapproved or denied.
3. Agent polls GET /api/ai/v1/status?request_id=<id>until the response reports approved, then receives its ai_* token.
4. Agent includes token in Authorization: Bearer ai_<token>on every subsequent API call. GET /api/ai/v1/status (no query param) verifies the token is still valid.

Endpoints

BYOK — bring your own key

Agents that need to run their own AI calls (classification, generation, embeddings) can ship user-provided provider keys. EdgeURL supports:

• OpenAI (gpt-4o, gpt-4o-mini, o-series)
• Anthropic (Claude 4.x family)
• Google (Gemini 1.5/2.0)
• Mistral (small/medium/large)
• Cohere (command-r/command-r-plus)

BYOK calls route through the user's key with zero platform markup. When no BYOK is set, calls use the platform key at cost-plus pricing. Both paths emit the same usage events for attribution.

Rate limits

Separate sliding-window limits per agent token (not per IP or user):

• Read (GET): 60 requests / 10 seconds
• Write (POST/PATCH on links, profile): 20 requests / 10 seconds
• Purchase: 5 requests / minute, with a hard daily spend cap set at grant time
• Authorize flow: 10 requests / 10 seconds per IP

Attribution + cost tracking

Every call writes a row into ai_usage_events with the agent's token prefix, action taken, resource touched, and (if AI was called) model + prompt/completion tokens. Admins see platform-wide per-agent breakdowns at /admin/unit-economics. User-facing per-agent usage dashboards ship in a later release.