{ "components": { "schemas": { "AgentDecision": { "properties": { "financial_advice": { "const": false, "type": "boolean" }, "needs_human_review": { "type": "boolean" }, "safe_to_summarize": { "type": "boolean" } }, "required": [ "safe_to_summarize", "financial_advice", "needs_human_review" ], "type": "object" }, "AssessmentFreshness": { "properties": { "freshness_window_hours": { "maximum": 168, "minimum": 1, "type": "integer" }, "last_attempted_sync_at": { "format": "date-time", "type": [ "string", "null" ] }, "last_completed_sync_at": { "format": "date-time", "type": [ "string", "null" ] }, "last_status": { "enum": [ "running", "completed", "completed_with_errors", "failed", null ], "type": [ "string", "null" ] }, "last_successful_sync_at": { "format": "date-time", "type": [ "string", "null" ] }, "status": { "enum": [ "never_synced", "fresh", "stale", "degraded", "failed", "sync_running", "not_tracked" ], "type": "string" } }, "required": [ "freshness_window_hours", "status", "last_attempted_sync_at", "last_completed_sync_at", "last_successful_sync_at", "last_status" ], "type": "object" }, "AssessmentSource": { "properties": { "accession_number": { "type": "string" }, "content_sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "filing_date": { "format": "date", "type": "string" }, "provenance_status": { "enum": [ "available", "unavailable" ], "type": "string" }, "retrieved_at": { "format": "date-time", "type": "string" }, "source_document_url": { "type": "string" }, "source_metadata_url": { "type": "string" } }, "required": [ "accession_number", "filing_date", "provenance_status" ], "type": "object" }, "CacheMetadata": { "properties": { "status": { "enum": [ "hit", "miss", "bypass", "unavailable" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "CacheReadinessCheck": { "properties": { "backend": { "enum": [ "memory", "redis" ], "type": "string" }, "status": { "enum": [ "ok", "unavailable" ], "type": "string" } }, "required": [ "status", "backend" ], "type": "object" }, "Caveat": { "properties": { "code": { "enum": [ "ticker_never_synced", "sync_in_progress", "latest_sync_failed", "freshness_degraded", "data_stale", "partial_source_provenance", "source_provenance_unavailable", "missing_price_data", "missing_share_data", "form4_amendments_excluded", "ticker_not_in_watchlist", "no_transactions_not_proof_of_no_activity", "period_limited", "scheduled_plan_context_not_extracted", "limited_insider_role_context", "limited_watchlist_coverage", "insider_activity_not_necessarily_predictive", "not_financial_advice" ], "type": "string" }, "message": { "type": "string" }, "severity": { "enum": [ "info", "warning", "critical" ], "type": "string" } }, "required": [ "code", "severity", "message" ], "type": "object" }, "ErrorBody": { "properties": { "code": { "enum": [ "unauthorized", "rate_limited", "not_found", "invalid_ticker", "invalid_period", "invalid_freshness_window", "invalid_accession_number", "provenance_not_available", "internal_error" ], "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" }, "request_id": { "pattern": "^req_[A-Za-z0-9_-]+$", "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "FilingProvenanceResponse": { "properties": { "accession_number": { "pattern": "^[0-9]{10}-[0-9]{2}-[0-9]{6}$", "type": "string" }, "api_version": { "const": "v1", "type": "string" }, "caveats": { "items": { "type": "string" }, "type": "array" }, "generated_at": { "format": "date-time", "type": "string" }, "methodology": { "items": { "type": "string" }, "type": "array" }, "provenance_status": { "const": "available", "type": "string" }, "request_id": { "pattern": "^req_[A-Za-z0-9_-]+$", "type": "string" }, "source": { "$ref": "#/components/schemas/FilingProvenanceSource" } }, "required": [ "request_id", "api_version", "generated_at", "accession_number", "provenance_status", "source", "methodology", "caveats" ], "type": "object" }, "FilingProvenanceSource": { "properties": { "content_sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "content_size_bytes": { "minimum": 0, "type": "integer" }, "content_type": { "type": [ "string", "null" ] }, "normalizer_version": { "type": "string" }, "parser_version": { "type": "string" }, "retrieved_at": { "format": "date-time", "type": "string" }, "source": { "type": "string" }, "source_document_url": { "type": "string" }, "source_metadata_url": { "type": [ "string", "null" ] } }, "required": [ "source", "source_document_url", "source_metadata_url", "retrieved_at", "content_sha256", "content_size_bytes", "content_type", "parser_version", "normalizer_version" ], "type": "object" }, "HealthResponse": { "properties": { "request_id": { "pattern": "^req_[A-Za-z0-9_-]+$", "type": "string" }, "status": { "const": "ok", "type": "string" } }, "required": [ "request_id", "status" ], "type": "object" }, "InsiderActivityAssessment": { "properties": { "activity_level": { "enum": [ "none", "low", "moderate", "elevated" ], "type": "string" }, "data_quality": { "enum": [ "clean", "limited", "degraded", "unavailable" ], "type": "string" }, "dominant_activity": { "enum": [ "none", "sales", "purchases", "mixed", "other" ], "type": "string" }, "summary_text": { "type": "string" } }, "required": [ "activity_level", "dominant_activity", "data_quality", "summary_text" ], "type": "object" }, "InsiderActivityAssessmentResponse": { "properties": { "api_version": { "const": "v1", "type": "string" }, "assessment": { "$ref": "#/components/schemas/InsiderActivityAssessment" }, "caveats": { "items": { "$ref": "#/components/schemas/Caveat" }, "type": "array" }, "data_as_of": { "description": "Latest filing_date among transactions included in this assessment, formatted as a UTC midnight timestamp; null when no transactions are included.", "format": "date-time", "type": [ "string", "null" ] }, "freshness": { "$ref": "#/components/schemas/AssessmentFreshness" }, "generated_at": { "format": "date-time", "type": "string" }, "methodology": { "$ref": "#/components/schemas/Methodology" }, "period": { "enum": [ "30d", "90d", "180d" ], "type": "string" }, "request_id": { "pattern": "^req_[A-Za-z0-9_-]+$", "type": "string" }, "sources": { "items": { "$ref": "#/components/schemas/AssessmentSource" }, "type": "array" }, "summary": { "$ref": "#/components/schemas/InsiderActivityAssessmentSummary" }, "ticker": { "maxLength": 10, "minLength": 1, "pattern": "^[A-Z0-9.-]+$", "type": "string" } }, "required": [ "request_id", "api_version", "generated_at", "data_as_of", "ticker", "period", "freshness", "assessment", "summary", "caveats", "methodology", "sources" ], "type": "object" }, "InsiderActivityAssessmentSummary": { "properties": { "filing_count": { "minimum": 0, "type": "integer" }, "filings_with_source_provenance_count": { "minimum": 0, "type": "integer" }, "missing_price_count": { "minimum": 0, "type": "integer" }, "missing_share_count": { "minimum": 0, "type": "integer" }, "other_transaction_count": { "minimum": 0, "type": "integer" }, "purchase_transaction_count": { "minimum": 0, "type": "integer" }, "sale_transaction_count": { "minimum": 0, "type": "integer" }, "transaction_count": { "minimum": 0, "type": "integer" } }, "required": [ "transaction_count", "sale_transaction_count", "purchase_transaction_count", "other_transaction_count", "missing_price_count", "missing_share_count", "filing_count", "filings_with_source_provenance_count" ], "type": "object" }, "InsiderRelationship": { "properties": { "is_director": { "type": [ "boolean", "null" ] }, "is_officer": { "type": [ "boolean", "null" ] }, "is_ten_percent_owner": { "type": [ "boolean", "null" ] }, "officer_title": { "type": [ "string", "null" ] } }, "required": [ "is_director", "is_officer", "is_ten_percent_owner", "officer_title" ], "type": "object" }, "InsiderSellingSignal": { "properties": { "description": { "type": "string" }, "type": { "enum": [ "multiple_insiders_selling", "more_sale_transactions_than_purchases", "no_insider_buying_present" ], "type": "string" } }, "required": [ "type", "description" ], "type": "object" }, "InsiderSellingSummary": { "properties": { "largest_sale": { "oneOf": [ { "$ref": "#/components/schemas/LargestSale" }, { "type": "null" } ] }, "net_sales_value": { "description": "Decimal money value serialized as a string with exactly 2 decimal places.", "type": "string" }, "purchase_transaction_count": { "minimum": 0, "type": "integer" }, "sale_transaction_count": { "minimum": 0, "type": "integer" }, "total_purchase_value": { "description": "Decimal money value serialized as a string with exactly 2 decimal places.", "type": "string" }, "total_sales_value": { "description": "Decimal money value serialized as a string with exactly 2 decimal places.", "type": "string" }, "total_shares_sold": { "description": "Decimal share quantity serialized as a string.", "type": "string" }, "transaction_count": { "minimum": 0, "type": "integer" }, "unique_insiders_buying": { "minimum": 0, "type": "integer" }, "unique_insiders_selling": { "minimum": 0, "type": "integer" } }, "required": [ "transaction_count", "sale_transaction_count", "purchase_transaction_count", "total_sales_value", "total_purchase_value", "net_sales_value", "total_shares_sold", "unique_insiders_selling", "unique_insiders_buying", "largest_sale" ], "type": "object" }, "InsiderSellingSummaryResponse": { "properties": { "agent_decision": { "$ref": "#/components/schemas/AgentDecision" }, "api_version": { "const": "v1", "type": "string" }, "cache": { "$ref": "#/components/schemas/CacheMetadata" }, "caveats": { "items": { "type": "string" }, "type": "array" }, "data_as_of": { "format": "date-time", "type": [ "string", "null" ] }, "generated_at": { "format": "date-time", "type": "string" }, "methodology": { "$ref": "#/components/schemas/Methodology" }, "period": { "enum": [ "30d", "90d", "180d" ], "type": "string" }, "request_id": { "pattern": "^req_[A-Za-z0-9_-]+$", "type": "string" }, "signals": { "items": { "$ref": "#/components/schemas/InsiderSellingSignal" }, "type": "array" }, "sources": { "items": { "$ref": "#/components/schemas/Source" }, "type": "array" }, "summary": { "$ref": "#/components/schemas/InsiderSellingSummary" }, "ticker": { "maxLength": 10, "minLength": 1, "pattern": "^[A-Z0-9.-]+$", "type": "string" } }, "required": [ "request_id", "api_version", "generated_at", "data_as_of", "ticker", "period", "summary", "signals", "agent_decision", "methodology", "sources", "caveats", "cache" ], "type": "object" }, "InsiderTransaction": { "properties": { "accession_number": { "type": "string" }, "direction": { "enum": [ "purchase", "sale" ], "type": "string" }, "filing_date": { "format": "date", "type": "string" }, "insider_cik": { "type": [ "string", "null" ] }, "insider_name": { "type": "string" }, "price": { "description": "Decimal money value serialized as a string with exactly 2 decimal places.", "type": [ "string", "null" ] }, "relationship": { "$ref": "#/components/schemas/InsiderRelationship" }, "security_title": { "type": "string" }, "shares": { "type": [ "string", "null" ] }, "shares_owned_after": { "type": [ "string", "null" ] }, "transaction_code": { "type": "string" }, "transaction_date": { "format": "date", "type": "string" }, "transaction_external_id": { "type": "string" }, "value": { "description": "Decimal money value serialized as a string with exactly 2 decimal places when shares and price are both available.", "type": [ "string", "null" ] } }, "required": [ "transaction_external_id", "accession_number", "filing_date", "transaction_date", "insider_name", "insider_cik", "relationship", "security_title", "transaction_code", "direction", "shares", "price", "value", "shares_owned_after" ], "type": "object" }, "InsiderTransactionsResponse": { "properties": { "api_version": { "const": "v1", "type": "string" }, "caveats": { "items": { "type": "string" }, "type": "array" }, "data_as_of": { "format": "date-time", "type": [ "string", "null" ] }, "generated_at": { "format": "date-time", "type": "string" }, "methodology": { "$ref": "#/components/schemas/Methodology" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "period": { "enum": [ "30d", "90d", "180d" ], "type": "string" }, "request_id": { "pattern": "^req_[A-Za-z0-9_-]+$", "type": "string" }, "sources": { "items": { "$ref": "#/components/schemas/Source" }, "type": "array" }, "ticker": { "maxLength": 10, "minLength": 1, "pattern": "^[A-Z0-9.-]+$", "type": "string" }, "transactions": { "items": { "$ref": "#/components/schemas/InsiderTransaction" }, "type": "array" } }, "required": [ "request_id", "api_version", "generated_at", "data_as_of", "ticker", "period", "transactions", "pagination", "methodology", "sources", "caveats" ], "type": "object" }, "LargestSale": { "properties": { "accession_number": { "type": "string" }, "insider_cik": { "type": [ "string", "null" ] }, "insider_name": { "type": "string" }, "price": { "description": "Decimal money value serialized as a string with exactly 2 decimal places.", "type": [ "string", "null" ] }, "shares": { "type": [ "string", "null" ] }, "transaction_date": { "format": "date", "type": "string" }, "value": { "description": "Decimal money value serialized as a string with exactly 2 decimal places.", "type": "string" } }, "required": [ "insider_name", "insider_cik", "transaction_date", "shares", "price", "value", "accession_number" ], "type": "object" }, "Methodology": { "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "rules": { "items": { "type": "string" }, "type": "array" }, "version": { "type": "string" } }, "required": [ "version", "name", "description", "rules" ], "type": "object" }, "Pagination": { "properties": { "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "limit", "next_cursor" ], "type": "object" }, "PaidApiMetadataResponse": { "properties": { "category": { "type": "string" }, "contact": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "free_preview_url": { "type": "string" }, "health_url": { "type": "string" }, "openapi_url": { "type": "string" }, "paid_endpoints": { "items": { "$ref": "#/components/schemas/PaidEndpointMetadata" }, "type": "array" }, "protocols": { "items": { "enum": [ "L402" ], "type": "string" }, "type": "array" }, "service_name": { "type": "string" } }, "required": [ "service_name", "description", "protocols", "category", "health_url", "openapi_url", "free_preview_url", "paid_endpoints", "contact" ], "type": "object" }, "PaidEndpointMetadata": { "properties": { "currently_enforced": { "const": false, "type": "boolean" }, "method": { "enum": [ "GET" ], "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "price_sats": { "minimum": 0, "type": "integer" }, "protocol": { "const": "L402", "type": "string" } }, "required": [ "name", "method", "path", "price_sats", "protocol", "currently_enforced" ], "type": "object" }, "ReadinessCheck": { "properties": { "status": { "enum": [ "ok", "unavailable" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "ReadinessResponse": { "properties": { "checks": { "properties": { "cache": { "$ref": "#/components/schemas/CacheReadinessCheck" }, "database": { "$ref": "#/components/schemas/ReadinessCheck" } }, "required": [ "database", "cache" ], "type": "object" }, "request_id": { "pattern": "^req_[A-Za-z0-9_-]+$", "type": "string" }, "status": { "enum": [ "ok", "unavailable" ], "type": "string" } }, "required": [ "request_id", "status", "checks" ], "type": "object" }, "Source": { "properties": { "accession_number": { "type": "string" }, "filing_date": { "format": "date", "type": "string" }, "form": { "type": "string" }, "issuer_cik": { "type": "string" }, "issuer_ticker": { "type": "string" }, "reporting_owner_cik": { "type": [ "string", "null" ] }, "reporting_owner_name": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "type": { "type": "string" } }, "required": [ "type", "form", "accession_number", "filing_date", "issuer_cik", "issuer_ticker", "reporting_owner_cik", "reporting_owner_name", "source_url" ], "type": "object" }, "TickerPreviewResponse": { "properties": { "agent_decision": { "$ref": "#/components/schemas/AgentDecision" }, "api_version": { "const": "v1", "type": "string" }, "availability": { "type": "boolean" }, "caveats": { "items": { "type": "string" }, "type": "array" }, "data_as_of": { "format": "date-time", "type": [ "string", "null" ] }, "generated_at": { "format": "date-time", "type": "string" }, "methodology": { "$ref": "#/components/schemas/Methodology" }, "pricing_metadata_url": { "const": "/.well-known/paid-api.json", "type": "string" }, "request_id": { "pattern": "^req_[A-Za-z0-9_-]+$", "type": "string" }, "sources": { "items": { "$ref": "#/components/schemas/Source" }, "type": "array" }, "ticker": { "maxLength": 10, "minLength": 1, "pattern": "^[A-Z0-9.-]+$", "type": "string" } }, "required": [ "request_id", "api_version", "generated_at", "data_as_of", "ticker", "availability", "pricing_metadata_url", "sources", "caveats", "agent_decision", "methodology" ], "type": "object" }, "WatchedTickerFreshness": { "properties": { "freshness_status": { "enum": [ "never_synced", "fresh", "stale", "degraded", "failed", "sync_running" ], "type": "string" }, "last_attempted_sync_at": { "format": "date-time", "type": [ "string", "null" ] }, "last_completed_sync_at": { "format": "date-time", "type": [ "string", "null" ] }, "last_discovered_count": { "minimum": 0, "type": [ "integer", "null" ] }, "last_error_message": { "type": [ "string", "null" ] }, "last_failed_count": { "minimum": 0, "type": [ "integer", "null" ] }, "last_imported_count": { "minimum": 0, "type": [ "integer", "null" ] }, "last_skipped_count": { "minimum": 0, "type": [ "integer", "null" ] }, "last_status": { "enum": [ "running", "completed", "completed_with_errors", "failed", null ], "type": [ "string", "null" ] }, "last_successful_sync_at": { "format": "date-time", "type": [ "string", "null" ] }, "ticker": { "maxLength": 10, "minLength": 1, "pattern": "^[A-Z0-9.-]+$", "type": "string" } }, "required": [ "ticker", "freshness_status", "last_attempted_sync_at", "last_completed_sync_at", "last_successful_sync_at", "last_status", "last_discovered_count", "last_imported_count", "last_skipped_count", "last_failed_count", "last_error_message" ], "type": "object" }, "WatchlistFreshnessResponse": { "properties": { "api_version": { "const": "v1", "type": "string" }, "caveats": { "items": { "type": "string" }, "type": "array" }, "data_as_of": { "description": "Latest terminal ingestion completed_at timestamp across enabled watched tickers; null when no terminal run exists.", "format": "date-time", "type": [ "string", "null" ] }, "freshness_window_hours": { "maximum": 168, "minimum": 1, "type": "integer" }, "generated_at": { "format": "date-time", "type": "string" }, "methodology": { "items": { "type": "string" }, "type": "array" }, "request_id": { "pattern": "^req_[A-Za-z0-9_-]+$", "type": "string" }, "status": { "enum": [ "empty", "fresh", "degraded", "unavailable" ], "type": "string" }, "summary": { "$ref": "#/components/schemas/WatchlistFreshnessSummary" }, "tickers": { "items": { "$ref": "#/components/schemas/WatchedTickerFreshness" }, "type": "array" } }, "required": [ "request_id", "api_version", "generated_at", "data_as_of", "freshness_window_hours", "status", "summary", "tickers", "methodology", "caveats" ], "type": "object" }, "WatchlistFreshnessSummary": { "properties": { "degraded": { "minimum": 0, "type": "integer" }, "enabled_tickers": { "minimum": 0, "type": "integer" }, "failed": { "minimum": 0, "type": "integer" }, "fresh": { "minimum": 0, "type": "integer" }, "never_synced": { "minimum": 0, "type": "integer" }, "stale": { "minimum": 0, "type": "integer" }, "sync_running": { "minimum": 0, "type": "integer" } }, "required": [ "enabled_tickers", "fresh", "stale", "degraded", "failed", "sync_running", "never_synced" ], "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "info": { "description": "Canonical public contracts for Headless Records API v1. Responses summarize imported public SEC filing data with source-backed context, deterministic caveats, and non-advisory methodology.", "title": "Headless Records API", "version": "v1" }, "openapi": "3.1.0", "paths": { "/.well-known/paid-api.json": { "get": { "description": "Returns machine-readable metadata for future L402 paid API endpoints. Payment enforcement is not currently active.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaidApiMetadataResponse" } } }, "description": "Paid API pricing metadata document." } }, "summary": "Paid API metadata" } }, "/health": { "get": { "description": "Returns operational health for the API process.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } }, "description": "API process is healthy." } }, "summary": "Health check" } }, "/openapi.json": { "get": { "description": "Returns the machine-readable OpenAPI schema for implemented public routes.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OpenAPI schema document." } }, "summary": "OpenAPI schema" } }, "/ready": { "get": { "description": "Checks whether the API can serve real traffic by verifying required dependencies.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } }, "description": "Required dependencies are ready." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } }, "description": "A required dependency is unavailable." } }, "summary": "Readiness check" } }, "/v1/freshness": { "get": { "description": "Reports freshness for the bounded enabled watched ticker universe from stored SEC Form 4 ingestion status rows.", "parameters": [ { "in": "query", "name": "freshness_window_hours", "required": false, "schema": { "default": 24, "maximum": 168, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "freshness": { "externalValue": "../examples/responses/freshness.json" } }, "schema": { "$ref": "#/components/schemas/WatchlistFreshnessResponse" } } }, "description": "Watchlist freshness was computed." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "freshness_window_hours is invalid." }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "A valid API key is required." }, "request_id": "req_example_401" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Please retry later." }, "request_id": "req_example_429" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Client exceeded the API-key endpoint rate limit.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying.", "schema": { "minimum": 1, "type": "integer" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "value": { "error": { "code": "internal_error", "message": "Internal server error." }, "request_id": "req_example_500" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Freshness could not be computed from the database." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Freshness" } }, "/v1/insider-activity/{ticker}/assessment": { "get": { "description": "Returns a deterministic assessment of reported insider filing activity for one ticker from imported SEC Form 4 data. The response is descriptive, source-backed where provenance is available, and is not financial advice.", "parameters": [ { "in": "path", "name": "ticker", "required": true, "schema": { "maxLength": 10, "minLength": 1, "pattern": "^[A-Za-z0-9.-]+$", "type": "string" } }, { "in": "query", "name": "period", "required": false, "schema": { "default": "90d", "enum": [ "30d", "90d", "180d" ], "type": "string" } }, { "in": "query", "name": "freshness_window_hours", "required": false, "schema": { "default": 24, "maximum": 168, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "assessment": { "externalValue": "../examples/responses/assessment_tsla_90d.json" } }, "schema": { "$ref": "#/components/schemas/InsiderActivityAssessmentResponse" } } }, "description": "Ticker was accepted and a deterministic insider activity assessment was returned." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Ticker, period, or freshness_window_hours is invalid." }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "A valid API key is required." }, "request_id": "req_example_401" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Please retry later." }, "request_id": "req_example_429" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Client exceeded the API-key endpoint rate limit.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying.", "schema": { "minimum": 1, "type": "integer" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "value": { "error": { "code": "internal_error", "message": "Internal server error." }, "request_id": "req_example_500" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Assessment could not be computed from the database." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Insider activity assessment" } }, "/v1/provenance/filing/{accession_number}": { "get": { "description": "Returns source-backed, hash-verifiable provenance for an imported filing only when that filing is linked to a source document. The hash identifies the bytes processed by ingestion; it is not an SEC signature and does not make claims about investment merit or trading signals.", "parameters": [ { "in": "path", "name": "accession_number", "required": true, "schema": { "pattern": "^[0-9]{10}-[0-9]{2}-[0-9]{6}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "provenance": { "externalValue": "../examples/responses/provenance_available.json" } }, "schema": { "$ref": "#/components/schemas/FilingProvenanceResponse" } } }, "description": "Filing provenance is available." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Accession number format is invalid." }, "401": { "content": { "application/json": { "examples": { "unauthorized": { "value": { "error": { "code": "unauthorized", "message": "A valid API key is required." }, "request_id": "req_example_401" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Missing or invalid API key." }, "404": { "content": { "application/json": { "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "Resource not found." }, "request_id": "req_example_404" } }, "provenance_not_available": { "value": { "error": { "code": "provenance_not_available", "message": "Provenance is not available for this filing." }, "request_id": "req_example_404_provenance" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Filing was not found, or provenance is not available for the filing." }, "429": { "content": { "application/json": { "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Please retry later." }, "request_id": "req_example_429" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Client exceeded the API-key endpoint rate limit.", "headers": { "Retry-After": { "description": "Seconds the client should wait before retrying.", "schema": { "minimum": 1, "type": "integer" } } } }, "500": { "content": { "application/json": { "examples": { "internal_error": { "value": { "error": { "code": "internal_error", "message": "Internal server error." }, "request_id": "req_example_500" } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Provenance could not be read from the database." } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Filing provenance" } }, "/v1/ticker/{ticker}/insider-selling-summary": { "get": { "description": "Returns factual insider purchase and sale summary metrics from imported Form 4 data.", "parameters": [ { "in": "path", "name": "ticker", "required": true, "schema": { "maxLength": 10, "minLength": 1, "pattern": "^[A-Za-z0-9.-]+$", "type": "string" } }, { "in": "query", "name": "period", "required": false, "schema": { "default": "90d", "enum": [ "30d", "90d", "180d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsiderSellingSummaryResponse" } } }, "description": "Ticker was accepted and summary metrics were returned." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Ticker or period format is invalid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Client exceeded the API-key endpoint rate limit." } }, "summary": "Insider-selling summary" } }, "/v1/ticker/{ticker}/insider-transactions": { "get": { "description": "Returns normalized insider transactions from imported Form 4 data.", "parameters": [ { "in": "path", "name": "ticker", "required": true, "schema": { "maxLength": 10, "minLength": 1, "pattern": "^[A-Za-z0-9.-]+$", "type": "string" } }, { "in": "query", "name": "period", "required": false, "schema": { "default": "90d", "enum": [ "30d", "90d", "180d" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsiderTransactionsResponse" } } }, "description": "Ticker was accepted and normalized transactions were returned." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Ticker or period format is invalid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Client exceeded the API-key endpoint rate limit." } }, "summary": "Insider transactions" } }, "/v1/ticker/{ticker}/preview": { "get": { "description": "Validates and normalizes a ticker path parameter and reports preview availability.", "parameters": [ { "in": "path", "name": "ticker", "required": true, "schema": { "maxLength": 10, "minLength": 1, "pattern": "^[A-Za-z0-9.-]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TickerPreviewResponse" } } }, "description": "Ticker was accepted and preview metadata was returned." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Ticker format is invalid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Client exceeded the API-key endpoint rate limit." } }, "summary": "Ticker filing data preview" } }, "/v1/watchlist/freshness": { "get": { "description": "Compatibility alias for /v1/freshness. Reports the same bounded enabled watched ticker universe from stored SEC Form 4 ingestion status rows.", "parameters": [ { "in": "query", "name": "freshness_window_hours", "required": false, "schema": { "default": 24, "maximum": 168, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchlistFreshnessResponse" } } }, "description": "Watchlist freshness was computed." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "freshness_window_hours is invalid." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Client exceeded the API-key endpoint rate limit." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Freshness could not be computed from the database." } }, "summary": "Watchlist freshness alias" } } }, "servers": [ { "description": "Hosted API base URL", "url": "https://api.headlessrecords.dev" } ] }