{ "openapi": "3.0.3", "info": { "title": "SeeLLM REST API", "version": "1.0.0", "description": "The public contract for currently documented, authenticated analytics, jobs, and Agent Hooks endpoints." }, "servers": [ { "url": "https://api.seellm.link/api" } ], "paths": { "/analytics/ai-sources": { "get": { "summary": "Break down traffic by AI source", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "ai_source": { "type": "string" }, "visits": { "type": "number" }, "percentage": { "type": "number" }, "agent_fetches": { "type": "number" }, "ai_referrals": { "type": "number" } }, "required": [ "ai_source", "visits", "percentage", "agent_fetches", "ai_referrals" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/developer-tools": { "get": { "summary": "Break down traffic from developer AI tools", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/devices": { "get": { "summary": "Break down traffic by device", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/operating-systems": { "get": { "summary": "Break down traffic by operating system", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/browsers": { "get": { "summary": "Break down traffic by browser", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/hourly-activity": { "get": { "summary": "Break down traffic by hour", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/daily-activity": { "get": { "summary": "Break down traffic by day", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/time-series": { "get": { "summary": "Return a daily traffic series", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "total_visits": { "type": "number" }, "human_clicks": { "type": "number" }, "ai_visits": { "type": "number" }, "mobile_visits": { "type": "number" }, "desktop_visits": { "type": "number" } }, "required": [ "date", "total_visits", "human_clicks", "ai_visits", "mobile_visits", "desktop_visits" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/weekend-vs-weekday": { "get": { "summary": "Compare weekend and weekday traffic", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/top-links": { "get": { "summary": "List top links", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/utm-campaigns": { "get": { "summary": "List UTM campaign performance", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/geographic": { "get": { "summary": "Break down traffic by geography", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/referrers": { "get": { "summary": "Break down traffic by referrer", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/ai-confidence": { "get": { "summary": "Break down AI detection confidence", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/device-by-ai-source": { "get": { "summary": "Break down devices by AI source", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/ai-platform-market-share": { "get": { "summary": "Return Search AI request mix", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/dev-tools-adoption": { "get": { "summary": "Return developer tool adoption", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/ai-to-human-conversion": { "get": { "summary": "Return AI-to-human conversion data", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/traffic-value-breakdown": { "get": { "summary": "Return traffic value breakdown", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/bot-traffic": { "get": { "summary": "List classified bot traffic", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "traffic_type", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/traffic-overview": { "get": { "summary": "Return traffic totals", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "total_visits": { "type": "number" }, "human_clicks": { "type": "number" }, "ai_visits": { "type": "number" }, "other_visits": { "type": "number" }, "ai_percentage": { "type": "number" } }, "required": [ "total_visits", "human_clicks", "ai_visits", "other_visits", "ai_percentage" ], "additionalProperties": false } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/peak-times": { "get": { "summary": "Return peak traffic times", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true, "nullable": true } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/dashboard": { "get": { "summary": "Return the combined dashboard data", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "overview": { "type": "object", "properties": { "total_visits": { "type": "number" }, "human_clicks": { "type": "number" }, "ai_visits": { "type": "number" }, "other_visits": { "type": "number" }, "ai_percentage": { "type": "number" } }, "required": [ "total_visits", "human_clicks", "ai_visits", "other_visits", "ai_percentage" ], "additionalProperties": false }, "ai_sources": { "type": "array", "items": { "type": "object", "properties": { "ai_source": { "type": "string" }, "visits": { "type": "number" }, "percentage": { "type": "number" }, "agent_fetches": { "type": "number" }, "ai_referrals": { "type": "number" } }, "required": [ "ai_source", "visits", "percentage", "agent_fetches", "ai_referrals" ], "additionalProperties": false } }, "developer_tools": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "devices": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "time_series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "total_visits": { "type": "number" }, "human_clicks": { "type": "number" }, "ai_visits": { "type": "number" }, "mobile_visits": { "type": "number" }, "desktop_visits": { "type": "number" } }, "required": [ "date", "total_visits", "human_clicks", "ai_visits", "mobile_visits", "desktop_visits" ], "additionalProperties": false } }, "top_links": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "peak_times": { "type": "object", "properties": {}, "additionalProperties": true, "nullable": true }, "weekend_vs_weekday": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "geographic": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "referrers": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "decision_events": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true } }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "type": "string" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false } }, "required": [ "overview", "ai_sources", "developer_tools", "devices", "time_series", "top_links", "peak_times", "weekend_vs_weekday", "geographic", "referrers", "decision_events", "date_range" ], "additionalProperties": false } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/domain-breakdown": { "get": { "summary": "Break down traffic by domain", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "total_visits": { "type": "number" }, "human_clicks": { "type": "number" }, "ai_visits": { "type": "number" }, "ai_percentage": { "type": "number" }, "mobile_visits": { "type": "number" }, "desktop_visits": { "type": "number" }, "unique_links": { "type": "number" }, "percentage_of_total": { "type": "number" } }, "required": [ "domain", "total_visits", "human_clicks", "ai_visits", "ai_percentage", "mobile_visits", "desktop_visits", "unique_links", "percentage_of_total" ], "additionalProperties": false } } }, "required": [ "domains" ], "additionalProperties": false } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/filter-values": { "get": { "summary": "Return available analytics filter values", "security": [ { "Authorization": [] } ], "responses": { "200": { "description": "Available filter values", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/weekly-trend": { "get": { "summary": "Return weekly traffic trends", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "7d", "30d", "90d" ] } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "short_code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "target_url", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analytics data", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "weekly": { "type": "array", "items": { "type": "object", "properties": { "week": { "type": "string" }, "total_visits": { "type": "number" }, "human_visits": { "type": "number" }, "ai_visits": { "type": "number" }, "other_visits": { "type": "number" }, "ai_pct": { "type": "number" } }, "required": [ "week", "total_visits", "human_visits", "ai_visits", "other_visits", "ai_pct" ], "additionalProperties": false } }, "byPlatform": { "type": "array", "items": { "type": "object", "properties": { "week": { "type": "string" }, "ai_source": { "type": "string" }, "visits": { "type": "number" } }, "required": [ "week", "ai_source", "visits" ], "additionalProperties": false } } }, "required": [ "weekly", "byPlatform" ], "additionalProperties": false } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/analytics/cache-stats": { "get": { "summary": "Return analytics cache statistics", "security": [ { "Authorization": [] } ], "responses": { "200": { "description": "Cache statistics", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobs": { "get": { "summary": "List organization jobs", "description": "Returns every job for the authenticated organization, newest first. This endpoint has no pagination or filters.", "security": [ { "Authorization": [] } ], "responses": { "200": { "description": "Jobs", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "type": { "type": "string", "enum": [ "ai_attention_gap", "new_ai_crawler", "page_error", "citation_opportunity" ] }, "domain": { "type": "string" }, "page_url": { "type": "string" }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ] }, "status": { "type": "string", "enum": [ "new", "reviewed", "approved", "sent", "dismissed", "resolved" ] }, "headline": { "type": "string" }, "summary": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "detail": { "type": "string" } }, "required": [ "label", "value" ], "additionalProperties": false } }, "recommended_action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "implementation_options": { "type": "array", "items": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] } }, "status": { "type": "string", "enum": [ "recommended", "available", "approved", "dismissed", "completed" ] }, "selected_implementation_id": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "label", "implementation_options", "status" ], "additionalProperties": false } }, "implementations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] }, "status": { "type": "string", "enum": [ "requested", "selected", "created", "shipped", "failed" ] }, "action_id": { "type": "string" }, "implementation_id": { "type": "string" }, "note": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false } }, "required": [ "id", "type", "status", "action_id", "created_at" ], "additionalProperties": false } }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "autopilot_task", "system", "api" ] }, "id": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false }, "approved_at": { "type": "string" }, "dismissed_at": { "type": "string" } }, "required": [ "id", "org_id", "type", "domain", "priority", "status", "headline", "summary", "evidence", "recommended_action", "actions", "implementations", "source", "created_at", "updated_at" ], "additionalProperties": false } } }, "required": [ "jobs" ], "additionalProperties": false } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobs/{id}": { "get": { "summary": "Get an organization job", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "type": { "type": "string", "enum": [ "ai_attention_gap", "new_ai_crawler", "page_error", "citation_opportunity" ] }, "domain": { "type": "string" }, "page_url": { "type": "string" }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ] }, "status": { "type": "string", "enum": [ "new", "reviewed", "approved", "sent", "dismissed", "resolved" ] }, "headline": { "type": "string" }, "summary": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "detail": { "type": "string" } }, "required": [ "label", "value" ], "additionalProperties": false } }, "recommended_action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "implementation_options": { "type": "array", "items": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] } }, "status": { "type": "string", "enum": [ "recommended", "available", "approved", "dismissed", "completed" ] }, "selected_implementation_id": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "label", "implementation_options", "status" ], "additionalProperties": false } }, "implementations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] }, "status": { "type": "string", "enum": [ "requested", "selected", "created", "shipped", "failed" ] }, "action_id": { "type": "string" }, "implementation_id": { "type": "string" }, "note": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false } }, "required": [ "id", "type", "status", "action_id", "created_at" ], "additionalProperties": false } }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "autopilot_task", "system", "api" ] }, "id": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false }, "approved_at": { "type": "string" }, "dismissed_at": { "type": "string" } }, "required": [ "id", "org_id", "type", "domain", "priority", "status", "headline", "summary", "evidence", "recommended_action", "actions", "implementations", "source", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "job" ], "additionalProperties": false } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobs/from-autopilot-task": { "post": { "summary": "Create a job from an Autopilot task", "description": "Requires an editor or admin Firebase role; API keys authenticate as editors. The endpoint does not accept an idempotency key.", "security": [ { "Authorization": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "task_id" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created job and Agent Hook delivery result", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "type": { "type": "string", "enum": [ "ai_attention_gap", "new_ai_crawler", "page_error", "citation_opportunity" ] }, "domain": { "type": "string" }, "page_url": { "type": "string" }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ] }, "status": { "type": "string", "enum": [ "new", "reviewed", "approved", "sent", "dismissed", "resolved" ] }, "headline": { "type": "string" }, "summary": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "detail": { "type": "string" } }, "required": [ "label", "value" ], "additionalProperties": false } }, "recommended_action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "implementation_options": { "type": "array", "items": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] } }, "status": { "type": "string", "enum": [ "recommended", "available", "approved", "dismissed", "completed" ] }, "selected_implementation_id": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "label", "implementation_options", "status" ], "additionalProperties": false } }, "implementations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] }, "status": { "type": "string", "enum": [ "requested", "selected", "created", "shipped", "failed" ] }, "action_id": { "type": "string" }, "implementation_id": { "type": "string" }, "note": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false } }, "required": [ "id", "type", "status", "action_id", "created_at" ], "additionalProperties": false } }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "autopilot_task", "system", "api" ] }, "id": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false }, "approved_at": { "type": "string" }, "dismissed_at": { "type": "string" } }, "required": [ "id", "org_id", "type", "domain", "priority", "status", "headline", "summary", "evidence", "recommended_action", "actions", "implementations", "source", "created_at", "updated_at" ], "additionalProperties": false }, "hook_delivery": { "type": "object", "properties": { "attempted": { "type": "number" }, "delivered": { "type": "number" }, "failed": { "type": "number" } }, "required": [ "attempted", "delivered", "failed" ], "additionalProperties": false } }, "required": [ "job", "hook_delivery" ], "additionalProperties": false } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/jobs/{id}/actions": { "post": { "summary": "Approve or dismiss a job action", "description": "Requires an editor or admin Firebase role; API keys authenticate as editors. `implementation_id` is optional.", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action_id": { "type": "string", "minLength": 1, "maxLength": 120 }, "implementation_type": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ], "default": "manual" }, "implementation_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "action_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated job and implementation", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "type": { "type": "string", "enum": [ "ai_attention_gap", "new_ai_crawler", "page_error", "citation_opportunity" ] }, "domain": { "type": "string" }, "page_url": { "type": "string" }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ] }, "status": { "type": "string", "enum": [ "new", "reviewed", "approved", "sent", "dismissed", "resolved" ] }, "headline": { "type": "string" }, "summary": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "detail": { "type": "string" } }, "required": [ "label", "value" ], "additionalProperties": false } }, "recommended_action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "implementation_options": { "type": "array", "items": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] } }, "status": { "type": "string", "enum": [ "recommended", "available", "approved", "dismissed", "completed" ] }, "selected_implementation_id": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "label", "implementation_options", "status" ], "additionalProperties": false } }, "implementations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] }, "status": { "type": "string", "enum": [ "requested", "selected", "created", "shipped", "failed" ] }, "action_id": { "type": "string" }, "implementation_id": { "type": "string" }, "note": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false } }, "required": [ "id", "type", "status", "action_id", "created_at" ], "additionalProperties": false } }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "autopilot_task", "system", "api" ] }, "id": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false }, "approved_at": { "type": "string" }, "dismissed_at": { "type": "string" } }, "required": [ "id", "org_id", "type", "domain", "priority", "status", "headline", "summary", "evidence", "recommended_action", "actions", "implementations", "source", "created_at", "updated_at" ], "additionalProperties": false }, "implementation": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] }, "status": { "type": "string", "enum": [ "requested", "selected", "created", "shipped", "failed" ] }, "action_id": { "type": "string" }, "implementation_id": { "type": "string" }, "note": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false } }, "required": [ "id", "type", "status", "action_id", "created_at" ], "additionalProperties": false } }, "required": [ "job", "implementation" ], "additionalProperties": false } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-hooks": { "post": { "summary": "Create an Agent Hook", "description": "Requires an editor or admin Firebase role; API keys authenticate as editors. The returned signing secret is shown once.", "security": [ { "Authorization": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "The name is trimmed before the 120-character limit is applied; whitespace-only names are invalid.", "x-seellm-trimmed-max-length": 120 }, "url": { "type": "string", "format": "uri", "pattern": "^https:" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "job.created", "job.priority_changed", "job.approved", "job.dismissed", "job.resolved", "job.evidence_updated" ] }, "minItems": 1, "default": [ "job.created" ] } }, "required": [ "name", "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created Agent Hook and one-time signing secret", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "job.created", "job.priority_changed", "job.approved", "job.dismissed", "job.resolved", "job.evidence_updated" ] } }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_tested_at": { "type": "string" }, "last_delivery_status": { "type": "string", "enum": [ "success", "failed" ] }, "last_delivery_http_status": { "type": "number" }, "last_delivery_error": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "name", "url", "events", "status", "created_at", "updated_at", "secret" ], "additionalProperties": false } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List Agent Hooks", "security": [ { "Authorization": [] } ], "responses": { "200": { "description": "Agent Hooks without signing secrets", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "hooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "job.created", "job.priority_changed", "job.approved", "job.dismissed", "job.resolved", "job.evidence_updated" ] } }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_tested_at": { "type": "string" }, "last_delivery_status": { "type": "string", "enum": [ "success", "failed" ] }, "last_delivery_http_status": { "type": "number" }, "last_delivery_error": { "type": "string" } }, "required": [ "id", "name", "url", "events", "status", "created_at", "updated_at" ], "additionalProperties": false } } }, "required": [ "hooks" ], "additionalProperties": false } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent-hooks/{id}/test": { "post": { "summary": "Send an Agent Hook test delivery", "description": "Requires an editor or admin Firebase role; API keys authenticate as editors. `domain` defaults to `example.com` when omitted.", "security": [ { "Authorization": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 3, "maxLength": 253, "default": "example.com", "description": "When supplied, the domain is trimmed and lowercased before test delivery." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful test delivery", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "status": { "type": "number" }, "event_id": { "type": "string" } }, "required": [ "success", "status", "event_id" ], "additionalProperties": false } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed downstream delivery", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "status": { "type": "number" }, "error": { "type": "string" } }, "required": [ "success", "error" ], "additionalProperties": false } } } } } } } }, "components": { "securitySchemes": { "Authorization": { "type": "http", "scheme": "bearer", "bearerFormat": "Firebase JWT or SeeLLM API key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "retryAfter": { "type": "number" }, "limit": { "type": "number" }, "remaining": { "type": "number" } }, "required": [ "error" ], "additionalProperties": false }, "Job": { "type": "object", "properties": { "id": { "type": "string" }, "org_id": { "type": "string" }, "type": { "type": "string", "enum": [ "ai_attention_gap", "new_ai_crawler", "page_error", "citation_opportunity" ] }, "domain": { "type": "string" }, "page_url": { "type": "string" }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ] }, "status": { "type": "string", "enum": [ "new", "reviewed", "approved", "sent", "dismissed", "resolved" ] }, "headline": { "type": "string" }, "summary": { "type": "string" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "detail": { "type": "string" } }, "required": [ "label", "value" ], "additionalProperties": false } }, "recommended_action": { "type": "string" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "implementation_options": { "type": "array", "items": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] } }, "status": { "type": "string", "enum": [ "recommended", "available", "approved", "dismissed", "completed" ] }, "selected_implementation_id": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "label", "implementation_options", "status" ], "additionalProperties": false } }, "implementations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] }, "status": { "type": "string", "enum": [ "requested", "selected", "created", "shipped", "failed" ] }, "action_id": { "type": "string" }, "implementation_id": { "type": "string" }, "note": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false } }, "required": [ "id", "type", "status", "action_id", "created_at" ], "additionalProperties": false } }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "autopilot_task", "system", "api" ] }, "id": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false }, "approved_at": { "type": "string" }, "dismissed_at": { "type": "string" } }, "required": [ "id", "org_id", "type", "domain", "priority", "status", "headline", "summary", "evidence", "recommended_action", "actions", "implementations", "source", "created_at", "updated_at" ], "additionalProperties": false }, "JobImplementation": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "patch", "edge_page", "manual", "agent_hook" ] }, "status": { "type": "string", "enum": [ "requested", "selected", "created", "shipped", "failed" ] }, "action_id": { "type": "string" }, "implementation_id": { "type": "string" }, "note": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "uid": { "type": "string" }, "email": { "type": "string" } }, "required": [ "uid" ], "additionalProperties": false } }, "required": [ "id", "type", "status", "action_id", "created_at" ], "additionalProperties": false }, "AgentHook": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "job.created", "job.priority_changed", "job.approved", "job.dismissed", "job.resolved", "job.evidence_updated" ] } }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "last_tested_at": { "type": "string" }, "last_delivery_status": { "type": "string", "enum": [ "success", "failed" ] }, "last_delivery_http_status": { "type": "number" }, "last_delivery_error": { "type": "string" } }, "required": [ "id", "name", "url", "events", "status", "created_at", "updated_at" ], "additionalProperties": false } } } }