{ "openapi": "3.1.0", "info": { "title": "Arche API", "description": "Reconciled, point-in-time SEC fundamentals.\n\nEvery statement is normalized from the filing it came from and kept immutably: a restatement is the amendment filing, kept as filed beside the original rather than overwriting it, so a query can ask what was known on a given date and get the same answer every time. Values Arche derived are marked as derived, and each one traces back to the filed fact it came from.\n\nAuthenticate with an API key in the `X-Api-Key` header.", "termsOfService": "https://arche.fi/legal/terms", "contact": { "name": "Arche support", "url": "https://arche.fi/contact", "email": "hello@protos.fi" }, "version": "0.1.0" }, "servers": [ { "url": "https://api.arche.fi", "description": "Arche API" } ], "paths": { "/health/z": { "get": { "tags": [ "Health" ], "summary": "Liveness", "description": "Return a fast liveness signal (no external I/O).", "operationId": "health_liveness", "responses": { "200": { "description": "Service is alive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LivenessResponse" } } } } } } }, "/health/readiness": { "get": { "tags": [ "Health" ], "summary": "Readiness", "description": "Return readiness status based on DB/Redis probes.", "operationId": "health_readiness", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } } }, "503": { "description": "Service degraded or down", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" }, "example": { "status": "down", "checks": [ { "name": "db", "status": "down", "detail": "connection refused", "duration_ms": 12.4 }, { "name": "redis", "status": "ok", "duration_ms": 1.4 } ] } } } } } } }, "/v1/system/metadata": { "get": { "tags": [ "System" ], "summary": "Get system metadata.", "description": "Return static API metadata and client limits, including the public HTTP API version and maximum page size.", "operationId": "get_system_metadata", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemMetadataEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "system" } }, "/v1/system/ingestion/status": { "get": { "tags": [ "System" ], "summary": "Get EDGAR feed freshness.", "description": "Return how current each EDGAR feed is: when it last succeeded, how far behind it is, and whether it is stale, so a job can check the corpus is current before it runs.", "operationId": "get_ingestion_status", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestionStatusEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "system" } }, "/v1/metrics/segments": { "get": { "tags": [ "Metrics" ], "summary": "List segment/geography metric disclosures", "description": "Return source disclosure rows classified as SEGMENT or GEOGRAPHY. Deterministic ordering: statement_date DESC NULLS LAST, dimension_type ASC, axis_qname ASC, member_qname ASC, metric_code ASC, period_start ASC, period_end ASC, value ASC, with a fixed tie-break. A value is identified by its company and those fields; a value the filing reports more than once is listed once.", "operationId": "list_segment_metrics", "parameters": [ { "name": "company_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Company identifier (UUID). Provide this or cik.", "examples": [ "11111111-1111-1111-1111-111111111111" ], "title": "Company Id" }, "description": "Company identifier (UUID). Provide this or cik." }, { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SEC Central Index Key. Provide this, company_id, or `ticker`. Send `cik` or `ticker`, not both.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "SEC Central Index Key. Provide this, company_id, or `ticker`. Send `cik` or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company filter by ticker symbol, in place of `cik`.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Company filter by ticker symbol, in place of `cik`." }, { "name": "period", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional statement period end date filter (YYYY-MM-DD).", "examples": [ "2024-09-28" ], "title": "Period" }, "description": "Optional statement period end date filter (YYYY-MM-DD)." }, { "name": "dimension_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/MetricDimensionType" }, { "type": "null" } ], "description": "Optional dimension type filter: SEGMENT or GEOGRAPHY.", "title": "Dimension Type" }, "description": "Optional dimension type filter: SEGMENT or GEOGRAPHY." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1-200).", "default": 50, "title": "Page Size" }, "description": "Page size (1-200)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricDimensionPage" }, "example": { "page": 1, "page_size": 2, "total": 4100, "items": [ { "accession_id": "0000320193-26-000013", "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "statement_type": "INCOME_STATEMENT", "statement_date": "2026-06-27", "fiscal_year": 2026, "fiscal_period": "Q3", "metric_code": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", "canonical_metric_code": "REVENUE", "unit": "USD", "value": "21700000000.000000", "period_start": "2025-09-28", "period_end": "2026-06-27", "dimension_type": "SEGMENT", "axis_qname": "srt:ProductOrServiceAxis", "member_qname": "aapl:IPadMember", "axis_label": "ProductOrServiceAxis", "member_label": "IPadMember", "dimension_key": "srt:ProductOrServiceAxis=aapl:IPadMember" }, { "accession_id": "0000320193-26-000013", "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "statement_type": "INCOME_STATEMENT", "statement_date": "2026-06-27", "fiscal_year": 2026, "fiscal_period": "Q3", "metric_code": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", "canonical_metric_code": "REVENUE", "unit": "USD", "value": "21071000000.000000", "period_start": "2024-09-29", "period_end": "2025-06-28", "dimension_type": "SEGMENT", "axis_qname": "srt:ProductOrServiceAxis", "member_qname": "aapl:IPadMember", "axis_label": "ProductOrServiceAxis", "member_label": "IPadMember", "dimension_key": "srt:ProductOrServiceAxis=aapl:IPadMember" } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/metrics/definitions": { "get": { "tags": [ "Metrics" ], "summary": "List metric definitions", "description": "Return the deterministic public registry of canonical and derived metric definitions. Ordering is metric ASC.", "operationId": "list_metric_definitions", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricDefinitionListEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "read" } }, "/v1/metrics/definitions/{metric}": { "get": { "tags": [ "Metrics" ], "summary": "Get one metric definition", "description": "Return one deterministic metric definition by metric code. Unknown metrics return the canonical ErrorEnvelope.", "operationId": "get_metric_definition", "parameters": [ { "name": "metric", "in": "path", "required": true, "schema": { "type": "string", "title": "Metric" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricDefinitionEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/fundamentals/macro/series": { "get": { "tags": [ "Fundamentals" ], "summary": "Approved macro series registry", "description": "Return the explicit approved macro context registry. Arche does not expose a generic FRED series explorer; only registered series are returned.", "operationId": "list_macro_series", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacroSeriesDefinitionListEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "read" } }, "/v1/fundamentals/macro/series/{series_code}": { "get": { "tags": [ "Fundamentals" ], "summary": "Approved macro series observations", "description": "Return deterministic observations for one approved macro series. Arbitrary user-supplied FRED series codes are not supported.", "operationId": "get_macro_series", "parameters": [ { "name": "series_code", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/MacroSeriesCode" } }, { "name": "from_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Inclusive start date for the observation window.", "title": "From Date" }, "description": "Inclusive start date for the observation window." }, { "name": "to_date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Inclusive end date for the observation window.", "title": "To Date" }, "description": "Inclusive end date for the observation window." }, { "name": "as_of_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional as-of date for PIT historical values.", "title": "As Of Date" }, "description": "Optional as-of date for PIT historical values." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacroSeriesEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/fundamentals/macro/context/{target_date}": { "get": { "tags": [ "Fundamentals" ], "summary": "Macro context for a date", "description": "Return a compact government macro context snapshot for a target date. This surface is contextual only and does not turn Arche into a macro platform.", "operationId": "get_macro_context", "parameters": [ { "name": "target_date", "in": "path", "required": true, "schema": { "type": "string", "format": "date", "title": "Target Date" } }, { "name": "as_of_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional as-of date for PIT historical values.", "title": "As Of Date" }, "description": "Optional as-of date for PIT historical values." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacroContextEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/filings": { "get": { "tags": [ "Filings" ], "summary": "List EDGAR filings for a company", "description": "Returns a paginated list of normalized EDGAR filing headers for the given CIK. Supports optional filtering by filing type and filing date window.\n\nDeterministic ordering: latest filings first (filing_date desc, accession_id desc), with a fixed tie-break.", "operationId": "list_filings", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "filing_types", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/FilingType" } }, { "type": "null" } ], "description": "Optional list of filing types to include (e.g., 10-K,10-Q). If omitted, all supported filing types are considered.", "examples": [ [ "10-K", "10-Q" ] ], "title": "Filing Types" }, "description": "Optional list of filing types to include (e.g., 10-K,10-Q). If omitted, all supported filing types are considered." }, { "name": "from_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional lower bound on filing_date (inclusive, YYYY-MM-DD).", "examples": [ "2023-01-01" ], "title": "From Date" }, "description": "Optional lower bound on filing_date (inclusive, YYYY-MM-DD)." }, { "name": "to_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional upper bound on filing_date (inclusive, YYYY-MM-DD).", "examples": [ "2024-12-31" ], "title": "To Date" }, "description": "Optional upper bound on filing_date (inclusive, YYYY-MM-DD)." }, { "name": "include_amendments", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to include amended forms (e.g., 10-K/A).", "default": true, "title": "Include Amendments" }, "description": "Whether to include amended forms (e.g., 10-K/A)." }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "1-indexed page number.", "title": "Page" }, "description": "1-indexed page number." }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Items per page (bounded).", "title": "Page Size" }, "description": "Items per page (bounded)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Deprecated alias.", "title": "Per Page" }, "description": "Deprecated alias." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarFilingPage" }, "example": { "page": 1, "page_size": 2, "total": 372, "items": [ { "accession_id": "0001140361-26-035325", "cik": "0000320193", "company_name": "Apple Inc.", "filing_type": "8-K", "filing_date": "2026-09-01", "period_end_date": "2026-04-17", "is_amendment": true, "amendment_sequence": 1, "primary_document": "ef20081427_8ka.htm", "accepted_at": "2026-09-01T20:30:35Z" }, { "accession_id": "0000320193-26-000020", "cik": "0000320193", "company_name": "Apple Inc.", "filing_type": "10-Q", "filing_date": "2026-07-31", "period_end_date": "2026-06-27", "is_amendment": false, "primary_document": "aapl-20260627.htm", "accepted_at": "2026-07-31T10:01:02Z" } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/filings/{accession_id}": { "get": { "tags": [ "Filings" ], "summary": "Get EDGAR filing detail", "description": "Return normalized EDGAR filing metadata for a specific filing. Future versions may include normalized statement and long-form payloads.", "operationId": "get_filing", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "accession_id", "in": "path", "required": true, "schema": { "type": "string", "description": "EDGAR accession ID (e.g., 0000320193-24-000012).", "examples": [ "0000320193-24-000012" ], "title": "Accession Id" }, "description": "EDGAR accession ID (e.g., 0000320193-24-000012)." }, { "name": "include_statements", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Reserved for future use; currently ignored.", "default": true, "title": "Include Statements" }, "description": "Reserved for future use; currently ignored." }, { "name": "include_long_form", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Reserved for future normalized long-form payload; currently ignored.", "default": false, "title": "Include Long Form" }, "description": "Reserved for future normalized long-form payload; currently ignored." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarFilingEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}": { "get": { "tags": [ "Companies" ], "summary": "Get canonical EDGAR company profile", "description": "Return a canonical SEC/EDGAR company profile for a CIK with provenance metadata. The response is strictly EDGAR-derived and does not include enrichment.", "operationId": "get_company", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarCompanyProfileEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Company profile not found.", "content": { "application/json": { "examples": { "company_not_found": { "summary": "Unknown CIK", "value": { "error": { "code": "COMPANY_NOT_FOUND", "http_status": 404, "message": "Company profile not found.", "details": { "cik": "0000000000" }, "trace_id": "req-123" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies:resolve": { "get": { "tags": [ "Companies" ], "summary": "Resolve canonical CIK by ticker", "description": "Resolve a canonical CIK from ticker at a point-in-time date. Returns 409 with deterministic bounded candidates when ambiguous.", "operationId": "resolve_company", "parameters": [ { "name": "ticker", "in": "query", "required": true, "schema": { "type": "string", "description": "Ticker symbol (A-Z, length 1-10).", "examples": [ "MSFT" ], "title": "Ticker" }, "description": "Ticker symbol (A-Z, length 1-10)." }, { "name": "as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Point-in-time date (YYYY-MM-DD). Defaults to current UTC date.", "examples": [ "2026-03-01" ], "title": "As Of" }, "description": "Point-in-time date (YYYY-MM-DD). Defaults to current UTC date." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarCompanyResolveEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Ticker mapping not found.", "content": { "application/json": { "examples": { "ticker_not_found": { "summary": "Unknown ticker", "value": { "error": { "code": "TICKER_NOT_FOUND", "http_status": 404, "message": "No ticker mapping found.", "details": { "ticker": "MSFT", "as_of": "2026-03-01" }, "trace_id": "req-123" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Ticker resolution is ambiguous.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Multiple matching CIKs", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker maps to multiple CIKs.", "details": { "ticker": "ABC", "as_of": "2026-03-01", "candidate_count": 2, "candidates": [ { "cik": "0000000001", "entity_name": "ABC HOLDINGS INC", "ticker": "ABC", "exchange": "XNYS", "effective_from": "2020-01-01" }, { "cik": "0000000002", "entity_name": "ABC BIOTECH LTD", "ticker": "ABC", "exchange": "XNAS", "effective_from": "2021-05-01" } ] }, "trace_id": "req-123" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/completeness": { "get": { "tags": [ "Coverage" ], "summary": "Get EDGAR completeness summary for a company", "description": "Return a minimal completeness summary for a company, including the latest filing identifiers and how many statements each statement type has.\n\nDeterministic ordering: latest filing by filing date desc, with a fixed tie-break; statement types sorted asc.", "operationId": "get_company_completeness", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarCompanyCompletenessEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/statements": { "get": { "tags": [ "Statements" ], "summary": "List EDGAR statements for a company", "description": "Returns a paginated list of normalized statements (income, balance sheet, cash flow) for a company over a date range.\n\nBy default each statement date returns the one statement that serves it. With `include_restated=true` each date returns one row per SEC filing that reported it (an original and its amendments), each the filing's current figures.\n\nDeterministic ordering: statement_date desc, then the later-accepted filing first, with a stable tie-break so pages never overlap.", "operationId": "list_statements", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "type": "string", "description": "Statement type filter (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "examples": [ "INCOME_STATEMENT" ], "title": "Statement Type" }, "description": "Statement type filter (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "from_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional lower bound on statement_date (inclusive, YYYY-MM-DD).", "title": "From Date" }, "description": "Optional lower bound on statement_date (inclusive, YYYY-MM-DD)." }, { "name": "to_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional upper bound on statement_date (inclusive, YYYY-MM-DD).", "title": "To Date" }, "description": "Optional upper bound on statement_date (inclusive, YYYY-MM-DD)." }, { "name": "include_restated", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to list every filing that reported each statement date, one row per filing, rather than only the statement serving the date (default: false).", "default": false, "title": "Include Restated" }, "description": "Whether to list every filing that reported each statement date, one row per filing, rather than only the statement serving the date (default: false)." }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When false (the default), each statement carries its figures as values and units, one entry per metric. When true, each statement also carries content (its facts with their dimensions, periods and per-metric provenance) and its quality block.", "default": false, "title": "Detail" }, "description": "When false (the default), each statement carries its figures as values and units, one entry per metric. When true, each statement also carries content (its facts with their dimensions, periods and per-metric provenance) and its quality block." }, { "name": "include_usd", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, each fact also carries usd: its value in US dollars, with the rate, the rate's dates and its source. A value over a period (income and cash-flow statements) converts at the average of the Federal Reserve Board's H.10 daily rates over that period; a balance-sheet value at the rate on its date. value stays as filed. Default false.", "default": false, "title": "Include Usd" }, "description": "When true, each fact also carries usd: its value in US dollars, with the rate, the rate's dates and its source. A value over a period (income and cash-flow statements) converts at the average of the Federal Reserve Board's H.10 daily rates over that period; a balance-sheet value at the rate on its date. value stays as filed. Default false." }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "1-indexed page number.", "title": "Page" }, "description": "1-indexed page number." }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Items per page (bounded).", "title": "Page Size" }, "description": "Items per page (bounded)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Deprecated alias.", "title": "Per Page" }, "description": "Deprecated alias." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarStatementPage" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/filings/{accession_id}/statements": { "get": { "tags": [ "Statements" ], "summary": "Get the statements a filing reported", "description": "Return the statements (income, balance sheet, cash flow) a specific EDGAR filing reported: one row per statement type and statement date, carrying the filing's current figures. A statement a later filing restated is still returned here, because this filing reported it.", "operationId": "list_filing_statements", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "accession_id", "in": "path", "required": true, "schema": { "type": "string", "description": "EDGAR accession ID (e.g., 0000320193-24-000012).", "examples": [ "0000320193-24-000012" ], "title": "Accession Id" }, "description": "EDGAR accession ID (e.g., 0000320193-24-000012)." }, { "name": "statement_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/StatementType" }, { "type": "null" } ], "description": "Optional statement type filter (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "title": "Statement Type" }, "description": "Optional statement type filter (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When false (the default), each statement carries its figures as values and units, one entry per metric. When true, each statement also carries content (its facts with their dimensions, periods and per-metric provenance) and its quality block.", "default": false, "title": "Detail" }, "description": "When false (the default), each statement carries its figures as values and units, one entry per metric. When true, each statement also carries content (its facts with their dimensions, periods and per-metric provenance) and its quality block." }, { "name": "include_usd", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, each fact also carries usd: its value in US dollars, with the rate, the rate's dates and its source. A value over a period (income and cash-flow statements) converts at the average of the Federal Reserve Board's H.10 daily rates over that period; a balance-sheet value at the rate on its date. value stays as filed. Default false.", "default": false, "title": "Include Usd" }, "description": "When true, each fact also carries usd: its value in US dollars, with the rate, the rate's dates and its source. A value over a period (income and cash-flow statements) converts at the average of the Federal Reserve Board's H.10 daily rates over that period; a balance-sheet value at the rate on its date. value stays as filed. Default false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarStatementListEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/statements/restatement-timeline": { "get": { "tags": [ "Statements" ], "summary": "Get restatement metric timeline for a statement identity", "description": "Return the restatement timeline and per-metric deltas for a specific statement identity across the SEC filings that reported it, in acceptance order. Each filing counts once, as its current figures.\n\nA period the filer has reported once has never been restated, and is answered with an empty timeline: `total_hops` is 0, `by_metric` is empty and `timeline_severity` is `NONE`. That is a complete answer rather than missing data, and it is also what a period with two filings that differ in no metric returns.\n\nA statement identity no filing reported is answered with 404 `EDGAR_STATEMENTS_NOT_FOUND`.\n\nOne fiscal identity can hold several period ends, because a quarter is sometimes labelled FY. A timeline covers the revisions of a single period: the one the statement routes return. A fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, each with its own timeline; `statement_date` names the one to return, and without it the later period's is returned.\n\nA later filing can repeat an earlier filing's figures unchanged. Each run of such filings counts as one hop, ending on its latest filing, unless `include_unchanged_filings=true`.", "operationId": "get_restatement_timeline", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "type": "string", "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "examples": [ "INCOME_STATEMENT" ], "title": "Statement Type" }, "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year for the statement identity.", "title": "Fiscal Year" }, "description": "Fiscal year for the statement identity." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "type": "string", "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4).", "examples": [ "FY" ], "title": "Fiscal Period" }, "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4)." }, { "name": "include_unchanged_filings", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include hops where a later filing repeated the earlier filing's figures. By default each run of filings with identical figures is reduced to its latest filing, so every hop reflects a change in reported figures.", "default": false, "title": "Include Unchanged Filings" }, "description": "Include hops where a later filing repeated the earlier filing's figures. By default each run of filings with identical figures is reduced to its latest filing, so every hop reflects a change in reported figures." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestatementMetricTimelineEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/filings/{accession_id}/statements/{statement_type}/{fiscal_year}/{fiscal_period}/fact-revisions": { "get": { "tags": [ "Statements" ], "summary": "Get the fact revision ledger of a filing's statement", "description": "Return the immutable fact revision events one filing's statement recorded against the earlier filing it revised. The statement is named by company, accession, statement type, fiscal year and fiscal period, and by statement_date when the filing reports two OTHER periods in the year. An unknown filing or statement identity is answered with 404 `EDGAR_STATEMENTS_NOT_FOUND`.", "operationId": "list_fact_revisions", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "accession_id", "in": "path", "required": true, "schema": { "type": "string", "description": "EDGAR accession ID of the filing that reported the statement (e.g., 0000320193-24-000123).", "examples": [ "0000320193-24-000123" ], "title": "Accession Id" }, "description": "EDGAR accession ID of the filing that reported the statement (e.g., 0000320193-24-000123)." }, { "name": "statement_type", "in": "path", "required": true, "schema": { "type": "string", "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "examples": [ "INCOME_STATEMENT" ], "title": "Statement Type" }, "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "fiscal_year", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year of the statement.", "examples": [ 2024 ], "title": "Fiscal Year" }, "description": "Fiscal year of the statement." }, { "name": "fiscal_period", "in": "path", "required": true, "schema": { "type": "string", "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4).", "examples": [ "FY" ], "title": "Fiscal Period" }, "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4)." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactRevisionLedgerEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/filings/{accession_id}/statements/{statement_type}/{fiscal_year}/{fiscal_period}/metrics/{metric_name}/audit-chain": { "get": { "tags": [ "Statements" ], "summary": "Get the metric audit chain of a filing's statement", "description": "Return the filing, XBRL concept and mapping behind one metric of one filing's statement, and every override applied to it in order. The statement is named by company, accession, statement type, fiscal year and fiscal period, and by statement_date when the filing reports two OTHER periods in the year. An unknown filing, statement identity or metric is answered with 404 `EDGAR_STATEMENTS_NOT_FOUND`.", "operationId": "get_metric_audit_chain", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "accession_id", "in": "path", "required": true, "schema": { "type": "string", "description": "EDGAR accession ID of the filing that reported the statement (e.g., 0000320193-24-000123).", "examples": [ "0000320193-24-000123" ], "title": "Accession Id" }, "description": "EDGAR accession ID of the filing that reported the statement (e.g., 0000320193-24-000123)." }, { "name": "statement_type", "in": "path", "required": true, "schema": { "type": "string", "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "examples": [ "BALANCE_SHEET" ], "title": "Statement Type" }, "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "fiscal_year", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year of the statement.", "examples": [ 2024 ], "title": "Fiscal Year" }, "description": "Fiscal year of the statement." }, { "name": "fiscal_period", "in": "path", "required": true, "schema": { "type": "string", "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4).", "examples": [ "FY" ], "title": "Fiscal Period" }, "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4)." }, { "name": "metric_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Canonical metric name (e.g., TOTAL_ASSETS).", "examples": [ "TOTAL_ASSETS" ], "title": "Metric Name" }, "description": "Canonical metric name (e.g., TOTAL_ASSETS)." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementMetricAuditChainEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/filings/{accession_id}/statements/{statement_type}/{fiscal_year}/{fiscal_period}/metrics/{metric_name}/provenance": { "get": { "tags": [ "Statements" ], "summary": "Get simplified metric provenance for a filing's statement", "description": "Return the simplified public provenance drill-down for one metric of one filing's statement. The statement is named by company, accession, statement type, fiscal year and fiscal period, and by statement_date when the filing reports two OTHER periods in the year. It reports only the provenance recorded for the statement, never an inferred one. An unknown filing, statement identity or metric is answered with 404 `EDGAR_STATEMENTS_NOT_FOUND`.", "operationId": "get_metric_provenance", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "accession_id", "in": "path", "required": true, "schema": { "type": "string", "description": "EDGAR accession ID of the filing that reported the statement (e.g., 0000320193-24-000123).", "examples": [ "0000320193-24-000123" ], "title": "Accession Id" }, "description": "EDGAR accession ID of the filing that reported the statement (e.g., 0000320193-24-000123)." }, { "name": "statement_type", "in": "path", "required": true, "schema": { "type": "string", "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "examples": [ "INCOME_STATEMENT" ], "title": "Statement Type" }, "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "fiscal_year", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year of the statement.", "examples": [ 2024 ], "title": "Fiscal Year" }, "description": "Fiscal year of the statement." }, { "name": "fiscal_period", "in": "path", "required": true, "schema": { "type": "string", "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4).", "examples": [ "FY" ], "title": "Fiscal Period" }, "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4)." }, { "name": "metric_name", "in": "path", "required": true, "schema": { "type": "string", "description": "Canonical metric name (e.g., TOTAL_ASSETS).", "examples": [ "REVENUE" ], "title": "Metric Name" }, "description": "Canonical metric name (e.g., TOTAL_ASSETS)." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementMetricPublicProvenanceEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/disclosures": { "get": { "tags": [ "Filings" ], "summary": "List a company's narrative disclosures", "description": "Returns a paginated list of the narrative disclosures a company has filed: accounting policies, segment descriptions, debt terms, contingencies and the other text blocks that accompany the statements.\n\nDisclosure text is not included here. A single filing can carry hundreds of kilobytes across its text blocks, so a listing returns each disclosure's identity and `char_count`, and the text is read one disclosure at a time from `/v1/edgar/disclosures/{disclosure_id}`.\n\nDeterministic ordering: period_of_report desc, then concept, with a tie-break on the disclosure identifier.\n\nA company with no extracted disclosures returns an empty page rather than an error.", "operationId": "list_disclosures", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "period_of_report", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional exact period the filing reports on (YYYY-MM-DD).", "title": "Period Of Report" }, "description": "Optional exact period the filing reports on (YYYY-MM-DD)." }, { "name": "accession_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional accession to restrict the listing to.", "title": "Accession Id" }, "description": "Optional accession to restrict the listing to." }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "1-indexed page number.", "title": "Page" }, "description": "1-indexed page number." }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Items per page (bounded).", "title": "Page Size" }, "description": "Items per page (bounded)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Deprecated alias.", "title": "Per Page" }, "description": "Deprecated alias." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarFilingDisclosureSummaryPage" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/disclosures/{disclosure_id}": { "get": { "tags": [ "Filings" ], "summary": "Read one narrative disclosure", "description": "Returns a single disclosure and its narrative text. The filer's markup is stripped before storage, so `disclosure_text` is plain text.\n\nIdentifiers come from `/v1/edgar/companies/{cik}/disclosures`. An unknown identifier answers 404 `EDGAR_DISCLOSURE_NOT_FOUND`.", "operationId": "get_disclosure", "parameters": [ { "name": "disclosure_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Disclosure identifier from the company listing.", "examples": [ "6d9f1b0e-6c1a-4a1f-9a3c-2f9a1c7d5e10" ], "title": "Disclosure Id" }, "description": "Disclosure identifier from the company listing." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarFilingDisclosureEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/facts/concepts": { "get": { "tags": [ "Filings" ], "summary": "List every XBRL concept a company reported", "description": "Returns each XBRL concept the company has reported, with the taxonomy's label and definition, the units used, how many values were reported and the span of periods they cover. Use it to find the concept to read from `/v1/edgar/companies/{cik}/facts`.\n\nValues come from SEC's XBRL company facts, exactly as each filing reported them: every concept in the us-gaap, ifrs-full, dei, srt and invest taxonomies, undimensioned (consolidated) values only. Filer-specific extension concepts and dimensional breakdowns are not included. A company's facts are refreshed from SEC at most a day after its latest filing appears there.\n\nDeterministic ordering: concept ascending; a qualified concept is unique, so it is its own tie-break.\n\nA company with no XBRL facts returns an empty page rather than an error.", "operationId": "list_as_reported_concepts", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "taxonomy", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional taxonomy to keep: us-gaap, ifrs-full, dei, srt or invest.", "examples": [ "us-gaap" ], "title": "Taxonomy" }, "description": "Optional taxonomy to keep: us-gaap, ifrs-full, dei, srt or invest." }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional text the concept name or label must contain, ignoring case.", "examples": [ "research" ], "title": "Search" }, "description": "Optional text the concept name or label must contain, ignoring case." }, { "name": "as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional point in time (YYYY-MM-DD): only values filed on or before this date are counted, so a backtest sees what was public then.", "title": "As Of" }, "description": "Optional point in time (YYYY-MM-DD): only values filed on or before this date are counted, so a backtest sees what was public then." }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "1-indexed page number.", "title": "Page" }, "description": "1-indexed page number." }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Items per page (bounded).", "title": "Page Size" }, "description": "Items per page (bounded)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Deprecated alias.", "title": "Per Page" }, "description": "Deprecated alias." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsReportedConceptPage" }, "example": { "page": 1, "page_size": 1, "total": 505, "items": [ { "concept": "us-gaap:ResearchAndDevelopmentExpense", "taxonomy": "us-gaap", "label": "Research and Development Expense", "description": "The aggregate costs incurred (1) in a planned search or critical investigation aimed at discovery of new knowledge ...", "units": [ "USD" ], "fact_count": 234, "first_period_end": "2007-09-29", "last_period_end": "2026-06-27" } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/facts": { "get": { "tags": [ "Filings" ], "summary": "List the values a company reported in XBRL", "description": "Returns the values the company reported under any XBRL concept, not only the canonical statement metrics: each with its unit, period, and the filing that reported it. A value restated by a later filing appears once for each filing that reported it.\n\nValues come from SEC's XBRL company facts, exactly as each filing reported them: every concept in the us-gaap, ifrs-full, dei, srt and invest taxonomies, undimensioned (consolidated) values only. Filer-specific extension concepts and dimensional breakdowns are not included. A company's facts are refreshed from SEC at most a day after its latest filing appears there.\n\nNarrow by `concepts` (qualified, such as `us-gaap:Revenues`, or a bare name matching any taxonomy), `units`, `filing_types`, the period end and `as_of`.\n\nDeterministic ordering: concept, unit, then newest period end, newest period start and newest filing date, with the accession as the tie-break.\n\nA company with no XBRL facts returns an empty page rather than an error.", "operationId": "list_as_reported_facts", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "concepts", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Optional concepts to keep, qualified (us-gaap:Revenues) or bare (Revenues, matching any taxonomy); case is ignored.", "examples": [ [ "us-gaap:ResearchAndDevelopmentExpense" ] ], "title": "Concepts" }, "description": "Optional concepts to keep, qualified (us-gaap:Revenues) or bare (Revenues, matching any taxonomy); case is ignored." }, { "name": "units", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Optional units to keep, e.g. USD or shares.", "examples": [ [ "USD" ] ], "title": "Units" }, "description": "Optional units to keep, e.g. USD or shares." }, { "name": "filing_types", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Optional forms of the reporting filing to keep, e.g. 10-K or 10-Q.", "examples": [ [ "10-K" ] ], "title": "Filing Types" }, "description": "Optional forms of the reporting filing to keep, e.g. 10-K or 10-Q." }, { "name": "period_end_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional lower bound on period_end (inclusive, YYYY-MM-DD).", "title": "Period End From" }, "description": "Optional lower bound on period_end (inclusive, YYYY-MM-DD)." }, { "name": "period_end_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional upper bound on period_end (inclusive, YYYY-MM-DD).", "title": "Period End To" }, "description": "Optional upper bound on period_end (inclusive, YYYY-MM-DD)." }, { "name": "as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional point in time (YYYY-MM-DD): only values filed on or before this date are counted, so a backtest sees what was public then.", "title": "As Of" }, "description": "Optional point in time (YYYY-MM-DD): only values filed on or before this date are counted, so a backtest sees what was public then." }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "1-indexed page number.", "title": "Page" }, "description": "1-indexed page number." }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Items per page (bounded).", "title": "Page Size" }, "description": "Items per page (bounded)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Deprecated alias.", "title": "Per Page" }, "description": "Deprecated alias." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsReportedFactPage" }, "example": { "page": 1, "page_size": 1, "total": 51, "items": [ { "concept": "us-gaap:ResearchAndDevelopmentExpense", "unit": "USD", "value": "34550000000", "period_start": "2024-09-29", "period_end": "2025-09-27", "accession_id": "0000320193-25-000079", "filing_type": "10-K", "filing_date": "2025-10-31", "fiscal_year": 2025, "fiscal_period": "FY", "frame": "CY2025" } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/filings/{accession_id}/facts": { "get": { "tags": [ "Filings" ], "summary": "List every numeric fact in a filing's XBRL", "description": "Returns every numeric value the filing tagged in XBRL, exactly as filed: the standard taxonomies' concepts and the filer's own extension concepts (such as `aapl:...`), consolidated values and every value broken out by an axis -- segment, product or service, geography and the rest -- with the axis and member in `dimensions`. These are the filer's tags as filed; they are not normalized or compared across companies.\n\nNarrow by `concepts` (qualified, or bare to match any prefix), `taxonomies` (concept prefixes such as `us-gaap` or `aapl`), `axes`, and `dimensioned` (`false` for consolidated values only).\n\nDeterministic ordering: concept, unit, consolidated before dimensional, then axis and member, newest period end and newest period start, with the value as the tie-break.\n\nThe first read of a filing fetches it from SEC and can take a few seconds; later reads are served from storage. A filing without XBRL returns an empty page; a filing Arche does not hold for the company answers `404`.", "operationId": "list_filing_facts", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "accession_id", "in": "path", "required": true, "schema": { "type": "string", "description": "EDGAR accession of the filing.", "examples": [ "0000320193-25-000079" ], "title": "Accession Id" }, "description": "EDGAR accession of the filing." }, { "name": "concepts", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Optional concepts to keep, qualified (us-gaap:Revenues) or bare (Revenues, matching any prefix); case is ignored.", "examples": [ [ "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax" ] ], "title": "Concepts" }, "description": "Optional concepts to keep, qualified (us-gaap:Revenues) or bare (Revenues, matching any prefix); case is ignored." }, { "name": "taxonomies", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Optional concept prefixes to keep, e.g. us-gaap or the filer's own.", "examples": [ [ "aapl" ] ], "title": "Taxonomies" }, "description": "Optional concept prefixes to keep, e.g. us-gaap or the filer's own." }, { "name": "axes", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Optional axes: keep only values broken out by at least one of them.", "examples": [ [ "srt:ProductOrServiceAxis" ] ], "title": "Axes" }, "description": "Optional axes: keep only values broken out by at least one of them." }, { "name": "dimensioned", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Optional: false keeps only consolidated values, true only values broken out by an axis.", "title": "Dimensioned" }, "description": "Optional: false keeps only consolidated values, true only values broken out by an axis." }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "1-indexed page number.", "title": "Page" }, "description": "1-indexed page number." }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Items per page (bounded).", "title": "Page Size" }, "description": "Items per page (bounded)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Deprecated alias.", "title": "Per Page" }, "description": "Deprecated alias." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingFactPage" }, "example": { "page": 1, "page_size": 1, "total": 4, "items": [ { "concept": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", "unit": "USD", "value": "209586000000", "decimals": -6, "period_start": "2024-09-29", "period_end": "2025-09-27", "dimensions": [ { "axis": "srt:ProductOrServiceAxis", "member": "aapl:IPhoneMember" } ] } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/as-of/{date}/financials/{cik}": { "get": { "tags": [ "Statements" ], "summary": "Get EDGAR financials as-of a date or time", "description": "Return normalized EDGAR financial statements as known at a date or an exact time.\n\nEach statement carries its figures as values, one decimal string per metric code for the statement's own period and consolidated entity, with units beside them. detail=true adds each statement's facts, per-metric provenance and quality block, and the snapshot's reconciliation and data-quality summaries in _meta.\n\nA date (YYYY-MM-DD) includes every filing the SEC dated on or before it. EDGAR dates a filing accepted after 5:30 pm Eastern the next business day, so a filing made after the close is not known on the day it was accepted.\n\nA timestamp with an offset (for example 2023-11-02T16:00:00-04:00) includes every filing the SEC accepted at or before that instant.\n\nDeterministic ordering for statements: statement_type, accounting_standard, statement_date, fiscal_year, fiscal_period, currency, is_restated, accession_id.\n\nThis route returns every statement of the selection. To return only some, by statement type, fiscal year range or fiscal period, with a limit, use GET /v1/edgar/as-of/{date}/financials/{cik}/page.", "operationId": "get_as_of_financials", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "date", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ], "description": "A date (YYYY-MM-DD), which includes filings the SEC dated on or before it, or a timestamp with an offset, which includes filings the SEC accepted at or before it.", "examples": [ "2024-03-31", "2023-11-02T16:00:00-04:00" ], "title": "Date" }, "description": "A date (YYYY-MM-DD), which includes filings the SEC dated on or before it, or a timestamp with an offset, which includes filings the SEC accepted at or before it." }, { "name": "audit_mode", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, a period with a restated statement also returns the statement as first reported, so the two can be compared. Default false returns one statement per period.", "default": false, "title": "Audit Mode" }, "description": "When true, a period with a restated statement also returns the statement as first reported, so the two can be compared. Default false returns one statement per period." }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When false (the default), each statement carries its figures as values and units, one entry per metric. When true, each statement also carries content (its facts with their dimensions, periods and per-metric provenance) and its quality block. The snapshot's _meta reconciliation and data-quality summaries are returned only when true.", "default": false, "title": "Detail" }, "description": "When false (the default), each statement carries its figures as values and units, one entry per metric. When true, each statement also carries content (its facts with their dimensions, periods and per-metric provenance) and its quality block. The snapshot's _meta reconciliation and data-quality summaries are returned only when true." }, { "name": "include_usd", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, each fact also carries usd: its value in US dollars, with the rate, the rate's dates and its source. A value over a period (income and cash-flow statements) converts at the average of the Federal Reserve Board's H.10 daily rates over that period; a balance-sheet value at the rate on its date. value stays as filed. Default false.", "default": false, "title": "Include Usd" }, "description": "When true, each fact also carries usd: its value in US dollars, with the rate, the rate's dates and its source. A value over a period (income and cash-flow statements) converts at the average of the Federal Reserve Board's H.10 daily rates over that period; a balance-sheet value at the rate on its date. value stays as filed. Default false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarFinancialsAsOfEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "snapshot" } }, "/v1/edgar/as-of/{date}/financials/{cik}/page": { "get": { "tags": [ "Statements" ], "summary": "Get one page of EDGAR financials as-of a date or time", "description": "Return one page of a company's normalized EDGAR statements as known at a date or an exact time, selected by statement type, fiscal year and fiscal period.\n\nThe as-of rule and the ordering are those of GET /v1/edgar/as-of/{date}/financials/{cik}, and so is snapshot_hash: it identifies the full as-of selection whatever the filters or page. snapshot_statement_count, matched_count and selected_count give the size of the selection, of the statements matching the filters, and of what is paged; read the next page with offset.\n\nEach statement carries its identity, its filing and its figures as values and units, one entry per metric code. detail=true adds its facts, per-metric provenance and quality block; a fact's correction and split-adjustment fields, and a metric's override fields, are present only when they apply. _meta is null: the snapshot's reconciliation and data-quality summaries cover the full selection, which the full route returns.", "operationId": "get_as_of_financials_page", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "date", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ], "description": "A date (YYYY-MM-DD), which includes filings the SEC dated on or before it, or a timestamp with an offset, which includes filings the SEC accepted at or before it.", "examples": [ "2024-03-31", "2023-11-02T16:00:00-04:00" ], "title": "Date" }, "description": "A date (YYYY-MM-DD), which includes filings the SEC dated on or before it, or a timestamp with an offset, which includes filings the SEC accepted at or before it." }, { "name": "limit", "in": "query", "required": true, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Statements per page (1-50).", "title": "Limit" }, "description": "Statements per page (1-50)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Statements of the filtered selection to skip.", "default": 0, "title": "Offset" }, "description": "Statements of the filtered selection to skip." }, { "name": "statement_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/StatementType" }, { "type": "null" } ], "description": "Return only statements of this type.", "title": "Statement Type" }, "description": "Return only statements of this type." }, { "name": "fiscal_year_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 2100, "minimum": 1900 }, { "type": "null" } ], "description": "Return only statements with fiscal_year at or after this year.", "title": "Fiscal Year From" }, "description": "Return only statements with fiscal_year at or after this year." }, { "name": "fiscal_year_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 2100, "minimum": 1900 }, { "type": "null" } ], "description": "Return only statements with fiscal_year at or before this year.", "title": "Fiscal Year To" }, "description": "Return only statements with fiscal_year at or before this year." }, { "name": "fiscal_period", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/FiscalPeriod" }, { "type": "null" } ], "description": "Return only statements for this fiscal period (FY for annual).", "title": "Fiscal Period" }, "description": "Return only statements for this fiscal period (FY for annual)." }, { "name": "latest_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, keep only the most recent statement of each statement type within the filters.", "default": false, "title": "Latest Only" }, "description": "When true, keep only the most recent statement of each statement type within the filters." }, { "name": "audit_mode", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, a period with a restated statement also returns the statement as first reported, so the two can be compared. Default false returns one statement per period.", "default": false, "title": "Audit Mode" }, "description": "When true, a period with a restated statement also returns the statement as first reported, so the two can be compared. Default false returns one statement per period." }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When false (the default), each statement carries its figures as values and units, one entry per metric. When true, each statement also carries content (its facts with their dimensions, periods and per-metric provenance) and its quality block.", "default": false, "title": "Detail" }, "description": "When false (the default), each statement carries its figures as values and units, one entry per metric. When true, each statement also carries content (its facts with their dimensions, periods and per-metric provenance) and its quality block." }, { "name": "include_usd", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, each fact also carries usd: its value in US dollars, with the rate, the rate's dates and its source. A value over a period (income and cash-flow statements) converts at the average of the Federal Reserve Board's H.10 daily rates over that period; a balance-sheet value at the rate on its date. value stays as filed. Default false.", "default": false, "title": "Include Usd" }, "description": "When true, each fact also carries usd: its value in US dollars, with the rate, the rate's dates and its source. A value over a period (income and cash-flow statements) converts at the average of the Federal Reserve Board's H.10 daily rates over that period; a balance-sheet value at the rate on its date. value stays as filed. Default false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarFinancialsAsOfPageEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "snapshot" } }, "/v1/edgar/statements/restatements/delta": { "get": { "tags": [ "Statements" ], "summary": "Get restatement delta between two filings", "description": "Compare two filings that report one statement and return the per-metric changes between them (old, new and diff for each canonical metric that changed).\n\nName the two filings with `from_accession` and `to_accession`, the SEC accession numbers of the filings. Each resolves to the statement that filing reports.\n\nWith neither, the earliest-accepted filing for the period is compared with the latest one: the net change from first report to now. A period that was never restated returns no deltas, with both ends naming the same filing. This default moves when a new amendment is filed; pass accessions for a result that stays fixed.\n\nOnly metrics both filings carry are diffed. Metrics only one filing carries are listed in `metrics_only_in_from` and `metrics_only_in_to`, and `comparability_warning` is true when either list is not empty.\n\nGiving only one side of the pair returns 400. The `from` filing must have been accepted by the SEC before the `to` filing. An accession that reports no statement for this cik, statement type and period returns 404, listing the accessions the period does have. `from_version` and `to_version` in the response name the filings that were compared.", "operationId": "get_restatement_delta", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "type": "string", "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "examples": [ "INCOME_STATEMENT" ], "title": "Statement Type" }, "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year for the statement identity.", "title": "Fiscal Year" }, "description": "Fiscal year for the statement identity." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "type": "string", "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4).", "examples": [ "FY" ], "title": "Fiscal Period" }, "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4)." }, { "name": "from_accession", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SEC accession of the filing to compare from, resolved to the statement that filing reports. Give together with to_accession. Omit both accessions to compare the earliest-accepted filing with the latest; that default moves when a new amendment is filed, so pass accessions for a fixed result.", "examples": [ "0001069183-25-000019" ], "title": "From Accession" }, "description": "SEC accession of the filing to compare from, resolved to the statement that filing reports. Give together with to_accession. Omit both accessions to compare the earliest-accepted filing with the latest; that default moves when a new amendment is filed, so pass accessions for a fixed result." }, { "name": "to_accession", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SEC accession of the filing to compare to, resolved to the statement that filing reports. Give together with from_accession. Omit both accessions to compare the earliest-accepted filing with the latest; that default moves when a new amendment is filed, so pass accessions for a fixed result.", "examples": [ "0001069183-25-000075" ], "title": "To Accession" }, "description": "SEC accession of the filing to compare to, resolved to the statement that filing reports. Give together with from_accession. Omit both accessions to compare the earliest-accepted filing with the latest; that default moves when a new amendment is filed, so pass accessions for a fixed result." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestatementDeltaSuccessEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/statements/restatements/ledger": { "get": { "tags": [ "Statements" ], "summary": "Get restatement ledger for a statement identity", "description": "Return the restatement ledger for a given (cik, statement_type, fiscal_year, fiscal_period) identity.\n\nEach hop compares two filings that report the statement, in SEC acceptance order; each filing appears once. A filing whose figures match the filing before it, such as an amendment that leaves this statement untouched, is merged into the run it repeats unless `include_unchanged_filings=true`, so by default every hop reflects a change in reported figures.\n\nEach hop names its two filings in `from_version` and `to_version` by SEC accession; pass the accessions to the restatement delta as `from_accession` and `to_accession` to compare exactly that hop.", "operationId": "get_restatement_ledger", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "type": "string", "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "examples": [ "INCOME_STATEMENT" ], "title": "Statement Type" }, "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year for the ledger identity.", "title": "Fiscal Year" }, "description": "Fiscal year for the ledger identity." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "type": "string", "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4).", "examples": [ "FY" ], "title": "Fiscal Period" }, "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4)." }, { "name": "include_unchanged_filings", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Include filings whose figures match the filing before them. By default each run of filings with identical figures is reduced to its latest filing, so every hop reflects a change in reported figures.", "default": false, "title": "Include Unchanged Filings" }, "description": "Include filings whose figures match the filing before them. By default each run of filings with identical figures is reduced to its latest filing, so every hop reflects a change in reported figures." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestatementLedgerEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/restatement-alerts": { "get": { "tags": [ "Statements" ], "summary": "List restatement alert events", "description": "List restatement alert events. Deterministic ordering: latest SEC acceptance of the restating filing first (accepted_at desc, restatement_alert_event_id asc), with a fixed tie-break.", "operationId": "list_restatement_alerts", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Issuer CIK filter.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "Issuer CIK filter." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Primary ticker filter when the alert was generated with ticker metadata.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Primary ticker filter when the alert was generated with ticker metadata." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive UTC date lower bound on the restating filing's SEC acceptance.", "title": "From" }, "description": "Inclusive UTC date lower bound on the restating filing's SEC acceptance." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive UTC date upper bound on the restating filing's SEC acceptance.", "title": "To" }, "description": "Inclusive UTC date upper bound on the restating filing's SEC acceptance." }, { "name": "statement_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/StatementType" }, { "type": "null" } ], "description": "Optional statement type filter.", "title": "Statement Type" }, "description": "Optional statement type filter." }, { "name": "materiality_score", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/MaterialityClass" }, { "type": "null" } ], "description": "Optional materiality severity filter.", "title": "Materiality Score" }, "description": "Optional materiality severity filter." }, { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "1-indexed page number.", "title": "Page" }, "description": "1-indexed page number." }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Items per page (bounded).", "title": "Page Size" }, "description": "Items per page (bounded)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Deprecated alias.", "title": "Per Page" }, "description": "Deprecated alias." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestatementAlertEventPage" }, "example": { "page": 1, "page_size": 2, "total": 16584, "items": [ { "restatement_alert_event_id": "d3f24fb1-ca96-b5eb-0095-7bfb8c100c4a", "company_id": "2eb4d8b9-d3dd-400a-b15f-ac4e37c0e293", "cik": "0001938338", "ticker": "GLTK", "accession_id": "0001477932-23-006781", "prior_accession_id": "0001477932-23-006211", "statement_type": "BALANCE_SHEET", "statement_date": "2022-12-31", "fiscal_year": 2022, "fiscal_period": "FY", "accepted_at": "2023-09-09T00:37:40Z", "facts_changed_count": 2, "material_facts_count": 0, "materiality_score": "LOW", "change_class_counts": { "NEW_DISCLOSURE": 2 }, "summary_metrics": [ { "metric_code": "additional_paid_in_capital", "change_type": "NEW_DISCLOSURE", "new_value": "0.000000" }, { "metric_code": "goodwill", "change_type": "NEW_DISCLOSURE", "new_value": "0.000000" } ], "materiality_summary": "LOW severity across 2 fact revisions; impacts: current_ratio, working_capital", "model_impacts": [ { "impact_code": "current_ratio", "previous_value": "0.3249", "current_value": "0.3249", "delta_value": "0.0000" }, { "impact_code": "working_capital", "previous_value": "-26022828", "current_value": "-26022828", "delta_value": "0" } ] }, { "restatement_alert_event_id": "1aac811b-b6d0-abf1-5b7e-15b5a1e69e5d", "company_id": "2eb4d8b9-d3dd-400a-b15f-ac4e37c0e293", "cik": "0001938338", "ticker": "GLTK", "accession_id": "0001477932-23-006785", "prior_accession_id": "0001477932-23-006277", "statement_type": "CASH_FLOW_STATEMENT", "statement_date": "2023-06-30", "fiscal_year": 2023, "fiscal_period": "Q2", "accepted_at": "2023-09-11T10:07:02Z", "facts_changed_count": 1, "material_facts_count": 0, "materiality_score": "LOW", "change_class_counts": { "NEW_DISCLOSURE": 1 }, "summary_metrics": [ { "metric_code": "depreciation_and_amortization_in_cfo", "change_type": "NEW_DISCLOSURE", "new_value": "1403906.000000" } ], "materiality_summary": "LOW severity across 1 fact revisions", "model_impacts": [] } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/restatement-alerts/{restatement_alert_event_id}": { "get": { "tags": [ "Statements" ], "summary": "Get one restatement alert event", "description": "Return one restatement alert event by identifier.", "operationId": "get_restatement_alert", "parameters": [ { "name": "restatement_alert_event_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Restatement Alert Event Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestatementAlertEventEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/reconciliation/ledger": { "get": { "tags": [ "Coverage" ], "summary": "Get reconciliation ledger for a statement identity", "description": "Return the reconciliation results recorded for a statement identity. Every statement type is reconciled, once per filing's statement, against these rules. BALANCE_SHEET: bs_assets_eq_liab_plus_equity (Assets equal liabilities plus equity); bs_assets_eq_current_plus_noncurrent (Current assets plus non-current assets equal total assets); bs_liabilities_eq_current_plus_noncurrent (Current liabilities plus non-current liabilities equal total liabilities); cash_rollforward_adjacent_periods (Opening cash plus the net change in cash, and any exchange-rate effect, equals closing cash); retained_earnings_rollforward (Opening retained earnings plus net income less dividends equals closing retained earnings, over a full fiscal year). INCOME_STATEMENT: is_gross_profit_eq_revenue_less_cost (Gross profit equals revenue minus cost of revenue); is_gross_profit_within_revenue (Gross profit does not exceed revenue); is_pretax_income_eq_net_income_plus_tax (Net income plus income tax expense and noncontrolling interest equals income before tax); segment_revenue_eq_segment_total (Reportable segment revenues sum to the segment total); segment_revenue_eq_consolidated_revenue (Segment revenues reconcile to consolidated revenue). CASH_FLOW_STATEMENT: cf_net_change_eq_activity_totals (Net change in cash equals operating + investing + financing cash flows); cf_start_eq_net_income (Cash-flow starting income equals income-statement net income). Annual statements of every type: calendar_fiscal_year_end_consistent (Fiscal year-end month matches the filer's established close). A rule a statement cannot be checked against is reported as SKIPPED with its reason. A statement with no recorded results answers 404 NOT_FOUND with details.reason NOT_RECONCILED, never an empty list. Deterministic ordering: stable sort with a fixed tie-break, so pages never overlap.", "operationId": "get_reconciliation_ledger", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "type": "string", "description": "Statement type code (HTTP).", "title": "Statement Type" }, "description": "Statement type code (HTTP)." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year.", "title": "Fiscal Year" }, "description": "Fiscal year." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "type": "string", "description": "Fiscal period code (HTTP).", "title": "Fiscal Period" }, "description": "Fiscal period code (HTTP)." }, { "name": "accession_id", "in": "query", "required": true, "schema": { "type": "string", "description": "SEC accession of the filing whose statement to read, as returned by /v1/edgar/companies/{cik}/statements. The filing's current statement is read. An accession that serves no statement for the requested cik, statement type and period answers 404 with details.available_accessions.", "examples": [ "0001069183-25-000075" ], "title": "Accession Id" }, "description": "SEC accession of the filing whose statement to read, as returned by /v1/edgar/companies/{cik}/statements. The filing's current statement is read. An accession that serves no statement for the requested cik, statement type and period answers 404 with details.available_accessions." }, { "name": "rule_category", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ReconciliationRuleCategory" }, { "type": "null" } ], "description": "Optional category filter.", "title": "Rule Category" }, "description": "Optional category filter." }, { "name": "statuses", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationStatus" } }, { "type": "null" } ], "description": "Return only results with these rule outcomes: PASS, FAIL or SKIPPED.", "title": "Statuses" }, "description": "Return only results with these rule outcomes: PASS, FAIL or SKIPPED." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 20000, "minimum": 1 }, { "type": "null" } ], "description": "Optional max rows returned before pagination.", "title": "Limit" }, "description": "Optional max rows returned before pagination." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1–200).", "default": 200, "title": "Page Size" }, "description": "Page size (1–200)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationResultPage" }, "example": { "page": 2, "page_size": 3, "total": 6, "items": [ { "cik": "0000320193", "statement_type": "BALANCE_SHEET", "fiscal_year": 2024, "fiscal_period": "FY", "accession_id": "0000320193-24-000123", "rule_id": "bs_liabilities_eq_current_plus_noncurrent", "rule_category": "IDENTITY", "status": "PASS", "severity": "NONE", "expected_value": "308030000000.000000", "actual_value": "308030000000.000000", "delta": "0.000000", "notes": { "basis": "AS_REPORTED", "equation": "LIABILITIES_SUBTOTALS", "tolerance": "1500000", "lhs_metrics": [ "TOTAL_CURRENT_LIABILITIES", "TOTAL_NON_CURRENT_LIABILITIES" ], "rhs_metrics": [ "TOTAL_LIABILITIES" ], "reporting_unit": "1000000", "statement_types": [ "BALANCE_SHEET" ] } }, { "cik": "0000320193", "statement_type": "BALANCE_SHEET", "fiscal_year": 2024, "fiscal_period": "FY", "accession_id": "0000320193-24-000123", "rule_id": "cash_rollforward_adjacent_periods", "rule_category": "ROLLFORWARD", "status": "SKIPPED", "severity": "NONE", "notes": { "reason": "INCOMPARABLE_CASH_SCOPES", "details": { "reason": "INCOMPARABLE_CASH_SCOPES", "scope_evidence": { "residual": "772000000", "flow_period": "2023-10-01_TO_2024-09-28", "balance_scope": "CASH_AND_CASH_EQUIVALENTS", "net_change_scope": "INCLUDING_RESTRICTED_CASH", "closing_balance_sheet": "2024_FY_2024-09-28", "opening_balance_sheet": "2023_FY_2023-09-30" } }, "status_reason": "SKIPPED", "rollforward_rule_name": "cash_rollforward_adjacent_periods" } }, { "cik": "0000320193", "statement_type": "BALANCE_SHEET", "fiscal_year": 2024, "fiscal_period": "FY", "accession_id": "0000320193-24-000123", "rule_id": "retained_earnings_rollforward", "rule_category": "ROLLFORWARD", "status": "SKIPPED", "severity": "NONE", "notes": { "reason": "DIRECT_MOVEMENTS_UNRESOLVED", "details": { "reason": "DIRECT_MOVEMENTS_UNRESOLVED", "scope_evidence": { "actual": "-19154000000", "expected": "78288000000", "residual": "-97442000000", "tolerance": "3810500000.00", "flow_period": "2023-10-01_TO_2024-09-28", "share_repurchases": "94949000000", "closing_balance_sheet": "2024_FY_2024-09-28", "opening_balance_sheet": "2023_FY_2023-09-30" } }, "status_reason": "SKIPPED", "rollforward_rule_name": "retained_earnings_rollforward" } } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "growth", "x-rate-limit-class": "read" } }, "/v1/edgar/reconciliation/summary": { "get": { "tags": [ "Coverage" ], "summary": "Get reconciliation summary for a fiscal-year window", "description": "Return PASS/FAIL/SKIPPED counts by category over a multi-year window, one filing's current statement per bucket. Every statement type is reconciled, once per filing's statement, against these rules. BALANCE_SHEET: bs_assets_eq_liab_plus_equity (Assets equal liabilities plus equity); bs_assets_eq_current_plus_noncurrent (Current assets plus non-current assets equal total assets); bs_liabilities_eq_current_plus_noncurrent (Current liabilities plus non-current liabilities equal total liabilities); cash_rollforward_adjacent_periods (Opening cash plus the net change in cash, and any exchange-rate effect, equals closing cash); retained_earnings_rollforward (Opening retained earnings plus net income less dividends equals closing retained earnings, over a full fiscal year). INCOME_STATEMENT: is_gross_profit_eq_revenue_less_cost (Gross profit equals revenue minus cost of revenue); is_gross_profit_within_revenue (Gross profit does not exceed revenue); is_pretax_income_eq_net_income_plus_tax (Net income plus income tax expense and noncontrolling interest equals income before tax); segment_revenue_eq_segment_total (Reportable segment revenues sum to the segment total); segment_revenue_eq_consolidated_revenue (Segment revenues reconcile to consolidated revenue). CASH_FLOW_STATEMENT: cf_net_change_eq_activity_totals (Net change in cash equals operating + investing + financing cash flows); cf_start_eq_net_income (Cash-flow starting income equals income-statement net income). Annual statements of every type: calendar_fiscal_year_end_consistent (Fiscal year-end month matches the filer's established close). A rule a statement cannot be checked against is reported as SKIPPED with its reason. A statement with no recorded results answers 404 NOT_FOUND with details.reason NOT_RECONCILED, never an empty list.", "operationId": "get_reconciliation_summary", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "type": "string", "description": "Statement type code (HTTP).", "title": "Statement Type" }, "description": "Statement type code (HTTP)." }, { "name": "fiscal_year_from", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Inclusive start fiscal year.", "title": "Fiscal Year From" }, "description": "Inclusive start fiscal year." }, { "name": "fiscal_year_to", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Inclusive end fiscal year.", "title": "Fiscal Year To" }, "description": "Inclusive end fiscal year." }, { "name": "rule_category", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/ReconciliationRuleCategory" }, { "type": "null" } ], "description": "Optional category filter.", "title": "Rule Category" }, "description": "Optional category filter." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50000, "minimum": 1, "description": "Maximum ledger rows scanned.", "default": 5000, "title": "Limit" }, "description": "Maximum ledger rows scanned." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationSummaryBucketListEnvelope" }, "example": { "data": [ { "fiscal_year": 2024, "fiscal_period": "FY", "accession_id": "0000320193-24-000123", "rule_category": "CALENDAR", "pass_count": 1, "fail_count": 0, "skip_count": 0 }, { "fiscal_year": 2024, "fiscal_period": "FY", "accession_id": "0000320193-24-000123", "rule_category": "IDENTITY", "pass_count": 3, "fail_count": 0, "skip_count": 0 }, { "fiscal_year": 2024, "fiscal_period": "FY", "accession_id": "0000320193-24-000123", "rule_category": "ROLLFORWARD", "pass_count": 0, "fail_count": 0, "skip_count": 2 } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "growth", "x-rate-limit-class": "read" } }, "/v1/edgar/derived-metrics/catalog": { "get": { "tags": [ "Fundamentals" ], "summary": "List derived metrics catalog", "description": "Return the canonical catalog of derived metric definitions.", "operationId": "list_derived_metrics", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarDerivedMetricsCatalogEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/derived-metrics/time-series": { "get": { "tags": [ "Fundamentals" ], "summary": "Get derived metrics time series", "description": "Return a derived metrics time series for one or more companies with deterministic ordering and stable metric definitions. Market-dependent derived metrics require caller-supplied market inputs and are not emitted by this EDGAR-only route.", "operationId": "get_derived_metrics_time_series", "parameters": [ { "name": "ciks", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Companies named by CIK. Repeat the parameter (for example `?ciks=0000320193&ciks=0000789019`) or separate CIKs with commas. Send this or `tickers`, not both. At most 25 companies per request.", "examples": [ [ "0000320193", "0000789019" ] ], "title": "Ciks" }, "description": "Companies named by CIK. Repeat the parameter (for example `?ciks=0000320193&ciks=0000789019`) or separate CIKs with commas. Send this or `tickers`, not both. At most 25 companies per request." }, { "name": "tickers", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Companies named by ticker symbol, in place of `ciks`; send one or the other. Repeat the parameter or separate symbols with commas. Each resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none. At most 25 companies per request.", "examples": [ [ "AAPL", "MSFT" ] ], "title": "Tickers" }, "description": "Companies named by ticker symbol, in place of `ciks`; send one or the other. Repeat the parameter or separate symbols with commas. Each resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none. At most 25 companies per request." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Statement type used as the base for derived metrics (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "examples": [ "INCOME_STATEMENT" ], "title": "Statement Type" }, "description": "Statement type used as the base for derived metrics (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "metrics", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/DerivedMetric" }, "minItems": 1 }, { "type": "null" } ], "description": "Optional list of derived metric codes to include. If omitted, all EDGAR-computable derived metrics are considered. Metrics that require caller-supplied market inputs are not emitted by this EDGAR-only route.", "examples": [ [ "CURRENT_RATIO", "QUICK_RATIO", "DSO", "CASH_CONVERSION_CYCLE" ] ], "title": "Metrics" }, "description": "Optional list of derived metric codes to include. If omitted, all EDGAR-computable derived metrics are considered. Metrics that require caller-supplied market inputs are not emitted by this EDGAR-only route." }, { "name": "frequency", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "description": "Time-series frequency: 'annual' or 'quarterly' (default: 'annual').", "examples": [ "annual" ], "default": "annual", "title": "Frequency" }, "description": "Time-series frequency: 'annual' or 'quarterly' (default: 'annual')." }, { "name": "from_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional lower bound on statement_date (inclusive, YYYY-MM-DD).", "examples": [ "2019-01-01" ], "title": "From Date" }, "description": "Optional lower bound on statement_date (inclusive, YYYY-MM-DD)." }, { "name": "to_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional upper bound on statement_date (inclusive, YYYY-MM-DD).", "examples": [ "2024-12-31" ], "title": "To Date" }, "description": "Optional upper bound on statement_date (inclusive, YYYY-MM-DD)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarDerivedMetricsTimeSeriesEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/metrics/{metric}/time-series": { "get": { "tags": [ "Fundamentals" ], "summary": "Get normalized metric time series", "description": "Return a deterministic ordered time series of normalized EDGAR facts for one metric. Deterministic ordering is period_end ASC, fiscal_year ASC, fiscal_period ASC, statement_type ASC, with a fixed tie-break so pages never overlap. When as_of_date is supplied, only filings public by that date are included. Responses use the canonical PaginatedEnvelope.", "operationId": "get_metric_time_series", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "metric", "in": "path", "required": true, "schema": { "type": "string", "title": "Metric" } }, { "name": "statement_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Statement Type" } }, { "name": "fiscal_period", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fiscal Period" } }, { "name": "fiscal_year_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fiscal Year From" } }, { "name": "fiscal_year_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fiscal Year To" } }, { "name": "period_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Period Type" } }, { "name": "as_reported", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "As Reported" } }, { "name": "as_of_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "As Of Date" } }, { "name": "include_provenance", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Include Provenance" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEnvelopeMetricTimeSeriesHTTP" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/metric-bundles": { "get": { "tags": [ "Fundamentals" ], "summary": "List filing-based metric bundles", "description": "Return the additive catalog of filing-based EDGAR metric bundles supported by this phase. Responses use the canonical SuccessEnvelope.", "operationId": "list_metric_bundles", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricBundleCatalogItemListEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/metric-bundles/{bundle_code}/time-series": { "get": { "tags": [ "Fundamentals" ], "summary": "Get filing-based metric bundle time series", "description": "Return deterministic aligned bundle rows by fiscal period for one company and bundle code. Deterministic ordering is period_end ASC, fiscal_year ASC, fiscal_period ASC, with a fixed tie-break so pages never overlap. Responses use the canonical PaginatedEnvelope.", "operationId": "get_metric_bundle_time_series", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "bundle_code", "in": "path", "required": true, "schema": { "type": "string", "title": "Bundle Code" } }, { "name": "fiscal_period", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fiscal Period" } }, { "name": "fiscal_year_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fiscal Year From" } }, { "name": "fiscal_year_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fiscal Year To" } }, { "name": "period_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Period Type" } }, { "name": "as_of_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "As Of Date" } }, { "name": "include_provenance", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Provenance" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricBundleTimeSeriesRowPage" }, "example": { "page": 1, "page_size": 2, "total": 18, "items": [ { "cik": "0000320193", "bundle_code": "profitability", "period_type": "annual", "period_end": "2008-09-27", "fiscal_year": 2008, "fiscal_period": "FY", "filing_accession": "0001193125-10-238044", "filing_type": "10-K", "filing_date": "2010-10-27", "accepted_at": "2010-10-27T20:36:21Z", "metrics": { "GROSS_MARGIN": "0.352004", "OPERATING_MARGIN": "0.222107", "NET_MARGIN": "0.163213", "ROE": "0.274432" } }, { "cik": "0000320193", "bundle_code": "profitability", "period_type": "annual", "period_end": "2009-09-26", "fiscal_year": 2009, "fiscal_period": "FY", "filing_accession": "0001193125-10-012091", "filing_type": "10-K", "filing_date": "2010-01-25", "accepted_at": "2010-01-25T21:25:58Z", "metrics": { "GROSS_MARGIN": "0.401398", "OPERATING_MARGIN": "0.273628", "NET_MARGIN": "0.191936", "ROE": "0.260272" } } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/financial-state/time-series": { "get": { "tags": [ "Fundamentals" ], "summary": "Get aligned financial-state time series", "description": "Return one aligned EDGAR financial-state row per fiscal period for a company. The response aligns the income statement, balance sheet, and cash flow statement public at the boundary by fiscal period, preserves decimal-string values, and uses deterministic ordering by period_end ASC, fiscal_year ASC, fiscal_period ASC with tie-break on cik.", "operationId": "get_financial_state_time_series", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "fiscal_period", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fiscal Period" } }, { "name": "fiscal_year_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fiscal Year From" } }, { "name": "fiscal_year_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fiscal Year To" } }, { "name": "period_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Period Type" } }, { "name": "as_of_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "As Of Date" } }, { "name": "include_provenance", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Provenance" } }, { "name": "include_macro_context", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Macro Context" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialStatePeriodPage" }, "example": { "page": 1, "page_size": 2, "total": 18, "items": [ { "cik": "0000320193", "fiscal_year": 2008, "fiscal_period": "FY", "period_end": "2008-09-27", "accepted_at": "2010-10-27T20:36:21Z", "filing_date": "2010-10-27", "source_accessions": [ "0001193125-10-238044" ], "metrics": { "ACCUMULATED_OTHER_COMPREHENSIVE_INCOME": "-9000000.000000" }, "completeness": { "metrics_expected": 71, "metrics_populated": 35, "completeness_ratio": "0.4929577464788732394366197183", "missing_metrics": [ "ACCOUNTS_PAYABLE", "ACCOUNTS_RECEIVABLE_NET" ], "by_statement_type": { "INCOME_STATEMENT": { "metrics_expected": 19, "metrics_populated": 16, "completeness_ratio": "0.8421052631578947368421052632", "missing_metrics": [ "INTEREST_EXPENSE", "INTEREST_INCOME" ] }, "BALANCE_SHEET": { "metrics_expected": 30, "metrics_populated": 5, "completeness_ratio": "0.1666666666666666666666666667", "missing_metrics": [ "ACCOUNTS_PAYABLE", "ACCOUNTS_RECEIVABLE_NET" ] }, "CASH_FLOW_STATEMENT": { "metrics_expected": 22, "metrics_populated": 14, "completeness_ratio": "0.6363636363636363636363636364", "missing_metrics": [ "CASH_PAID_FOR_INTEREST", "CHANGE_IN_OTHER_CURRENT_ASSETS" ] } } } }, { "cik": "0000320193", "fiscal_year": 2009, "fiscal_period": "FY", "period_end": "2009-09-26", "accepted_at": "2010-01-25T21:25:58Z", "filing_date": "2010-01-25", "source_accessions": [ "0001193125-10-012091" ], "metrics": { "ACCOUNTS_PAYABLE": "5601000000.000000", "ACCOUNTS_RECEIVABLE_NET": "3361000000.000000", "ACCUMULATED_OTHER_COMPREHENSIVE_INCOME": "77000000.000000" }, "completeness": { "metrics_expected": 71, "metrics_populated": 47, "completeness_ratio": "0.6619718309859154929577464789", "missing_metrics": [ "ADDITIONAL_PAID_IN_CAPITAL", "CASH_PAID_FOR_INTEREST" ], "by_statement_type": { "INCOME_STATEMENT": { "metrics_expected": 19, "metrics_populated": 16, "completeness_ratio": "0.8421052631578947368421052632", "missing_metrics": [ "INTEREST_EXPENSE", "INTEREST_INCOME" ] }, "BALANCE_SHEET": { "metrics_expected": 30, "metrics_populated": 17, "completeness_ratio": "0.5666666666666666666666666667", "missing_metrics": [ "ADDITIONAL_PAID_IN_CAPITAL", "CURRENT_PORTION_OF_LONG_TERM_DEBT" ] }, "CASH_FLOW_STATEMENT": { "metrics_expected": 22, "metrics_populated": 14, "completeness_ratio": "0.6363636363636363636363636364", "missing_metrics": [ "CASH_PAID_FOR_INTEREST", "CHANGE_IN_OTHER_CURRENT_ASSETS" ] } } } } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/statements/dq/overlay": { "get": { "tags": [ "Coverage" ], "summary": "Get a normalized statement with DQ overlay", "description": "Return a normalized statement payload with DQ anomalies and severity overlays for one filing's statement, named by cik, statement_type, fiscal_year, fiscal_period and the filing's accession_id. The filing's current statement is read. An accession that serves no statement for the identity answers 404 EDGAR_STATEMENT_NOT_FOUND with details.available_accessions. A filing that reports two OTHER periods in the year needs statement_date.", "operationId": "get_statement_dq_overlay", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "type": "string", "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "examples": [ "INCOME_STATEMENT" ], "title": "Statement Type" }, "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year for the statement identity (>= 1).", "examples": [ 2024 ], "title": "Fiscal Year" }, "description": "Fiscal year for the statement identity (>= 1)." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "type": "string", "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4).", "examples": [ "FY" ], "title": "Fiscal Period" }, "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4)." }, { "name": "accession_id", "in": "query", "required": true, "schema": { "type": "string", "description": "SEC accession of the filing whose statement to overlay, as returned by /v1/edgar/companies/{cik}/statements. The filing's current statement is read.", "examples": [ "0001069183-25-000075" ], "title": "Accession Id" }, "description": "SEC accession of the filing whose statement to overlay, as returned by /v1/edgar/companies/{cik}/statements. The filing's current statement is read." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementDQOverlayEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/edgar/companies/{cik}/statements/overrides/trace": { "get": { "tags": [ "Statements" ], "summary": "Inspect XBRL mapping overrides for a statement identity", "description": "Return an override trace showing which mapping rules were evaluated, applied, or suppressed for one filing's statement, named by cik, statement_type, fiscal_year, fiscal_period and the filing's accession_id. The filing's current statement is read. An accession that serves no statement for the identity answers 404 EDGAR_STATEMENT_NOT_FOUND with details.available_accessions.", "operationId": "get_statement_override_trace", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "type": "string", "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "examples": [ "INCOME_STATEMENT" ], "title": "Statement Type" }, "description": "Statement type (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year for the statement identity (>= 1).", "examples": [ 2024 ], "title": "Fiscal Year" }, "description": "Fiscal year for the statement identity (>= 1)." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "type": "string", "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4).", "examples": [ "FY" ], "title": "Fiscal Period" }, "description": "Fiscal period code (e.g., FY, Q1, Q2, Q3, Q4)." }, { "name": "accession_id", "in": "query", "required": true, "schema": { "type": "string", "description": "SEC accession of the filing whose statement to trace, as returned by /v1/edgar/companies/{cik}/statements. The filing's current statement is read.", "examples": [ "0001069183-25-000075" ], "title": "Accession Id" }, "description": "SEC accession of the filing whose statement to trace, as returned by /v1/edgar/companies/{cik}/statements. The filing's current statement is read." }, { "name": "gaap_concept", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional GAAP/IFRS concept filter (e.g., Revenues).", "title": "Gaap Concept" }, "description": "Optional GAAP/IFRS concept filter (e.g., Revenues)." }, { "name": "canonical_metric_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional canonical metric code filter (e.g., REVENUE, NET_INCOME).", "title": "Canonical Metric Code" }, "description": "Optional canonical metric code filter (e.g., REVENUE, NET_INCOME)." }, { "name": "dimension_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional dimension key filter (e.g., segment slice).", "title": "Dimension Key" }, "description": "Optional dimension key filter (e.g., segment slice)." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementOverrideTraceEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/fundamentals/companies/{cik}/metrics/{metric}/time-series/real": { "get": { "tags": [ "Fundamentals" ], "summary": "Inflation-adjusted EDGAR metric time series", "description": "Return a nominal and CPI-adjusted metric time series for an existing Arche fundamental metric. Normalized statements remain unchanged; the real-value projection is computed on read using approved CPI context.", "operationId": "get_real_metric_time_series", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "0000320193", "AAPL" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "metric", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CanonicalStatementMetric" } }, { "name": "base_year", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1900 }, { "type": "null" } ], "description": "Optional CPI base year; defaults to latest CPI year.", "title": "Base Year" }, "description": "Optional CPI base year; defaults to latest CPI year." }, { "name": "fiscal_period", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/FiscalPeriod" }, { "type": "null" } ], "description": "Optional fiscal period filter.", "title": "Fiscal Period" }, "description": "Optional fiscal period filter." }, { "name": "fiscal_year_from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1900 }, { "type": "null" } ], "description": "Optional lower fiscal-year bound.", "title": "Fiscal Year From" }, "description": "Optional lower fiscal-year bound." }, { "name": "fiscal_year_to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1900 }, { "type": "null" } ], "description": "Optional upper fiscal-year bound.", "title": "Fiscal Year To" }, "description": "Optional upper fiscal-year bound." }, { "name": "as_of_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional as-of date for PIT macro alignment.", "title": "As Of Date" }, "description": "Optional as-of date for PIT macro alignment." }, { "name": "cpi_series", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/MacroSeriesCode", "description": "Approved CPI series code.", "default": "CPIAUCSL" }, "description": "Approved CPI series code." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RealFundamentalMetricSeriesEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/identity/companies/{cik}": { "get": { "tags": [ "Companies" ], "summary": "List company identity history by CIK", "description": "Return deterministic identity rows for one CIK. Deterministic ordering is active_from ASC, active_to ASC NULLS LAST, ticker ASC with a fixed tie-break. Responses use the canonical PaginatedEnvelope.", "operationId": "list_company_identity_history", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "title": "Cik" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIdentityPage" }, "example": { "page": 1, "page_size": 1, "total": 1, "items": [ { "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "ticker": "AAPL", "company_name": "Apple Inc.", "exchange": "XNAS", "active_from": "2026-07-17", "is_active": true, "source": "sec:company_submissions", "source_filing_accession": "0001140361-26-035325" } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/identity/tickers/{ticker}": { "get": { "tags": [ "Companies" ], "summary": "List ticker identity history", "description": "Return deterministic identity rows for one ticker symbol across time. Deterministic ordering is active_from ASC, active_to ASC NULLS LAST, cik ASC with a fixed tie-break. Responses use the canonical PaginatedEnvelope.", "operationId": "list_ticker_identity_history", "parameters": [ { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string", "title": "Ticker" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIdentityPage" }, "example": { "page": 1, "page_size": 1, "total": 1, "items": [ { "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "ticker": "AAPL", "company_name": "Apple Inc.", "exchange": "XNAS", "active_from": "2026-07-17", "is_active": true, "source": "sec:company_submissions", "source_filing_accession": "0001140361-26-035325" } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/identity/search": { "get": { "tags": [ "Companies" ], "summary": "Search companies by ticker, CIK, or name", "description": "Search deterministic company identity records by ticker, CIK, or company name. Deterministic ordering is ticker ASC, active_from ASC, active_to ASC NULLS LAST, cik ASC with a fixed tie-break. Responses use the canonical PaginatedEnvelope.", "operationId": "search_companies", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "title": "Query" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIdentityPage" }, "example": { "page": 1, "page_size": 2, "total": 7, "items": [ { "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "ticker": "AAPL", "company_name": "Apple Inc.", "exchange": "XNAS", "active_from": "2026-07-17", "is_active": true, "source": "sec:company_submissions", "source_filing_accession": "0001140361-26-035325" }, { "company_id": "9263e1c4-e253-40e5-a0b0-f4d120c383ca", "cik": "0001134982", "ticker": "AAPI", "company_name": "Apple iSports Group, Inc.", "exchange": "OTCM", "active_from": "2026-07-17", "is_active": true, "source": "sec:company_submissions", "source_filing_accession": "0001477932-26-003393" } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/identity/resolve": { "get": { "tags": [ "Companies" ], "summary": "Resolve a ticker to one company as of a date", "description": "Resolve a ticker symbol to the single company identity visible on the requested as-of date. Resolution is date-aware and deterministic over historical ticker mappings and symbol changes. Responses use the canonical SuccessEnvelope or ErrorEnvelope.", "operationId": "resolve_company_as_of", "parameters": [ { "name": "ticker", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "title": "Ticker" } }, { "name": "as_of_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "As Of Date" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIdentityResolveEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/views/metrics": { "get": { "tags": [ "Views" ], "summary": "List registered metric views (bundles)", "description": "Return the catalog of registered metric views (bundles) that can be used with the derived-metrics time-series endpoints. Each view represents an opinionated set of derived metrics (e.g., 'core_fundamentals', 'liquidity', 'efficiency'). Catalog metadata identifies whether a view is EDGAR-only safe or requires external market inputs.", "operationId": "list_metric_views", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricViewsCatalogEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "read" } }, "/v1/views/metrics/{bundle_code}": { "get": { "tags": [ "Views" ], "summary": "Get derived metrics time series for a metric view", "description": "Return a derived metrics time series for one or more companies using a predefined metric view (bundle). Views are opinionated metric sets such as 'core_fundamentals' that group margins, growth rates, cash flows, leverage, and returns. EDGAR-only routes reject bundles that require external market inputs.\n\nThis endpoint reuses the same time-series structure as `/v1/edgar/derived-metrics/time-series` but selects metrics via the bundle code.", "operationId": "get_metric_view_time_series", "parameters": [ { "name": "bundle_code", "in": "path", "required": true, "schema": { "type": "string", "description": "Metric view (bundle) code, e.g. 'core_fundamentals'. Bundle codes are case-insensitive.", "examples": [ "liquidity" ], "title": "Bundle Code" }, "description": "Metric view (bundle) code, e.g. 'core_fundamentals'. Bundle codes are case-insensitive." }, { "name": "ciks", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Companies named by CIK. Repeat the parameter (for example `?ciks=0000320193&ciks=0000789019`) or separate CIKs with commas. Send this or `tickers`, not both. At most 25 companies per request.", "examples": [ [ "0000320193", "0000789019" ] ], "title": "Ciks" }, "description": "Companies named by CIK. Repeat the parameter (for example `?ciks=0000320193&ciks=0000789019`) or separate CIKs with commas. Send this or `tickers`, not both. At most 25 companies per request." }, { "name": "tickers", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Companies named by ticker symbol, in place of `ciks`; send one or the other. Repeat the parameter or separate symbols with commas. Each resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none. At most 25 companies per request.", "examples": [ [ "AAPL", "MSFT" ] ], "title": "Tickers" }, "description": "Companies named by ticker symbol, in place of `ciks`; send one or the other. Repeat the parameter or separate symbols with commas. Each resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none. At most 25 companies per request." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "type": "string", "description": "Statement type used as the base for derived metrics (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT).", "title": "Statement Type" }, "description": "Statement type used as the base for derived metrics (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, { "name": "metrics", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/DerivedMetric" } }, { "type": "null" } ], "description": "Optional list of derived metric codes to include. When a bundle_code is provided, explicit metrics are not allowed.", "title": "Metrics" }, "description": "Optional list of derived metric codes to include. When a bundle_code is provided, explicit metrics are not allowed." }, { "name": "frequency", "in": "query", "required": false, "schema": { "type": "string", "description": "Time-series frequency: 'annual' or 'quarterly' (default: 'annual').", "default": "annual", "title": "Frequency" }, "description": "Time-series frequency: 'annual' or 'quarterly' (default: 'annual')." }, { "name": "from_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional lower bound on statement_date (inclusive, YYYY-MM-DD).", "title": "From Date" }, "description": "Optional lower bound on statement_date (inclusive, YYYY-MM-DD)." }, { "name": "to_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Optional upper bound on statement_date (inclusive, YYYY-MM-DD).", "title": "To Date" }, "description": "Optional upper bound on statement_date (inclusive, YYYY-MM-DD)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgarDerivedMetricsTimeSeriesEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/data-quality/issues": { "get": { "tags": [ "Coverage" ], "summary": "List public data-quality issues", "description": "Return EDGAR data-quality issues with deterministic ordering: severity DESC, cik ASC, fiscal_year ASC NULLS LAST, fiscal_period ASC NULLS LAST, rule_code ASC, with a fixed tie-break so pages never overlap. All filters are optional, so the listing can be browsed across the whole corpus.", "operationId": "list_data_quality_issues", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional company CIK filter. Send this or `ticker`, not both.", "title": "Cik" }, "description": "Optional company CIK filter. Send this or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional company filter by ticker symbol, in place of `cik`.", "title": "Ticker" }, "description": "Optional company filter by ticker symbol, in place of `cik`." }, { "name": "metric", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional metric code filter.", "title": "Metric" }, "description": "Optional metric code filter." }, { "name": "statement_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional statement type filter.", "title": "Statement Type" }, "description": "Optional statement type filter." }, { "name": "fiscal_year", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optional fiscal year filter.", "title": "Fiscal Year" }, "description": "Optional fiscal year filter." }, { "name": "fiscal_period", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional fiscal period filter.", "title": "Fiscal Period" }, "description": "Optional fiscal period filter." }, { "name": "severity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional severity filter.", "title": "Severity" }, "description": "Optional severity filter." }, { "name": "rule_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional rule code filter.", "title": "Rule Code" }, "description": "Optional rule code filter." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1-200).", "default": 50, "title": "Page Size" }, "description": "Page size (1-200)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataQualityIssuePage" }, "example": { "page": 1, "page_size": 2, "total": 2090899, "items": [ { "cik": "0000001750", "metric": "OPERATING_INCOME", "statement_type": "INCOME_STATEMENT", "fiscal_year": 2009, "fiscal_period": "FY", "filing_accession": "0001047469-11-006302", "rule_code": "PRESENCE", "rule_category": "DQ_ANOMALY", "severity": "HIGH", "status": "OPEN", "message": "PRESENCE:FAIL", "materiality": "HIGH", "created_at": "2026-09-22T04:12:40Z" }, { "cik": "0000001750", "metric": "GROSS_PROFIT", "statement_type": "INCOME_STATEMENT", "fiscal_year": 2009, "fiscal_period": "FY", "filing_accession": "0001047469-11-006302", "rule_code": "PRESENCE", "rule_category": "DQ_ANOMALY", "severity": "HIGH", "status": "OPEN", "message": "PRESENCE:FAIL", "materiality": "HIGH", "created_at": "2026-09-22T04:12:40Z" } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/fundamentals/time-series": { "get": { "tags": [ "Fundamentals" ], "summary": "Fundamentals time series", "description": "Return a panel-friendly fundamentals time series derived from normalized EDGAR statements. This endpoint is for canonical statement facts over time; the /v1/modeling routes answer from a point-in-time as-of snapshot instead. The endpoint supports a CIK universe, canonical metric selection, annual/quarterly frequency, and a deterministic time window. Deterministic ordering: stable sort with a fixed tie-break, so pages never overlap.", "operationId": "get_fundamentals_time_series", "parameters": [ { "name": "ciks", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Companies named by CIK. Repeat the parameter (for example `?ciks=0000320193&ciks=0000789019`) or separate CIKs with commas. Send this or `tickers`, not both. At most 25 companies per request.", "examples": [ [ "0000320193", "0000789019" ] ], "title": "Ciks" }, "description": "Companies named by CIK. Repeat the parameter (for example `?ciks=0000320193&ciks=0000789019`) or separate CIKs with commas. Send this or `tickers`, not both. At most 25 companies per request." }, { "name": "tickers", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Companies named by ticker symbol, in place of `ciks`; send one or the other. Repeat the parameter or separate symbols with commas. Each resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none. At most 25 companies per request.", "examples": [ [ "AAPL", "MSFT" ] ], "title": "Tickers" }, "description": "Companies named by ticker symbol, in place of `ciks`; send one or the other. Repeat the parameter or separate symbols with commas. Each resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none. At most 25 companies per request." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/StatementType", "description": "Statement type to use as the source of fundamentals (e.g., INCOME_STATEMENT)." }, "description": "Statement type to use as the source of fundamentals (e.g., INCOME_STATEMENT)." }, { "name": "metrics", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalStatementMetric" } }, { "type": "null" } ], "description": "Optional subset of canonical metrics to include. When omitted, all metrics present in the underlying normalized payloads are considered for each point.", "title": "Metrics" }, "description": "Optional subset of canonical metrics to include. When omitted, all metrics present in the underlying normalized payloads are considered for each point." }, { "name": "frequency", "in": "query", "required": false, "schema": { "type": "string", "description": "Requested frequency: 'annual' (FY) or 'quarterly' (Q1–Q4).", "default": "annual", "title": "Frequency" }, "description": "Requested frequency: 'annual' (FY) or 'quarterly' (Q1–Q4)." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive lower bound for statement_date (YYYY-MM-DD). When omitted, defaults to 1994-01-01.", "title": "From" }, "description": "Inclusive lower bound for statement_date (YYYY-MM-DD). When omitted, defaults to 1994-01-01." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive upper bound for statement_date (YYYY-MM-DD). When omitted, defaults to today's date.", "title": "To" }, "description": "Inclusive upper bound for statement_date (YYYY-MM-DD). When omitted, defaults to today's date." }, { "name": "core_metrics_only", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true and `metrics` is omitted, restrict the series to the core metrics of the requested statement_type, from: REVENUE, GROSS_PROFIT, OPERATING_INCOME, NET_INCOME, BASIC_EPS, DILUTED_EPS, TOTAL_ASSETS, TOTAL_LIABILITIES, TOTAL_EQUITY, CASH_AND_CASH_EQUIVALENTS, LONG_TERM_DEBT, NET_CASH_FROM_OPERATING_ACTIVITIES, CAPITAL_EXPENDITURES, FREE_CASH_FLOW and NET_INCREASE_DECREASE_IN_CASH.", "default": false, "title": "Core Metrics Only" }, "description": "When true and `metrics` is omitted, restrict the series to the core metrics of the requested statement_type, from: REVENUE, GROSS_PROFIT, OPERATING_INCOME, NET_INCOME, BASIC_EPS, DILUTED_EPS, TOTAL_ASSETS, TOTAL_LIABILITIES, TOTAL_EQUITY, CASH_AND_CASH_EQUIVALENTS, LONG_TERM_DEBT, NET_CASH_FROM_OPERATING_ACTIVITIES, CAPITAL_EXPENDITURES, FREE_CASH_FLOW and NET_INCREASE_DECREASE_IN_CASH." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index for pagination.", "default": 1, "title": "Page" }, "description": "1-based page index for pagination." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum number of items to return per page (1–200).", "default": 50, "title": "Page Size" }, "description": "Maximum number of items to return per page (1–200)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEnvelopeFundamentalsTimeSeriesHTTP" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/fundamentals/derived/time-series": { "get": { "tags": [ "Fundamentals" ], "summary": "Derived metrics time series", "description": "Return a panel-friendly derived metrics time series (margins, growth, cash flows, returns) computed from normalized EDGAR statements when requested; the /v1/modeling ratio and growth routes answer from a point-in-time as-of snapshot instead. The endpoint supports a CIK universe, derived metric selection, annual/quarterly frequency, and a deterministic time window. When metrics are omitted, only EDGAR-safe derived metrics are attempted. Market-dependent metrics require explicit caller-supplied market inputs and are not emitted by this EDGAR-only route. Deterministic ordering: stable sort with a fixed tie-break, so pages never overlap.", "operationId": "get_fundamentals_derived_time_series", "parameters": [ { "name": "ciks", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Companies named by CIK. Repeat the parameter (for example `?ciks=0000320193&ciks=0000789019`) or separate CIKs with commas. Send this or `tickers`, not both. At most 25 companies per request.", "examples": [ [ "0000320193", "0000789019" ] ], "title": "Ciks" }, "description": "Companies named by CIK. Repeat the parameter (for example `?ciks=0000320193&ciks=0000789019`) or separate CIKs with commas. Send this or `tickers`, not both. At most 25 companies per request." }, { "name": "tickers", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Companies named by ticker symbol, in place of `ciks`; send one or the other. Repeat the parameter or separate symbols with commas. Each resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none. At most 25 companies per request.", "examples": [ [ "AAPL", "MSFT" ] ], "title": "Tickers" }, "description": "Companies named by ticker symbol, in place of `ciks`; send one or the other. Repeat the parameter or separate symbols with commas. Each resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none. At most 25 companies per request." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/StatementType", "description": "Statement type to use as the primary source for fundamentals (e.g., INCOME_STATEMENT, BALANCE_SHEET)." }, "description": "Statement type to use as the primary source for fundamentals (e.g., INCOME_STATEMENT, BALANCE_SHEET)." }, { "name": "metrics", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/DerivedMetric" } }, { "type": "null" } ], "description": "Optional subset of derived metrics to include (e.g., GROSS_MARGIN, ROE). When omitted, only EDGAR-safe derived metrics are attempted. Market-dependent metrics require explicit caller-supplied market inputs and are not emitted by this EDGAR-only route.", "title": "Metrics" }, "description": "Optional subset of derived metrics to include (e.g., GROSS_MARGIN, ROE). When omitted, only EDGAR-safe derived metrics are attempted. Market-dependent metrics require explicit caller-supplied market inputs and are not emitted by this EDGAR-only route." }, { "name": "frequency", "in": "query", "required": false, "schema": { "type": "string", "description": "Requested frequency: 'annual' (FY) or 'quarterly' (Q1–Q4).", "default": "annual", "title": "Frequency" }, "description": "Requested frequency: 'annual' (FY) or 'quarterly' (Q1–Q4)." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive lower bound for statement_date (YYYY-MM-DD). When omitted, defaults to 1994-01-01.", "title": "From" }, "description": "Inclusive lower bound for statement_date (YYYY-MM-DD). When omitted, defaults to 1994-01-01." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive upper bound for statement_date (YYYY-MM-DD). When omitted, defaults to today's date.", "title": "To" }, "description": "Inclusive upper bound for statement_date (YYYY-MM-DD). When omitted, defaults to today's date." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index for pagination.", "default": 1, "title": "Page" }, "description": "1-based page index for pagination." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Maximum number of items to return per page (1–200).", "default": 50, "title": "Page Size" }, "description": "Maximum number of items to return per page (1–200)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DerivedMetricsTimeSeriesPointPage" }, "example": { "data": { "ciks": [ "0000320193" ], "statement_type": "INCOME_STATEMENT", "frequency": "annual", "from_date": "1994-01-01", "to_date": "2026-09-23", "points": [ { "cik": "0000320193", "statement_type": "INCOME_STATEMENT", "accounting_standard": "US_GAAP", "statement_date": "2008-09-27", "fiscal_year": 2008, "fiscal_period": "FY", "currency": "USD", "metrics": { "ASSET_TURNOVER": "1.036493", "BOOK_VALUE_PER_SHARE": "24.715703", "CAPEX_TO_CFO": "0.113693", "CAPEX_TO_REVENUE": "0.029100" }, "dividend_period_basis": "annual", "payout_ratio_period_basis": "annual" }, { "cik": "0000320193", "statement_type": "INCOME_STATEMENT", "accounting_standard": "US_GAAP", "statement_date": "2009-09-26", "fiscal_year": 2009, "fiscal_period": "FY", "currency": "USD", "metrics": { "ASSET_TURNOVER": "0.903244", "BOOK_VALUE_PER_SHARE": "34.884041", "CAPEX_TO_CFO": "0.112610", "CAPEX_TO_REVENUE": "0.026664" }, "dividend_period_basis": "annual", "payout_ratio_period_basis": "annual" } ] } } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/fundamentals/restatement-delta": { "get": { "tags": [ "Fundamentals" ], "summary": "Restatement delta for a single statement", "description": "Compare two filings that report one statement and return the per-metric changes between them (old, new and diff for each canonical metric that changed).\n\nName the two filings with `from_accession` and `to_accession`, the SEC accession numbers of the filings. Each resolves to the statement that filing reports.\n\nWith neither, the earliest-accepted filing for the period is compared with the latest one: the net change from first report to now. A period that was never restated returns no deltas, with both ends naming the same filing. This default moves when a new amendment is filed; pass accessions for a result that stays fixed.\n\nOnly metrics both filings carry are diffed. Metrics only one filing carries are listed in `metrics_only_in_from` and `metrics_only_in_to`, and `comparability_warning` is true when either list is not empty.\n\nGiving only one side of the pair returns 400. The `from` filing must have been accepted by the SEC before the `to` filing. An accession that reports no statement for this cik, statement type and period returns 404, listing the accessions the period does have. `from_version` and `to_version` in the response name the filings that were compared.", "operationId": "get_fundamentals_restatement_delta", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/StatementType", "description": "Statement type (e.g., INCOME_STATEMENT, BALANCE_SHEET)." }, "description": "Statement type (e.g., INCOME_STATEMENT, BALANCE_SHEET)." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year associated with the statement (>= 1). The filer's own name for its fiscal year, as its annual reports declare it: a year closing 2025-02-01 that the filer calls fiscal 2024 is served as 2024.", "title": "Fiscal Year" }, "description": "Fiscal year associated with the statement (>= 1). The filer's own name for its fiscal year, as its annual reports declare it: a year closing 2025-02-01 that the filer calls fiscal 2024 is served as 2024." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period within the year (e.g., FY, Q1, Q2)." }, "description": "Fiscal period within the year (e.g., FY, Q1, Q2)." }, { "name": "from_accession", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SEC accession of the filing to compare from, resolved to the statement that filing reports. Give together with to_accession. Omit both accessions to compare the earliest-accepted filing with the latest; that default moves when a new amendment is filed, so pass accessions for a fixed result.", "examples": [ "0001069183-25-000019" ], "title": "From Accession" }, "description": "SEC accession of the filing to compare from, resolved to the statement that filing reports. Give together with to_accession. Omit both accessions to compare the earliest-accepted filing with the latest; that default moves when a new amendment is filed, so pass accessions for a fixed result." }, { "name": "to_accession", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SEC accession of the filing to compare to, resolved to the statement that filing reports. Give together with from_accession. Omit both accessions to compare the earliest-accepted filing with the latest; that default moves when a new amendment is filed, so pass accessions for a fixed result.", "examples": [ "0001069183-25-000075" ], "title": "To Accession" }, "description": "SEC accession of the filing to compare to, resolved to the statement that filing reports. Give together with from_accession. Omit both accessions to compare the earliest-accepted filing with the latest; that default moves when a new amendment is filed, so pass accessions for a fixed result." }, { "name": "metrics", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalStatementMetric" } }, { "type": "null" } ], "description": "Optional subset of canonical metrics to consider. When omitted, all metrics present in both versions are inspected and only those that changed are returned.", "title": "Metrics" }, "description": "Optional subset of canonical metrics to consider. When omitted, all metrics present in both versions are inspected and only those that changed are returned." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestatementDeltaSuccessEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/fundamentals/normalized-statements": { "get": { "tags": [ "Fundamentals" ], "summary": "Normalized EDGAR statement as each filing reported it", "description": "Return the latest normalized EDGAR statement for a given (CIK, statement_type, fiscal_year, fiscal_period) identity tuple, optionally with the statement as each SEC filing reported it, the original and each amendment, one entry per filing in acceptance order. A fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods; `periods` lists both, ordered by statement_date, and statement_date narrows the response to one. A statement_date that names no period of the identity is answered with 404 `EDGAR_STATEMENT_NOT_FOUND`, listing the dates in `details.available_statement_dates`.", "operationId": "get_normalized_statement", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/StatementType", "description": "Statement type (e.g., INCOME_STATEMENT, BALANCE_SHEET)." }, "description": "Statement type (e.g., INCOME_STATEMENT, BALANCE_SHEET)." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year associated with the statement (>= 1). The filer's own name for its fiscal year, as its annual reports declare it: a year closing 2025-02-01 that the filer calls fiscal 2024 is served as 2024.", "title": "Fiscal Year" }, "description": "Fiscal year associated with the statement (>= 1). The filer's own name for its fiscal year, as its annual reports declare it: a year closing 2025-02-01 that the filer calls fiscal 2024 is served as 2024." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period within the year (e.g., FY, Q1, Q2)." }, "description": "Fiscal period within the year (e.g., FY, Q1, Q2)." }, { "name": "include_version_history", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to include the statement as each filing reported it, one entry per SEC filing in acceptance order.", "default": true, "title": "Include Version History" }, "description": "Whether to include the statement as each filing reported it, one entry per SEC filing in acceptance order." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Narrows the response to one period when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and without it both are listed in `periods`. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Narrows the response to one period when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and without it both are listed in `periods`. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`." }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When false (the default), each statement carries its figures as values and units, one entry per metric. When true, each statement also carries content (its facts with their dimensions, periods and per-metric provenance) and its quality block.", "default": false, "title": "Detail" }, "description": "When false (the default), each statement carries its figures as values and units, one entry per metric. When true, each statement also carries content (its facts with their dimensions, periods and per-metric provenance) and its quality block." }, { "name": "include_usd", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, each fact also carries usd: its value in US dollars, with the rate, the rate's dates and its source. A value over a period (income and cash-flow statements) converts at the average of the Federal Reserve Board's H.10 daily rates over that period; a balance-sheet value at the rate on its date. value stays as filed. Default false.", "default": false, "title": "Include Usd" }, "description": "When true, each fact also carries usd: its value in US dollars, with the rate, the rate's dates and its source. A value over a period (income and cash-flow statements) converts at the average of the Federal Reserve Board's H.10 daily rates over that period; a balance-sheet value at the rate on its date. value stays as filed. Default false." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NormalizedStatementViewEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/fundamentals/normalized-statements/dq-overlay": { "get": { "tags": [ "Fundamentals" ], "summary": "Normalized statement with data-quality overlay", "description": "Return a normalized EDGAR statement for a given identity tuple, combined with its fact-level data-quality overlay (fact-quality flags and anomalies). It answers as GET /v1/edgar/companies/{cik}/statements/dq/overlay does.", "operationId": "get_normalized_statement_dq_overlay", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/StatementType", "description": "Statement type (e.g., INCOME_STATEMENT, BALANCE_SHEET)." }, "description": "Statement type (e.g., INCOME_STATEMENT, BALANCE_SHEET)." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year associated with the statement (>= 1). The filer's own name for its fiscal year, as its annual reports declare it: a year closing 2025-02-01 that the filer calls fiscal 2024 is served as 2024.", "title": "Fiscal Year" }, "description": "Fiscal year associated with the statement (>= 1). The filer's own name for its fiscal year, as its annual reports declare it: a year closing 2025-02-01 that the filer calls fiscal 2024 is served as 2024." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period within the year (e.g., FY, Q1, Q2)." }, "description": "Fiscal period within the year (e.g., FY, Q1, Q2)." }, { "name": "accession_id", "in": "query", "required": true, "schema": { "type": "string", "description": "SEC accession of the filing whose statement to overlay, as returned by /v1/edgar/companies/{cik}/statements. The filing's current statement is read; an accession that serves no statement for the identity answers 404 with details.available_accessions.", "examples": [ "0001069183-25-000075" ], "title": "Accession Id" }, "description": "SEC accession of the filing whose statement to overlay, as returned by /v1/edgar/companies/{cik}/statements. The filing's current statement is read; an accession that serves no statement for the identity answers 404 with details.available_accessions." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Needed only when the filing reports more than one statement for the fiscal year and period: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods. Without it such a request answers 409 `EDGAR_STATEMENT_AMBIGUOUS`, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementDQOverlayEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/modeling/companies/{company_id}/periods": { "get": { "tags": [ "Modeling" ], "summary": "Modeling periods", "description": "Return point-in-time modeling period rows for a company. Unlike `/v1/fundamentals/time-series`, this endpoint answers from the company's as-of snapshot for the requested boundary, so every row is what was known at that date. Deterministic ordering: stable sort with a fixed tie-break, so pages never overlap.", "operationId": "get_modeling_periods", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date.", "title": "Company Id" }, "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date." }, { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Point-in-time boundary (YYYY-MM-DD): figures reflect filings the SEC accepted on or before this date. Dates on or after the company's most recent filing are covered; an earlier date returns 404 where no model is available for the filings current on that date.", "title": "As Of" }, "description": "Point-in-time boundary (YYYY-MM-DD): figures reflect filings the SEC accepted on or before this date. Dates on or after the company's most recent filing are covered; an earlier date returns 404 where no model is available for the filings current on that date." }, { "name": "statement_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/StatementType" }, { "type": "null" } ], "description": "Optional statement type filter.", "title": "Statement Type" }, "description": "Optional statement type filter." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive lower bound for statement_date.", "title": "From" }, "description": "Inclusive lower bound for statement_date." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive upper bound for statement_date.", "title": "To" }, "description": "Inclusive upper bound for statement_date." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort fields (e.g., 'statement_date' or '-statement_date').", "title": "Sort" }, "description": "Sort fields (e.g., 'statement_date' or '-statement_date')." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1-200).", "default": 50, "title": "Page Size" }, "description": "Page size (1-200)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPeriodPage" }, "example": { "page": 1, "page_size": 1, "total": 1, "items": [ { "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "statement_type": "INCOME_STATEMENT", "accounting_standard": "US_GAAP", "statement_date": "2024-09-28", "fiscal_year": 2024, "fiscal_period": "FY", "currency": "USD", "as_of_timestamp": "2024-09-28T23:59:59.999999Z", "snapshot_hash": "a72dfbddd2389aac94af5036938c298031340601dc6e89c819026800a7d5048c", "dq": { "dq_max_severity": "LOW", "dq_issue_count": 1 }, "reconciliation": { "reconciliation_max_severity": "LOW", "reconciliation_fail_count": 0 }, "accession_id": "0000320193-24-000123", "dimension_key": "default", "metrics": { "REVENUE": "391035000000", "GROSS_PROFIT": "180683000000", "OPERATING_INCOME": "123216000000", "NET_INCOME": "93736000000" } } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "growth", "x-rate-limit-class": "modeling" } }, "/v1/modeling/companies/{company_id}/ttm": { "get": { "tags": [ "Modeling" ], "summary": "Modeling TTM", "description": "Return point-in-time trailing-twelve-month modeling rows. Rows are fixed to an as-of snapshot boundary, unlike statement facts over a free-form time window. Deterministic ordering: stable sort with a fixed tie-break, so pages never overlap.", "operationId": "get_modeling_ttm", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date.", "title": "Company Id" }, "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date." }, { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Point-in-time boundary (YYYY-MM-DD): figures reflect filings the SEC accepted on or before this date. Dates on or after the company's most recent filing are covered; an earlier date returns 404 where no model is available for the filings current on that date.", "title": "As Of" }, "description": "Point-in-time boundary (YYYY-MM-DD): figures reflect filings the SEC accepted on or before this date. Dates on or after the company's most recent filing are covered; an earlier date returns 404 where no model is available for the filings current on that date." }, { "name": "statement_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/StatementType" }, { "type": "null" } ], "description": "Optional statement type filter.", "title": "Statement Type" }, "description": "Optional statement type filter." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive lower bound for statement_date.", "title": "From" }, "description": "Inclusive lower bound for statement_date." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive upper bound for statement_date.", "title": "To" }, "description": "Inclusive upper bound for statement_date." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort fields (e.g., 'statement_date' or '-statement_date').", "title": "Sort" }, "description": "Sort fields (e.g., 'statement_date' or '-statement_date')." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1-200).", "default": 50, "title": "Page Size" }, "description": "Page size (1-200)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelTTMPage" }, "example": { "page": 1, "page_size": 1, "total": 1, "items": [ { "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "statement_type": "INCOME_STATEMENT", "accounting_standard": "US_GAAP", "statement_date": "2024-09-28", "fiscal_year": 2024, "fiscal_period": "FY", "currency": "USD", "as_of_timestamp": "2024-09-28T23:59:59.999999Z", "snapshot_hash": "a72dfbddd2389aac94af5036938c298031340601dc6e89c819026800a7d5048c", "dq": { "dq_max_severity": "LOW", "dq_issue_count": 1 }, "reconciliation": { "reconciliation_max_severity": "LOW", "reconciliation_fail_count": 0 }, "ttm_window_start": "2023-10-01", "ttm_window_end": "2024-09-28", "metrics": { "REVENUE": "391035000000.000000", "COST_OF_REVENUE": "210352000000.000000", "GROSS_PROFIT": "180683000000.000000", "RESEARCH_AND_DEVELOPMENT_EXPENSE": "31370000000.000000", "SELLING_GENERAL_AND_ADMINISTRATIVE_EXPENSE": "26097000000.000000", "DEPRECIATION_AND_AMORTIZATION_EXPENSE": "11445000000.000000", "OPERATING_INCOME": "123216000000.000000", "OPERATING_EXPENSE": "57467000000.000000", "OTHER_NON_OPERATING_INCOME_EXPENSE": "269000000.000000", "INCOME_BEFORE_TAX": "123485000000.000000", "INCOME_TAX_EXPENSE": "29749000000.000000", "NET_INCOME": "93736000000.000000", "BASIC_EPS": "6.110000", "DILUTED_EPS": "6.080000", "WEIGHTED_AVERAGE_SHARES_BASIC": "15343783000.000000", "WEIGHTED_AVERAGE_SHARES_DILUTED": "15408095000.000000" }, "unavailable_metrics": [] } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "growth", "x-rate-limit-class": "modeling" } }, "/v1/modeling/companies/{company_id}/growth": { "get": { "tags": [ "Modeling" ], "summary": "Modeling growth", "description": "Return point-in-time growth rows (YoY/QoQ/CAGR). Rows are fixed to an as-of snapshot boundary, unlike the derived metrics of `/v1/fundamentals/derived/time-series`. Deterministic ordering: stable sort with a fixed tie-break, so pages never overlap.", "operationId": "get_modeling_growth", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date.", "title": "Company Id" }, "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date." }, { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Point-in-time boundary (YYYY-MM-DD): figures reflect filings the SEC accepted on or before this date. Dates on or after the company's most recent filing are covered; an earlier date returns 404 where no model is available for the filings current on that date.", "title": "As Of" }, "description": "Point-in-time boundary (YYYY-MM-DD): figures reflect filings the SEC accepted on or before this date. Dates on or after the company's most recent filing are covered; an earlier date returns 404 where no model is available for the filings current on that date." }, { "name": "statement_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/StatementType" }, { "type": "null" } ], "description": "Optional statement type filter.", "title": "Statement Type" }, "description": "Optional statement type filter." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive lower bound for statement_date.", "title": "From" }, "description": "Inclusive lower bound for statement_date." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive upper bound for statement_date.", "title": "To" }, "description": "Inclusive upper bound for statement_date." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort fields (e.g., 'statement_date' or '-statement_date').", "title": "Sort" }, "description": "Sort fields (e.g., 'statement_date' or '-statement_date')." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1-200).", "default": 50, "title": "Page Size" }, "description": "Page size (1-200)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelGrowthPage" }, "example": { "page": 1, "page_size": 1, "total": 1, "items": [ { "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "statement_type": "INCOME_STATEMENT", "accounting_standard": "US_GAAP", "statement_date": "2024-09-28", "fiscal_year": 2024, "fiscal_period": "FY", "currency": "USD", "as_of_timestamp": "2024-09-28T23:59:59.999999Z", "snapshot_hash": "a72dfbddd2389aac94af5036938c298031340601dc6e89c819026800a7d5048c", "dq": { "dq_max_severity": "LOW", "dq_issue_count": 1 }, "reconciliation": { "reconciliation_max_severity": "LOW", "reconciliation_fail_count": 0 }, "cagr_years": 3, "metrics": { "REVENUE_GROWTH_YOY": "0.020220", "REVENUE_GROWTH_CAGR": "0.022470", "NET_INCOME_GROWTH_YOY": "-0.033600", "NET_INCOME_GROWTH_CAGR": "-0.003335", "EPS_DILUTED_GROWTH_YOY": "-0.008157", "EPS_DILUTED_GROWTH_CAGR": "0.027181", "REVENUE_GROWTH_TTM": "0.014087", "EPS_DILUTED_GROWTH": "-0.008157" }, "unavailable_metrics": [ { "metric": "EPS_DILUTED_GROWTH_QOQ", "reason": "NOT_APPLICABLE_TO_PERIOD", "missing_inputs": [] }, { "metric": "NET_INCOME_GROWTH_QOQ", "reason": "NOT_APPLICABLE_TO_PERIOD", "missing_inputs": [] }, { "metric": "REVENUE_GROWTH_QOQ", "reason": "NOT_APPLICABLE_TO_PERIOD", "missing_inputs": [] } ] } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "growth", "x-rate-limit-class": "modeling" } }, "/v1/modeling/companies/{company_id}/ratios": { "get": { "tags": [ "Modeling" ], "summary": "Modeling ratios", "description": "Return point-in-time ratio rows (margins, returns, leverage). Ratios are fixed to an as-of snapshot boundary, unlike `/v1/fundamentals/derived/time-series`. Deterministic ordering: stable sort with a fixed tie-break, so pages never overlap.", "operationId": "get_modeling_ratios", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date.", "title": "Company Id" }, "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date." }, { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Point-in-time boundary (YYYY-MM-DD): figures reflect filings the SEC accepted on or before this date. Dates on or after the company's most recent filing are covered; an earlier date returns 404 where no model is available for the filings current on that date.", "title": "As Of" }, "description": "Point-in-time boundary (YYYY-MM-DD): figures reflect filings the SEC accepted on or before this date. Dates on or after the company's most recent filing are covered; an earlier date returns 404 where no model is available for the filings current on that date." }, { "name": "statement_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/StatementType" }, { "type": "null" } ], "description": "Optional statement type filter.", "title": "Statement Type" }, "description": "Optional statement type filter." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive lower bound for statement_date.", "title": "From" }, "description": "Inclusive lower bound for statement_date." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive upper bound for statement_date.", "title": "To" }, "description": "Inclusive upper bound for statement_date." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort fields (e.g., 'statement_date' or '-statement_date').", "title": "Sort" }, "description": "Sort fields (e.g., 'statement_date' or '-statement_date')." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1-200).", "default": 50, "title": "Page Size" }, "description": "Page size (1-200)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelRatiosPage" }, "example": { "page": 1, "page_size": 1, "total": 1, "items": [ { "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "statement_type": "INCOME_STATEMENT", "accounting_standard": "US_GAAP", "statement_date": "2024-06-29", "fiscal_year": 2024, "fiscal_period": "Q3", "currency": "USD", "as_of_timestamp": "2024-09-28T23:59:59.999999Z", "snapshot_hash": "a72dfbddd2389aac94af5036938c298031340601dc6e89c819026800a7d5048c", "dq": { "dq_max_severity": "LOW", "dq_issue_count": 1 }, "reconciliation": { "reconciliation_max_severity": "LOW", "reconciliation_fail_count": 0 }, "metrics": { "GROSS_MARGIN": "0.462572", "OPERATING_MARGIN": "0.295557", "NET_MARGIN": "0.250044", "ROE": "0.321521", "ROA": "0.064678", "ROIC": "0.152944", "DEBT_TO_EQUITY": "1.473736", "CURRENT_RATIO": "0.952980", "QUICK_RATIO": "0.642710", "BOOK_VALUE_PER_SHARE": "4.346315", "DSO": "23.917251", "DPO": "92.879672", "INVENTORY_TURNOVER": "7.477534", "CASH_CONVERSION_CYCLE": "-56.926368" }, "unavailable_metrics": [ { "metric": "INTEREST_COVERAGE", "reason": "MISSING_INPUT", "missing_inputs": [ "INTEREST_EXPENSE" ] } ] } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "growth", "x-rate-limit-class": "modeling" } }, "/v1/modeling/companies/{company_id}/multi-year": { "get": { "tags": [ "Modeling" ], "summary": "Modeling multi-year inputs", "description": "Return point-in-time valuation inputs for multi-year modeling. Valuation primitives are derived from the modeling periods of the as-of snapshot for the requested boundary. Deterministic ordering: stable sort with a fixed tie-break, so pages never overlap.", "operationId": "get_modeling_multi_year_inputs", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date.", "title": "Company Id" }, "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date." }, { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Point-in-time boundary (YYYY-MM-DD): figures reflect filings the SEC accepted on or before this date. Dates on or after the company's most recent filing are covered; an earlier date returns 404 where no model is available for the filings current on that date.", "title": "As Of" }, "description": "Point-in-time boundary (YYYY-MM-DD): figures reflect filings the SEC accepted on or before this date. Dates on or after the company's most recent filing are covered; an earlier date returns 404 where no model is available for the filings current on that date." }, { "name": "statement_type", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/StatementType" }, { "type": "null" } ], "description": "Optional statement type filter.", "title": "Statement Type" }, "description": "Optional statement type filter." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive lower bound for statement_date.", "title": "From" }, "description": "Inclusive lower bound for statement_date." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Inclusive upper bound for statement_date.", "title": "To" }, "description": "Inclusive upper bound for statement_date." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sort fields (e.g., 'statement_date' or '-statement_date').", "title": "Sort" }, "description": "Sort fields (e.g., 'statement_date' or '-statement_date')." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1-200).", "default": 50, "title": "Page Size" }, "description": "Page size (1-200)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelMultiYearPage" }, "example": { "page": 1, "page_size": 1, "total": 1, "items": [ { "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "statement_type": "INCOME_STATEMENT", "accounting_standard": "US_GAAP", "statement_date": "2024-09-28", "fiscal_year": 2024, "fiscal_period": "FY", "currency": "USD", "as_of_timestamp": "2024-09-28T23:59:59.999999Z", "snapshot_hash": "a72dfbddd2389aac94af5036938c298031340601dc6e89c819026800a7d5048c", "dq": { "dq_max_severity": "LOW", "dq_issue_count": 1 }, "reconciliation": { "reconciliation_max_severity": "LOW", "reconciliation_fail_count": 0 }, "dimension_key": "", "valuation_inputs": { "revenue": "391035000000.000000", "gross_profit": "180683000000.000000", "operating_income": "123216000000.000000", "net_income": "93736000000.000000", "income_before_tax": "123485000000.000000", "income_tax_expense": "29749000000.000000", "depreciation_and_amortization": "11445000000.000000", "weighted_average_shares_basic": "15343783000.000000", "weighted_average_shares_diluted": "15408095000.000000", "ebitda": "134661000000.000000", "tax_rate": "0.240912" }, "unavailable_metrics": [ { "metric": "capital_expenditures", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "CAPITAL_EXPENDITURES" ] }, { "metric": "cash_and_cash_equivalents", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "CASH_AND_CASH_EQUIVALENTS" ] }, { "metric": "cash_from_operations", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "NET_CASH_FROM_OPERATING_ACTIVITIES" ] }, { "metric": "change_in_accounts_payable", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "CHANGE_IN_ACCOUNTS_PAYABLE" ] }, { "metric": "change_in_accounts_receivable", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "CHANGE_IN_ACCOUNTS_RECEIVABLE" ] }, { "metric": "change_in_inventories", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "CHANGE_IN_INVENTORIES" ] }, { "metric": "change_in_other_current_assets", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "CHANGE_IN_OTHER_CURRENT_ASSETS" ] }, { "metric": "change_in_other_current_liabilities", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "CHANGE_IN_OTHER_CURRENT_LIABILITIES" ] }, { "metric": "current_portion_long_term_debt", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "CURRENT_PORTION_OF_LONG_TERM_DEBT" ] }, { "metric": "depreciation_and_amortization_in_cfo", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "DEPRECIATION_AND_AMORTIZATION_IN_CFO" ] }, { "metric": "ebit", "reason": "MISSING_INPUT", "missing_inputs": [ "INTEREST_EXPENSE", "INTEREST_INCOME" ] }, { "metric": "free_cash_flow", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "FREE_CASH_FLOW", "NET_CASH_FROM_OPERATING_ACTIVITIES", "CAPITAL_EXPENDITURES" ] }, { "metric": "interest_expense", "reason": "NOT_REPORTED", "missing_inputs": [ "INTEREST_EXPENSE" ] }, { "metric": "interest_income", "reason": "NOT_REPORTED", "missing_inputs": [ "INTEREST_INCOME" ] }, { "metric": "invested_capital", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "TOTAL_EQUITY", "SHORT_TERM_DEBT", "CURRENT_PORTION_OF_LONG_TERM_DEBT", "LONG_TERM_DEBT" ] }, { "metric": "long_term_debt", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "LONG_TERM_DEBT" ] }, { "metric": "net_capex", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "CAPITAL_EXPENDITURES" ] }, { "metric": "net_debt", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "SHORT_TERM_DEBT", "CURRENT_PORTION_OF_LONG_TERM_DEBT", "LONG_TERM_DEBT" ] }, { "metric": "net_working_capital_change", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "CHANGE_IN_ACCOUNTS_RECEIVABLE", "CHANGE_IN_INVENTORIES", "CHANGE_IN_ACCOUNTS_PAYABLE", "CHANGE_IN_OTHER_CURRENT_ASSETS", "CHANGE_IN_OTHER_CURRENT_LIABILITIES" ] }, { "metric": "nopat", "reason": "MISSING_INPUT", "missing_inputs": [ "INTEREST_EXPENSE", "INTEREST_INCOME" ] }, { "metric": "short_term_debt", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "SHORT_TERM_DEBT" ] }, { "metric": "stock_based_compensation_in_cfo", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "STOCK_BASED_COMPENSATION_IN_CFO" ] }, { "metric": "total_assets", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "TOTAL_ASSETS" ] }, { "metric": "total_current_assets", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "TOTAL_CURRENT_ASSETS" ] }, { "metric": "total_current_liabilities", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "TOTAL_CURRENT_LIABILITIES" ] }, { "metric": "total_debt", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "SHORT_TERM_DEBT", "CURRENT_PORTION_OF_LONG_TERM_DEBT", "LONG_TERM_DEBT" ] }, { "metric": "total_equity", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "TOTAL_EQUITY" ] }, { "metric": "unlevered_free_cash_flow", "reason": "MISSING_INPUT", "missing_inputs": [ "INTEREST_EXPENSE", "INTEREST_INCOME", "DEPRECIATION_AND_AMORTIZATION_IN_CFO", "CAPITAL_EXPENDITURES" ] }, { "metric": "working_capital", "reason": "NOT_ON_STATEMENT", "missing_inputs": [ "TOTAL_CURRENT_ASSETS", "TOTAL_CURRENT_LIABILITIES" ] } ] } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "growth", "x-rate-limit-class": "modeling" } }, "/v1/modeling/universe/pit-snapshot": { "post": { "tags": [ "Modeling" ], "summary": "Universe point-in-time snapshot", "description": "Return an institutional-safe batch compare snapshot for a CIK universe at a single as-of date. Deterministic ordering: cik ASC, statement_type ASC, metric_name ASC with tie-break by statement_date ASC and accession_id ASC. Companies are modeled ahead of time as their filings arrive, and a company's model serves every date until it files again. A company that has not been modeled for the requested date is modeled on request; when that cannot finish in time the response is 202 with status BUILDING, the companies still pending, and a Retry-After header, and repeating the same request after that delay returns the snapshot. This endpoint is for cross-company point-in-time comparison and has no fundamentals-surface equivalent.", "operationId": "get_universe_pit_snapshot", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1-200).", "default": 50, "title": "Page Size" }, "description": "Page size (1-200)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniversePITSnapshotRequestHTTP" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniversePITSnapshotMetricPage" }, "example": { "page": 1, "page_size": 1, "total": 1, "items": [ { "cik": "0000320193", "statement_type": "INCOME_STATEMENT", "metric_name": "REVENUE", "metric_value": "391035000000", "statement_date": "2024-09-28", "fiscal_year": 2024, "fiscal_period": "FY", "meta": { "snapshot_id": "0c09a980-b58b-4b69-a047-caf56a7c53f6", "snapshot_hash": "a72dfbddd2389aac94af5036938c298031340601dc6e89c819026800a7d5048c", "accession_id": "0000320193-24-000123" } } ] } } } }, "202": { "description": "Some companies are still being modeled; repeat the request after the Retry-After delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniversePITSnapshotBuildingEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.\n\n**Error codes:**\n- `IDEMPOTENCY_KEY_CONFLICT`: Idempotency-Key reused with different payload.\n- `IDEMPOTENCY_KEY_IN_PROGRESS`: Another request with the same Idempotency-Key is currently being processed.", "content": { "application/json": { "examples": { "key_conflict": { "summary": "Payload conflict", "value": { "error": { "code": "IDEMPOTENCY_KEY_CONFLICT", "http_status": 409, "message": "Idempotency-Key reused with a different request payload.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "in_progress": { "summary": "In-progress conflict", "value": { "error": { "code": "IDEMPOTENCY_KEY_IN_PROGRESS", "http_status": 409, "message": "Another request with the same Idempotency-Key is in progress.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "growth", "x-rate-limit-class": "modeling" } }, "/v1/analysis/version-delta": { "get": { "tags": [ "Fundamentals" ], "summary": "First-filed versus latest-filed metric delta", "description": "Return the change in one metric between a reporting period's first-filed figures and its latest-filed figures, across the SEC filings that reported it. Market-dependent derived metrics are rejected on this EDGAR-only route.", "operationId": "get_version_delta", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/StatementType", "description": "Statement type." }, "description": "Statement type." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year.", "title": "Fiscal Year" }, "description": "Fiscal year." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period." }, "description": "Fiscal period." }, { "name": "metric", "in": "query", "required": true, "schema": { "type": "string", "description": "Canonical or derived metric code.", "title": "Metric" }, "description": "Canonical or derived metric code." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionMetricDeltaEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/analysis/metric-drift": { "get": { "tags": [ "Fundamentals" ], "summary": "Metric drift analytics", "description": "Return original-versus-latest drift analytics for a single reporting period. Market-dependent derived metrics are rejected on this EDGAR-only route.", "operationId": "get_metric_drift", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/StatementType", "description": "Statement type." }, "description": "Statement type." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year.", "title": "Fiscal Year" }, "description": "Fiscal year." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period." }, "description": "Fiscal period." }, { "name": "metric", "in": "query", "required": true, "schema": { "type": "string", "description": "Canonical or derived metric code.", "title": "Metric" }, "description": "Canonical or derived metric code." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricDriftEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/analysis/model-impact": { "get": { "tags": [ "Fundamentals" ], "summary": "Model impact of restatements", "description": "Return valuation and sensitivity analytics comparing a period's first-filed figures with its latest-filed figures. This route uses market inputs such as MARKET_CAP or ENTERPRISE_VALUE when they are available, and callers must acknowledge market-input use explicitly.", "operationId": "get_model_impact", "parameters": [ { "name": "cik", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both.", "examples": [ "0000320193" ], "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193). Send this or `ticker`, not both." }, { "name": "ticker", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "examples": [ "AAPL" ], "title": "Ticker" }, "description": "Ticker symbol naming the company, in place of `cik`; send one or the other. Resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." }, { "name": "statement_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/StatementType", "description": "Statement type." }, "description": "Statement type." }, { "name": "fiscal_year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Fiscal year.", "title": "Fiscal Year" }, "description": "Fiscal year." }, { "name": "fiscal_period", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period." }, "description": "Fiscal period." }, { "name": "allow_market_inputs", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Acknowledge that this endpoint may use market-input fields such as MARKET_CAP or ENTERPRISE_VALUE when available.", "default": false, "title": "Allow Market Inputs" }, "description": "Acknowledge that this endpoint may use market-input fields such as MARKET_CAP or ENTERPRISE_VALUE when available." }, { "name": "statement_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`.", "examples": [ "2023-01-31" ], "title": "Statement Date" }, "description": "End date of the statement's period (YYYY-MM-DD). Names the period to compare when the identity reports more than one: a fiscal year split at a business combination or fresh-start reorganization is reported as two OTHER periods, and each is compared across filings on its own. Without it the comparison covers the later period. A date that names no period of the identity answers 404, listing the dates in `details.available_statement_dates`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelImpactEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/query/execute": { "post": { "tags": [ "Coverage" ], "summary": "Execute a deterministic public query", "description": "Execute one supported deterministic query, compute immutable manifest hashes, persist the manifest and the result, and optionally return the result payload. Supported query types are financial_state_time_series, metric_time_series, metric_bundle_time_series and financials_as_of; financials_as_of is the as-of financials read and requires as_of_date. Parameters the query type does not take are ignored and not stored. The same query over the same data always yields the same replay_token, and each organization receives a manifest of its own: running a query again returns your organization's first manifest for it, with its created_at.", "operationId": "execute_query", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryExecuteRequestHTTP" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryExecuteResponseEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Idempotency conflict.\n\n**Error codes:**\n- `IDEMPOTENCY_KEY_CONFLICT`: Idempotency-Key reused with different payload.\n- `IDEMPOTENCY_KEY_IN_PROGRESS`: Another request with the same Idempotency-Key is currently being processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "key_conflict": { "summary": "Payload conflict", "value": { "error": { "code": "IDEMPOTENCY_KEY_CONFLICT", "http_status": 409, "message": "Idempotency-Key reused with a different request payload.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "in_progress": { "summary": "In-progress conflict", "value": { "error": { "code": "IDEMPOTENCY_KEY_IN_PROGRESS", "http_status": 409, "message": "Another request with the same Idempotency-Key is in progress.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "snapshot" } }, "/v1/query/replay/{replay_token}": { "get": { "tags": [ "Coverage" ], "summary": "Replay a query from its replay token", "description": "Return the response a replay token was minted for, exactly as first returned, beside its immutable manifest, and re-verify it. The query is re-executed at the manifest's as-of date and the recomputation's hash compared with the recorded one: replay_mode is 'recomputed_verified' with matches_original_result true when they match, 'recomputed_format_changed' when the same filings and values come back in a response whose bytes differ, and 'recomputed_diverged' when the underlying data has changed since; in both of those matches_original_result is false and recomputed_result carries what the query returns now. When the query can no longer be re-executed, replay_mode is 'stored_manifest' and the original result is still returned. A replay token is shareable: anyone whose plan covers the query's company can replay it. The manifest returned is your organization's own when it executed the query, and otherwise the token's first manifest.", "operationId": "replay_query", "parameters": [ { "name": "replay_token", "in": "path", "required": true, "schema": { "type": "string", "description": "Stable replay token returned by POST /v1/query/execute.", "title": "Replay Token" }, "description": "Stable replay token returned by POST /v1/query/execute." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryReplayResponseEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/query/verify/{replay_token}": { "get": { "tags": [ "Coverage" ], "summary": "Verify a replay token", "description": "Re-run the query a replay token was minted for and say whether it still returns the same data. No API key is needed: anyone given a token, such as the reviewer of a figure an agent quoted, can check it. verdict is MATCHES when the re-run returns the same statements and values, DOES_NOT_MATCH when it returns different data, and NOT_RECOMPUTED when the query can no longer be re-run. The response names the query, its hashes and the SEC filings the result was read from; the figures themselves are returned by GET /v1/query/replay/{replay_token}, which takes a key.", "operationId": "verify_query", "parameters": [ { "name": "replay_token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$", "description": "Replay token returned by POST /v1/query/execute or an MCP as-of tool.", "title": "Replay Token" }, "description": "Replay token returned by POST /v1/query/execute or an MCP as-of tool." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryVerificationEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "verify" } }, "/v1/bulk/datasets": { "get": { "tags": [ "Bulk Export" ], "summary": "List the bulk export dataset contract", "description": "Return every dataset a snapshot holds, with its columns, types, key and partition column. Column names and meanings match the HTTP schema of the route each dataset mirrors, so a reader written against the API reads the files. This is the contract to generate table definitions from.", "operationId": "list_bulk_datasets", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDatasetListEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-required-tier": "scale", "x-rate-limit-class": "bulk" } }, "/v1/bulk/snapshots": { "get": { "tags": [ "Bulk Export" ], "summary": "List published bulk export snapshots", "description": "Return published snapshots with each dataset's rows, bytes, file count and how many of those files changed since the previous snapshot. Deterministic ordering: published_at DESC, with a tie-break on snapshot_id DESC. Snapshots are retained for seven days; an expired one's files are deleted. File lists are not included here -- read one snapshot for those.", "operationId": "list_bulk_snapshots", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "1-indexed page number.", "title": "Page" }, "description": "1-indexed page number." }, { "name": "page_size", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Items per page (bounded).", "title": "Page Size" }, "description": "Items per page (bounded)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Deprecated alias.", "title": "Per Page" }, "description": "Deprecated alias." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSnapshotPage" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "scale", "x-rate-limit-class": "bulk" } }, "/v1/bulk/snapshots/{snapshot_id}": { "get": { "tags": [ "Bulk Export" ], "summary": "Read one bulk export snapshot's manifest", "description": "Return every file of one published snapshot: its path, dataset, partition, rows, bytes, sha256, and whether its bytes changed since the previous snapshot. A file whose changed flag is false carries the same sha256 as the previous snapshot's file at that path, so a sync can skip it. Pass 'latest' for the newest published snapshot.", "operationId": "get_bulk_snapshot", "parameters": [ { "name": "snapshot_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Snapshot identifier as YYYYMMDDTHHMMSSZ, or 'latest'.", "title": "Snapshot Id" }, "description": "Snapshot identifier as YYYYMMDDTHHMMSSZ, or 'latest'." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSnapshotManifestEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "scale", "x-rate-limit-class": "bulk" } }, "/v1/bulk/snapshots/{snapshot_id}/files/{file_path}": { "get": { "tags": [ "Bulk Export" ], "summary": "Issue a download URL for one snapshot file", "description": "Return a short-lived URL that reads one file of a published snapshot directly from object storage, beside the file's size and sha256. The path is the one the manifest lists. The URL carries its own credentials: fetch it without an API key, and within its expiry. Each URL is charged its file's full size against the organization's daily download allowance when it is issued. URLs are issued only to an organization that has accepted the current bulk-data license (GET /v1/bulk/license, POST /v1/bulk/license/acceptance); until then this answers 403 BULK_LICENSE_NOT_ACCEPTED.", "operationId": "get_bulk_snapshot_file_url", "parameters": [ { "name": "snapshot_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Snapshot identifier as YYYYMMDDTHHMMSSZ, or 'latest'.", "title": "Snapshot Id" }, "description": "Snapshot identifier as YYYYMMDDTHHMMSSZ, or 'latest'." }, { "name": "file_path", "in": "path", "required": true, "schema": { "type": "string", "description": "File path within the snapshot, as its manifest lists it.", "title": "File Path" }, "description": "File path within the snapshot, as its manifest lists it." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDownloadUrlEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "scale", "x-rate-limit-class": "bulk" } }, "/v1/bulk/license": { "get": { "tags": [ "Bulk Export" ], "summary": "Read the bulk-data license and whether it is accepted", "description": "Return the current bulk-data license -- its version, the SHA-256 of its text, and the text itself -- with whether the caller's organization has accepted it. Download URLs are issued only once it has. Accept it with POST /v1/bulk/license/acceptance, echoing license_version and license_sha256.", "operationId": "get_bulk_license", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLicenseEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-required-tier": "scale", "x-rate-limit-class": "bulk" } }, "/v1/bulk/license/acceptance": { "post": { "tags": [ "Bulk Export" ], "summary": "Accept the bulk-data license for the organization", "description": "Record the caller's organization's acceptance of the current bulk-data license. Send the license_version and license_sha256 GET /v1/bulk/license returned, which proves the acceptance is of that exact text; a version or digest that is not current answers 400 VALIDATION_ERROR with details.reason LICENSE_VERSION_MISMATCH. Name the person accepting, who confirms they may bind the organization. Answers 201 when the acceptance is recorded and 200 when the organization had already accepted this version, in which case the existing record is returned unchanged.", "operationId": "accept_bulk_license", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLicenseAcceptanceRequestHTTP" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkLicenseAcceptanceRecordEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Idempotency conflict.\n\n**Error codes:**\n- `IDEMPOTENCY_KEY_CONFLICT`: Idempotency-Key reused with different payload.\n- `IDEMPOTENCY_KEY_IN_PROGRESS`: Another request with the same Idempotency-Key is currently being processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "key_conflict": { "summary": "Payload conflict", "value": { "error": { "code": "IDEMPOTENCY_KEY_CONFLICT", "http_status": 409, "message": "Idempotency-Key reused with a different request payload.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "in_progress": { "summary": "In-progress conflict", "value": { "error": { "code": "IDEMPOTENCY_KEY_IN_PROGRESS", "http_status": 409, "message": "Another request with the same Idempotency-Key is in progress.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-required-tier": "scale", "x-rate-limit-class": "bulk" } }, "/v1/coverage/metrics": { "get": { "tags": [ "Coverage" ], "summary": "List metric coverage summaries", "description": "Return the EDGAR coverage and completeness summary for every canonical metric, each counted over every company Arche serves. A metric no company reports is listed with zero coverage. Deterministic ordering is metric ASC; metric is unique, so no tie-break is needed. Responses use the canonical PaginatedEnvelope.", "operationId": "list_metric_coverage", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1-200).", "default": 50, "title": "Page Size" }, "description": "Page size (1-200)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricCoverageSummaryPage" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/coverage/companies": { "get": { "tags": [ "Coverage" ], "summary": "List company coverage summaries", "description": "Return deterministic company-level EDGAR coverage and completeness summaries. Deterministic ordering is cik ASC, with a fixed tie-break. Responses use the canonical PaginatedEnvelope.", "operationId": "list_company_coverage", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 50, "title": "Page Size" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCoverageSummaryPage" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/coverage/companies/{cik}": { "get": { "tags": [ "Coverage" ], "summary": "Get company coverage summary", "description": "Return the company-level EDGAR coverage and completeness summary for one company, named by CIK or ticker. Responses use the canonical SuccessEnvelope or ErrorEnvelope.", "operationId": "get_company_coverage", "parameters": [ { "name": "cik", "in": "path", "required": true, "schema": { "type": "string", "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none.", "title": "Cik" }, "description": "Company CIK as digits (for example 0000320193), or a ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's as-of or period-end date, or as of today when the request has none." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCoverageSummaryEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/coverage/metrics/{metric}": { "get": { "tags": [ "Coverage" ], "summary": "Get metric coverage summary", "description": "Return the EDGAR coverage and completeness summary for one canonical metric, counted over every company Arche serves. Responses use the canonical SuccessEnvelope or ErrorEnvelope.", "operationId": "get_metric_coverage", "parameters": [ { "name": "metric", "in": "path", "required": true, "schema": { "type": "string", "title": "Metric" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricCoverageSummaryEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-rate-limit-class": "read" } }, "/v1/coverage/selection": { "get": { "tags": [ "Coverage" ], "summary": "Show the companies this plan covers", "description": "Return how the caller's coverage is decided, and, when it is the caller's own selection, which companies are held and when each slot frees itself. A company takes a slot the first time a request reaches it, and keeps it for as long as requests keep reaching it. Responses use the canonical SuccessEnvelope.", "operationId": "get_coverage_selection", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageSelectionEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "read" } }, "/v1/coverage/selection/release": { "post": { "tags": [ "Coverage" ], "summary": "Release one company's coverage slot", "description": "Give one company's slot back immediately rather than waiting out its window. Companies are claimed by querying them, so a mistyped identifier takes a slot; this is how it is returned. A release frees the slot but does not refund the claim: an organization may claim at most 30 companies in any 30 days, its 25 slots plus 5 corrections. Releasing a company that is not held succeeds and changes nothing. Responses use the canonical SuccessEnvelope.", "operationId": "release_coverage_slot", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageSelectionReleaseRequestHTTP" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageSelectionEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "read" } }, "/v1/agent/signup": { "post": { "tags": [ "Account" ], "summary": "Open a Free account for an agent's owner", "description": "Lets an AI agent open a Free Arche account with its owner's real email and receive a working API key without a browser. The key is returned once. The Free plan is sandbox-only, so it is a sandbox key; it reads the same data as a production key. Arche emails the owner an invitation; when the owner completes it, whichever email or existing login they sign in with, or signs up with that email, the account becomes theirs and the key keeps working. Until then the key stops working 14 days after the first signup. Signing up again with the same email before the owner claims the account replaces the key and keeps its expiry. An email that already has an Arche login is refused: its owner creates keys in the dashboard, as is one whose address without its `+` suffix has a login. No credentials are required. Responses use the canonical SuccessEnvelope.", "operationId": "agent_signup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignupRequestHTTP" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignupEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "read" } }, "/v1/agent/claim": { "post": { "tags": [ "Account" ], "summary": "Claim the account an agent opened", "description": "Makes the signed-in user the owner of the account an AI agent opened, named by the `agent_claim` token from the invitation Arche emailed the owner. The signed-in account must have the invited email verified: a login under another address adds and verifies that address in its account settings first, so a forwarded invitation claims nothing. The account's keys then stop expiring. Claiming an account this user already owns succeeds again. Requires a dashboard session token (Bearer), not an API key. Responses use the canonical SuccessEnvelope.", "operationId": "claim_agent_account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimRequestHTTP" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentClaimEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "read" } }, "/v1/agent/checkout-link": { "post": { "tags": [ "Account" ], "summary": "Get a payment link for the account's owner", "description": "Returns a checkout page for a self-serve plan, for the account the API key belongs to. Send the link to the account's owner: it asks them to sign in, or sign up with the account's email, before paying. A paid plan includes production keys, which the owner creates at https://app.arche.fi/keys. An account that already subscribes is refused with 409 and changes plan in the dashboard. Errors that a paid plan would lift name this endpoint in `details.checkout_link_endpoint`. Requires X-Api-Key. Responses use the canonical SuccessEnvelope.", "operationId": "create_agent_checkout_link", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AgentCheckoutLinkRequestHTTP" }, { "type": "null" } ], "title": "Payload" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCheckoutLinkEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "read" } }, "/v1/ai/companies/{company_id}/anomaly-explanations": { "get": { "tags": [ "AI" ], "summary": "Anomaly explanations", "description": "Return AI explanations of the data-quality anomalies found in a company's statements. Deterministic ordering: stable sort with a fixed tie-break, so pages never overlap.", "operationId": "list_anomaly_explanations", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date.", "title": "Company Id" }, "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date." }, { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Point-in-time boundary (YYYY-MM-DD). Must match a provisioned as-of snapshot with generated artifacts for the company; other dates return 404. Materialize snapshots with GET /v1/edgar/as-of/{date}/financials/{cik}.", "title": "As Of" }, "description": "Point-in-time boundary (YYYY-MM-DD). Must match a provisioned as-of snapshot with generated artifacts for the company; other dates return 404. Materialize snapshots with GET /v1/edgar/as-of/{date}/financials/{cik}." }, { "name": "min_severity", "in": "query", "required": false, "schema": { "anyOf": [ { "$ref": "#/components/schemas/MaterialityClass" }, { "type": "null" } ], "description": "Optional minimum severity filter.", "title": "Min Severity" }, "description": "Optional minimum severity filter." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1-200).", "default": 50, "title": "Page Size" }, "description": "Page size (1-200)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnomalyExplanationPage" }, "example": { "page": 1, "page_size": 1, "total": 1, "items": [ { "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "as_of_timestamp": "2024-09-28T23:59:59.999999Z", "statement_type": "INCOME_STATEMENT", "fiscal_year": 2024, "fiscal_period": "FY", "metric_code": "OTHER_OPERATING_INCOME_EXPENSE", "dimension_key": "", "severity": "LOW", "reason_codes": [ "METRIC_NOT_REPORTED" ], "rationale": "The filing reports no separate other operating income or expense line, so the metric is absent rather than zero.", "impacted_metrics": [], "created_at": "2024-11-02T03:21:04Z" } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "scale", "x-rate-limit-class": "read" } }, "/v1/ai/companies/{company_id}/narratives": { "get": { "tags": [ "AI" ], "summary": "Financial narratives", "description": "Return plain-language narratives of how a company's figures moved. Deterministic ordering: stable sort with a fixed tie-break, so pages never overlap.", "operationId": "list_narratives", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date.", "title": "Company Id" }, "description": "Company id (UUID), CIK as digits (for example 0000320193), or ticker symbol (for example AAPL). A ticker resolves to the company whose filings hold its statements as of the request's `as_of` date." }, { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "description": "Point-in-time boundary (YYYY-MM-DD). Must match a provisioned as-of snapshot with generated artifacts for the company; other dates return 404. Materialize snapshots with GET /v1/edgar/as-of/{date}/financials/{cik}.", "title": "As Of" }, "description": "Point-in-time boundary (YYYY-MM-DD). Must match a provisioned as-of snapshot with generated artifacts for the company; other dates return 404. Materialize snapshots with GET /v1/edgar/as-of/{date}/financials/{cik}." }, { "name": "narrative_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/NarrativeType", "description": "Narrative type selector." }, "description": "Narrative type selector." }, { "name": "statement_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/StatementType", "description": "Statement type for narrative inputs.", "default": "INCOME_STATEMENT" }, "description": "Statement type for narrative inputs." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "1-based page index.", "default": 1, "title": "Page" }, "description": "1-based page index." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "description": "Page size (1-200).", "default": 50, "title": "Page Size" }, "description": "Page size (1-200)." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NarrativePage" }, "example": { "page": 1, "page_size": 1, "total": 1, "items": [ { "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "cik": "0000320193", "as_of_timestamp": "2024-09-28T23:59:59.999999Z", "narrative_type": "CHANGE_SUMMARY", "window_label": "FY2023 to FY2024", "input_hash": "e3b0c44298fc1c149afbf4c8996fb924", "narrative_text": "Revenue rose 2.0% to $391.0B while gross margin widened to 46.2%, lifting operating income 12.0% to $123.2B.", "citations": [ { "metric_code": "REVENUE", "period": "FY2024", "value": "391035000000", "comparison": "383285000000" }, { "metric_code": "GROSS_PROFIT", "period": "FY2024", "value": "180683000000", "comparison": "169148000000" } ], "created_at": "2024-11-02T03:20:41Z" } ] } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "narrative_as_of_unavailable": { "summary": "No figures as of the date", "value": { "error": { "code": "NARRATIVE_AS_OF_UNAVAILABLE", "http_status": 404, "message": "No figures to narrate for this company as of the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "narrative_insufficient_history": { "summary": "Fewer than two comparable periods", "value": { "error": { "code": "NARRATIVE_INSUFFICIENT_HISTORY", "http_status": 404, "message": "Not enough periods to build narrative summary.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "narrative_metrics_unavailable": { "summary": "No cited metric in both periods", "value": { "error": { "code": "NARRATIVE_METRICS_UNAVAILABLE", "http_status": 404, "message": "No metrics available to build narrative summary.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-tier": "growth", "x-rate-limit-class": "read" } }, "/v1/account/webhook-subscriptions": { "get": { "tags": [ "Webhooks" ], "summary": "List account webhook subscriptions", "description": "List the organization's outbound webhook subscriptions for restatement alerts. Signing secrets are not returned here; only create and rotate-secret return one.\n\nAuthenticated with a dashboard session, not an API key: send a bearer token carrying `control_plane:read`. An API key is refused with `401 Missing bearer token`.", "operationId": "list_webhook_subscriptions", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionListEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "security": [ { "BearerAuth": [] } ], "x-rate-limit-class": "read" }, "post": { "tags": [ "Webhooks" ], "summary": "Create account webhook subscription", "description": "Create an outbound webhook subscription for restatement alerts. The response carries the subscription's signing secret; store it, since listing does not return it. Creating a subscription that already exists returns it with its current secret, and spends no slot.\n\n`event_type` accepts `restatement.detected` only, and `target_url` must be `https://`.\n\n**How many you may register.** The plan decides: Developer allows three, and Growth and above are uncapped, unless a negotiated limit is stored on the entitlement. A plan that does not include webhooks at all is refused with `403 FEATURE_NOT_AVAILABLE`, naming the plan that does. Creating one past the limit is refused with `409 WEBHOOK_SUBSCRIPTION_LIMIT_REACHED`, whose `details` name the limit and how many are held; delete a subscription to free a slot.\n\nAuthenticated with a dashboard session, not an API key: send a bearer token carrying `control_plane:write`. An API key is refused with `401 Missing bearer token`.", "operationId": "create_webhook_subscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionCreateRequestHTTP" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionWithSecretEnvelope" } } } }, "400": { "description": "Bad request. A parameter failed validation, `event_type` is not `restatement.detected`, or `target_url` is not `https://`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The organization already holds as many subscriptions as its plan allows. `details` names the limit and how many are held; delete a subscription to free a slot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "webhook_subscription_limit_reached": { "summary": "Plan's subscription limit reached", "value": { "error": { "code": "WEBHOOK_SUBSCRIPTION_LIMIT_REACHED", "http_status": 409, "message": "webhook_subscription_limit_reached", "details": { "limit": 3, "held": 3 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "security": [ { "BearerAuth": [] } ], "x-required-tier": "developer", "x-rate-limit-class": "read" } }, "/v1/account/webhook-subscriptions/{subscription_id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate a webhook subscription's signing secret", "description": "Issue a new signing secret for one of the organization's webhook subscriptions. Deliveries sent after this call are signed with the new secret, with no window in which both are valid. Use this to obtain a secret for a subscription created before per-subscription secrets existed.\n\nA plan that does not include webhooks is refused with `403 FEATURE_NOT_AVAILABLE`, and a subscription belonging to another organization with `404 webhook_subscription_not_found`.\n\nAuthenticated with a dashboard session, not an API key: send a bearer token carrying `control_plane:write`. An API key is refused with `401 Missing bearer token`.", "operationId": "rotate_webhook_secret", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Subscription Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionWithSecretEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ], "x-required-tier": "developer", "x-rate-limit-class": "read" } }, "/v1/account/webhook-subscriptions/{subscription_id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Delete account webhook subscription", "description": "Delete one of the organization's webhook subscriptions. Deliveries to its endpoint stop, including pending retries; restatement alerts remain available from the alerts endpoint, and the slot is freed for another subscription. A subscription belonging to another organization is refused with `404 webhook_subscription_not_found`.\n\nAuthenticated with a dashboard session, not an API key: send a bearer token carrying `control_plane:write`. An API key is refused with `401 Missing bearer token`.", "operationId": "delete_webhook_subscription", "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "title": "Subscription Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSubscriptionEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } }, "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerAuth": [] } ], "x-rate-limit-class": "read" } }, "/mcp": { "post": { "tags": [ "MCP" ], "summary": "Call the MCP server.", "description": "Model Context Protocol endpoint, speaking Streamable HTTP in JSON response mode. A body carrying a `jsonrpc` member is a JSON-RPC 2.0 message or batch: `initialize`, `ping`, `tools/list` and `tools/call` are supported, and notifications are acknowledged with 202. Tools, the plan each one requires and the enforced rate limits are published at `GET /mcp/manifest`. Requests are metered under the `mcp` rate-limit class. A body of the form `{method, params}` keeps the pre-existing envelope contract for current callers.", "operationId": "call_mcp", "requestBody": { "content": { "application/json": { "schema": { "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "integer", "null" ] }, "method": { "type": "string", "description": "`initialize`, `ping`, `tools/list`, `tools/call`, or a notification.", "examples": [ "tools/call" ] }, "params": { "type": "object" } }, "type": "object", "required": [ "jsonrpc", "method" ], "examples": [ { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "companies_resolve", "arguments": { "ticker": "AAPL" } } } ] } } }, "required": true }, "responses": { "200": { "description": "JSON-RPC response or legacy MCP envelope", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "items": { "type": "object" }, "type": "array" } ] } } } }, "202": { "description": "JSON-RPC notification accepted" }, "404": { "description": "Unknown MCP method (legacy envelope)" }, "413": { "description": "Request payload too large" }, "422": { "description": "Request validation error (legacy envelope)" }, "500": { "description": "MCP server failure" } }, "x-rate-limit-class": "mcp" } }, "/mcp/manifest": { "get": { "tags": [ "MCP" ], "summary": "Describe the MCP surface.", "description": "Return how to connect to the MCP endpoint (`POST /mcp`) and what it offers: every tool with its input schema and the least-entitled plan that may call it, and the `mcp` rate-limit class with the limit each plan is metered against; Enterprise limits are negotiated per agreement and carry no figure. MCP access is included on every plan; a tool above the caller's plan answers with a `FEATURE_NOT_AVAILABLE` tool error. No API key is required to read this document.", "operationId": "get_mcp_manifest", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPManifestEnvelope" } } } }, "400": { "description": "Bad request. A query parameter or path parameter failed the route's own validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Invalid parameter", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 400, "message": "Request validation failed", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "401": { "description": "Unauthorized. The API key is missing, malformed, or not recognized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "missing_api_key": { "summary": "No API key supplied", "value": { "error": { "code": "MISSING_API_KEY", "http_status": 401, "message": "API key required.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "invalid_api_key": { "summary": "API key not recognized", "value": { "error": { "code": "INVALID_API_KEY", "http_status": 401, "message": "API key is invalid or revoked.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "403": { "description": "Forbidden. The caller is authenticated but the plan does not cover this endpoint or this company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "feature_not_available": { "summary": "Plan does not cover the feature", "value": { "error": { "code": "FEATURE_NOT_AVAILABLE", "http_status": 403, "message": "This feature requires the growth plan or higher.", "details": { "required_tier": "growth", "current_tier": "developer" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "forbidden": { "summary": "Key not permitted", "value": { "error": { "code": "FORBIDDEN", "http_status": 403, "message": "API key is not permitted to access this resource.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "404": { "description": "Not found. No record matches the requested identifiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "not_found": { "summary": "No matching record", "value": { "error": { "code": "NOT_FOUND", "http_status": 404, "message": "No data found for the requested identifiers.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "409": { "description": "Conflict. The request matched more than one record and was refused rather than resolved arbitrarily. The specific code depends on the identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "ticker_ambiguous": { "summary": "Ambiguous ticker", "value": { "error": { "code": "TICKER_AMBIGUOUS", "http_status": 409, "message": "Ticker resolves to more than one company on the requested date.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "422": { "description": "Unprocessable content. The request body or query schema failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "validation_error": { "summary": "Schema validation failed", "value": { "error": { "code": "VALIDATION_ERROR", "http_status": 422, "message": "Request validation failed", "details": { "errors": [ { "type": "int_parsing", "loc": [ "query", "page" ], "msg": "Input should be a valid integer, unable to parse string as an integer", "input": "first" } ], "error_count": 1 }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "429": { "description": "Rate limit exceeded. `Retry-After` and the `X-RateLimit-*` headers carry the window state. `MONTHLY_QUOTA_EXCEEDED` means the organization's monthly request quota is spent; the `X-Quota-*` headers carry its state and `Retry-After` counts to the start of the next calendar month (UTC).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "code": "RATE_LIMITED", "http_status": 429, "message": "Rate limit exceeded. Retry after the interval in Retry-After.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "monthly_quota_exceeded": { "summary": "Monthly request quota exhausted", "value": { "error": { "code": "MONTHLY_QUOTA_EXCEEDED", "http_status": 429, "message": "Monthly request quota exhausted", "details": { "limit": 2000, "used": 2000, "remaining": 0, "reset_epoch": 1793491200, "retry_after_s": 86400, "tier": "free", "period": "2026-10" }, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "500": { "description": "Internal server error. The failure is logged against the trace id and no internals are exposed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "internal_error": { "summary": "Unhandled server error", "value": { "error": { "code": "INTERNAL_ERROR", "http_status": 500, "message": "Internal server error", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } }, "503": { "description": "Service unavailable. A dependency the request needs could not be reached or evaluated; the request is refused rather than answered from a guess.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "universe_unavailable": { "summary": "Plan coverage not evaluable", "value": { "error": { "code": "UNIVERSE_UNAVAILABLE", "http_status": 503, "message": "Plan coverage could not be evaluated. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } }, "service_unavailable": { "summary": "Dependency unavailable", "value": { "error": { "code": "SERVICE_UNAVAILABLE", "http_status": 503, "message": "A required dependency is unavailable. Retry later.", "details": {}, "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } } } } } } }, "x-rate-limit-class": "mcp" } } }, "components": { "schemas": { "AccountingStandard": { "type": "string", "enum": [ "US_GAAP", "IFRS", "OTHER" ], "title": "AccountingStandard", "description": "Accounting standards used in EDGAR filings." }, "AgentCheckoutLinkHTTP": { "properties": { "checkout_url": { "type": "string", "title": "Checkout Url", "description": "Payment page for the account's owner. It asks the owner to sign in, or sign up with the account's email, before paying. A paid plan includes production keys, which the owner creates at https://app.arche.fi/keys." }, "plan": { "type": "string", "title": "Plan", "description": "Plan the checkout buys." }, "interval": { "type": "string", "title": "Interval", "description": "Billing interval of the price." }, "amount": { "type": "string", "title": "Amount", "description": "Price per interval in the currency's minor units, as a decimal string." }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency code." } }, "additionalProperties": false, "type": "object", "required": [ "checkout_url", "plan", "interval", "amount", "currency" ], "title": "AgentCheckoutLinkHTTP", "description": "HTTP schema for a payment link the agent hands its owner.", "examples": [ { "amount": "14900", "checkout_url": "https://app.arche.fi/billing?_ptxn=txn_01jabc3k9v2m8q4r6t0w5y7z1x", "currency": "USD", "interval": "month", "plan": "developer" } ] }, "AgentCheckoutLinkRequestHTTP": { "properties": { "plan": { "type": "string", "enum": [ "developer", "growth", "scale" ], "title": "Plan", "description": "Plan the owner would buy. Developer covers every company Arche serves.", "default": "developer" }, "interval": { "type": "string", "enum": [ "month", "year" ], "title": "Interval", "description": "Billing interval of the price.", "default": "month" } }, "additionalProperties": false, "type": "object", "title": "AgentCheckoutLinkRequestHTTP", "description": "HTTP schema for requesting a payment link for the owner.", "examples": [ { "interval": "month", "plan": "developer" } ] }, "AgentClaimHTTP": { "properties": { "org_id": { "type": "string", "title": "Org Id", "description": "The organization the agent opened, which the signed-in user now owns. Send it as X-Org-Id to act on it in the dashboard API." }, "claimed": { "type": "boolean", "title": "Claimed", "description": "True when this call claimed the account; false when this user already had." } }, "additionalProperties": false, "type": "object", "required": [ "org_id", "claimed" ], "title": "AgentClaimHTTP", "description": "HTTP schema for an account an owner claimed.", "examples": [ { "claimed": true, "org_id": "0b8e6c1d-4f2a-4e57-9c3b-7a1d2e5f8c90" } ] }, "AgentClaimRequestHTTP": { "properties": { "claim_token": { "type": "string", "maxLength": 256, "minLength": 1, "title": "Claim Token", "description": "The `agent_claim` value from the invitation link Arche emailed the owner." } }, "additionalProperties": false, "type": "object", "required": [ "claim_token" ], "title": "AgentClaimRequestHTTP", "description": "HTTP schema for an owner claiming the account an agent opened.", "examples": [ { "claim_token": "3f0c9a2e7b6d4c1e8a5f2b9d0e7c4a61.Qx3vN8kR2mT5pW9yB1cD4fG7hJ0lZ6sA_eU-oI3rV8w" } ] }, "AgentSignupHTTP": { "properties": { "api_key": { "type": "string", "title": "Api Key", "description": "The API key. It is shown once and cannot be retrieved again; send it in the X-Api-Key header. The Free plan is sandbox-only, so it is a sandbox key, which reads the same data as a production key. Signing up again with the same email before the owner claims the account replaces it." }, "plan": { "type": "string", "const": "free", "title": "Plan", "description": "The account's plan." }, "owner_email": { "type": "string", "title": "Owner Email", "description": "The owner email the account was opened with." }, "owner_notified": { "type": "boolean", "title": "Owner Notified", "description": "True when the owner has been emailed an invitation. False when the email could not be sent; signing up again retries it." }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At", "description": "When the key stops working unless the owner claims the account, by completing the emailed invitation or signing in at `claim_url` with `owner_email`. Signing up again does not move it." }, "claim_url": { "type": "string", "title": "Claim Url", "description": "Where the owner signs in to take over the account and keep the key working." }, "checkout_link_endpoint": { "type": "string", "title": "Checkout Link Endpoint", "description": "Endpoint that returns a payment link for the owner when a call needs a paid plan." } }, "additionalProperties": false, "type": "object", "required": [ "api_key", "plan", "owner_email", "owner_notified", "expires_at", "claim_url", "checkout_link_endpoint" ], "title": "AgentSignupHTTP", "description": "HTTP schema for the key issued to an agent.", "examples": [ { "api_key": "ak_test_9fQ2xAqLrT0mW5bZcY7dNe3uHs1vKp8jGi4oXl6wRtE", "checkout_link_endpoint": "/v1/agent/checkout-link", "claim_url": "https://app.arche.fi/sign-up", "expires_at": "2026-10-25T09:30:00Z", "owner_email": "owner@yourcompany.com", "owner_notified": true, "plan": "free" } ] }, "AgentSignupRequestHTTP": { "properties": { "email": { "type": "string", "maxLength": 254, "minLength": 3, "title": "Email", "description": "The owner's real email address. Arche emails the owner an invitation to sign in and take over the account. Placeholder domains are refused." }, "agent_name": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Agent Name", "description": "A name for the agent, shown to the owner as the key's name." } }, "additionalProperties": false, "type": "object", "required": [ "email", "agent_name" ], "title": "AgentSignupRequestHTTP", "description": "HTTP schema for an agent opening a Free account for its owner.", "examples": [ { "agent_name": "research-assistant", "email": "owner@yourcompany.com" } ] }, "AnomalyExplanationHTTP": { "properties": { "company_id": { "type": "string", "format": "uuid", "title": "Company Id", "description": "Company identifier." }, "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "as_of_timestamp": { "type": "string", "format": "date-time", "title": "As Of Timestamp", "description": "As-of snapshot timestamp (UTC)." }, "statement_type": { "anyOf": [ { "$ref": "#/components/schemas/StatementType" }, { "type": "null" } ], "description": "Statement type context for the anomaly." }, "fiscal_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fiscal Year", "description": "Fiscal year context." }, "fiscal_period": { "anyOf": [ { "$ref": "#/components/schemas/FiscalPeriod" }, { "type": "null" } ], "description": "Fiscal period context." }, "metric_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Metric Code", "description": "Metric code, when applicable." }, "dimension_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dimension Key", "description": "Dimension key, when applicable." }, "severity": { "$ref": "#/components/schemas/MaterialityClass", "description": "Anomaly severity classification." }, "reason_codes": { "items": { "type": "string" }, "type": "array", "title": "Reason Codes", "description": "Reason codes used in the explanation." }, "rationale": { "type": "string", "title": "Rationale", "description": "Human-readable rationale." }, "impacted_metrics": { "items": { "$ref": "#/components/schemas/AnomalyImpactHTTP" }, "type": "array", "title": "Impacted Metrics", "description": "Impacted metrics referenced by the explanation." }, "historical_baseline": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Historical Baseline", "description": "Historical baseline summary." }, "peer_baseline": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Peer Baseline", "description": "Peer baseline summary." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Creation timestamp (UTC)." } }, "additionalProperties": false, "type": "object", "required": [ "company_id", "cik", "as_of_timestamp", "severity", "reason_codes", "rationale", "impacted_metrics", "created_at" ], "title": "AnomalyExplanationHTTP", "description": "HTTP schema for an anomaly explanation." }, "AnomalyImpactHTTP": { "properties": { "metric_code": { "type": "string", "title": "Metric Code", "description": "Canonical metric code impacted." }, "dimension_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dimension Key", "description": "Dimension key impacted, when applicable." } }, "additionalProperties": false, "type": "object", "required": [ "metric_code" ], "title": "AnomalyImpactHTTP", "description": "HTTP schema for impacted metrics in anomaly explanations." }, "AsOfDataQualityHTTP": { "properties": { "evaluated_rule_count": { "type": "integer", "minimum": 0.0, "title": "Evaluated Rule Count", "description": "Data-quality rules checked across the snapshot's statements. A rule that could not be checked (NOT_EVALUATED) is not counted." }, "passed_rule_count": { "type": "integer", "minimum": 0.0, "title": "Passed Rule Count", "description": "Checked data-quality rules that passed." }, "total_rule_count": { "type": "integer", "minimum": 0.0, "title": "Total Rule Count", "description": "Data-quality rules in scope, whether or not they could be checked." }, "not_evaluated_metric_count": { "type": "integer", "minimum": 0.0, "title": "Not Evaluated Metric Count", "description": "Metrics none of whose data-quality rules could be checked." }, "pass_rate": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Pass Rate", "description": "passed_rule_count over evaluated_rule_count, in [0,1] to four places. Null when no rule could be checked: an unchecked rule is neither a pass nor a fail." } }, "additionalProperties": false, "type": "object", "required": [ "evaluated_rule_count", "passed_rule_count", "total_rule_count", "not_evaluated_metric_count", "pass_rate" ], "title": "AsOfDataQualityHTTP", "description": "Data-quality findings summed over every statement in the snapshot." }, "AsOfMetaHTTP": { "properties": { "reconciliation": { "$ref": "#/components/schemas/ReconciliationMetaHTTP", "description": "Reconciliation metadata for as-of response." }, "data_quality": { "$ref": "#/components/schemas/AsOfDataQualityHTTP", "description": "Data-quality findings summed over the snapshot's statements." }, "availability": { "anyOf": [ { "$ref": "#/components/schemas/EndpointAvailabilityHTTP" }, { "type": "null" } ], "description": "Availability of the snapshot's statements as a whole, not of any one period." } }, "additionalProperties": false, "type": "object", "required": [ "reconciliation", "data_quality" ], "title": "AsOfMetaHTTP", "description": "As-of metadata container." }, "AsOfPageFactHTTP": { "properties": { "metric": { "type": "string", "title": "Metric", "description": "Canonical metric code (e.g., REVENUE, NET_INCOME)." }, "unit": { "type": "string", "title": "Unit", "description": "Unit code for the value (e.g., ISO 4217 currency code such as USD)." }, "value": { "type": "string", "title": "Value", "description": "Value as filed, as a decimal string in full units." }, "period_start": { "type": "string", "format": "date", "title": "Period Start", "description": "Inclusive start date of the reporting period." }, "period_end": { "type": "string", "format": "date", "title": "Period End", "description": "Inclusive end date of the reporting period." }, "source_line_item": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Line Item", "description": "Source XBRL concept the value was reported under, when recorded." }, "value_origin": { "type": "string", "title": "Value Origin", "description": "'SOURCE' (as reported by the filer), 'DERIVED' (computed from other reported values by an exact accounting identity) or 'UNRECORDED' (the origin was not captured)." }, "period_origin": { "type": "string", "title": "Period Origin", "description": "'SOURCE' (the span as filed), 'DERIVED' (inferred from the fiscal period and period_end) or 'INSTANT' (a balance-sheet instant, period_start equal to period_end)." }, "correction_rule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Correction Rule", "description": "Present only when a correction changed the value as tagged: the stable identifier of that correction. Check it before relying on the figure." }, "as_filed_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "As Filed Value", "description": "Present only with correction_rule: the value as the filing tagged it." }, "as_filed_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "As Filed Concept", "description": "Present only with correction_rule, when the correction replaced one selection with another: the concept the superseded value came from." }, "split_adjusted_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Split Adjusted Value", "description": "Present only when a later stock split applies to this share-denominated metric: the value restated into current share terms. value stays as filed." }, "split_adjustment_factor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Split Adjustment Factor", "description": "Present with split_adjusted_value: the cumulative split ratio applied." }, "dimension": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Dimension", "description": "Present only for a fact outside the consolidated default dimension." }, "dimension_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dimension Key", "description": "Present with dimension: the fact's stable dimension key." }, "usd": { "anyOf": [ { "$ref": "#/components/schemas/UsdValueHTTP" }, { "type": "null" } ], "description": "Present only when include_usd=true and the value converts: the value in US dollars, with its rate, the rate's dates and its source. Absent for a value that is not money (a share count), and when no rate covers its period: the Federal Reserve Board's H.10 release publishes rates for 22 currencies, and an as-of request uses only rates published by its date. value always stays as filed." } }, "additionalProperties": false, "type": "object", "required": [ "metric", "unit", "value", "period_start", "period_end", "value_origin", "period_origin" ], "title": "AsOfPageFactHTTP", "description": "One fact of a statement on an as-of page.\n\nThe correction, split-adjustment and dimension fields are present only when\nthey say something: a corrected value names its rule, and a fact outside the\nconsolidated default names its dimension." }, "AsOfPageMetricProvenanceHTTP": { "properties": { "xbrl_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Xbrl Concept", "description": "Source XBRL concept QName (e.g., us-gaap:Revenues), when recorded." }, "mapping_type": { "anyOf": [ { "type": "string", "enum": [ "DIRECT", "FALLBACK", "CALCULATED", "INFERRED", "UNKNOWN" ] }, { "type": "null" } ], "title": "Mapping Type", "description": "How the metric was mapped: DIRECT, FALLBACK, CALCULATED, INFERRED or UNKNOWN." }, "filing_accession": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filing Accession", "description": "Present only when the metric was taken from a filing other than the statement's own accession_id." }, "override_applied": { "type": "boolean", "title": "Override Applied", "description": "Present (true) only when an override rule set this metric. Check it before relying on the figure.", "default": false }, "override_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Override Reason", "description": "Present with override_applied when the override records a reason." } }, "additionalProperties": false, "type": "object", "title": "AsOfPageMetricProvenanceHTTP", "description": "Where one metric of a statement on an as-of page came from." }, "AsOfPageNormalizedStatementHTTP": { "properties": { "_meta": { "anyOf": [ { "$ref": "#/components/schemas/AsOfPageStatementMetaHTTP" }, { "type": "null" } ], "description": "Per-metric provenance, and the metrics withheld from the statement." }, "facts": { "items": { "$ref": "#/components/schemas/AsOfPageFactHTTP" }, "type": "array", "title": "Facts", "description": "The statement's facts, ordered by metric code." } }, "additionalProperties": false, "type": "object", "title": "AsOfPageNormalizedStatementHTTP", "description": "The facts of a statement on an as-of page, with their provenance." }, "AsOfPageStatementHTTP": { "properties": { "accession_id": { "type": "string", "title": "Accession Id", "description": "SEC accession of the filing that reported this statement. With cik, statement_type, fiscal_year and fiscal_period it identifies the statement." }, "cik": { "type": "string", "title": "Cik", "description": "Central Index Key of the filer." }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name", "description": "Company name, when known." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement type." }, "accounting_standard": { "$ref": "#/components/schemas/AccountingStandard", "description": "Accounting standard." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Statement period end date." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year of the statement." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period within the year. FY is a whole fiscal year: 358 to 372 days, or the year the filer declares. Q1-Q4 are quarters and H1 a half year. OTHER is any other reported span: a transition period, a short first year, or one of the two periods of a fiscal year split at a business combination or fresh-start reorganization. An OTHER period's dates are period_start and statement_date, and two OTHER periods are never added together into a year." }, "period_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period Start", "description": "First day of the period the statement reports; statement_date is the last. Null for a balance sheet, which reports a single date, and when the filing's span is not available." }, "reporting_entity": { "type": "string", "enum": [ "REGISTRANT", "PREDECESSOR" ], "title": "Reporting Entity", "description": "PREDECESSOR when the filing presents this period as its predecessor's: the business the registrant succeeded in a business combination or fresh-start reorganization, which it reports as its own history; otherwise REGISTRANT.", "default": "REGISTRANT" }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency code for reported values." }, "filing_type": { "type": "string", "title": "Filing Type", "description": "SEC form of the filing as the SEC lists it; an amendment carries the /A suffix (e.g. 10-K, 10-Q, 10-K/A)." }, "filing_date": { "type": "string", "format": "date", "title": "Filing Date", "description": "SEC filing date of the filing." }, "accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Accepted At", "description": "SEC acceptance time of the filing (UTC), when recorded." }, "is_amendment": { "type": "boolean", "title": "Is Amendment", "description": "Whether the filing amends a prior filing." }, "amendment_sequence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amendment Sequence", "description": "Present only for an amendment: the SEC's amendment sequence number." }, "is_restated": { "type": "boolean", "title": "Is Restated", "description": "Whether the statement is a restatement." }, "values": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Values", "description": "The statement's consolidated figures for its own period, one entry per metric code (e.g., REVENUE, NET_INCOME), each a decimal string in full units as filed. A metric the filing did not report is absent." }, "units": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Units", "description": "The unit of each entry in values, keyed by the same metric code." }, "usd": { "anyOf": [ { "$ref": "#/components/schemas/StatementUsdHTTP" }, { "type": "null" } ], "description": "Present only when include_usd=true and the statement converts: its money values in US dollars, with the rate, the rate's dates and its source. Absent when no rate covers the statement's period: the Federal Reserve Board's H.10 release publishes rates for 22 currencies, and an as-of request uses only rates published by its date. values always stay as filed." }, "content": { "anyOf": [ { "$ref": "#/components/schemas/AsOfPageNormalizedStatementHTTP" }, { "type": "null" } ], "description": "The statement's facts and their provenance. Null unless the request sets detail=true." }, "quality": { "anyOf": [ { "$ref": "#/components/schemas/StatementQualityHTTP" }, { "type": "null" } ], "description": "The statement's quality, part by part: metric completeness, reconciliation results, data-quality findings and how its metrics were mapped. Null unless the request sets detail=true." } }, "additionalProperties": false, "type": "object", "required": [ "accession_id", "cik", "statement_type", "accounting_standard", "statement_date", "fiscal_year", "fiscal_period", "currency", "filing_type", "filing_date", "is_amendment", "is_restated" ], "title": "AsOfPageStatementHTTP", "description": "One statement on an as-of page: its identity, its filing and its figures." }, "AsOfPageStatementMetaHTTP": { "properties": { "provenance": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/AsOfPageMetricProvenanceHTTP" }, "type": "object" }, { "type": "null" } ], "title": "Provenance", "description": "Per-metric provenance keyed by metric code." }, "withheld_metrics": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/WithheldMetricHTTP" }, "type": "object" }, { "type": "null" } ], "title": "Withheld Metrics", "description": "Present only when the filing reported a metric that is not served: the rule that withheld it, the figure as filed and its concept, keyed by metric code." } }, "additionalProperties": false, "type": "object", "title": "AsOfPageStatementMetaHTTP", "description": "Per-metric metadata of a statement on an as-of page.\n\n``provenance`` is always returned; ``withheld_metrics`` only when a metric\nwas withheld. The statement's quality is in its ``quality`` field." }, "AsReportedConceptHTTP": { "properties": { "concept": { "type": "string", "title": "Concept", "description": "Qualified XBRL concept, taxonomy prefix and name.", "examples": [ "us-gaap:ResearchAndDevelopmentExpense" ] }, "taxonomy": { "type": "string", "title": "Taxonomy", "description": "Taxonomy the concept belongs to: us-gaap, ifrs-full, dei, srt or invest." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "The taxonomy's standard label." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "The taxonomy's definition of the concept." }, "units": { "items": { "type": "string" }, "type": "array", "title": "Units", "description": "Units the company reported the concept in." }, "fact_count": { "type": "integer", "minimum": 0.0, "title": "Fact Count", "description": "Number of values reported under the concept." }, "first_period_end": { "type": "string", "format": "date", "title": "First Period End", "description": "Earliest period end reported." }, "last_period_end": { "type": "string", "format": "date", "title": "Last Period End", "description": "Latest period end reported." } }, "additionalProperties": false, "type": "object", "required": [ "concept", "taxonomy", "units", "fact_count", "first_period_end", "last_period_end" ], "title": "AsReportedConceptHTTP", "description": "One XBRL concept a company reported, with what it reported under it.", "examples": [ { "concept": "us-gaap:ResearchAndDevelopmentExpense", "description": "The aggregate costs incurred (1) in a planned search or critical investigation aimed at discovery of new knowledge ...", "fact_count": 234, "first_period_end": "2007-09-29", "label": "Research and Development Expense", "last_period_end": "2026-06-27", "taxonomy": "us-gaap", "units": [ "USD" ] } ] }, "AsReportedFactHTTP": { "properties": { "concept": { "type": "string", "title": "Concept", "description": "Qualified XBRL concept, taxonomy prefix and name." }, "unit": { "type": "string", "title": "Unit", "description": "Unit of measure, e.g. USD, shares or USD/shares.", "examples": [ "USD" ] }, "value": { "type": "string", "title": "Value", "description": "The value exactly as reported, as a decimal string." }, "period_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period Start", "description": "First day of the period; null for a value at a point in time." }, "period_end": { "type": "string", "format": "date", "title": "Period End", "description": "Last day of the period, or the date of a point-in-time value." }, "accession_id": { "type": "string", "title": "Accession Id", "description": "Accession of the filing that reported the value." }, "filing_type": { "type": "string", "title": "Filing Type", "description": "Form of that filing, e.g. 10-K, 10-Q or 10-K/A." }, "filing_date": { "type": "string", "format": "date", "title": "Filing Date", "description": "Date SEC received that filing." }, "fiscal_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fiscal Year", "description": "Fiscal year of the filing that reported the value. A 10-K reports earlier years as comparatives, so this can differ from the value's own period." }, "fiscal_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fiscal Period", "description": "Fiscal period of the filing that reported the value: FY, Q1, Q2 or Q3." }, "frame": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Frame", "description": "SEC's calendar frame when SEC chose this value to represent one, e.g. CY2025 for a calendar year, CY2025Q4 for a quarter, CY2025Q4I for an instant. Taking only framed values gives one value per concept, unit and period." } }, "additionalProperties": false, "type": "object", "required": [ "concept", "unit", "value", "period_end", "accession_id", "filing_type", "filing_date" ], "title": "AsReportedFactHTTP", "description": "One value a filing reported for one XBRL concept, unit and period.", "examples": [ { "accession_id": "0000320193-25-000079", "concept": "us-gaap:ResearchAndDevelopmentExpense", "filing_date": "2025-10-31", "filing_type": "10-K", "fiscal_period": "FY", "fiscal_year": 2025, "frame": "CY2025", "period_end": "2025-09-27", "period_start": "2024-09-29", "unit": "USD", "value": "34550000000" } ] }, "BulkColumnHTTP": { "properties": { "name": { "type": "string", "title": "Name", "description": "Column name, as it appears in the Parquet files." }, "type": { "type": "string", "title": "Type", "description": "Logical column type: string, string_list, decimal, integer, boolean, date or timestamp." }, "nullable": { "type": "boolean", "title": "Nullable", "description": "Whether the column may hold nulls." }, "description": { "type": "string", "title": "Description", "description": "What the column holds." } }, "additionalProperties": false, "type": "object", "required": [ "name", "type", "nullable", "description" ], "title": "BulkColumnHTTP", "description": "One column of an exported dataset." }, "BulkDatasetHTTP": { "properties": { "dataset": { "type": "string", "title": "Dataset", "description": "Dataset name, which is also its directory name." }, "description": { "type": "string", "title": "Description", "description": "What the dataset holds and which route it mirrors." }, "key": { "items": { "type": "string" }, "type": "array", "title": "Key", "description": "Columns that uniquely identify a row." }, "partition_column": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Partition Column", "description": "Column the dataset is partitioned by, or null when it is a single directory. A partition directory is named '_'." }, "columns": { "items": { "$ref": "#/components/schemas/BulkColumnHTTP" }, "type": "array", "title": "Columns", "description": "Columns in file order." }, "statement_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Statement Types", "description": "Statement types the dataset covers, where its contract states a scope: the reconciliation dataset lists the statement types the ledger's rules apply to. Null for a dataset that states none." } }, "additionalProperties": false, "type": "object", "required": [ "dataset", "description", "key", "columns" ], "title": "BulkDatasetHTTP", "description": "One exported dataset's contract.", "examples": [ { "columns": [ { "description": "SEC Central Index Key, 10 digits.", "name": "cik", "nullable": false, "type": "string" } ], "dataset": "companies", "description": "Company profiles, as GET /v1/edgar/companies/{cik} serves them.", "key": [ "cik" ] } ] }, "BulkDatasetTotalsHTTP": { "properties": { "dataset": { "type": "string", "title": "Dataset", "description": "Dataset name." }, "schema_version": { "type": "integer", "title": "Schema Version", "description": "Format version the files were written with." }, "rows": { "type": "integer", "title": "Rows", "description": "Rows across the dataset's files." }, "bytes": { "type": "integer", "title": "Bytes", "description": "Bytes across the dataset's files." }, "files": { "type": "integer", "title": "Files", "description": "Files the dataset holds in this snapshot." }, "changed_files": { "type": "integer", "title": "Changed Files", "description": "Files whose bytes differ from the previous snapshot's. The rest carry the same sha256 and need not be downloaded again." }, "statement_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Statement Types", "description": "Statement types the dataset covers, as recorded in the snapshot's manifest. Null for a dataset that states no scope." } }, "additionalProperties": false, "type": "object", "required": [ "dataset", "schema_version", "rows", "bytes", "files", "changed_files" ], "title": "BulkDatasetTotalsHTTP", "description": "One dataset's totals within a snapshot." }, "BulkDownloadUrlHTTP": { "properties": { "snapshot_id": { "type": "string", "title": "Snapshot Id", "description": "Snapshot the file belongs to." }, "file_path": { "type": "string", "title": "File Path", "description": "Path of the file within the snapshot." }, "url": { "type": "string", "title": "Url", "description": "URL that reads the file directly from object storage until expires_at. It carries its own credentials: send no API key with it." }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At", "description": "When the URL stops working (UTC)." }, "bytes": { "type": "integer", "title": "Bytes", "description": "Size of the file the URL reads." }, "sha256": { "type": "string", "title": "Sha256", "description": "Hex SHA-256 of the file's bytes, to verify the download." } }, "additionalProperties": false, "type": "object", "required": [ "snapshot_id", "file_path", "url", "expires_at", "bytes", "sha256" ], "title": "BulkDownloadUrlHTTP", "description": "A short-lived URL for one snapshot file.", "examples": [ { "bytes": 41234567, "expires_at": "2026-09-23T10:10:00Z", "file_path": "financials/fiscal_year_2025/part-0000.parquet", "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "snapshot_id": "20260922T200638Z", "url": "https://s3.amazonaws.com/..." } ] }, "BulkFileHTTP": { "properties": { "path": { "type": "string", "title": "Path", "description": "Path within the snapshot, and the value to pass to the download route." }, "dataset": { "type": "string", "title": "Dataset", "description": "Dataset the file belongs to." }, "partition": { "anyOf": [ { "additionalProperties": { "type": "integer" }, "type": "object" }, { "type": "null" } ], "title": "Partition", "description": "Partition column and value, or null for an unpartitioned dataset." }, "rows": { "type": "integer", "title": "Rows", "description": "Rows in the file." }, "bytes": { "type": "integer", "title": "Bytes", "description": "File size." }, "sha256": { "type": "string", "title": "Sha256", "description": "Hex SHA-256 of the file's bytes." }, "changed": { "type": "boolean", "title": "Changed", "description": "Whether the bytes differ from the previous snapshot's file at this path. False means a client holding that snapshot already has these bytes." } }, "additionalProperties": false, "type": "object", "required": [ "path", "dataset", "rows", "bytes", "sha256", "changed" ], "title": "BulkFileHTTP", "description": "One file of a snapshot, as its manifest lists it." }, "BulkLicenseAcceptanceHTTP": { "properties": { "accepted_at": { "type": "string", "format": "date-time", "title": "Accepted At", "description": "When the acceptance was recorded (UTC)." }, "accepted_by_name": { "type": "string", "title": "Accepted By Name", "description": "Name of the person who accepted for the organization." }, "accepted_by_email": { "type": "string", "title": "Accepted By Email", "description": "Email of the person who accepted for the organization." } }, "additionalProperties": false, "type": "object", "required": [ "accepted_at", "accepted_by_name", "accepted_by_email" ], "title": "BulkLicenseAcceptanceHTTP", "description": "Who accepted the bulk-data license for an organization, and when.", "examples": [ { "accepted_at": "2026-10-03T09:15:00Z", "accepted_by_email": "jane.doe@example.com", "accepted_by_name": "Jane Doe" } ] }, "BulkLicenseAcceptanceRecordHTTP": { "properties": { "license_version": { "type": "string", "title": "License Version", "description": "License version accepted." }, "license_sha256": { "type": "string", "title": "License Sha256", "description": "Hex SHA-256 of the license text accepted." }, "accepted_at": { "type": "string", "format": "date-time", "title": "Accepted At", "description": "When the acceptance was recorded (UTC)." }, "accepted_by_name": { "type": "string", "title": "Accepted By Name", "description": "Name of the person who accepted for the organization." }, "accepted_by_email": { "type": "string", "title": "Accepted By Email", "description": "Email of the person who accepted for the organization." } }, "additionalProperties": false, "type": "object", "required": [ "license_version", "license_sha256", "accepted_at", "accepted_by_name", "accepted_by_email" ], "title": "BulkLicenseAcceptanceRecordHTTP", "description": "The acceptance on record for the caller's organization.", "examples": [ { "accepted_at": "2026-10-03T09:15:00Z", "accepted_by_email": "jane.doe@example.com", "accepted_by_name": "Jane Doe", "license_sha256": "fdf07a4138e6b333e919a548b3a9cf1ded1203ea0ef120c60ad22ceb4dba9131", "license_version": "bulk-data-v1" } ] }, "BulkLicenseAcceptanceRequestHTTP": { "properties": { "license_version": { "type": "string", "maxLength": 32, "minLength": 1, "title": "License Version", "description": "License version read from GET /v1/bulk/license." }, "license_sha256": { "type": "string", "maxLength": 64, "minLength": 1, "title": "License Sha256", "description": "license_sha256 read from GET /v1/bulk/license, for the text accepted." }, "accepted_by_name": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "\\S", "title": "Accepted By Name", "description": "Name of the person accepting; they confirm they may bind the organization." }, "accepted_by_email": { "type": "string", "maxLength": 320, "minLength": 3, "pattern": "^\\s*[^@\\s]+@[^@\\s]+\\.[^@\\s]+\\s*$", "title": "Accepted By Email", "description": "Email of the person accepting." } }, "additionalProperties": false, "type": "object", "required": [ "license_version", "license_sha256", "accepted_by_name", "accepted_by_email" ], "title": "BulkLicenseAcceptanceRequestHTTP", "description": "An organization's acceptance of the current bulk-data license.", "examples": [ { "accepted_by_email": "jane.doe@example.com", "accepted_by_name": "Jane Doe", "license_sha256": "fdf07a4138e6b333e919a548b3a9cf1ded1203ea0ef120c60ad22ceb4dba9131", "license_version": "bulk-data-v1" } ] }, "BulkLicenseHTTP": { "properties": { "license_version": { "type": "string", "title": "License Version", "description": "Current license version; echo it back to accept.", "examples": [ "bulk-data-v1" ] }, "license_sha256": { "type": "string", "title": "License Sha256", "description": "Hex SHA-256 of the UTF-8 bytes of text, exactly as served; echo it back to accept, which proves the acceptance is of this exact text." }, "text": { "type": "string", "title": "Text", "description": "The full license text, in Markdown." }, "accepted": { "type": "boolean", "title": "Accepted", "description": "Whether the caller's organization has accepted this version. Download URLs are issued only once it has." }, "acceptance": { "anyOf": [ { "$ref": "#/components/schemas/BulkLicenseAcceptanceHTTP" }, { "type": "null" } ], "description": "The organization's acceptance of this version, or null when there is none." } }, "additionalProperties": false, "type": "object", "required": [ "license_version", "license_sha256", "text", "accepted" ], "title": "BulkLicenseHTTP", "description": "The current bulk-data license, and whether the caller's organization accepted it.", "examples": [ { "accepted": false, "license_sha256": "fdf07a4138e6b333e919a548b3a9cf1ded1203ea0ef120c60ad22ceb4dba9131", "license_version": "bulk-data-v1", "text": "# Arche Bulk Data License (bulk-data-v1)\n\n..." } ] }, "BulkSnapshotHTTP": { "properties": { "snapshot_id": { "type": "string", "title": "Snapshot Id", "description": "Snapshot identifier, the build's start as YYYYMMDDTHHMMSSZ." }, "build_kind": { "type": "string", "title": "Build Kind", "description": "'full' when every partition was reread, 'incremental' when unchanged partitions were carried forward." }, "format_version": { "type": "integer", "title": "Format Version", "description": "Version of the file format. A change means every file is written differently, so no file is carried across it." }, "previous_snapshot_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Snapshot Id", "description": "Snapshot unchanged files were carried from, if any." }, "published_at": { "type": "string", "format": "date-time", "title": "Published At", "description": "When the snapshot was published (UTC)." }, "read_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Read At", "description": "The point in time the snapshot reflects (UTC). Nothing accepted by EDGAR after this moment is in the files." }, "rows": { "type": "integer", "title": "Rows", "description": "Rows across every dataset." }, "bytes": { "type": "integer", "title": "Bytes", "description": "Bytes across every dataset." }, "datasets": { "items": { "$ref": "#/components/schemas/BulkDatasetTotalsHTTP" }, "type": "array", "title": "Datasets", "description": "Per-dataset totals, in dataset-name order." } }, "additionalProperties": false, "type": "object", "required": [ "snapshot_id", "build_kind", "format_version", "published_at", "rows", "bytes", "datasets" ], "title": "BulkSnapshotHTTP", "description": "One published snapshot, without its file list.", "examples": [ { "build_kind": "incremental", "bytes": 6900000000, "datasets": [ { "bytes": 900000000, "changed_files": 17, "dataset": "financials", "files": 22, "rows": 15133655, "schema_version": 1 } ], "format_version": 1, "previous_snapshot_id": "20260921T180544Z", "published_at": "2026-09-22T21:05:11Z", "read_at": "2026-09-22T20:06:38Z", "rows": 31000000, "snapshot_id": "20260922T200638Z" } ] }, "BulkSnapshotManifestHTTP": { "properties": { "snapshot_id": { "type": "string", "title": "Snapshot Id", "description": "Snapshot identifier." }, "build_kind": { "type": "string", "title": "Build Kind", "description": "'full' or 'incremental'." }, "format_version": { "type": "integer", "title": "Format Version", "description": "Version of the file format." }, "previous_snapshot_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Snapshot Id", "description": "Snapshot unchanged files were carried from, if any." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Published At", "description": "When the snapshot was published (UTC)." }, "read_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Read At", "description": "The point in time the snapshot reflects (UTC)." }, "rows": { "type": "integer", "title": "Rows", "description": "Rows across every dataset." }, "bytes": { "type": "integer", "title": "Bytes", "description": "Bytes across every dataset." }, "datasets": { "items": { "$ref": "#/components/schemas/BulkDatasetTotalsHTTP" }, "type": "array", "title": "Datasets", "description": "Per-dataset totals, in dataset-name order." }, "files": { "items": { "$ref": "#/components/schemas/BulkFileHTTP" }, "type": "array", "title": "Files", "description": "Every file in the snapshot, ordered by path." } }, "additionalProperties": false, "type": "object", "required": [ "snapshot_id", "build_kind", "format_version", "rows", "bytes", "datasets", "files" ], "title": "BulkSnapshotManifestHTTP", "description": "Every file of one published snapshot." }, "CanonicalStatementMetric": { "type": "string", "enum": [ "REVENUE", "COST_OF_REVENUE", "GROSS_PROFIT", "RESEARCH_AND_DEVELOPMENT_EXPENSE", "SELLING_GENERAL_AND_ADMINISTRATIVE_EXPENSE", "DEPRECIATION_AND_AMORTIZATION_EXPENSE", "OPERATING_INCOME", "OPERATING_EXPENSE", "INTEREST_INCOME", "INTEREST_EXPENSE", "NET_INTEREST_INCOME", "OTHER_NON_OPERATING_INCOME_EXPENSE", "INCOME_BEFORE_TAX", "INCOME_TAX_EXPENSE", "NET_INCOME", "NET_INCOME_ATTRIBUTABLE_TO_NONCONTROLLING_INTEREST", "INCOME_FROM_DISCONTINUED_OPERATIONS", "INCOME_FROM_EQUITY_METHOD_INVESTMENTS", "BASIC_EPS", "DILUTED_EPS", "WEIGHTED_AVERAGE_SHARES_BASIC", "WEIGHTED_AVERAGE_SHARES_DILUTED", "TOTAL_ASSETS", "TOTAL_CURRENT_ASSETS", "CASH_AND_CASH_EQUIVALENTS", "CASH_CASH_EQUIVALENTS_AND_RESTRICTED_CASH", "SHORT_TERM_INVESTMENTS", "ACCOUNTS_RECEIVABLE_NET", "INVENTORIES", "OTHER_CURRENT_ASSETS", "TOTAL_NON_CURRENT_ASSETS", "PROPERTY_PLANT_AND_EQUIPMENT_NET", "GOODWILL", "INTANGIBLE_ASSETS_NET", "OTHER_NON_CURRENT_ASSETS", "TOTAL_LIABILITIES", "TOTAL_CURRENT_LIABILITIES", "ACCOUNTS_PAYABLE", "SHORT_TERM_DEBT", "CURRENT_PORTION_OF_LONG_TERM_DEBT", "OTHER_CURRENT_LIABILITIES", "TOTAL_NON_CURRENT_LIABILITIES", "LONG_TERM_DEBT", "OTHER_NON_CURRENT_LIABILITIES", "TOTAL_EQUITY", "TEMPORARY_EQUITY", "RETAINED_EARNINGS", "ADDITIONAL_PAID_IN_CAPITAL", "TREASURY_STOCK", "ACCUMULATED_OTHER_COMPREHENSIVE_INCOME", "NET_CASH_FROM_OPERATING_ACTIVITIES", "NET_CASH_FROM_INVESTING_ACTIVITIES", "NET_CASH_FROM_FINANCING_ACTIVITIES", "EFFECT_OF_EXCHANGE_RATE_ON_CASH", "NET_INCREASE_DECREASE_IN_CASH", "CASH_FLOW_STARTING_NET_INCOME", "CASH_PAID_FOR_INTEREST", "CASH_PAID_FOR_INCOME_TAXES", "STOCK_BASED_COMPENSATION_IN_CFO", "DEPRECIATION_AND_AMORTIZATION_IN_CFO", "CHANGE_IN_ACCOUNTS_RECEIVABLE", "CHANGE_IN_INVENTORIES", "CHANGE_IN_ACCOUNTS_PAYABLE", "CHANGE_IN_OTHER_CURRENT_ASSETS", "CHANGE_IN_OTHER_CURRENT_LIABILITIES", "CAPITAL_EXPENDITURES", "FREE_CASH_FLOW", "DIVIDENDS_PAID", "SHARE_REPURCHASES_PAID", "SHARE_ISSUANCE_PROCEEDS", "OTHER_OPERATING_INCOME_EXPENSE", "OTHER_ASSETS", "OTHER_LIABILITIES", "OTHER_CASH_FLOW_FROM_OPERATIONS", "OTHER_CASH_FLOW_FROM_INVESTING", "OTHER_CASH_FLOW_FROM_FINANCING" ], "title": "CanonicalStatementMetric", "description": "Canonical financial statement metrics.\n\nThe enum names are UPPER_SNAKE_CASE and the values are the same strings,\nensuring stable identifiers in JSON and other serialized forms." }, "CheckResult": { "properties": { "name": { "type": "string", "title": "Name", "examples": [ "db", "redis" ] }, "status": { "type": "string", "enum": [ "ok", "down" ], "title": "Status" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Detail" }, "duration_ms": { "type": "number", "title": "Duration Ms" } }, "additionalProperties": false, "type": "object", "required": [ "name", "status", "duration_ms" ], "title": "CheckResult", "description": "Result of a single dependency check.\n\nAttributes:\n name: Logical name for the dependency (e.g., \"db\", \"redis\").\n status: Per-check outcome: \"ok\" when the probe succeeded, otherwise \"down\".\n detail: Optional human-readable diagnostic detail (e.g., exception message).\n duration_ms: Time spent on the probe in milliseconds (float)." }, "CompanyCoverageSummaryHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Canonical 10-digit CIK." }, "ticker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ticker", "description": "Ticker when available." }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name", "description": "Issuer legal name." }, "first_fiscal_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "First Fiscal Year", "description": "Earliest fiscal year with a statement for this company. Counts only the periods a filing reports or compares against: a statement counts when its period ended no more than three years (1,098 days) before the period the filing covers, so a late-filed report still counts for its own period." }, "latest_fiscal_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Latest Fiscal Year", "description": "Latest fiscal year with a statement for this company. Counts only the periods a filing reports or compares against: a statement counts when its period ended no more than three years (1,098 days) before the period the filing covers, so a late-filed report still counts for its own period." }, "annual_periods_expected": { "type": "integer", "minimum": 0.0, "title": "Annual Periods Expected", "description": "Annual periods expected: one for each fiscal year from the first annual statement served for this company to the latest, plus one for each annual report the company filed outside those years once the SEC required XBRL financial statements (fiscal periods ending after 2011-06-15, or on or after 2017-12-15 for 20-F and 40-F filers). A history missing its first or latest years therefore reads as incomplete." }, "annual_periods_populated": { "type": "integer", "minimum": 0.0, "title": "Annual Periods Populated", "description": "Annual periods with at least one statement. Counts only the periods a filing reports or compares against: a statement counts when its period ended no more than three years (1,098 days) before the period the filing covers, so a late-filed report still counts for its own period." }, "quarterly_periods_expected": { "type": "integer", "minimum": 0.0, "title": "Quarterly Periods Expected", "description": "Quarterly periods expected over the same years: none for a company that files no 10-Q, four a year for one that reports a fourth quarter, and otherwise three a year, the fourth quarter closing inside the 10-K." }, "quarterly_periods_populated": { "type": "integer", "minimum": 0.0, "title": "Quarterly Periods Populated", "description": "Quarterly periods with at least one statement. Counts only the periods a filing reports or compares against: a statement counts when its period ended no more than three years (1,098 days) before the period the filing covers, so a late-filed report still counts for its own period." }, "income_statement_completeness": { "type": "string", "title": "Income Statement Completeness", "description": "Share of expected annual and quarterly periods with an income statement, as a decimal string from 0 to 1. This is period coverage: a period counts once it has the statement, however many of its metrics the statement carries." }, "balance_sheet_completeness": { "type": "string", "title": "Balance Sheet Completeness", "description": "Share of expected annual and quarterly periods with a balance sheet, as a decimal string from 0 to 1. This is period coverage: a period counts once it has the statement, however many of its metrics the statement carries." }, "cash_flow_statement_completeness": { "type": "string", "title": "Cash Flow Statement Completeness", "description": "Share of expected annual and quarterly periods with a cash flow statement, as a decimal string from 0 to 1. This is period coverage: a period counts once it has the statement, however many of its metrics the statement carries." }, "core_metric_completeness": { "type": "string", "title": "Core Metric Completeness", "description": "Share of expected periods holding at least one core metric, as a decimal string. This is period coverage, not the share of metrics populated within a period." }, "annual_reporting_continuous": { "type": "boolean", "title": "Annual Reporting Continuous", "description": "Whether every fiscal year from the first annual statement served for this company to the latest has an annual statement: no hole inside the series. Years missing before the first or after the latest do not count here; annual_periods_expected reports them. Quarterly periods are excluded." }, "filing_count": { "type": "integer", "minimum": 0.0, "title": "Filing Count", "description": "Number of SEC filings with a statement for this company. An amendment counts as its own filing." }, "latest_filing_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Latest Filing Date", "description": "Filing date of the company's most recent filing." }, "latest_accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Latest Accepted At", "description": "UTC time the SEC accepted the company's most recent filing." }, "computed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Computed At", "description": "When these figures were computed. They are computed ahead of the request, so they can lag the newest filings Arche serves: read this before quoting a coverage figure, and treat an old timestamp as old numbers. Null means the figures were computed for this request and are current." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "annual_periods_expected", "annual_periods_populated", "quarterly_periods_expected", "quarterly_periods_populated", "income_statement_completeness", "balance_sheet_completeness", "cash_flow_statement_completeness", "core_metric_completeness", "annual_reporting_continuous", "filing_count" ], "title": "CompanyCoverageSummaryHTTP", "description": "HTTP schema for one company coverage summary.", "examples": [ { "annual_periods_expected": 18, "annual_periods_populated": 18, "annual_reporting_continuous": true, "balance_sheet_completeness": "0.944444", "cash_flow_statement_completeness": "1.000000", "cik": "0000320193", "company_name": "Apple Inc.", "computed_at": "2026-10-06T02:31:20Z", "core_metric_completeness": "1.000000", "filing_count": 68, "first_fiscal_year": 2008, "income_statement_completeness": "1.000000", "latest_accepted_at": "2026-07-31T10:01:02Z", "latest_filing_date": "2026-07-31", "latest_fiscal_year": 2026, "quarterly_periods_expected": 54, "quarterly_periods_populated": 54, "ticker": "AAPL" } ] }, "CompanyIdentityHTTP": { "properties": { "company_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Id", "description": "Company key accepted by /v1/modeling and /v1/ai routes. Null when the filer is not in the company reference." }, "cik": { "type": "string", "title": "Cik", "description": "Canonical 10-digit SEC CIK." }, "ticker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ticker", "description": "Ticker symbol when available." }, "company_name": { "type": "string", "title": "Company Name", "description": "Issuer legal name." }, "exchange": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exchange", "description": "ISO 10383 MIC of the exchange the ticker lists on, such as XNAS or XNYS; null when no source names one." }, "active_from": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Active From", "description": "Inclusive start of the mapping as observed, not the date the ticker began trading. The SEC ticker file carries no history, so this is the first date Arche saw the mapping in it. It is not a listing date and does not answer what a company traded as at an earlier time." }, "active_to": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Active To", "description": "Inclusive end of the mapping, set only when the SEC ticker file stopped listing it. An open end means the file still lists the mapping, not that it has been continuously active." }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the mapping is currently active." }, "source": { "type": "string", "title": "Source", "description": "Source/provenance identifier." }, "source_filing_accession": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Filing Accession", "description": "Filing accession backing the identity evidence, when available." }, "confidence_score": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Confidence Score", "description": "Optional confidence score as a decimal string." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "company_name", "is_active", "source" ], "title": "CompanyIdentityHTTP", "description": "HTTP schema for one company identity record." }, "CompanyIdentityResolveHTTP": { "properties": { "as_of_date": { "type": "string", "format": "date", "title": "As Of Date", "description": "Resolution date boundary." }, "identity": { "$ref": "#/components/schemas/CompanyIdentityHTTP", "description": "Resolved identity record." } }, "additionalProperties": false, "type": "object", "required": [ "as_of_date", "identity" ], "title": "CompanyIdentityResolveHTTP", "description": "HTTP schema for date-aware ticker resolution.", "examples": [ { "as_of_date": "2026-09-23", "identity": { "active_from": "2026-07-17", "cik": "0000320193", "company_id": "a2cb31b5-dc0f-4a17-a665-e41f59cb8e0a", "company_name": "Apple Inc.", "exchange": "XNAS", "is_active": true, "source": "sec:company_submissions", "source_filing_accession": "0001140361-26-035325", "ticker": "AAPL" } } ] }, "CoverageSelectionHTTP": { "properties": { "mode": { "type": "string", "enum": [ "selected", "full", "dow30", "sp500" ], "title": "Mode", "description": "How this plan's coverage is decided. 'selected' means the companies below, chosen by querying them; anything else is a fixed list and the companies below are empty." }, "limit": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Limit", "description": "How many companies may be held at once. Null when coverage is not chosen." }, "window_days": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Window Days", "description": "How many days a company keeps its slot without being queried. Null when coverage is not chosen." }, "slots_used": { "type": "integer", "minimum": 0.0, "title": "Slots Used", "description": "How many companies are held right now." }, "slots_available": { "anyOf": [ { "type": "integer", "minimum": 0.0 }, { "type": "null" } ], "title": "Slots Available", "description": "How many further companies may be added. Null when coverage is not chosen." }, "companies": { "items": { "$ref": "#/components/schemas/CoverageSlotHTTP" }, "type": "array", "title": "Companies", "description": "Companies held, oldest claim first. Empty unless coverage is chosen." } }, "additionalProperties": false, "type": "object", "required": [ "mode", "slots_used" ], "title": "CoverageSelectionHTTP", "description": "HTTP schema for the companies a plan covers right now.", "examples": [ { "companies": [ { "cik": "0000320193", "claimed_at": "2026-09-01T09:14:22Z", "expires_at": "2026-10-20T16:02:47Z", "last_queried_at": "2026-09-20T16:02:47Z" } ], "limit": 25, "mode": "selected", "slots_available": 24, "slots_used": 1, "window_days": 30 } ] }, "CoverageSelectionReleaseRequestHTTP": { "properties": { "cik": { "type": "string", "minLength": 1, "title": "Cik", "description": "Company to release, as a CIK with or without leading zeros. Releasing frees the slot at once rather than waiting out the window." } }, "additionalProperties": false, "type": "object", "required": [ "cik" ], "title": "CoverageSelectionReleaseRequestHTTP", "description": "HTTP schema for releasing one company's slot.", "examples": [ { "cik": "0000320193" } ] }, "CoverageSlotHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Ten-digit CIK of the company held." }, "claimed_at": { "type": "string", "format": "date-time", "title": "Claimed At", "description": "UTC timestamp when this company first took a slot." }, "last_queried_at": { "type": "string", "format": "date-time", "title": "Last Queried At", "description": "UTC timestamp of the most recent request that reached this company." }, "expires_at": { "type": "string", "format": "date-time", "title": "Expires At", "description": "UTC timestamp when the slot frees itself if nothing queries the company again. Every request that reaches the company moves it forward." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "claimed_at", "last_queried_at", "expires_at" ], "title": "CoverageSlotHTTP", "description": "HTTP schema for one company a chosen-coverage plan holds.", "examples": [ { "cik": "0000320193", "claimed_at": "2026-09-01T09:14:22Z", "expires_at": "2026-10-20T16:02:47Z", "last_queried_at": "2026-09-20T16:02:47Z" } ] }, "DQAnomalyHTTP": { "properties": { "metric": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Metric", "description": "Metric code this anomaly refers to, if any." }, "dimension_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dimension Key", "description": "Dimension key this anomaly refers to, if any." }, "rule_code": { "type": "string", "title": "Rule Code", "description": "Code of the rule that produced this anomaly (e.g. NON_NEGATIVE)." }, "severity": { "$ref": "#/components/schemas/MaterialityClass", "description": "Anomaly severity (LOW, MEDIUM, HIGH)." }, "message": { "type": "string", "title": "Message", "description": "Human-readable anomaly description." }, "details": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Details", "description": "Machine-readable details (thresholds, prior values, etc.)." } }, "additionalProperties": false, "type": "object", "required": [ "rule_code", "severity", "message" ], "title": "DQAnomalyHTTP", "description": "One rule-level data-quality anomaly." }, "DQSummaryHTTP": { "properties": { "dq_max_severity": { "anyOf": [ { "$ref": "#/components/schemas/MaterialityClass" }, { "type": "null" } ], "description": "Max DQ severity across facts/anomalies." }, "dq_issue_count": { "type": "integer", "minimum": 0.0, "title": "Dq Issue Count", "description": "Count of DQ issues/anomalies.", "default": 0 } }, "additionalProperties": false, "type": "object", "title": "DQSummaryHTTP", "description": "HTTP schema for a DQ summary block.", "examples": [ { "dq_issue_count": 3, "dq_max_severity": "HIGH" } ] }, "DataQualityFlagItemHTTP": { "properties": { "metric_name": { "type": "string", "title": "Metric Name", "description": "Canonical metric code." }, "rule_name": { "type": "string", "title": "Rule Name", "description": "Stable identifier of the data-quality rule." }, "severity": { "$ref": "#/components/schemas/MaterialityClass", "description": "How material the finding is." } }, "additionalProperties": false, "type": "object", "required": [ "metric_name", "rule_name", "severity" ], "title": "DataQualityFlagItemHTTP", "description": "One data-quality rule a metric failed." }, "DataQualityIssueHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "metric": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Metric", "description": "Associated metric code, if any." }, "statement_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Statement Type", "description": "Statement type, if any." }, "fiscal_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fiscal Year", "description": "Fiscal year, if any." }, "fiscal_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fiscal Period", "description": "Fiscal period code, if any." }, "filing_accession": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filing Accession", "description": "SEC accession of the filing whose statement the issue describes, if any. With cik, statement_type, fiscal_year and fiscal_period it names one public statement.", "examples": [ "0001069183-25-000075" ] }, "rule_code": { "type": "string", "title": "Rule Code", "description": "Stable issue or rule code." }, "rule_category": { "type": "string", "title": "Rule Category", "description": "Issue category label." }, "severity": { "$ref": "#/components/schemas/MaterialityClass", "description": "Issue severity." }, "status": { "type": "string", "title": "Status", "description": "Stable issue status label." }, "message": { "type": "string", "title": "Message", "description": "Human-readable issue description." }, "expected_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expected Value", "description": "Expected numeric value, if any." }, "actual_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actual Value", "description": "Observed numeric value, if any." }, "materiality": { "anyOf": [ { "$ref": "#/components/schemas/MaterialityClass" }, { "type": "null" } ], "description": "Optional materiality classification, if distinct from severity." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "UTC timestamp when the issue was recorded." }, "provenance": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Provenance", "description": "Optional machine-readable provenance payload safe for clients." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "rule_code", "rule_category", "severity", "status", "message", "created_at" ], "title": "DataQualityIssueHTTP", "description": "One public data-quality issue.", "examples": [ { "cik": "0000320193", "created_at": "2025-03-01T00:00:00Z", "filing_accession": "0000320193-25-000010", "fiscal_period": "FY", "fiscal_year": 2024, "materiality": "HIGH", "message": "Revenue deviates materially from recent history.", "metric": "REVENUE", "rule_category": "DQ_ANOMALY", "rule_code": "HISTORY_OUTLIER", "severity": "HIGH", "statement_type": "INCOME_STATEMENT", "status": "OPEN" } ] }, "DerivedMetric": { "type": "string", "enum": [ "GROSS_MARGIN", "OPERATING_MARGIN", "NET_MARGIN", "EBIT_MARGIN", "CFO_MARGIN", "EBITDA_MARGIN", "FCF_MARGIN", "SBC_TO_REVENUE", "SBC_TO_CFO", "CAPEX_TO_REVENUE", "CAPEX_TO_CFO", "CASH_TAX_RATE", "REVENUE_GROWTH_YOY", "REVENUE_GROWTH_QOQ", "REVENUE_GROWTH_TTM", "EPS_DILUTED_GROWTH", "EBITDA", "EBIT", "LEVERED_FREE_CASH_FLOW", "UNLEVERED_FREE_CASH_FLOW", "DIVIDENDS_PAID", "DIVIDENDS_PER_SHARE", "DIVIDEND_YIELD", "BUYBACK_YIELD", "TOTAL_SHAREHOLDER_YIELD", "WORKING_CAPITAL", "CURRENT_RATIO", "QUICK_RATIO", "BOOK_VALUE_PER_SHARE", "DEBT_TO_EQUITY", "NET_DEBT_TO_EQUITY", "NET_DEBT_TO_EBITDA", "DEBT_TO_ASSETS", "INTEREST_COVERAGE", "CASH_RATIO", "CFO_TO_NET_INCOME", "FCF_CONVERSION", "DSO", "DPO", "DIO", "INVENTORY_TURNOVER", "CASH_CONVERSION_CYCLE", "ASSET_TURNOVER", "ROE", "ROA", "ROIC", "EV_TO_EBIT", "EARNINGS_YIELD", "PAYOUT_RATIO", "SHARE_REPURCHASES", "NET_BUYBACK", "REVENUE_PER_SHARE", "FCF_PER_SHARE", "RECEIVABLES_TURNOVER", "PAYABLES_TURNOVER", "TANGIBLE_BOOK_VALUE", "TANGIBLE_BOOK_VALUE_PER_SHARE", "REINVESTMENT_RATE", "RETENTION_RATIO", "NET_DISTRIBUTION_RATE", "PAYOUT_PLUS_BUYBACK_RATIO" ], "title": "DerivedMetric", "description": "Derived financial metrics used in analytics and modeling." }, "DerivedMetricsTimeSeriesPointHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Central Index Key for the filer." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Primary statement type used for derived metrics." }, "accounting_standard": { "$ref": "#/components/schemas/AccountingStandard", "description": "Accounting standard (e.g., US_GAAP, IFRS)." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Reporting period end date for this derived-metrics point." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year associated with the underlying statement (e.g., 2024)." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period within the year (e.g., Q1, Q2, FY)." }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency code for derived monetary metrics (e.g., USD)." }, "metrics": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metrics", "description": "Mapping of derived metric codes (e.g., GROSS_MARGIN) to decimal string values. Only successfully computed metrics are included." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "accounting_standard", "statement_date", "fiscal_year", "fiscal_period", "currency" ], "title": "DerivedMetricsTimeSeriesPointHTTP", "description": "HTTP schema for a single derived metrics time-series point.\n\nThis schema represents a modeling-friendly view of derived analytics\n(margins, growth rates, cash-flow measures, returns) computed from\ncanonical normalized EDGAR payloads.\n\nAttributes:\n cik:\n Central Index Key for the filer.\n statement_type:\n Statement type that served as the primary source (e.g., income\n statement, balance sheet).\n accounting_standard:\n Accounting standard (e.g., US_GAAP, IFRS).\n statement_date:\n Reporting period end date.\n fiscal_year:\n Fiscal year associated with the statement (>= 1).\n fiscal_period:\n Fiscal period within the year (e.g., FY, Q1, Q2).\n currency:\n ISO 4217 currency code (e.g., \"USD\").\n metrics:\n Mapping from derived metric codes (e.g., \"GROSS_MARGIN\") to\n decimal string values." }, "EdgarCompanyCompletenessHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Central Index Key string for the filer." }, "latest_filing_accession": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Filing Accession", "description": "Accession identifier for the latest filing, if available." }, "latest_filed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Latest Filed At", "description": "Filing timestamp for the latest filing, if available." }, "latest_period_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Latest Period End", "description": "Reporting period end date for the latest filing, if available." }, "statement_types_available": { "items": { "$ref": "#/components/schemas/StatementType" }, "type": "array", "title": "Statement Types Available", "description": "Statement types with at least one filed statement available." }, "statements_count_by_statement_type": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Statements Count By Statement Type", "description": "Mapping of statement type to the number of filed statements available, counting each filing once per period it reports." }, "last_updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Updated At", "description": "Deterministic last-updated timestamp derived from filings and statements." } }, "additionalProperties": false, "type": "object", "required": [ "cik" ], "title": "EdgarCompanyCompletenessHTTP", "description": "HTTP schema for an EDGAR company completeness summary.", "examples": [ { "cik": "0000320193", "last_updated_at": "2024-11-01T00:00:00+00:00", "latest_filed_at": "2024-11-01T00:00:00+00:00", "latest_filing_accession": "0000320193-24-000001", "latest_period_end": "2024-09-28", "statement_types_available": [ "INCOME_STATEMENT", "BALANCE_SHEET", "CASH_FLOW_STATEMENT" ], "statements_count_by_statement_type": { "BALANCE_SHEET": 1, "CASH_FLOW_STATEMENT": 1, "INCOME_STATEMENT": 1 } } ] }, "EdgarCompanyProfileHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Canonical CIK (zero-padded 10 digits)." }, "entity_name": { "type": "string", "title": "Entity Name", "description": "SEC entity legal name." }, "tickers": { "items": { "type": "string" }, "type": "array", "title": "Tickers", "description": "Deterministically ordered ticker symbols for the entity." }, "exchanges": { "items": { "type": "string" }, "type": "array", "title": "Exchanges", "description": "ISO 10383 MICs of the exchanges the entity's current tickers list on, each once, sorted." }, "sic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sic", "description": "SEC SIC code when available." }, "sic_description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sic Description", "description": "SEC SIC description when available." }, "state_of_incorporation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State Of Incorporation", "description": "State or country of incorporation code when available." }, "fiscal_year_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fiscal Year End", "description": "Fiscal year end marker (MMDD) when available." }, "last_updated_at": { "type": "string", "format": "date-time", "title": "Last Updated At", "description": "UTC timestamp for local record freshness." }, "source": { "$ref": "#/components/schemas/EdgarCompanyProfileSourceHTTP", "description": "Provenance metadata." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "entity_name", "last_updated_at", "source" ], "title": "EdgarCompanyProfileHTTP", "description": "HTTP schema for canonical EDGAR company profiles.", "examples": [ { "cik": "0000789019", "entity_name": "MICROSOFT CORP", "exchanges": [ "XNAS" ], "fiscal_year_end": "0630", "last_updated_at": "2026-03-01T12:34:56Z", "sic": "7372", "sic_description": "SERVICES-PREPACKAGED SOFTWARE", "source": { "as_of": "2026-03-01", "dataset": "submissions", "fetched_at": "2026-03-01T12:35:00Z", "provider": "sec" }, "state_of_incorporation": "WA", "tickers": [ "MSFT" ] } ] }, "EdgarCompanyProfileSourceHTTP": { "properties": { "provider": { "type": "string", "title": "Provider", "description": "Upstream provider identifier (always `sec`)." }, "dataset": { "type": "string", "title": "Dataset", "description": "Source SEC dataset identifier." }, "as_of": { "type": "string", "format": "date", "title": "As Of", "description": "Source dataset as-of date." }, "fetched_at": { "type": "string", "format": "date-time", "title": "Fetched At", "description": "UTC timestamp when source data was fetched." } }, "additionalProperties": false, "type": "object", "required": [ "provider", "dataset", "as_of", "fetched_at" ], "title": "EdgarCompanyProfileSourceHTTP", "description": "HTTP schema for company profile provenance metadata." }, "EdgarCompanyResolveHTTP": { "properties": { "ticker": { "type": "string", "title": "Ticker", "description": "Normalized uppercase ticker input." }, "exchange": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exchange", "description": "ISO 10383 MIC of the exchange the resolved company lists this ticker on, as stated in its SEC filings; for a security listed on more than one, the exchange it listed on first. Null when the filings name none." }, "as_of": { "type": "string", "format": "date", "title": "As Of", "description": "Effective as-of date for resolution." }, "cik": { "type": "string", "title": "Cik", "description": "Resolved canonical CIK." } }, "additionalProperties": false, "type": "object", "required": [ "ticker", "as_of", "cik" ], "title": "EdgarCompanyResolveHTTP", "description": "HTTP schema for ticker-to-CIK resolution results.", "examples": [ { "as_of": "2026-03-01", "cik": "0000789019", "exchange": "XNAS", "ticker": "MSFT" } ] }, "EdgarDerivedMetricSpecHTTP": { "properties": { "code": { "type": "string", "title": "Code", "description": "Derived metric code, matching the DerivedMetric enum value." }, "category": { "type": "string", "title": "Category", "description": "High-level category for the metric (e.g., MARGIN, GROWTH)." }, "description": { "type": "string", "title": "Description", "description": "Short human-readable description of the metric definition." }, "is_experimental": { "type": "boolean", "title": "Is Experimental", "description": "Whether this metric is considered experimental." }, "required_statement_types": { "items": { "$ref": "#/components/schemas/StatementType" }, "type": "array", "title": "Required Statement Types", "description": "Statement types for which this metric is conceptually valid (e.g., INCOME_STATEMENT, BALANCE_SHEET)." }, "required_inputs": { "items": { "type": "string" }, "type": "array", "title": "Required Inputs", "description": "Canonical input metric codes required to compute this metric, expressed as string identifiers." }, "uses_history": { "type": "boolean", "title": "Uses History", "description": "Whether the metric inspects prior-period history." }, "window_requirements": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Window Requirements", "description": "History window requirements keyed by requirement name, such as {\"history_periods\": 7} for TTM metrics." } }, "additionalProperties": false, "type": "object", "required": [ "code", "category", "description", "is_experimental", "uses_history" ], "title": "EdgarDerivedMetricSpecHTTP", "description": "HTTP schema for a single derived metric specification.\n\nWhat a derived metric is, what it needs, and how it is computed." }, "EdgarDerivedMetricsCatalogHTTP": { "properties": { "metrics": { "items": { "$ref": "#/components/schemas/EdgarDerivedMetricSpecHTTP" }, "type": "array", "title": "Metrics", "description": "Collection of all registered derived metrics." } }, "additionalProperties": false, "type": "object", "title": "EdgarDerivedMetricsCatalogHTTP", "description": "HTTP schema for the catalog of registered derived metrics.", "examples": [ { "metrics": [ { "category": "EFFICIENCY", "code": "ASSET_TURNOVER", "description": "Revenue divided by total assets.", "is_experimental": false, "required_inputs": [ "REVENUE", "TOTAL_ASSETS" ], "required_statement_types": [ "BALANCE_SHEET", "INCOME_STATEMENT" ], "uses_history": false, "window_requirements": {} }, { "category": "LIQUIDITY", "code": "BOOK_VALUE_PER_SHARE", "description": "Total equity divided by weighted-average shares (diluted-first).", "is_experimental": false, "required_inputs": [ "TOTAL_EQUITY" ], "required_statement_types": [ "BALANCE_SHEET", "INCOME_STATEMENT" ], "uses_history": false, "window_requirements": {} } ] } ] }, "EdgarDerivedMetricsPointHTTP": { "properties": { "cik": { "type": "string", "title": "Cik" }, "statement_type": { "$ref": "#/components/schemas/StatementType" }, "accounting_standard": { "$ref": "#/components/schemas/AccountingStandard" }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date" }, "fiscal_year": { "type": "integer", "title": "Fiscal Year" }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod" }, "currency": { "type": "string", "title": "Currency" }, "metrics": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metrics", "description": "Derived metric code to decimal-string mapping for EDGAR-computable metrics. May include margin metrics (EBIT_MARGIN, CFO_MARGIN, EBITDA_MARGIN, FCF_MARGIN), leverage/liquidity metrics (CASH_RATIO, NET_DEBT_TO_EBITDA, DEBT_TO_ASSETS, TANGIBLE_BOOK_VALUE), efficiency metrics (DSO, DIO, DPO, INVENTORY_TURNOVER, CASH_CONVERSION_CYCLE, RECEIVABLES_TURNOVER, PAYABLES_TURNOVER, ASSET_TURNOVER), and per-share metrics (REVENUE_PER_SHARE, FCF_PER_SHARE, TANGIBLE_BOOK_VALUE_PER_SHARE) when requested and computable. Market-dependent metrics such as DIVIDEND_YIELD, BUYBACK_YIELD, TOTAL_SHAREHOLDER_YIELD, EV_TO_EBIT, EARNINGS_YIELD, and NET_DISTRIBUTION_RATE require caller-supplied market inputs and are not emitted by this EDGAR-only endpoint.", "examples": [ { "CASH_RATIO": "0.250000", "DIO": "73.000000", "EBITDA_MARGIN": "0.300000", "EBIT_MARGIN": "0.240000", "FCF_PER_SHARE": "0.400000", "RECEIVABLES_TURNOVER": "5.000000", "TANGIBLE_BOOK_VALUE_PER_SHARE": "1.500000" } ] }, "dividend_period_basis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dividend Period Basis", "description": "Period basis for dividends-per-share calculations. FY rows use 'annual'; non-FY rows use 'periodic'. Null when DIVIDENDS_PER_SHARE was not requested or could not be computed from statement inputs." }, "payout_ratio_period_basis": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payout Ratio Period Basis", "description": "Period basis for payout-ratio calculations. FY rows use 'annual'; non-FY rows use 'periodic'. Null when PAYOUT_RATIO was not requested or could not be computed from statement inputs." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "accounting_standard", "statement_date", "fiscal_year", "fiscal_period", "currency", "metrics" ], "title": "EdgarDerivedMetricsPointHTTP", "description": "HTTP schema for a single derived metrics time-series point.\n\nMetrics are a mapping from metric *codes* (strings) to decimal-string\nvalues.", "examples": [ { "accounting_standard": "US_GAAP", "cik": "0000320193", "currency": "USD", "dividend_period_basis": "annual", "fiscal_period": "FY", "fiscal_year": 2024, "metrics": { "ASSET_TURNOVER": "2.500000", "CASH_RATIO": "0.250000", "CFO_MARGIN": "0.180000", "DIO": "73.000000", "EBITDA_MARGIN": "0.300000", "EBIT_MARGIN": "0.240000", "FCF_MARGIN": "0.150000", "NET_DEBT_TO_EBITDA": "1.600000", "PAYABLES_TURNOVER": "6.000000", "RECEIVABLES_TURNOVER": "5.000000", "REVENUE_PER_SHARE": "10.000000", "TANGIBLE_BOOK_VALUE": "150.000000", "TANGIBLE_BOOK_VALUE_PER_SHARE": "1.500000" }, "payout_ratio_period_basis": "annual", "statement_date": "2024-12-31", "statement_type": "INCOME_STATEMENT" } ] }, "EdgarDerivedMetricsTimeSeriesHTTP": { "properties": { "ciks": { "items": { "type": "string" }, "type": "array", "title": "Ciks" }, "statement_type": { "$ref": "#/components/schemas/StatementType" }, "frequency": { "type": "string", "title": "Frequency" }, "from_date": { "type": "string", "format": "date", "title": "From Date" }, "to_date": { "type": "string", "format": "date", "title": "To Date" }, "points": { "items": { "$ref": "#/components/schemas/EdgarDerivedMetricsPointHTTP" }, "type": "array", "title": "Points" }, "view": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "View", "description": "Metric view (bundle) identifier when the series is derived from a named view; null for ad-hoc metric selections." } }, "additionalProperties": false, "type": "object", "required": [ "ciks", "statement_type", "frequency", "from_date", "to_date", "points" ], "title": "EdgarDerivedMetricsTimeSeriesHTTP", "description": "HTTP schema for a derived metrics time series.\n\nAttributes:\n ciks:\n Normalized list of company CIKs included in the series.\n statement_type:\n Primary statement type used as the base for the derived metrics.\n frequency:\n Time-series frequency (\"annual\" or \"quarterly\").\n from_date:\n Inclusive lower bound on statement_date.\n to_date:\n Inclusive upper bound on statement_date.\n points:\n Derived metrics time-series points in deterministic order.\n view:\n Optional metric view (bundle) identifier when the series is\n produced via a named view. Null for ad-hoc metric selections.", "examples": [ { "ciks": [ "0000320193" ], "frequency": "annual", "from_date": "1994-01-01", "points": [ { "accounting_standard": "US_GAAP", "cik": "0000320193", "currency": "USD", "dividend_period_basis": "annual", "fiscal_period": "FY", "fiscal_year": 2008, "metrics": { "ASSET_TURNOVER": "1.036493", "BOOK_VALUE_PER_SHARE": "24.715703", "CAPEX_TO_CFO": "0.113693", "CAPEX_TO_REVENUE": "0.029100" }, "payout_ratio_period_basis": "annual", "statement_date": "2008-09-27", "statement_type": "INCOME_STATEMENT" }, { "accounting_standard": "US_GAAP", "cik": "0000320193", "currency": "USD", "dividend_period_basis": "annual", "fiscal_period": "FY", "fiscal_year": 2009, "metrics": { "ASSET_TURNOVER": "0.903244", "BOOK_VALUE_PER_SHARE": "34.884041", "CAPEX_TO_CFO": "0.112610", "CAPEX_TO_REVENUE": "0.026664" }, "payout_ratio_period_basis": "annual", "statement_date": "2009-09-26", "statement_type": "INCOME_STATEMENT" } ], "statement_type": "INCOME_STATEMENT", "to_date": "2026-09-23" } ] }, "EdgarFilingDisclosureHTTP": { "properties": { "disclosure_id": { "type": "string", "format": "uuid", "title": "Disclosure Id", "description": "Identifier for this disclosure." }, "accession_id": { "type": "string", "title": "Accession Id", "description": "Accession the disclosure was extracted from." }, "cik": { "type": "string", "title": "Cik", "description": "Company CIK as digits." }, "period_of_report": { "type": "string", "format": "date", "title": "Period Of Report", "description": "Period the filing reports on." }, "concept": { "type": "string", "title": "Concept", "description": "Source XBRL concept the disclosure was tagged as." }, "title": { "type": "string", "title": "Title", "description": "Human-readable rendering of the concept." }, "char_count": { "type": "integer", "minimum": 0.0, "title": "Char Count", "description": "Length of the disclosure text in characters." }, "disclosure_text": { "type": "string", "title": "Disclosure Text", "description": "The disclosure's narrative text. The filer's markup is stripped before storage, so this is plain text." } }, "additionalProperties": false, "type": "object", "required": [ "disclosure_id", "accession_id", "cik", "period_of_report", "concept", "title", "char_count", "disclosure_text" ], "title": "EdgarFilingDisclosureHTTP", "description": "A disclosure together with its narrative text.", "examples": [ { "accession_id": "0000320193-26-000013", "char_count": 426, "cik": "0000320193", "concept": "src:CommercialPaperCashFlowSummaryTableTextBlock", "disclosure_id": "752dddf7-13e7-4658-8a2d-eec39180499d", "disclosure_text": "The following table provides a summary of cash flows associated with commercial paper for the six months ended March 28, 2026 and March 29, 2025 (in millions): Six Months Ended March 28, 2026 March 29, 2025 Maturities 90 days or less: Repayments of commercial paper, net $ (2,123) $ (3,968) Maturities greater than 90 days: Repayments of commercial paper (3,788) — Total repayments of commercial paper, net $ (5,911) $ (3,968)", "period_of_report": "2026-03-28", "title": "Commercial Paper Cash Flow Summary Table" } ] }, "EdgarFilingDisclosureSummaryHTTP": { "properties": { "disclosure_id": { "type": "string", "format": "uuid", "title": "Disclosure Id", "description": "Identifier used to read the disclosure." }, "accession_id": { "type": "string", "title": "Accession Id", "description": "Accession the disclosure was extracted from." }, "cik": { "type": "string", "title": "Cik", "description": "Company CIK as digits." }, "period_of_report": { "type": "string", "format": "date", "title": "Period Of Report", "description": "Period the filing reports on." }, "concept": { "type": "string", "title": "Concept", "description": "Source XBRL concept the disclosure was tagged as." }, "title": { "type": "string", "title": "Title", "description": "Human-readable rendering of the concept." }, "char_count": { "type": "integer", "minimum": 0.0, "title": "Char Count", "description": "Length of the disclosure text in characters." } }, "additionalProperties": false, "type": "object", "required": [ "disclosure_id", "accession_id", "cik", "period_of_report", "concept", "title", "char_count" ], "title": "EdgarFilingDisclosureSummaryHTTP", "description": "A disclosure's identity and size, without its text.\n\nListings return this rather than the disclosure itself: one filing can\ncarry hundreds of kilobytes of narrative across its text blocks.", "examples": [ { "accession_id": "0000320193-24-000123", "char_count": 18422, "cik": "0000320193", "concept": "us-gaap:SegmentReportingDisclosureTextBlock", "disclosure_id": "6d9f1b0e-6c1a-4a1f-9a3c-2f9a1c7d5e10", "period_of_report": "2024-09-28", "title": "Segment Reporting Disclosure" } ] }, "EdgarFilingHTTP": { "properties": { "accession_id": { "type": "string", "title": "Accession Id", "description": "EDGAR accession identifier (e.g., '0000123456-24-000001')." }, "cik": { "type": "string", "title": "Cik", "description": "Central Index Key string for the filer." }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name", "description": "Legal company name for the filer, when known." }, "filing_type": { "type": "string", "title": "Filing Type", "description": "SEC form of the filing as the SEC lists it; an amendment carries the /A suffix (e.g. 10-K, 10-Q, 10-K/A)." }, "filing_date": { "type": "string", "format": "date", "title": "Filing Date", "description": "Filing date as recorded by EDGAR." }, "period_end_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period End Date", "description": "Reporting period end date, if provided." }, "is_amendment": { "type": "boolean", "title": "Is Amendment", "description": "Whether this filing represents an amendment (e.g., 10-K/A)." }, "amendment_sequence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amendment Sequence", "description": "Optional amendment sequence number, when tracked." }, "primary_document": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Primary Document", "description": "Primary document filename for the filing, when known." }, "accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Accepted At", "description": "Optional EDGAR acceptance timestamp, when available." } }, "additionalProperties": false, "type": "object", "required": [ "accession_id", "cik", "filing_type", "filing_date", "is_amendment" ], "title": "EdgarFilingHTTP", "description": "One SEC filing: its accession, form, dates and acceptance time.", "examples": [ { "accepted_at": "2024-11-01T10:01:36Z", "accession_id": "0000320193-24-000123", "cik": "0000320193", "company_name": "Apple Inc.", "filing_date": "2024-11-01", "filing_type": "10-K", "is_amendment": false, "period_end_date": "2024-09-28", "primary_document": "aapl-20240928.htm" } ] }, "EdgarFinancialsAsOfHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK for the requested snapshot." }, "as_of_date": { "type": "string", "format": "date", "title": "As Of Date", "description": "Requested as-of date (YYYY-MM-DD); for a timestamp request, the date the timestamp falls on in its own offset." }, "as_of_timestamp": { "type": "string", "format": "date-time", "title": "As Of Timestamp", "description": "Cutoff used for selection, in UTC. For a date request it is the end of that date, and filings count by the date the SEC gave them; for a timestamp request it is the requested instant, and filings count by when the SEC accepted them." }, "audit_mode": { "type": "boolean", "title": "Audit Mode", "description": "Whether a restated period's statement as first reported was returned beside the restated one.", "default": false }, "snapshot_hash": { "type": "string", "title": "Snapshot Hash", "description": "Identifies the selection: two responses, or two pages of one selection, carry the same snapshot_hash exactly when they select the same filings." }, "_meta": { "anyOf": [ { "$ref": "#/components/schemas/AsOfMetaHTTP" }, { "type": "null" } ], "description": "The snapshot's reconciliation, data-quality and availability summaries. Null unless the request sets detail=true." }, "statements": { "items": { "$ref": "#/components/schemas/EdgarStatementHTTP" }, "type": "array", "title": "Statements", "description": "Deterministically ordered resolved statement payloads." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "as_of_date", "as_of_timestamp", "snapshot_hash" ], "title": "EdgarFinancialsAsOfHTTP", "description": "HTTP schema for an as-of financial snapshot response.", "examples": [ { "_meta": { "data_quality": { "evaluated_rule_count": 12, "not_evaluated_metric_count": 1, "pass_rate": "0.9167", "passed_rule_count": 11, "total_rule_count": 18 }, "reconciliation": { "cross_statement": { "failed_rules": [], "pass_rate": "1.0", "skipped_rules": [], "skipped_rules_count": 0, "supported_rules_count": 2, "total_rules_count": 2 }, "identity": { "checks": [ { "actual_value": "352583000000", "delta": "0", "expected_value": "352583000000", "fiscal_period": "FY", "fiscal_year": 2023, "rule_id": "bs_assets_eq_liab_plus_equity", "severity": "NONE", "statement_type": "BALANCE_SHEET", "status": "PASS" }, { "actual_value": "169147000000", "delta": "-1000000", "expected_value": "169148000000", "fiscal_period": "FY", "fiscal_year": 2023, "rule_id": "is_gross_profit_eq_revenue_less_cost", "severity": "LOW", "statement_type": "INCOME_STATEMENT", "status": "FAIL" }, { "fiscal_period": "FY", "fiscal_year": 2023, "reason": "MISSING_REQUIRED_METRICS", "rule_id": "bs_assets_eq_current_plus_noncurrent", "severity": "NONE", "statement_type": "BALANCE_SHEET", "status": "SKIPPED" } ], "failed_rules_count": 1, "pass_rate": "0.5", "skipped_rules_count": 1, "supported_rules_count": 2, "total_rules_count": 3 }, "reconciliation_skipped_rules_count": 1, "reconciliation_supported_rules_count": 6, "reconciliation_total_rules_count": 7, "rollforward": { "failed_rules": [], "pass_rate": "1.0", "skipped_rules": [], "skipped_rules_count": 0, "supported_rules_count": 2, "total_rules_count": 2 } } }, "as_of_date": "2024-03-31", "as_of_timestamp": "2024-03-31T23:59:59.999999Z", "cik": "0000320193", "snapshot_hash": "b3c5b4caa72f3b6fe5ed2104399ad9c6c5f0a8e0a6e1f5e8c6b4d329b19d6a4f", "statements": [] } ] }, "EdgarFinancialsAsOfPageHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK for the requested snapshot." }, "as_of_date": { "type": "string", "format": "date", "title": "As Of Date", "description": "Requested as-of date (YYYY-MM-DD); for a timestamp request, the date the timestamp falls on in its own offset." }, "as_of_timestamp": { "type": "string", "format": "date-time", "title": "As Of Timestamp", "description": "Cutoff used for selection, in UTC. For a date request it is the end of that date, and filings count by the date the SEC gave them; for a timestamp request it is the requested instant, and filings count by when the SEC accepted them." }, "audit_mode": { "type": "boolean", "title": "Audit Mode", "description": "Whether a restated period's statement as first reported was returned beside the restated one.", "default": false }, "snapshot_hash": { "type": "string", "title": "Snapshot Hash", "description": "Identifies the selection: two responses, or two pages of one selection, carry the same snapshot_hash exactly when they select the same filings." }, "_meta": { "anyOf": [ { "$ref": "#/components/schemas/AsOfMetaHTTP" }, { "type": "null" } ], "description": "Always null on a page. Reconciliation and data quality are summarized over the full selection; GET /v1/edgar/as-of/{date}/financials/{cik} returns them." }, "statements": { "items": { "$ref": "#/components/schemas/AsOfPageStatementHTTP" }, "type": "array", "title": "Statements", "description": "The page's statements, in the full route's deterministic order: identity, filing and values, and with detail=true the facts, per-metric provenance and the statement's quality block." }, "snapshot_statement_count": { "type": "integer", "title": "Snapshot Statement Count", "description": "Statements in the full as-of selection, before filters." }, "matched_count": { "type": "integer", "title": "Matched Count", "description": "Statements in the selection that match the filters." }, "selected_count": { "type": "integer", "title": "Selected Count", "description": "Statements eligible for paging: matched_count, or one per statement type when latest_only is true." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "as_of_date", "as_of_timestamp", "snapshot_hash", "snapshot_statement_count", "matched_count", "selected_count" ], "title": "EdgarFinancialsAsOfPageHTTP", "description": "One page of a company's as-of selection.\n\n``statements`` holds the page's statements only, each\nwith its identity, filing and values, and with ``detail`` its facts,\nper-metric provenance and quality block. ``_meta`` is\nnull: reconciliation and data quality are summarized over the full\nselection, which the full route returns. ``snapshot_hash`` identifies the full selection, as\non the full route." }, "EdgarStatementHTTP": { "properties": { "accession_id": { "type": "string", "title": "Accession Id", "description": "EDGAR accession identifier of the filing that reported this statement. With cik, statement_type, fiscal_year and fiscal_period it identifies the statement; a filing that splits one fiscal year into two OTHER periods is told apart by statement_date." }, "cik": { "type": "string", "title": "Cik", "description": "Central Index Key string for the filer." }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name", "description": "Legal company name for the filer, when available." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "High-level statement taxonomy (income, balance sheet, cash flow)." }, "accounting_standard": { "$ref": "#/components/schemas/AccountingStandard", "description": "Accounting standard used (e.g., US_GAAP, IFRS)." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Statement period end date." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year associated with the statement. The filer's own name for its fiscal year, as its annual reports declare it: a year closing 2025-02-01 that the filer calls fiscal 2024 is served as 2024." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period within the year. FY is a whole fiscal year: 358 to 372 days, or the year the filer declares. Q1-Q4 are quarters and H1 a half year. OTHER is any other reported span: a transition period, a short first year, or one of the two periods of a fiscal year split at a business combination or fresh-start reorganization. An OTHER period's dates are period_start and statement_date, and two OTHER periods are never added together into a year." }, "period_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period Start", "description": "First day of the period the statement reports; statement_date is the last. Null for a balance sheet, which reports a single date, and when the filing's span is not available." }, "reporting_entity": { "type": "string", "enum": [ "REGISTRANT", "PREDECESSOR" ], "title": "Reporting Entity", "description": "PREDECESSOR when the filing presents this period as its predecessor's: the business the registrant succeeded in a business combination or fresh-start reorganization, which it reports as its own history; otherwise REGISTRANT.", "default": "REGISTRANT" }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency code for reported values (e.g., USD)." }, "is_restated": { "type": "boolean", "title": "Is Restated", "description": "Whether this statement restates figures the company reported earlier." }, "filing_type": { "type": "string", "title": "Filing Type", "description": "SEC form of the underlying filing as the SEC lists it; an amendment carries the /A suffix (e.g. 10-K, 10-Q, 10-K/A)." }, "is_amendment": { "type": "boolean", "title": "Is Amendment", "description": "Whether the underlying filing amends a prior submission (e.g., 10-K/A)." }, "amendment_sequence": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amendment Sequence", "description": "Amendment sequence number of the underlying filing, when it is an amendment." }, "filing_date": { "type": "string", "format": "date", "title": "Filing Date", "description": "Filing date of the underlying filing." }, "accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Accepted At", "description": "EDGAR acceptance timestamp, when available." }, "values": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Values", "description": "The statement's consolidated figures for its own period, one entry per metric code (e.g., REVENUE, NET_INCOME), each a decimal string in full units as filed. A metric the filing did not report is absent." }, "units": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Units", "description": "The unit of each entry in values, keyed by the same metric code (e.g., USD, USD/share, SHARE)." }, "usd": { "anyOf": [ { "$ref": "#/components/schemas/StatementUsdHTTP" }, { "type": "null" } ], "description": "Present only when include_usd=true and the statement converts: its money values in US dollars, with the rate, the rate's dates and its source. Absent when no rate covers the statement's period: the Federal Reserve Board's H.10 release publishes rates for 22 currencies, and an as-of request uses only rates published by its date. values always stay as filed." }, "content": { "anyOf": [ { "$ref": "#/components/schemas/NormalizedStatementHTTP" }, { "type": "null" } ], "description": "The statement's facts with their dimensions, periods and per-metric provenance. Null unless the request sets detail=true." }, "quality": { "anyOf": [ { "$ref": "#/components/schemas/StatementQualityHTTP" }, { "type": "null" } ], "description": "The statement's quality, part by part: metric completeness, reconciliation results, data-quality findings and how its metrics were mapped. Null unless the request sets detail=true." } }, "additionalProperties": false, "type": "object", "required": [ "accession_id", "cik", "statement_type", "accounting_standard", "statement_date", "fiscal_year", "fiscal_period", "currency", "is_restated", "filing_type", "is_amendment", "filing_date" ], "title": "EdgarStatementHTTP", "description": "One SEC filing's statement: its identity, its filing and, optionally, its figures.", "examples": [ { "accepted_at": "2026-07-31T10:01:02Z", "accession_id": "0000320193-26-000020", "accounting_standard": "US_GAAP", "cik": "0000320193", "company_name": "Apple Inc.", "currency": "USD", "filing_date": "2026-07-31", "filing_type": "10-Q", "fiscal_period": "Q3", "fiscal_year": 2026, "is_amendment": false, "is_restated": false, "period_start": "2026-03-29", "reporting_entity": "REGISTRANT", "statement_date": "2026-06-27", "statement_type": "INCOME_STATEMENT", "units": { "NET_INCOME": "USD", "REVENUE": "USD" }, "values": { "NET_INCOME": "29789000000", "REVENUE": "109417000000" } } ] }, "EdgarStatementListHTTP": { "properties": { "filing": { "anyOf": [ { "$ref": "#/components/schemas/EdgarFilingHTTP" }, { "type": "null" } ], "description": "The filing every listed statement came from." }, "items": { "items": { "$ref": "#/components/schemas/EdgarStatementHTTP" }, "type": "array", "title": "Items", "description": "The statements the filing reported." } }, "additionalProperties": false, "type": "object", "title": "EdgarStatementListHTTP", "description": "The statements one SEC filing reported, with the filing they came from.", "examples": [ { "filing": { "accepted_at": "2024-11-01T10:01:36Z", "accession_id": "0000320193-24-000123", "cik": "0000320193", "company_name": "Apple Inc.", "filing_date": "2024-11-01", "filing_type": "10-K", "is_amendment": false, "period_end_date": "2024-09-28", "primary_document": "aapl-20240928.htm" }, "items": [ { "accepted_at": "2024-11-01T10:01:36Z", "accession_id": "0000320193-24-000123", "accounting_standard": "US_GAAP", "cik": "0000320193", "company_name": "Apple Inc.", "currency": "USD", "filing_date": "2024-11-01", "filing_type": "10-K", "fiscal_period": "FY", "fiscal_year": 2024, "is_amendment": false, "is_restated": false, "period_start": "2023-10-01", "reporting_entity": "REGISTRANT", "statement_date": "2024-09-28", "statement_type": "CASH_FLOW_STATEMENT" }, { "accepted_at": "2024-11-01T10:01:36Z", "accession_id": "0000320193-24-000123", "accounting_standard": "US_GAAP", "cik": "0000320193", "company_name": "Apple Inc.", "currency": "USD", "filing_date": "2024-11-01", "filing_type": "10-K", "fiscal_period": "FY", "fiscal_year": 2024, "is_amendment": false, "is_restated": false, "reporting_entity": "REGISTRANT", "statement_date": "2024-09-28", "statement_type": "BALANCE_SHEET" } ] } ] }, "EndpointAvailabilityEvidenceHTTP": { "properties": { "accession_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accession Id", "description": "SEC accession of the filing, when there is one." } }, "additionalProperties": false, "type": "object", "title": "EndpointAvailabilityEvidenceHTTP", "description": "The SEC filing behind an availability decision." }, "EndpointAvailabilityHTTP": { "properties": { "availability_status": { "type": "string", "title": "Availability Status", "description": "Availability classification: PUBLISHED, TERMINAL_SOURCE_GAP, NOT_REQUIRED_OUTSIDE_REPORTING_LIFECYCLE, NO_DATA, UNSUPPORTED_QUERY, or MIXED." }, "reporting_lifecycle_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reporting Lifecycle Status", "description": "Issuer reporting lifecycle status when available." }, "source_gap_terminal": { "type": "boolean", "title": "Source Gap Terminal", "description": "Whether the missing data is a terminal source gap.", "default": false }, "required": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Required", "description": "Whether the period falls inside the company's SEC reporting lifecycle." }, "identity": { "$ref": "#/components/schemas/EndpointAvailabilityIdentityHTTP", "description": "Statement identity represented by this metadata." }, "evidence": { "anyOf": [ { "$ref": "#/components/schemas/EndpointAvailabilityEvidenceHTTP" }, { "type": "null" } ], "description": "The SEC filing behind the availability decision, when there is one." }, "summary": { "anyOf": [ { "$ref": "#/components/schemas/EndpointAvailabilitySummaryHTTP" }, { "type": "null" } ], "description": "Optional query-window summary counts." } }, "additionalProperties": false, "type": "object", "required": [ "availability_status", "identity" ], "title": "EndpointAvailabilityHTTP", "description": "Whether the requested statements are available, and if not, why." }, "EndpointAvailabilityIdentityHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Canonical zero-padded company CIK." }, "statement_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Statement Type", "description": "Canonical statement type." }, "fiscal_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Fiscal Year", "description": "Fiscal year when applicable." }, "fiscal_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Fiscal Period", "description": "Fiscal period when applicable." } }, "additionalProperties": false, "type": "object", "required": [ "cik" ], "title": "EndpointAvailabilityIdentityHTTP", "description": "HTTP statement identity represented by availability metadata." }, "EndpointAvailabilitySummaryHTTP": { "properties": { "published": { "type": "integer", "minimum": 0.0, "title": "Published", "description": "Periods with a served statement.", "default": 0 }, "terminal_source_gap": { "type": "integer", "minimum": 0.0, "title": "Terminal Source Gap", "description": "Periods the filer's SEC filings do not support.", "default": 0 }, "outside_lifecycle": { "type": "integer", "minimum": 0.0, "title": "Outside Lifecycle", "description": "Periods outside the company's SEC reporting lifecycle.", "default": 0 }, "ordinary_no_data": { "type": "integer", "minimum": 0.0, "title": "Ordinary No Data", "description": "Periods with no data.", "default": 0 }, "unsupported_query": { "type": "integer", "minimum": 0.0, "title": "Unsupported Query", "description": "Periods the query cannot answer.", "default": 0 }, "total": { "type": "integer", "minimum": 0.0, "title": "Total", "description": "Periods classified.", "default": 0 } }, "additionalProperties": false, "type": "object", "title": "EndpointAvailabilitySummaryHTTP", "description": "HTTP aggregate availability counts for a query window." }, "ErrorEnvelope": { "properties": { "error": { "$ref": "#/components/schemas/ErrorObject", "description": "Structured error details." } }, "additionalProperties": false, "type": "object", "required": [ "error" ], "title": "ErrorEnvelope", "description": "Canonical error envelope: {\"error\": ErrorObject}.", "examples": [ { "error": { "code": "VALIDATION_ERROR", "details": {}, "http_status": 422, "message": "Request validation failed", "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } } ] }, "ErrorObject": { "properties": { "code": { "type": "string", "title": "Code", "description": "Stable machine-readable error code.\n\n**Idempotency codes:**\n- `IDEMPOTENCY_KEY_CONFLICT`: Key reused with different request payload.\n- `IDEMPOTENCY_KEY_IN_PROGRESS`: Another request with same key is in progress.\n\nOther subsystems define additional codes (e.g. MARKET_DATA_*, VALIDATION_ERROR)." }, "http_status": { "type": "integer", "title": "Http Status", "description": "Associated HTTP status." }, "message": { "type": "string", "title": "Message", "description": "Human-readable error description." }, "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Details", "description": "Optional structured details safe for clients." }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Trace Id", "description": "Request correlation identifier." } }, "additionalProperties": false, "type": "object", "required": [ "code", "http_status", "message" ], "title": "ErrorObject", "description": "Structured error object inside ErrorEnvelope.\n\nError codes follow API Standards:\n - UPPER_SNAKE_CASE\n - Stable across releases\n - Client-visible and testable\n\nIdempotency-specific codes included:\n - IDEMPOTENCY_KEY_CONFLICT: Key reused with different payload.\n - IDEMPOTENCY_KEY_IN_PROGRESS: Another request with same key is in-flight.", "examples": [ { "code": "VALIDATION_ERROR", "details": {}, "http_status": 422, "message": "Request validation failed", "trace_id": "0f4a6d1c-3f2b-4a85-9d0e-2b7c8e5a1f33" } ] }, "FactQualityHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "statement_type": { "type": "string", "title": "Statement Type", "description": "Statement type (e.g. INCOME_STATEMENT)." }, "fiscal_year": { "type": "integer", "minimum": 0.0, "title": "Fiscal Year", "description": "Fiscal year (>= 0)." }, "fiscal_period": { "type": "string", "title": "Fiscal Period", "description": "Fiscal period (e.g. FY, Q1, Q2, Q3, Q4)." }, "metric": { "type": "string", "title": "Metric", "description": "Canonical metric code for the fact." }, "dimension_key": { "type": "string", "title": "Dimension Key", "description": "Dimensional key for the fact (e.g. segment)." }, "severity": { "$ref": "#/components/schemas/MaterialityClass", "description": "Fact-level severity (NONE, LOW, MEDIUM, HIGH)." }, "is_present": { "type": "boolean", "title": "Is Present", "description": "Whether the fact is present in the data set." }, "is_non_negative": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Non Negative", "description": "Whether the fact passed the NON_NEGATIVE rule (if applicable)." }, "is_consistent_with_history": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Consistent With History", "description": "Whether the fact is consistent with historical behavior (if applicable)." }, "has_known_issue": { "type": "boolean", "title": "Has Known Issue", "description": "Whether the fact is known to have an issue." }, "details": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Details", "description": "Machine-readable details for the quality evaluation." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "fiscal_year", "fiscal_period", "metric", "dimension_key", "severity", "is_present", "has_known_issue" ], "title": "FactQualityHTTP", "description": "Data-quality evaluation of one fact." }, "FactRevisionEventHTTP": { "properties": { "accession_id": { "type": "string", "title": "Accession Id", "description": "EDGAR accession of the filing whose statement recorded the revision." }, "previous_accession_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Accession Id", "description": "EDGAR accession of the earlier filing the revision is measured against, when there is one." }, "metric_code": { "type": "string", "title": "Metric Code" }, "dimension_key": { "type": "string", "title": "Dimension Key" }, "previous_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Value" }, "current_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Value" }, "delta_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Delta Value" }, "previous_unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Unit" }, "current_unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Unit" }, "previous_source_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Previous Source Concept" }, "current_source_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Source Concept" }, "change_type": { "type": "string", "enum": [ "NEW_DISCLOSURE", "REMOVED_DISCLOSURE", "VALUE_REVISION", "RECLASSIFICATION", "PERIOD_CORRECTION", "CONCEPT_CHANGE", "PRESENTATION_ONLY" ], "title": "Change Type", "description": "What the filing changed about the fact." }, "effective_at": { "type": "string", "format": "date-time", "title": "Effective At" }, "known_at": { "type": "string", "format": "date-time", "title": "Known At" } }, "additionalProperties": false, "type": "object", "required": [ "accession_id", "metric_code", "dimension_key", "change_type", "effective_at", "known_at" ], "title": "FactRevisionEventHTTP", "description": "HTTP schema for one immutable fact revision event." }, "FactRevisionLedgerHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Canonical company CIK of the statement." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement family (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year of the statement." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period of the statement (e.g., FY, Q1)." }, "accession_id": { "type": "string", "title": "Accession Id", "description": "EDGAR accession of the filing that reported the statement." }, "items": { "items": { "$ref": "#/components/schemas/FactRevisionEventHTTP" }, "type": "array", "title": "Items", "description": "Revision events the filing's statement recorded against the earlier filing, ordered by metric_code, dimension_key, then event identifier." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "fiscal_year", "fiscal_period", "accession_id" ], "title": "FactRevisionLedgerHTTP", "description": "HTTP schema for one filing statement's fact revision ledger.", "examples": [ { "accession_id": "0000320193-24-000123", "cik": "0000320193", "fiscal_period": "FY", "fiscal_year": 2024, "items": [], "statement_type": "INCOME_STATEMENT" } ] }, "FilingFactDimensionHTTP": { "properties": { "axis": { "type": "string", "title": "Axis", "description": "Qualified XBRL axis.", "examples": [ "srt:ProductOrServiceAxis" ] }, "member": { "type": "string", "title": "Member", "description": "Qualified member of the axis, or the value itself for a typed axis.", "examples": [ "aapl:IPhoneMember" ] } }, "additionalProperties": false, "type": "object", "required": [ "axis", "member" ], "title": "FilingFactDimensionHTTP", "description": "One axis and member qualifying a filing fact." }, "FilingFactHTTP": { "properties": { "concept": { "type": "string", "title": "Concept", "description": "Qualified XBRL concept. A prefix other than a standard taxonomy's (us-gaap, ifrs-full, dei, srt) is the filer's own extension concept." }, "unit": { "type": "string", "title": "Unit", "description": "Unit of measure, e.g. USD, shares or USD/shares." }, "value": { "type": "string", "title": "Value", "description": "The value exactly as filed, as a decimal string." }, "decimals": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Decimals", "description": "The filer's stated precision: -6 means accurate to millions. Null when the value is exact." }, "period_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period Start", "description": "First day of the period; null for a value at a point in time." }, "period_end": { "type": "string", "format": "date", "title": "Period End", "description": "Last day of the period, or the date of a point-in-time value." }, "dimensions": { "items": { "$ref": "#/components/schemas/FilingFactDimensionHTTP" }, "type": "array", "title": "Dimensions", "description": "Axes and members the value is broken out by, such as a segment, product or country; empty for the consolidated company." } }, "additionalProperties": false, "type": "object", "required": [ "concept", "unit", "value", "period_end", "dimensions" ], "title": "FilingFactHTTP", "description": "One numeric value a filing tagged in XBRL, as filed.", "examples": [ { "concept": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", "decimals": -6, "dimensions": [ { "axis": "srt:ProductOrServiceAxis", "member": "aapl:IPhoneMember" } ], "period_end": "2025-09-27", "period_start": "2024-09-29", "unit": "USD", "value": "209586000000" } ] }, "FilingType": { "type": "string", "enum": [ "10-K", "10-Q", "10-KT", "10-QT", "8-K", "20-F", "40-F", "6-K", "S-1", "S-3", "OTHER", "10-K", "10-Q", "8-K", "20-F", "40-F", "6-K", "S-1", "S-3" ], "title": "FilingType", "description": "Supported EDGAR filing types.\n\nValues are normalized, provider-agnostic tokens rather than raw SEC form codes.\nNaming is stable and JSON/OpenAPI-friendly; values preserve the original\nEDGAR form codes (e.g., \"10-K\")." }, "FinancialStateCompletenessHTTP": { "properties": { "metrics_expected": { "type": "integer", "title": "Metrics Expected", "description": "Count of aligned canonical metrics expected." }, "metrics_populated": { "type": "integer", "title": "Metrics Populated", "description": "Count of aligned canonical metrics with values." }, "completeness_ratio": { "type": "string", "title": "Completeness Ratio", "description": "Decimal-string completeness ratio." }, "missing_metrics": { "items": { "type": "string" }, "type": "array", "title": "Missing Metrics", "description": "Deterministically ordered canonical metrics missing from the row." }, "by_statement_type": { "additionalProperties": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "integer" }, { "items": { "type": "string" }, "type": "array" } ] }, "type": "object" }, "type": "object", "title": "By Statement Type", "description": "Per-statement completeness keyed by statement type." } }, "additionalProperties": false, "type": "object", "required": [ "metrics_expected", "metrics_populated", "completeness_ratio", "missing_metrics", "by_statement_type" ], "title": "FinancialStateCompletenessHTTP", "description": "HTTP schema for deterministic completeness metadata on financial-state rows." }, "FinancialStatePeriodHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Canonical company CIK." }, "fiscal_year": { "type": "integer", "title": "Fiscal Year", "description": "Fiscal year." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period." }, "period_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period Start", "description": "Earliest known period start." }, "period_end": { "type": "string", "format": "date", "title": "Period End", "description": "Aligned fiscal period end date." }, "accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Accepted At", "description": "Latest visible SEC acceptance timestamp across aligned statements." }, "filing_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Filing Date", "description": "Latest visible filing date across aligned statements." }, "source_accessions": { "items": { "type": "string" }, "type": "array", "title": "Source Accessions", "description": "Deterministically ordered source filing accessions for the row." }, "metrics": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "object", "title": "Metrics", "description": "Aligned canonical metric values; unavailable metrics remain null." }, "provenance": { "anyOf": [ { "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/MetricProvenanceHTTP" }, { "type": "null" } ] }, "type": "object" }, { "type": "null" } ], "title": "Provenance", "description": "Optional per-metric provenance keyed by metric code." }, "macro_context": { "anyOf": [ { "$ref": "#/components/schemas/MacroContextHTTP" }, { "type": "null" } ], "description": "Optional macro context aligned to the period end date." }, "completeness": { "$ref": "#/components/schemas/FinancialStateCompletenessHTTP", "description": "Deterministic completeness summary for the aligned row." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "fiscal_year", "fiscal_period", "period_end", "source_accessions", "metrics", "completeness" ], "title": "FinancialStatePeriodHTTP", "description": "HTTP schema for one aligned financial-state row." }, "FiscalPeriod": { "type": "string", "enum": [ "FY", "Q1", "Q2", "Q3", "Q4", "H1", "OTHER" ], "title": "FiscalPeriod", "description": "Fiscal period of a statement.\n\nExamples:\n FY: Full year\n Q1, Q2, Q3, Q4: Quarterly\n H1: First half, if applicable." }, "FundamentalsTimeSeriesPointHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Central Index Key for the filer." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "High-level statement taxonomy (income, balance sheet, cash flow)." }, "accounting_standard": { "$ref": "#/components/schemas/AccountingStandard", "description": "Accounting standard (e.g., US_GAAP, IFRS)." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Reporting period end date for this time-series point." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year associated with the statement (e.g., 2024)." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period within the year (e.g., Q1, Q2, FY)." }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency code for all monetary metrics (e.g., USD)." }, "metrics": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metrics", "description": "Mapping of canonical metric codes (e.g., REVENUE) to decimal string values. Only metrics present in the underlying normalized payload are included." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "accounting_standard", "statement_date", "fiscal_year", "fiscal_period", "currency" ], "title": "FundamentalsTimeSeriesPointHTTP", "description": "HTTP schema for a single fundamentals time-series point.\n\nThis schema represents the modeling-friendly view of a normalized EDGAR\nstatement period, ready for panel/time-series analytics.\n\nAttributes:\n cik:\n Central Index Key for the filer.\n statement_type:\n Statement type (income, balance sheet, cash flow, etc.).\n accounting_standard:\n Accounting standard (e.g., US_GAAP, IFRS).\n statement_date:\n Reporting period end date.\n fiscal_year:\n Fiscal year associated with the statement (>= 1).\n fiscal_period:\n Fiscal period within the year (e.g., FY, Q1, Q2).\n currency:\n ISO 4217 currency code (e.g., \"USD\").\n metrics:\n Mapping from canonical metric codes (e.g., \"REVENUE\") to decimal\n string values (e.g., \"383285000000\"). Only metrics actually present\n in the underlying normalized payload are included.", "examples": [ { "accounting_standard": "US_GAAP", "cik": "0000320193", "currency": "USD", "fiscal_period": "FY", "fiscal_year": 2024, "metrics": { "NET_INCOME": "96995000000", "REVENUE": "383285000000" }, "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT" } ] }, "HealthState": { "type": "string", "enum": [ "ok", "degraded", "down" ], "title": "HealthState", "description": "Overall service health classification." }, "IdentityCheckHTTP": { "properties": { "rule_id": { "type": "string", "title": "Rule Id", "description": "Stable accounting-identity rule id." }, "statement_type": { "type": "string", "title": "Statement Type", "description": "Statement type the rule was evaluated against." }, "fiscal_year": { "type": "integer", "title": "Fiscal Year", "description": "Fiscal year of the checked statement." }, "fiscal_period": { "type": "string", "title": "Fiscal Period", "description": "Fiscal period of the checked statement." }, "status": { "type": "string", "title": "Status", "description": "Rule outcome: PASS, FAIL, or SKIPPED. SKIPPED means the rule could not be concluded for this period, for the reason in `reason`: the filing did not report an addend the identity requires (MISSING_REQUIRED_METRICS, with a null expected and actual value), or one of the compared figures was itself derived from this identity, so the figures hold by construction and say nothing about the filing (INPUT_DERIVED_FROM_IDENTITY, with the compared values shown). Pass rates are computed over concluded checks only, so SKIPPED checks are excluded from both numerator and denominator." }, "severity": { "type": "string", "title": "Severity", "description": "Materiality class configured for the rule." }, "expected_value": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Expected Value", "description": "Value the identity expected, as a decimal string." }, "actual_value": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Actual Value", "description": "Value the statement actually held, as a decimal string." }, "delta": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Delta", "description": "Actual minus expected, as a decimal string." }, "tolerance": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Tolerance", "description": "Bar this check was held to, as a decimal string. An identity is compared against a tolerance that scales with the size of the figures, so a delta is only readable next to it. A served statement can report a failing identity here, and the delta and tolerance say by how much. Null for a check that compares no magnitudes, such as a calendar rule, and for a check skipped for a missing figure." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Stable reason code for a check that was not concluded, such as MISSING_REQUIRED_METRICS or INPUT_DERIVED_FROM_IDENTITY. Null for a PASS or FAIL.", "examples": [ "INPUT_DERIVED_FROM_IDENTITY" ] } }, "additionalProperties": false, "type": "object", "required": [ "rule_id", "statement_type", "fiscal_year", "fiscal_period", "status", "severity" ], "title": "IdentityCheckHTTP", "description": "One evaluated accounting-identity reconciliation rule." }, "IdentitySummaryHTTP": { "properties": { "pass_rate": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Pass Rate", "description": "Pass rate in [0,1] across the accounting-identity checks that were evaluated (skipped checks are excluded). Null when no check was evaluated: a skipped check is neither a pass nor a fail." }, "total_rules_count": { "type": "integer", "minimum": 0.0, "title": "Total Rules Count", "description": "Total accounting-identity checks evaluated for this response." }, "supported_rules_count": { "type": "integer", "minimum": 0.0, "title": "Supported Rules Count", "description": "Identity checks with sufficient inputs (pass-rate denominator)." }, "skipped_rules_count": { "type": "integer", "minimum": 0.0, "title": "Skipped Rules Count", "description": "Identity checks not concluded: a required metric was absent, or a compared figure was derived from the identity itself." }, "failed_rules_count": { "type": "integer", "minimum": 0.0, "title": "Failed Rules Count", "description": "Identity checks whose two sides did not reconcile." }, "checks": { "items": { "$ref": "#/components/schemas/IdentityCheckHTTP" }, "type": "array", "title": "Checks", "description": "Every evaluated identity check with its expected and actual value, ordered by statement type, fiscal year, fiscal period and rule id." } }, "additionalProperties": false, "type": "object", "required": [ "pass_rate", "total_rules_count", "supported_rules_count", "skipped_rules_count", "failed_rules_count" ], "title": "IdentitySummaryHTTP", "description": "Accounting-identity reconciliation summary metadata." }, "IngestionJobStatusHTTP": { "properties": { "job_name": { "type": "string", "title": "Job Name", "description": "EDGAR feed identifier.", "examples": [ "edgar_filings" ] }, "source": { "type": "string", "title": "Source", "description": "Source system identifier.", "examples": [ "edgar" ] }, "last_triggered": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Triggered", "description": "UTC timestamp of the last job trigger (if any)." }, "last_success": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Success", "description": "UTC timestamp of the last successful run (if any)." }, "last_failure": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Failure", "description": "UTC timestamp of the last failed run (if any)." }, "consecutive_failures": { "type": "integer", "title": "Consecutive Failures", "description": "Count of consecutive failures since last success.", "examples": [ 0, 2 ] }, "last_error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Error Code", "description": "Stable error code from the last failure (if any).", "examples": [ "UPSTREAM_UNAVAILABLE" ] }, "lag_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Lag Seconds", "description": "Seconds since last success (now - last_success).", "examples": [ 120.0, 3600.0 ] }, "stale": { "type": "boolean", "title": "Stale", "description": "True when freshness exceeds the configured threshold." }, "stale_reason": { "type": "string", "title": "Stale Reason", "description": "Stable staleness reason. Values: `fresh`, `lag_exceeded`, `no_success`, `disabled`, `freshness_not_enforced`.", "examples": [ "fresh" ] } }, "additionalProperties": false, "type": "object", "required": [ "job_name", "source", "consecutive_failures", "stale", "stale_reason" ], "title": "IngestionJobStatusHTTP", "description": "How current one EDGAR feed is.", "examples": [ { "consecutive_failures": 0, "job_name": "edgar_filings", "lag_seconds": 3720.0, "last_success": "2025-01-02T02:48:00Z", "last_triggered": "2025-01-02T02:10:00Z", "source": "edgar", "stale": false, "stale_reason": "fresh" } ] }, "IngestionStatusHTTP": { "properties": { "jobs": { "items": { "$ref": "#/components/schemas/IngestionJobStatusHTTP" }, "type": "array", "title": "Jobs", "description": "One entry per EDGAR feed, in a fixed order." } }, "additionalProperties": false, "type": "object", "required": [ "jobs" ], "title": "IngestionStatusHTTP", "description": "How current each EDGAR feed is.", "examples": [ { "jobs": [ { "consecutive_failures": 1, "job_name": "edgar_filings", "lag_seconds": 112140.0, "last_error_code": "UPSTREAM_UNAVAILABLE", "last_failure": "2025-01-02T02:31:00Z", "last_success": "2025-01-01T02:51:00Z", "last_triggered": "2025-01-02T02:10:00Z", "source": "edgar", "stale": true, "stale_reason": "lag_exceeded" } ] } ] }, "LivenessResponse": { "properties": { "status": { "type": "string", "const": "ok", "title": "Status", "default": "ok" } }, "additionalProperties": false, "type": "object", "title": "LivenessResponse", "description": "Liveness response indicating the process is running.", "examples": [ { "status": "ok" } ] }, "MCPManifestHTTP": { "properties": { "server_name": { "type": "string", "title": "Server Name", "description": "Server name reported in `initialize`.", "examples": [ "arche-mcp" ] }, "version": { "type": "string", "title": "Version", "description": "MCP manifest version, reported as `serverInfo.version`.", "examples": [ "1.6.0" ] }, "path": { "type": "string", "title": "Path", "description": "Path of the MCP endpoint on this host.", "examples": [ "/mcp" ] }, "http_method": { "type": "string", "title": "Http Method", "description": "HTTP method the endpoint accepts.", "examples": [ "POST" ] }, "transport": { "type": "string", "title": "Transport", "description": "MCP transport. Streamable HTTP in JSON response mode: no SSE stream is offered, and GET on the endpoint returns 405.", "examples": [ "streamable-http" ] }, "protocol_versions": { "items": { "type": "string" }, "type": "array", "title": "Protocol Versions", "description": "MCP protocol versions `initialize` negotiates, newest first." }, "auth_header": { "type": "string", "title": "Auth Header", "description": "Header carrying the API key on every MCP request.", "examples": [ "X-Api-Key" ] }, "rate_limit_class": { "type": "string", "title": "Rate Limit Class", "description": "Rate-limit class the endpoint is metered under, separate from `read`.", "examples": [ "mcp" ] }, "rate_limits": { "items": { "$ref": "#/components/schemas/MCPRateLimitHTTP" }, "type": "array", "title": "Rate Limits", "description": "Enforced `mcp` class limit per plan, in plan order. A plan whose limits are negotiated per agreement (Enterprise) carries no figure." }, "request_max_bytes": { "type": "integer", "title": "Request Max Bytes", "description": "Largest request body accepted; larger bodies receive 413.", "examples": [ 1048576 ] }, "response_max_bytes": { "type": "integer", "title": "Response Max Bytes", "description": "Largest result a tool relays. A call whose result exceeds it fails with a `RESPONSE_TOO_LARGE` tool error; narrow the request instead.", "examples": [ 2097152 ] }, "tools": { "items": { "$ref": "#/components/schemas/MCPToolHTTP" }, "type": "array", "title": "Tools", "description": "Every tool, in the order `tools/list` returns them." } }, "additionalProperties": false, "type": "object", "required": [ "server_name", "version", "path", "http_method", "transport", "protocol_versions", "auth_header", "rate_limit_class", "rate_limits", "request_max_bytes", "response_max_bytes", "tools" ], "title": "MCPManifestHTTP", "description": "How to connect to the Arche MCP endpoint and what it offers.", "examples": [ { "auth_header": "X-Api-Key", "http_method": "POST", "path": "/mcp", "protocol_versions": [ "2025-06-18", "2025-03-26", "2024-11-05" ], "rate_limit_class": "mcp", "rate_limits": [ { "limit": 10, "negotiated": false, "tier": "free", "window_seconds": 60 }, { "limit": 600, "negotiated": false, "tier": "growth", "window_seconds": 60 }, { "negotiated": true, "tier": "enterprise", "window_seconds": 60 } ], "request_max_bytes": 1048576, "response_max_bytes": 2097152, "server_name": "arche-mcp", "tools": [ { "description": "Fetch modeling ratio rows for a company.", "input_schema": { "type": "object" }, "method": "modeling.ratios", "minimum_tier": "growth", "name": "modeling_ratios" } ], "transport": "streamable-http", "version": "1.6.0" } ] }, "MCPRateLimitHTTP": { "properties": { "tier": { "type": "string", "title": "Tier", "description": "Plan the limit applies to.", "examples": [ "free" ] }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit", "description": "Requests allowed per window. Null when `negotiated` is true: the plan's limit is set by its agreement and reported in the developer portal.", "examples": [ 10 ] }, "window_seconds": { "type": "integer", "title": "Window Seconds", "description": "Window length in seconds.", "examples": [ 60 ] }, "negotiated": { "type": "boolean", "title": "Negotiated", "description": "Whether the plan's limit is negotiated per agreement rather than published.", "examples": [ false ] } }, "additionalProperties": false, "type": "object", "required": [ "tier", "limit", "window_seconds", "negotiated" ], "title": "MCPRateLimitHTTP", "description": "The rate limit one plan is metered against on the MCP endpoint." }, "MCPToolHTTP": { "properties": { "name": { "type": "string", "title": "Name", "description": "Tool name to pass to `tools/call`.", "examples": [ "modeling_ratios" ] }, "method": { "type": "string", "title": "Method", "description": "Dotted method name accepted by the legacy `{method, params}` envelope.", "examples": [ "modeling.ratios" ] }, "description": { "type": "string", "title": "Description", "description": "What the tool returns and when to call it." }, "input_schema": { "additionalProperties": true, "type": "object", "title": "Input Schema", "description": "JSON Schema for the tool's `arguments`, identical to `inputSchema`." }, "minimum_tier": { "type": "string", "title": "Minimum Tier", "description": "Least-entitled plan that may call the tool. A key below it receives a `FEATURE_NOT_AVAILABLE` tool error. Values: `free`, `developer`, `growth`, `scale`, `enterprise`.", "examples": [ "growth" ] } }, "additionalProperties": false, "type": "object", "required": [ "name", "method", "description", "input_schema", "minimum_tier" ], "title": "MCPToolHTTP", "description": "One MCP tool, as `tools/list` returns it, with its minimum plan." }, "MacroContextHTTP": { "properties": { "as_of_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "As Of Date", "description": "Optional as-of date used for PIT semantics." }, "date": { "type": "string", "format": "date", "title": "Date", "description": "Target date for contextualization." }, "cpi": { "$ref": "#/components/schemas/MacroObservationHTTP", "description": "Headline CPI observation." }, "core_cpi": { "anyOf": [ { "$ref": "#/components/schemas/MacroObservationHTTP" }, { "type": "null" } ], "description": "Optional core CPI observation." }, "unemployment_rate": { "$ref": "#/components/schemas/MacroObservationHTTP", "description": "Unemployment rate observation." }, "fed_funds_rate": { "$ref": "#/components/schemas/MacroObservationHTTP", "description": "Fed funds observation." }, "treasury_2y": { "$ref": "#/components/schemas/MacroObservationHTTP", "description": "2-year Treasury observation." }, "treasury_10y": { "$ref": "#/components/schemas/MacroObservationHTTP", "description": "10-year Treasury observation." }, "yield_curve_10y_2y": { "type": "string", "title": "Yield Curve 10Y 2Y", "description": "10y minus 2y yield spread as decimal string." }, "retail_sales": { "anyOf": [ { "$ref": "#/components/schemas/MacroObservationHTTP" }, { "type": "null" } ], "description": "Optional retail sales context." }, "avg_hourly_earnings": { "anyOf": [ { "$ref": "#/components/schemas/MacroObservationHTTP" }, { "type": "null" } ], "description": "Optional wage pressure context." }, "sp500_index": { "anyOf": [ { "$ref": "#/components/schemas/MacroObservationHTTP" }, { "type": "null" } ], "description": "Optional benchmark index overlay." }, "macro_regime": { "$ref": "#/components/schemas/MacroRegimeHTTP", "description": "Deterministic macro regime tags." } }, "additionalProperties": false, "type": "object", "required": [ "date", "cpi", "unemployment_rate", "fed_funds_rate", "treasury_2y", "treasury_10y", "yield_curve_10y_2y", "macro_regime" ], "title": "MacroContextHTTP", "description": "HTTP schema for compact macro context.", "examples": [ { "avg_hourly_earnings": { "observation_date": "2024-06-01", "realtime_end": "2026-08-07", "realtime_start": "2026-08-07", "retrieved_at": "2026-08-26T23:39:33Z", "source_hash": "dd8b3708b165873b78c265696cf43adae4ee6a04ee3471a5b8cd6565b4bf23aa", "source_provider": "FRED", "source_series_id": "CES0500000003", "value": "35.01", "vintage_date": "2026-08-07" }, "core_cpi": { "observation_date": "2024-06-01", "realtime_end": "2026-08-12", "realtime_start": "2026-08-12", "retrieved_at": "2026-08-26T23:39:53Z", "source_hash": "32a807f96eb4612459af39cde7b6e0c2ba7b821b5c7d9db5433d08ae730f4eaa", "source_provider": "FRED", "source_series_id": "CPILFESL", "value": "318.39", "vintage_date": "2026-08-12" }, "cpi": { "observation_date": "2024-06-01", "realtime_end": "2026-08-12", "realtime_start": "2026-08-12", "retrieved_at": "2026-08-26T23:39:44Z", "source_hash": "9bed11292a6933df341da5a27c3fa4d0e51bc8e5336645ad0a7aedb0a3887280", "source_provider": "FRED", "source_series_id": "CPIAUCSL", "value": "313.044", "vintage_date": "2026-08-12" }, "date": "2024-06-30", "fed_funds_rate": { "observation_date": "2024-06-01", "realtime_end": "2026-08-03", "realtime_start": "2026-08-03", "retrieved_at": "2026-08-26T23:43:53Z", "source_hash": "9c49f373c6fdb0dd4c75981dc9591b95a7b14c63c4704d780043f747bccf8a4f", "source_provider": "FRED", "source_series_id": "FEDFUNDS", "value": "5.33", "vintage_date": "2026-08-03" }, "macro_regime": { "inflation_regime": "moderate_inflation", "inflation_yoy": "2.970257948647101778207582500" }, "retail_sales": { "observation_date": "2024-06-01", "realtime_end": "2026-08-14", "realtime_start": "2026-08-14", "retrieved_at": "2026-08-26T23:44:06Z", "source_hash": "0706b1b12eab607433a3da9779f45c0c4024ef58ae980ff4c94fda7d08b13ee0", "source_provider": "FRED", "source_series_id": "RSAFS", "value": "692449", "vintage_date": "2026-08-14" }, "sp500_index": { "observation_date": "2024-06-28", "realtime_end": "2026-08-25", "realtime_start": "2026-08-25", "retrieved_at": "2026-08-26T09:03:37Z", "source_hash": "7bc7e5f321e8b415d7fe1c081f88fdc2dab97c1b59e5b392b48e7228eea9431b", "source_provider": "FRED", "source_series_id": "SP500", "value": "5460.48" }, "treasury_10y": { "observation_date": "2024-06-28", "realtime_end": "2026-08-26", "realtime_start": "2026-08-26", "retrieved_at": "2026-08-26T23:41:44Z", "source_hash": "40e039f69081504dc169f11ee19a7794444a681fe384ec14983abec903992ad0", "source_provider": "FRED", "source_series_id": "DGS10", "value": "4.36", "vintage_date": "2026-08-26" }, "treasury_2y": { "observation_date": "2024-06-28", "realtime_end": "2026-08-26", "realtime_start": "2026-08-26", "retrieved_at": "2026-08-26T23:43:39Z", "source_hash": "a28b2e5b128b5d9c94bad6901df72b2d1be6490c98b2b4efa69aaff2c5d7f362", "source_provider": "FRED", "source_series_id": "DGS2", "value": "4.71", "vintage_date": "2026-08-26" }, "unemployment_rate": { "observation_date": "2024-06-01", "realtime_end": "2026-08-07", "realtime_start": "2026-08-07", "retrieved_at": "2026-08-26T23:44:18Z", "source_hash": "76a121d8d547a53cb81458237d4d1ef0e3e009e95554526342c01f306f41d015", "source_provider": "FRED", "source_series_id": "UNRATE", "value": "4.1", "vintage_date": "2026-08-07" }, "yield_curve_10y_2y": "-0.35" } ] }, "MacroObservationHTTP": { "properties": { "source_provider": { "type": "string", "title": "Source Provider", "description": "Source provider, currently FRED." }, "source_series_id": { "type": "string", "title": "Source Series Id", "description": "Upstream provider series identifier." }, "observation_date": { "type": "string", "format": "date", "title": "Observation Date", "description": "Observed date for the macro value." }, "value": { "type": "string", "title": "Value", "description": "Decimal-safe macro observation value." }, "realtime_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Realtime Start", "description": "Realtime period start for the observation when available." }, "realtime_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Realtime End", "description": "Realtime period end for the observation when available." }, "vintage_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Vintage Date", "description": "Vintage date when modeled explicitly." }, "retrieved_at": { "type": "string", "format": "date-time", "title": "Retrieved At", "description": "Timestamp when Arche retrieved the observation." }, "source_hash": { "type": "string", "title": "Source Hash", "description": "Hash of the observation as the provider published it." } }, "additionalProperties": false, "type": "object", "required": [ "source_provider", "source_series_id", "observation_date", "value", "retrieved_at", "source_hash" ], "title": "MacroObservationHTTP", "description": "HTTP schema for one macro observation." }, "MacroRegimeHTTP": { "properties": { "inflation_regime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inflation Regime", "description": "Inflation regime tag." }, "rate_regime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Rate Regime", "description": "Rate regime tag." }, "labor_regime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Labor Regime", "description": "Labor regime tag." }, "inflation_yoy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Inflation Yoy", "description": "Year-over-year CPI inflation rate as a decimal string percent." } }, "additionalProperties": false, "type": "object", "title": "MacroRegimeHTTP", "description": "HTTP schema for deterministic macro regime tags." }, "MacroSeriesCode": { "type": "string", "enum": [ "CPIAUCSL", "CPILFESL", "UNRATE", "FEDFUNDS", "DGS2", "DGS10", "RSAFS", "CES0500000003", "SP500" ], "title": "MacroSeriesCode", "description": "Explicitly approved macro series codes." }, "MacroSeriesDefinitionHTTP": { "properties": { "code": { "type": "string", "title": "Code", "description": "Approved macro series code." }, "display_name": { "type": "string", "title": "Display Name", "description": "Human-readable series name." }, "source_provider": { "type": "string", "title": "Source Provider", "description": "Source provider, currently FRED." }, "source_series_id": { "type": "string", "title": "Source Series Id", "description": "Upstream provider series id." }, "frequency": { "type": "string", "title": "Frequency", "description": "Series frequency." }, "unit": { "type": "string", "title": "Unit", "description": "Provider unit label." }, "category": { "type": "string", "title": "Category", "description": "Arche macro category." }, "enabled": { "type": "boolean", "title": "Enabled", "description": "Whether the series is enabled in the registry." }, "redistribution_policy_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Redistribution Policy Note", "description": "Nullable note about redistribution constraints or source terms." }, "description": { "type": "string", "title": "Description", "description": "Description of the contextual use in Arche." } }, "additionalProperties": false, "type": "object", "required": [ "code", "display_name", "source_provider", "source_series_id", "frequency", "unit", "category", "enabled", "description" ], "title": "MacroSeriesDefinitionHTTP", "description": "HTTP schema for an approved macro series definition.", "examples": [ { "category": "benchmark", "code": "SP500", "description": "Benchmark index overlay used only as contextual market backdrop.", "display_name": "S&P 500", "enabled": true, "frequency": "daily", "redistribution_policy_note": "Benchmark overlay only; not individual security market data.", "source_provider": "FRED", "source_series_id": "SP500", "unit": "index_level" } ] }, "MacroSeriesHTTP": { "properties": { "series_code": { "type": "string", "title": "Series Code", "description": "Approved macro series code." }, "observations": { "items": { "$ref": "#/components/schemas/MacroObservationHTTP" }, "type": "array", "title": "Observations", "description": "Deterministically ordered observations by observation_date ascending." } }, "additionalProperties": false, "type": "object", "required": [ "series_code" ], "title": "MacroSeriesHTTP", "description": "HTTP schema for a macro series query response.", "examples": [ { "observations": [ { "observation_date": "2024-01-01", "realtime_end": "2026-08-12", "realtime_start": "2026-08-12", "retrieved_at": "2026-08-26T23:39:44Z", "source_hash": "07b57a14846f515862dab7bd3dc9dc9812ebc3b69db1625670c8dbeee4f1941b", "source_provider": "FRED", "source_series_id": "CPIAUCSL", "value": "309.698", "vintage_date": "2026-08-12" }, { "observation_date": "2024-02-01", "realtime_end": "2026-08-12", "realtime_start": "2026-08-12", "retrieved_at": "2026-08-26T23:39:44Z", "source_hash": "97801f2a297775d0bfbe29ff25ab4cef55143a4811f9861bee4b6f398143311e", "source_provider": "FRED", "source_series_id": "CPIAUCSL", "value": "310.967", "vintage_date": "2026-08-12" } ], "series_code": "CPIAUCSL" } ] }, "MaterialityClass": { "type": "string", "enum": [ "NONE", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "title": "MaterialityClass", "description": "Materiality classification for restatement analytics.\n\nThis enum is used by restatement profiles and timelines to capture\nthe aggregate severity of changes across the SEC filings that reported a\nstatement." }, "MetricBundleCatalogItemHTTP": { "properties": { "code": { "type": "string", "title": "Code", "description": "Stable bundle code." }, "label": { "type": "string", "title": "Label", "description": "Human-readable bundle label." }, "description": { "type": "string", "title": "Description", "description": "Bundle description." }, "metrics": { "items": { "type": "string" }, "type": "array", "title": "Metrics", "description": "Ordered filing-based metric codes." } }, "additionalProperties": false, "type": "object", "required": [ "code", "label", "description", "metrics" ], "title": "MetricBundleCatalogItemHTTP", "description": "HTTP schema for one filing-based bundle definition.", "examples": [ { "code": "cash_flow_quality", "description": "Filing-based cash-flow quality metrics only.", "label": "Cash flow quality", "metrics": [ "CFO_TO_NET_INCOME", "FCF_CONVERSION" ] } ] }, "MetricBundleInputHTTP": { "properties": { "metric": { "type": "string", "title": "Metric", "description": "Canonical metric code of the input." }, "value": { "type": "string", "title": "Value", "description": "Stringified decimal value the computation read." }, "filing_accession": { "type": "string", "title": "Filing Accession", "description": "Accession of the filing the input was read from." }, "xbrl_concepts": { "items": { "type": "string" }, "type": "array", "title": "Xbrl Concepts", "description": "XBRL concepts the input was read from; empty when not recorded." } }, "additionalProperties": false, "type": "object", "required": [ "metric", "value", "filing_accession", "xbrl_concepts" ], "title": "MetricBundleInputHTTP", "description": "HTTP schema for one filed input a bundle metric was computed from." }, "MetricBundleProvenanceHTTP": { "properties": { "filing_accession": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filing Accession", "description": "EDGAR filing accession for the disclosure used as source, when available." }, "xbrl_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Xbrl Concept", "description": "Source XBRL concept QName (e.g., us-gaap:Revenues) when available." }, "mapping_type": { "anyOf": [ { "type": "string", "enum": [ "DIRECT", "FALLBACK", "CALCULATED", "INFERRED", "UNKNOWN" ] }, { "type": "null" } ], "title": "Mapping Type", "description": "How the metric was mapped from the filing, when recorded: DIRECT, FALLBACK, CALCULATED, INFERRED, or UNKNOWN." }, "override_applied": { "type": "boolean", "title": "Override Applied", "description": "Whether an override rule was applied for this metric mapping." }, "override_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Override Reason", "description": "Optional override reason when override_applied is true." }, "inputs": { "items": { "$ref": "#/components/schemas/MetricBundleInputHTTP" }, "type": "array", "title": "Inputs", "description": "Filed figures a computed metric was read from; empty for a metric read directly from the filing and for a metric with no value." }, "unavailable_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unavailable Reason", "description": "Why the metric has no value; null when it has one. A computed metric reports MISSING_INPUT, ZERO_DENOMINATOR, NEGATIVE_DENOMINATOR_GUARD, INPUTS_INCONSISTENT, INSUFFICIENT_HISTORY, INVALID_OPERATION, NOT_APPLICABLE or OTHER. A filed metric reports NOT_REPORTED (the filing has no fact for it), UNRESOLVED (the filing reports one that could not be mapped) or WITHHELD (the filer's own subtotals contradict it)." }, "missing_inputs": { "items": { "type": "string" }, "type": "array", "title": "Missing Inputs", "description": "Inputs the filing lacks, when unavailable_reason is MISSING_INPUT." } }, "additionalProperties": false, "type": "object", "required": [ "override_applied" ], "title": "MetricBundleProvenanceHTTP", "description": "HTTP schema for the provenance of one metric in a bundle row.", "examples": [ { "filing_accession": "0000320193-24-000123", "inputs": [ { "filing_accession": "0000320193-24-000123", "metric": "NET_INCOME", "value": "93736000000", "xbrl_concepts": [ "us-gaap:NetIncomeLoss" ] }, { "filing_accession": "0000320193-24-000123", "metric": "REVENUE", "value": "391035000000", "xbrl_concepts": [ "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax" ] } ], "mapping_type": "CALCULATED", "missing_inputs": [], "override_applied": false } ] }, "MetricBundleTimeSeriesRowHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Canonical company CIK." }, "bundle_code": { "type": "string", "title": "Bundle Code", "description": "Stable bundle code." }, "period_type": { "type": "string", "title": "Period Type", "description": "Requested period type." }, "period_end": { "type": "string", "format": "date", "title": "Period End", "description": "Period end date." }, "fiscal_year": { "type": "integer", "title": "Fiscal Year", "description": "Fiscal year." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period." }, "filing_accession": { "type": "string", "title": "Filing Accession", "description": "Source filing accession." }, "filing_type": { "type": "string", "title": "Filing Type", "description": "SEC form of the source filing as the SEC lists it; an amendment carries the /A suffix (e.g. 10-K/A)." }, "filing_date": { "type": "string", "format": "date", "title": "Filing Date", "description": "Source filing date." }, "accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Accepted At", "description": "SEC acceptance timestamp." }, "metrics": { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": "object", "title": "Metrics", "description": "Metric values for the aligned period; missing inputs remain null." }, "provenance": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/MetricBundleProvenanceHTTP" }, "type": "object" }, { "type": "null" } ], "title": "Provenance", "description": "Per-metric provenance keyed by metric code, when include_provenance is set: the filing and concept behind each filed metric, the filed inputs behind each computed one, and the reason for each metric with no value." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "bundle_code", "period_type", "period_end", "fiscal_year", "fiscal_period", "filing_accession", "filing_type", "filing_date", "metrics" ], "title": "MetricBundleTimeSeriesRowHTTP", "description": "HTTP schema for one aligned filing-based bundle row." }, "MetricCoverageSummaryHTTP": { "properties": { "metric": { "type": "string", "title": "Metric", "description": "Canonical metric code." }, "company_count": { "type": "integer", "minimum": 0.0, "title": "Company Count", "description": "Number of companies with at least one statement that reports this metric." }, "years_covered": { "type": "integer", "minimum": 0.0, "title": "Years Covered", "description": "Number of distinct fiscal years in which any company reports this metric. Counts only the periods a filing reports or compares against: a statement counts when its period ended no more than three years (1,098 days) before the period the filing covers, so a late-filed report still counts for its own period." }, "filing_count": { "type": "integer", "minimum": 0.0, "title": "Filing Count", "description": "Number of SEC filings with a statement that reports this metric, counted per company: an amendment counts as its own filing, and a filing several companies made jointly counts once for each." }, "statement_count": { "type": "integer", "minimum": 0.0, "title": "Statement Count", "description": "Number of statements that report this metric. A statement is one financial statement for one fiscal period in one company's filing, so a filing that also presents prior periods contributes one for each." }, "annual_completeness": { "type": "string", "title": "Annual Completeness", "description": "Share of annual periods that report this metric, as a decimal string from 0 to 1. Counted over the companies that report the metric, in the statements that carry it." }, "quarterly_completeness": { "type": "string", "title": "Quarterly Completeness", "description": "Share of quarterly periods that report this metric, as a decimal string from 0 to 1. Counted over the companies that report the metric, in the statements that carry it." }, "latest_filing_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Latest Filing Date", "description": "Filing date of the most recent filing that reports this metric." }, "latest_accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Latest Accepted At", "description": "UTC time the SEC accepted the most recent filing that reports this metric." } }, "additionalProperties": false, "type": "object", "required": [ "metric", "company_count", "years_covered", "filing_count", "statement_count", "annual_completeness", "quarterly_completeness" ], "title": "MetricCoverageSummaryHTTP", "description": "HTTP schema for one metric coverage summary.", "examples": [ { "annual_completeness": "0.900000", "company_count": 1000, "filing_count": 5000, "latest_accepted_at": "2026-01-02T21:00:00Z", "latest_filing_date": "2026-01-02", "metric": "REVENUE", "quarterly_completeness": "0.800000", "statement_count": 6000, "years_covered": 10 } ] }, "MetricDefinitionHTTP": { "properties": { "metric": { "type": "string", "title": "Metric", "description": "Stable metric code." }, "display_name": { "type": "string", "title": "Display Name", "description": "Human-readable metric label." }, "category": { "type": "string", "title": "Category", "description": "High-level category." }, "statement_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Statement Type", "description": "Primary statement affinity when exactly one statement type applies." }, "is_canonical": { "type": "boolean", "title": "Is Canonical", "description": "Whether the metric is canonical EDGAR data." }, "is_derived": { "type": "boolean", "title": "Is Derived", "description": "Whether the metric is computed rather than direct." }, "unit_type": { "type": "string", "title": "Unit Type", "description": "Unit-family descriptor for the metric." }, "formula": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Formula", "description": "The formula, or as_reported for a line the filer reports." }, "dependencies": { "items": { "type": "string" }, "type": "array", "title": "Dependencies", "description": "Required input metric codes." }, "denominator_zero_behavior": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Denominator Zero Behavior", "description": "Documented zero-denominator behavior when applicable." }, "missing_input_behavior": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Missing Input Behavior", "description": "Documented behavior when required inputs are missing." }, "market_data_required": { "type": "boolean", "title": "Market Data Required", "description": "Whether caller-supplied market inputs are required." }, "source_notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Notes", "description": "Where the metric comes from: reported by the filer, or computed." }, "provenance_behavior": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provenance Behavior", "description": "How provenance is represented for the metric." } }, "additionalProperties": false, "type": "object", "required": [ "metric", "display_name", "category", "is_canonical", "is_derived", "unit_type", "dependencies", "market_data_required" ], "title": "MetricDefinitionHTTP", "description": "HTTP payload for one public metric definition.", "examples": [ { "category": "REVENUE", "dependencies": [], "display_name": "Revenue", "formula": "as_reported", "is_canonical": true, "is_derived": false, "market_data_required": false, "metric": "REVENUE", "missing_input_behavior": "null_if_metric_not_available", "provenance_behavior": "statement_metric_provenance_when_available", "source_notes": "Reported by the filer in its XBRL financial statements.", "statement_type": "INCOME_STATEMENT", "unit_type": "currency" } ] }, "MetricDimensionHTTP": { "properties": { "accession_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accession Id", "description": "SEC accession number of the filing whose statement carries the disclosure. With cik, statement_type, fiscal_year and fiscal_period it identifies the public statement.", "examples": [ "0000320193-24-000123" ] }, "company_id": { "type": "string", "format": "uuid", "title": "Company Id", "description": "Company identifier." }, "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "statement_type": { "type": "string", "title": "Statement Type", "description": "Statement type code." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Statement period end date." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year." }, "fiscal_period": { "type": "string", "title": "Fiscal Period", "description": "Fiscal period code." }, "metric_code": { "type": "string", "title": "Metric Code", "description": "Source concept/metric code." }, "canonical_metric_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Canonical Metric Code", "description": "Canonical metric the source concept maps to, matching the vocabulary used by the statements API. Null for filer extensions." }, "unit": { "type": "string", "title": "Unit", "description": "Unit code for value." }, "value": { "type": "string", "title": "Value", "description": "Source fact value as decimal string." }, "period_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period Start", "description": "Period start for duration facts." }, "period_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period End", "description": "Period end or instant date." }, "dimension_type": { "type": "string", "title": "Dimension Type", "description": "Classified dimension type: SEGMENT or GEOGRAPHY." }, "axis_qname": { "type": "string", "title": "Axis Qname", "description": "XBRL axis QName." }, "member_qname": { "type": "string", "title": "Member Qname", "description": "XBRL member QName." }, "axis_label": { "type": "string", "title": "Axis Label", "description": "Human-oriented axis label." }, "member_label": { "type": "string", "title": "Member Label", "description": "Human-oriented member label." }, "dimension_key": { "type": "string", "title": "Dimension Key", "description": "Stable axis/member key." } }, "additionalProperties": false, "type": "object", "required": [ "company_id", "cik", "statement_type", "statement_date", "fiscal_year", "fiscal_period", "metric_code", "unit", "value", "dimension_type", "axis_qname", "member_qname", "axis_label", "member_label", "dimension_key" ], "title": "MetricDimensionHTTP", "description": "HTTP payload for segment/geography metric disclosures.\n\nNotes:\n - Rows are sourced directly from statement disclosures.\n - ``dimension_type`` is either ``SEGMENT`` or ``GEOGRAPHY``.\n - A value is identified by its company, statement_date, dimension_type,\n axis_qname, member_qname, metric_code, period_start, period_end and\n value; a value the filing reports more than once is listed once.", "examples": [ { "accession_id": "0000320193-24-000123", "axis_label": "StatementGeographicalAxis", "axis_qname": "srt:StatementGeographicalAxis", "canonical_metric_code": "REVENUE", "cik": "0000320193", "company_id": "11111111-1111-1111-1111-111111111111", "dimension_key": "srt:StatementGeographicalAxis=aapl:UnitedStatesMember", "dimension_type": "GEOGRAPHY", "fiscal_period": "FY", "fiscal_year": 2024, "member_label": "United States", "member_qname": "aapl:UnitedStatesMember", "metric_code": "us-gaap:Revenues", "period_end": "2024-09-28", "period_start": "2023-09-30", "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT", "unit": "USD", "value": "120000000000.000000" } ] }, "MetricDimensionType": { "type": "string", "enum": [ "SEGMENT", "GEOGRAPHY" ], "title": "MetricDimensionType", "description": "Supported disclosure dimension types." }, "MetricDriftHTTP": { "properties": { "metric": { "type": "string", "title": "Metric", "description": "Canonical or derived metric code." }, "original_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Original Value", "description": "Original metric value." }, "latest_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Latest Value", "description": "Latest metric value." }, "drift": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Drift", "description": "Latest minus original value." }, "drift_percent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Drift Percent", "description": "Drift divided by original value." } }, "additionalProperties": false, "type": "object", "required": [ "metric" ], "title": "MetricDriftHTTP", "description": "HTTP schema for metric drift analytics.", "examples": [ { "drift": "2.0", "drift_percent": "0.200000", "latest_value": "12.0", "metric": "NET_INCOME", "original_value": "10.0" } ] }, "MetricNullReason": { "type": "string", "enum": [ "NOT_REPORTED", "NOT_ON_STATEMENT", "MISSING_INPUT", "DENOMINATOR_ZERO", "NON_POSITIVE_VALUE", "NO_COMPARABLE_PERIOD", "NOT_APPLICABLE_TO_PERIOD", "INCOMPLETE_TRAILING_YEAR", "NOT_YET_COMPUTED", "INPUTS_INCONSISTENT" ], "title": "MetricNullReason", "description": "Why a modeling metric could not be computed for one period.\n\nAttributes:\n NOT_REPORTED: The filing does not report this line for the period.\n NOT_ON_STATEMENT: The metric is read from lines of a different\n financial statement than the row describes.\n MISSING_INPUT: One or more inputs the formula needs are not reported\n for the period; ``missing_inputs`` names them.\n DENOMINATOR_ZERO: Every input is present, but the divisor is zero.\n NON_POSITIVE_VALUE: Every input is present, but the formula is only\n defined for positive values (a compound growth rate, or a share\n count) and one is zero or negative.\n NO_COMPARABLE_PERIOD: A growth rate has no earlier period of the same\n length to compare against.\n NOT_APPLICABLE_TO_PERIOD: The metric is not defined for this kind of\n period, such as quarter-over-quarter growth on an annual row.\n INCOMPLETE_TRAILING_YEAR: The trailing twelve months do not have the\n line in every quarter they span.\n NOT_YET_COMPUTED: The inputs support a value that has not been\n computed yet. It is served once computed, with no action from the\n caller.\n INPUTS_INCONSISTENT: Every input is present, but the filer's own figures\n contradict each other, so a value computed from them would assert a\n relationship the filing does not support. The inputs themselves are\n still served as filed, with the failing check reported beside them." }, "MetricOverrideAuditHTTP": { "properties": { "applied_at": { "type": "string", "title": "Applied At", "description": "Timestamp when the override was applied (UTC, ISO-8601)." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Human-readable reason recorded for the override, when there is one." }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Who or what applied the override, when recorded." }, "prior_value_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prior Value Hash", "description": "Optional hash of the prior metric value before the override event." }, "new_value_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "New Value Hash", "description": "Optional hash of the metric value after the override event." } }, "additionalProperties": false, "type": "object", "required": [ "applied_at" ], "title": "MetricOverrideAuditHTTP", "description": "HTTP schema for one override event in a metric audit chain.", "examples": [ { "applied_at": "2024-11-03T12:00:00Z", "new_value_hash": "ffffeeee1111222233334444555566667777888899990000aaaabbbbccccdddd", "prior_value_hash": "aaaabbbbccccdddd1111222233334444555566667777888899990000aaaabbbb", "reason": "manual total assets mapping override", "source": "integration-test" } ] }, "MetricProvenanceHTTP": { "properties": { "filing_accession": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filing Accession", "description": "EDGAR filing accession for the disclosure used as source, when available." }, "xbrl_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Xbrl Concept", "description": "Source XBRL concept QName (e.g., us-gaap:Revenues) when available." }, "mapping_type": { "anyOf": [ { "type": "string", "enum": [ "DIRECT", "FALLBACK", "CALCULATED", "INFERRED", "UNKNOWN" ] }, { "type": "null" } ], "title": "Mapping Type", "description": "How the metric was mapped from the filing, when recorded: DIRECT, FALLBACK, CALCULATED, INFERRED, or UNKNOWN." }, "override_applied": { "type": "boolean", "title": "Override Applied", "description": "Whether an override rule was applied for this metric mapping." }, "override_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Override Reason", "description": "Optional override reason when override_applied is true." } }, "additionalProperties": false, "type": "object", "required": [ "override_applied" ], "title": "MetricProvenanceHTTP", "description": "HTTP schema for per-metric provenance metadata.\n\nAttributes:\n filing_accession: EDGAR filing accession for the source disclosure, when tracked.\n xbrl_concept: Source XBRL concept QName when available.\n mapping_type: Mapping strategy (`DIRECT`, `FALLBACK`, `CALCULATED`, `INFERRED`) or UNKNOWN.\n override_applied: Whether an override was applied.\n override_reason: Optional explanation for applied override.", "examples": [ { "filing_accession": "0000320193-24-000012", "mapping_type": "DIRECT", "override_applied": false, "xbrl_concept": "us-gaap:Revenues" } ] }, "MetricTimeSeriesPointHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Canonical company CIK." }, "metric": { "type": "string", "title": "Metric", "description": "Canonical metric code." }, "value": { "type": "string", "title": "Value", "description": "Stringified decimal value." }, "unit": { "type": "string", "title": "Unit", "description": "Unit code for the metric value." }, "period_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period Start", "description": "Period start date when known." }, "period_end": { "type": "string", "format": "date", "title": "Period End", "description": "Period end date." }, "fiscal_year": { "type": "integer", "title": "Fiscal Year", "description": "Fiscal year." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement type." }, "filing_accession": { "type": "string", "title": "Filing Accession", "description": "Source filing accession." }, "filing_type": { "type": "string", "title": "Filing Type", "description": "SEC form of the source filing as the SEC lists it; an amendment carries the /A suffix (e.g. 10-K/A)." }, "filing_date": { "type": "string", "format": "date", "title": "Filing Date", "description": "Source filing date." }, "accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Accepted At", "description": "SEC acceptance timestamp." }, "is_restated": { "type": "boolean", "title": "Is Restated", "description": "Whether the figure comes from a filing that restated the period." }, "source_line_item": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Line Item", "description": "Original source line item when available." }, "provenance": { "anyOf": [ { "$ref": "#/components/schemas/MetricProvenanceHTTP" }, { "type": "null" } ], "description": "Per-metric provenance, when requested." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "metric", "value", "unit", "period_end", "fiscal_year", "fiscal_period", "statement_type", "filing_accession", "filing_type", "filing_date", "is_restated" ], "title": "MetricTimeSeriesPointHTTP", "description": "HTTP schema for one normalized metric time-series point.", "examples": [ { "accepted_at": "2010-10-27T20:36:21Z", "cik": "0000320193", "filing_accession": "0001193125-10-238044", "filing_date": "2010-10-27", "filing_type": "10-K", "fiscal_period": "FY", "fiscal_year": 2008, "is_restated": false, "metric": "REVENUE", "period_end": "2008-09-27", "provenance": { "filing_accession": "0001193125-10-238044", "mapping_type": "DIRECT", "override_applied": false }, "source_line_item": "us-gaap:SalesRevenueNet", "statement_type": "INCOME_STATEMENT", "unit": "USD", "value": "37491000000.000000" } ] }, "MetricViewHTTP": { "properties": { "code": { "type": "string", "title": "Code", "description": "Metric view (bundle) code, e.g. 'core_fundamentals', 'shareholder_returns', 'liquidity', or 'efficiency'." }, "label": { "type": "string", "title": "Label", "description": "Short human-readable label for the view." }, "description": { "type": "string", "title": "Description", "description": "Longer description of the view's intent and use-cases." }, "metrics": { "items": { "type": "string" }, "type": "array", "title": "Metrics", "description": "Ordered list of derived metric codes belonging to this view." }, "market_data_required": { "type": "boolean", "title": "Market Data Required", "description": "Whether any metric in the view requires external market inputs." }, "requires_external_market_inputs": { "type": "boolean", "title": "Requires External Market Inputs", "description": "Whether the view requires caller-supplied or explicitly acknowledged market inputs." }, "allowed_on_edgar_only_surfaces": { "type": "boolean", "title": "Allowed On Edgar Only Surfaces", "description": "Whether the view can be served on EDGAR-only public routes." } }, "additionalProperties": false, "type": "object", "required": [ "code", "label", "description", "metrics", "market_data_required", "requires_external_market_inputs", "allowed_on_edgar_only_surfaces" ], "title": "MetricViewHTTP", "description": "HTTP schema for a single metric view (bundle) definition." }, "MetricViewsCatalogHTTP": { "properties": { "views": { "items": { "$ref": "#/components/schemas/MetricViewHTTP" }, "type": "array", "title": "Views", "description": "Collection of all registered metric views." } }, "additionalProperties": false, "type": "object", "title": "MetricViewsCatalogHTTP", "description": "HTTP schema for the catalog of registered metric views.", "examples": [ { "views": [ { "allowed_on_edgar_only_surfaces": true, "code": "core_fundamentals", "description": "Core fundamentals bundle including margins, revenue growth, cash flows, capital structure, and basic returns suitable for institutional modeling use-cases.", "label": "Core fundamentals", "market_data_required": false, "metrics": [ "GROSS_MARGIN", "OPERATING_MARGIN" ], "requires_external_market_inputs": false }, { "allowed_on_edgar_only_surfaces": false, "code": "core_fundamentals_with_market_inputs", "description": "Core fundamentals bundle extended with market-dependent valuation and distribution metrics that require caller-supplied or otherwise explicitly acknowledged market inputs.", "label": "Core fundamentals with market inputs", "market_data_required": true, "metrics": [ "GROSS_MARGIN", "OPERATING_MARGIN" ], "requires_external_market_inputs": true } ] } ] }, "ModelGrowthHTTP": { "properties": { "company_id": { "type": "string", "format": "uuid", "title": "Company Id", "description": "Company identifier (UUID)." }, "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement type." }, "accounting_standard": { "$ref": "#/components/schemas/AccountingStandard", "description": "Accounting standard." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Statement period end date." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year for the statement." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period (FY/Q1/Q2/etc.)." }, "currency": { "type": "string", "title": "Currency", "description": "ISO currency code for monetary metrics." }, "as_of_timestamp": { "type": "string", "format": "date-time", "title": "As Of Timestamp", "description": "As-of timestamp (UTC)." }, "snapshot_hash": { "type": "string", "title": "Snapshot Hash", "description": "Hash of the statements the as-of date serves. GET /v1/edgar/as-of/{date}/financials/{cik} reports the same hash for the same date, so equal hashes mean the same data." }, "cagr_years": { "type": "integer", "minimum": 1.0, "title": "Cagr Years", "description": "Year window used for CAGR." }, "metrics": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metrics", "description": "Mapping of growth metric codes to decimal string values." }, "dq": { "$ref": "#/components/schemas/DQSummaryHTTP", "description": "DQ summary for the statement." }, "unavailable_metrics": { "items": { "$ref": "#/components/schemas/UnavailableMetricHTTP" }, "type": "array", "title": "Unavailable Metrics", "description": "Every metric the endpoint computes that this row does not carry, each with the specific reason, ordered by metric. A metric appears either in metrics or here, never silently absent." }, "reconciliation": { "$ref": "#/components/schemas/ReconciliationSummaryHTTP", "description": "Reconciliation summary." } }, "additionalProperties": false, "type": "object", "required": [ "company_id", "cik", "statement_type", "accounting_standard", "statement_date", "fiscal_year", "fiscal_period", "currency", "as_of_timestamp", "snapshot_hash", "cagr_years", "dq", "reconciliation" ], "title": "ModelGrowthHTTP", "description": "HTTP schema for a modeling growth row.", "examples": [ { "accounting_standard": "US_GAAP", "as_of_timestamp": "2024-11-02T23:59:59Z", "cagr_years": 3, "cik": "0000320193", "company_id": "11111111-1111-1111-1111-111111111111", "currency": "USD", "dq": { "dq_issue_count": 0 }, "fiscal_period": "FY", "fiscal_year": 2024, "metrics": { "EPS_DILUTED_GROWTH": "-0.008157", "EPS_DILUTED_GROWTH_CAGR": "0.027181", "EPS_DILUTED_GROWTH_YOY": "-0.008157", "NET_INCOME_GROWTH_CAGR": "-0.003335", "NET_INCOME_GROWTH_YOY": "-0.033600", "REVENUE_GROWTH_CAGR": "0.022470", "REVENUE_GROWTH_TTM": "0.014087", "REVENUE_GROWTH_YOY": "0.020220" }, "reconciliation": { "reconciliation_fail_count": 0 }, "snapshot_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT", "unavailable_metrics": [ { "metric": "EPS_DILUTED_GROWTH_QOQ", "missing_inputs": [], "reason": "NOT_APPLICABLE_TO_PERIOD" }, { "metric": "NET_INCOME_GROWTH_QOQ", "missing_inputs": [], "reason": "NOT_APPLICABLE_TO_PERIOD" }, { "metric": "REVENUE_GROWTH_QOQ", "missing_inputs": [], "reason": "NOT_APPLICABLE_TO_PERIOD" } ] } ] }, "ModelImpactHTTP": { "properties": { "implied_fcf_yield": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Implied Fcf Yield", "description": "Free cash flow divided by enterprise value." }, "implied_margin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Implied Margin", "description": "EBIT divided by enterprise value." }, "implied_revenue_growth": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Implied Revenue Growth", "description": "Revenue growth implied by the first-filed vs latest-filed figures." }, "model_input_delta": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Input Delta", "description": "Primary modeling-input delta between the first-filed and latest-filed figures." }, "model_output_delta": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Output Delta", "description": "Primary model-output delta between the first-filed and latest-filed figures." }, "market_input_used": { "type": "boolean", "title": "Market Input Used", "description": "Whether the endpoint consumed market-input fields such as MARKET_CAP or ENTERPRISE_VALUE." }, "market_input_fields": { "items": { "type": "string" }, "type": "array", "title": "Market Input Fields", "description": "Deterministic list of market-input fields used or available to the endpoint." }, "market_input_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Market Input Source", "description": "Source of acknowledged market inputs when used." } }, "additionalProperties": false, "type": "object", "required": [ "market_input_used" ], "title": "ModelImpactHTTP", "description": "HTTP schema for model-aware analytics.", "examples": [ { "implied_fcf_yield": "0.052000", "implied_margin": "0.081500", "implied_revenue_growth": "0.030000", "market_input_fields": [ "ENTERPRISE_VALUE", "MARKET_CAP" ], "market_input_source": "persisted_extra_metrics", "market_input_used": true, "model_input_delta": "1500.0", "model_output_delta": "0.004500" } ] }, "ModelMultiYearHTTP": { "properties": { "company_id": { "type": "string", "format": "uuid", "title": "Company Id", "description": "Company identifier (UUID)." }, "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement type." }, "accounting_standard": { "$ref": "#/components/schemas/AccountingStandard", "description": "Accounting standard." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Statement period end date." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year for the statement." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period (FY/Q1/Q2/etc.)." }, "currency": { "type": "string", "title": "Currency", "description": "ISO currency code for monetary metrics." }, "as_of_timestamp": { "type": "string", "format": "date-time", "title": "As Of Timestamp", "description": "As-of timestamp (UTC)." }, "snapshot_hash": { "type": "string", "title": "Snapshot Hash", "description": "Hash of the statements the as-of date serves. GET /v1/edgar/as-of/{date}/financials/{cik} reports the same hash for the same date, so equal hashes mean the same data." }, "dimension_key": { "type": "string", "title": "Dimension Key", "description": "Dimension key used for the modeled metrics (e.g., default)." }, "valuation_inputs": { "$ref": "#/components/schemas/ValuationInputsHTTP", "description": "Valuation-grade input primitives for the period." }, "dq": { "$ref": "#/components/schemas/DQSummaryHTTP", "description": "DQ summary for the statement." }, "unavailable_metrics": { "items": { "$ref": "#/components/schemas/UnavailableMetricHTTP" }, "type": "array", "title": "Unavailable Metrics", "description": "Every metric the endpoint computes that this row does not carry, each with the specific reason, ordered by metric. A metric appears either in metrics or here, never silently absent." }, "reconciliation": { "$ref": "#/components/schemas/ReconciliationSummaryHTTP", "description": "Reconciliation summary." } }, "additionalProperties": false, "type": "object", "required": [ "company_id", "cik", "statement_type", "accounting_standard", "statement_date", "fiscal_year", "fiscal_period", "currency", "as_of_timestamp", "snapshot_hash", "dimension_key", "valuation_inputs", "dq", "reconciliation" ], "title": "ModelMultiYearHTTP", "description": "HTTP schema for multi-year valuation inputs.", "examples": [ { "accounting_standard": "US_GAAP", "as_of_timestamp": "2024-11-02T23:59:59Z", "cik": "0000320193", "company_id": "11111111-1111-1111-1111-111111111111", "currency": "USD", "dimension_key": "default", "dq": { "dq_issue_count": 3, "dq_max_severity": "HIGH" }, "fiscal_period": "FY", "fiscal_year": 2024, "reconciliation": { "reconciliation_fail_count": 2, "reconciliation_max_severity": "MEDIUM" }, "snapshot_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT", "unavailable_metrics": [ { "metric": "capital_expenditures", "missing_inputs": [ "CAPITAL_EXPENDITURES" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "cash_and_cash_equivalents", "missing_inputs": [ "CASH_AND_CASH_EQUIVALENTS" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "cash_from_operations", "missing_inputs": [ "NET_CASH_FROM_OPERATING_ACTIVITIES" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "change_in_accounts_payable", "missing_inputs": [ "CHANGE_IN_ACCOUNTS_PAYABLE" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "change_in_accounts_receivable", "missing_inputs": [ "CHANGE_IN_ACCOUNTS_RECEIVABLE" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "change_in_inventories", "missing_inputs": [ "CHANGE_IN_INVENTORIES" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "change_in_other_current_assets", "missing_inputs": [ "CHANGE_IN_OTHER_CURRENT_ASSETS" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "change_in_other_current_liabilities", "missing_inputs": [ "CHANGE_IN_OTHER_CURRENT_LIABILITIES" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "current_portion_long_term_debt", "missing_inputs": [ "CURRENT_PORTION_OF_LONG_TERM_DEBT" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "depreciation_and_amortization_in_cfo", "missing_inputs": [ "DEPRECIATION_AND_AMORTIZATION_IN_CFO" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "ebit", "missing_inputs": [ "INTEREST_EXPENSE", "INTEREST_INCOME" ], "reason": "MISSING_INPUT" }, { "metric": "free_cash_flow", "missing_inputs": [ "FREE_CASH_FLOW", "NET_CASH_FROM_OPERATING_ACTIVITIES", "CAPITAL_EXPENDITURES" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "interest_expense", "missing_inputs": [ "INTEREST_EXPENSE" ], "reason": "NOT_REPORTED" }, { "metric": "interest_income", "missing_inputs": [ "INTEREST_INCOME" ], "reason": "NOT_REPORTED" }, { "metric": "invested_capital", "missing_inputs": [ "TOTAL_EQUITY", "SHORT_TERM_DEBT", "CURRENT_PORTION_OF_LONG_TERM_DEBT", "LONG_TERM_DEBT" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "long_term_debt", "missing_inputs": [ "LONG_TERM_DEBT" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "net_capex", "missing_inputs": [ "CAPITAL_EXPENDITURES" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "net_debt", "missing_inputs": [ "SHORT_TERM_DEBT", "CURRENT_PORTION_OF_LONG_TERM_DEBT", "LONG_TERM_DEBT" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "net_working_capital_change", "missing_inputs": [ "CHANGE_IN_ACCOUNTS_RECEIVABLE", "CHANGE_IN_INVENTORIES", "CHANGE_IN_ACCOUNTS_PAYABLE", "CHANGE_IN_OTHER_CURRENT_ASSETS", "CHANGE_IN_OTHER_CURRENT_LIABILITIES" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "nopat", "missing_inputs": [ "INTEREST_EXPENSE", "INTEREST_INCOME" ], "reason": "MISSING_INPUT" }, { "metric": "short_term_debt", "missing_inputs": [ "SHORT_TERM_DEBT" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "stock_based_compensation_in_cfo", "missing_inputs": [ "STOCK_BASED_COMPENSATION_IN_CFO" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "total_assets", "missing_inputs": [ "TOTAL_ASSETS" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "total_current_assets", "missing_inputs": [ "TOTAL_CURRENT_ASSETS" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "total_current_liabilities", "missing_inputs": [ "TOTAL_CURRENT_LIABILITIES" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "total_debt", "missing_inputs": [ "SHORT_TERM_DEBT", "CURRENT_PORTION_OF_LONG_TERM_DEBT", "LONG_TERM_DEBT" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "total_equity", "missing_inputs": [ "TOTAL_EQUITY" ], "reason": "NOT_ON_STATEMENT" }, { "metric": "unlevered_free_cash_flow", "missing_inputs": [ "INTEREST_EXPENSE", "INTEREST_INCOME", "DEPRECIATION_AND_AMORTIZATION_IN_CFO", "CAPITAL_EXPENDITURES" ], "reason": "MISSING_INPUT" }, { "metric": "working_capital", "missing_inputs": [ "TOTAL_CURRENT_ASSETS", "TOTAL_CURRENT_LIABILITIES" ], "reason": "NOT_ON_STATEMENT" } ], "valuation_inputs": { "depreciation_and_amortization": "11445000000.000000", "ebitda": "134661000000.000000", "gross_profit": "180683000000.000000", "income_before_tax": "123485000000.000000", "income_tax_expense": "29749000000.000000", "net_income": "93736000000.000000", "operating_income": "123216000000.000000", "revenue": "391035000000.000000", "tax_rate": "0.240912", "weighted_average_shares_basic": "15343783000.000000", "weighted_average_shares_diluted": "15408095000.000000" } } ] }, "ModelPeriodHTTP": { "properties": { "company_id": { "type": "string", "format": "uuid", "title": "Company Id", "description": "Company identifier (UUID)." }, "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement type." }, "accounting_standard": { "$ref": "#/components/schemas/AccountingStandard", "description": "Accounting standard." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Statement period end date." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year for the statement." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period (FY/Q1/Q2/etc.)." }, "currency": { "type": "string", "title": "Currency", "description": "ISO currency code for monetary metrics." }, "accession_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accession Id", "description": "SEC accession number of the filing whose statement the row was built from. With cik, statement_type, fiscal_year and fiscal_period it identifies the public statement.", "examples": [ "0000320193-24-000123" ] }, "as_of_timestamp": { "type": "string", "format": "date-time", "title": "As Of Timestamp", "description": "As-of timestamp (UTC)." }, "snapshot_hash": { "type": "string", "title": "Snapshot Hash", "description": "Hash of the statements the as-of date serves. GET /v1/edgar/as-of/{date}/financials/{cik} reports the same hash for the same date, so equal hashes mean the same data." }, "dimension_key": { "type": "string", "title": "Dimension Key", "description": "Dimension key used for the modeled metrics (e.g., default)." }, "metrics": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metrics", "description": "Mapping of canonical metric codes to decimal string values." }, "dq": { "$ref": "#/components/schemas/DQSummaryHTTP", "description": "DQ summary for the statement." }, "reconciliation": { "$ref": "#/components/schemas/ReconciliationSummaryHTTP", "description": "Reconciliation summary." } }, "additionalProperties": false, "type": "object", "required": [ "company_id", "cik", "statement_type", "accounting_standard", "statement_date", "fiscal_year", "fiscal_period", "currency", "as_of_timestamp", "snapshot_hash", "dimension_key", "dq", "reconciliation" ], "title": "ModelPeriodHTTP", "description": "HTTP schema for a modeling period row.", "examples": [ { "accession_id": "0000320193-24-000123", "accounting_standard": "US_GAAP", "as_of_timestamp": "2024-11-02T23:59:59Z", "cik": "0000320193", "company_id": "11111111-1111-1111-1111-111111111111", "currency": "USD", "dimension_key": "default", "dq": { "dq_issue_count": 3, "dq_max_severity": "HIGH" }, "fiscal_period": "FY", "fiscal_year": 2024, "metrics": { "NET_INCOME": "25.00", "REVENUE": "100.00" }, "reconciliation": { "reconciliation_fail_count": 2, "reconciliation_max_severity": "MEDIUM" }, "snapshot_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT" } ] }, "ModelRatiosHTTP": { "properties": { "company_id": { "type": "string", "format": "uuid", "title": "Company Id", "description": "Company identifier (UUID)." }, "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement type." }, "accounting_standard": { "$ref": "#/components/schemas/AccountingStandard", "description": "Accounting standard." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Statement period end date." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year for the statement." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period (FY/Q1/Q2/etc.)." }, "currency": { "type": "string", "title": "Currency", "description": "ISO currency code for monetary metrics." }, "as_of_timestamp": { "type": "string", "format": "date-time", "title": "As Of Timestamp", "description": "As-of timestamp (UTC)." }, "snapshot_hash": { "type": "string", "title": "Snapshot Hash", "description": "Hash of the statements the as-of date serves. GET /v1/edgar/as-of/{date}/financials/{cik} reports the same hash for the same date, so equal hashes mean the same data." }, "metrics": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metrics", "description": "Mapping of ratio metric codes to decimal string values. Includes profitability, liquidity (e.g., CURRENT_RATIO, QUICK_RATIO, BOOK_VALUE_PER_SHARE), and efficiency ratios (e.g., DSO, DPO, INVENTORY_TURNOVER, CASH_CONVERSION_CYCLE) when inputs are available." }, "dq": { "$ref": "#/components/schemas/DQSummaryHTTP", "description": "DQ summary for the statement." }, "unavailable_metrics": { "items": { "$ref": "#/components/schemas/UnavailableMetricHTTP" }, "type": "array", "title": "Unavailable Metrics", "description": "Every metric the endpoint computes that this row does not carry, each with the specific reason, ordered by metric. A metric appears either in metrics or here, never silently absent." }, "reconciliation": { "$ref": "#/components/schemas/ReconciliationSummaryHTTP", "description": "Reconciliation summary." } }, "additionalProperties": false, "type": "object", "required": [ "company_id", "cik", "statement_type", "accounting_standard", "statement_date", "fiscal_year", "fiscal_period", "currency", "as_of_timestamp", "snapshot_hash", "dq", "reconciliation" ], "title": "ModelRatiosHTTP", "description": "HTTP schema for a modeling ratios row.", "examples": [ { "accounting_standard": "US_GAAP", "as_of_timestamp": "2024-11-02T23:59:59Z", "cik": "0000320193", "company_id": "11111111-1111-1111-1111-111111111111", "currency": "USD", "dq": { "dq_issue_count": 0 }, "fiscal_period": "Q3", "fiscal_year": 2024, "metrics": { "BOOK_VALUE_PER_SHARE": "4.346315", "CASH_CONVERSION_CYCLE": "-56.926368", "CURRENT_RATIO": "0.952980", "DEBT_TO_EQUITY": "1.473736", "DPO": "92.879672", "DSO": "23.917251", "GROSS_MARGIN": "0.462572", "INVENTORY_TURNOVER": "7.477534", "NET_MARGIN": "0.250044", "OPERATING_MARGIN": "0.295557", "QUICK_RATIO": "0.642710", "ROA": "0.064678", "ROE": "0.321521", "ROIC": "0.152944" }, "reconciliation": { "reconciliation_fail_count": 0 }, "snapshot_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "statement_date": "2024-06-29", "statement_type": "INCOME_STATEMENT", "unavailable_metrics": [ { "metric": "INTEREST_COVERAGE", "missing_inputs": [ "INTEREST_EXPENSE" ], "reason": "MISSING_INPUT" } ] } ] }, "ModelTTMHTTP": { "properties": { "company_id": { "type": "string", "format": "uuid", "title": "Company Id", "description": "Company identifier (UUID)." }, "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement type." }, "accounting_standard": { "$ref": "#/components/schemas/AccountingStandard", "description": "Accounting standard." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Statement period end date." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year for the statement." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period (FY/Q1/Q2/etc.)." }, "currency": { "type": "string", "title": "Currency", "description": "ISO currency code for monetary metrics." }, "as_of_timestamp": { "type": "string", "format": "date-time", "title": "As Of Timestamp", "description": "As-of timestamp (UTC)." }, "snapshot_hash": { "type": "string", "title": "Snapshot Hash", "description": "Hash of the statements the as-of date serves. GET /v1/edgar/as-of/{date}/financials/{cik} reports the same hash for the same date, so equal hashes mean the same data." }, "ttm_window_start": { "type": "string", "format": "date", "title": "Ttm Window Start", "description": "Start date for the TTM window." }, "ttm_window_end": { "type": "string", "format": "date", "title": "Ttm Window End", "description": "End date for the TTM window." }, "metrics": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metrics", "description": "Mapping of canonical metric codes to decimal string values." }, "dq": { "$ref": "#/components/schemas/DQSummaryHTTP", "description": "DQ summary for the window." }, "unavailable_metrics": { "items": { "$ref": "#/components/schemas/UnavailableMetricHTTP" }, "type": "array", "title": "Unavailable Metrics", "description": "Every metric the endpoint computes that this row does not carry, each with the specific reason, ordered by metric. A metric appears either in metrics or here, never silently absent." }, "reconciliation": { "$ref": "#/components/schemas/ReconciliationSummaryHTTP", "description": "Reconciliation summary." } }, "additionalProperties": false, "type": "object", "required": [ "company_id", "cik", "statement_type", "accounting_standard", "statement_date", "fiscal_year", "fiscal_period", "currency", "as_of_timestamp", "snapshot_hash", "ttm_window_start", "ttm_window_end", "dq", "reconciliation" ], "title": "ModelTTMHTTP", "description": "HTTP schema for a modeling TTM row.", "examples": [ { "accounting_standard": "US_GAAP", "as_of_timestamp": "2024-11-02T23:59:59Z", "cik": "0000320193", "company_id": "11111111-1111-1111-1111-111111111111", "currency": "USD", "dq": { "dq_issue_count": 0 }, "fiscal_period": "Q4", "fiscal_year": 2024, "metrics": { "BASIC_EPS": "6.110000", "COST_OF_REVENUE": "210352000000.000000", "DEPRECIATION_AND_AMORTIZATION_EXPENSE": "11445000000.000000", "DILUTED_EPS": "6.080000", "GROSS_PROFIT": "180683000000.000000", "INCOME_BEFORE_TAX": "123485000000.000000", "INCOME_TAX_EXPENSE": "29749000000.000000", "NET_INCOME": "93736000000.000000", "OPERATING_EXPENSE": "57467000000.000000", "OPERATING_INCOME": "123216000000.000000", "OTHER_NON_OPERATING_INCOME_EXPENSE": "269000000.000000", "RESEARCH_AND_DEVELOPMENT_EXPENSE": "31370000000.000000", "REVENUE": "391035000000.000000", "SELLING_GENERAL_AND_ADMINISTRATIVE_EXPENSE": "26097000000.000000", "WEIGHTED_AVERAGE_SHARES_BASIC": "15343783000.000000", "WEIGHTED_AVERAGE_SHARES_DILUTED": "15408095000.000000" }, "reconciliation": { "reconciliation_fail_count": 0 }, "snapshot_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT", "ttm_window_end": "2024-09-28", "ttm_window_start": "2023-12-30", "unavailable_metrics": [] } ] }, "NarrativeCitationHTTP": { "properties": { "metric_code": { "type": "string", "title": "Metric Code", "description": "Metric code cited." }, "period": { "type": "string", "title": "Period", "description": "Period label cited." }, "value": { "type": "string", "title": "Value", "description": "Value cited (decimal string)." }, "comparison": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comparison", "description": "Comparison period label, if applicable." } }, "additionalProperties": false, "type": "object", "required": [ "metric_code", "period", "value" ], "title": "NarrativeCitationHTTP", "description": "HTTP schema for narrative citations." }, "NarrativeHTTP": { "properties": { "company_id": { "type": "string", "format": "uuid", "title": "Company Id", "description": "Company identifier." }, "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "as_of_timestamp": { "type": "string", "format": "date-time", "title": "As Of Timestamp", "description": "As-of snapshot timestamp (UTC)." }, "narrative_type": { "$ref": "#/components/schemas/NarrativeType", "description": "Narrative type." }, "window_label": { "type": "string", "title": "Window Label", "description": "Narrative window label." }, "input_hash": { "type": "string", "title": "Input Hash", "description": "Hash of the figures the narrative was written from; equal hashes mean equal inputs." }, "narrative_text": { "type": "string", "title": "Narrative Text", "description": "Narrative text." }, "citations": { "items": { "$ref": "#/components/schemas/NarrativeCitationHTTP" }, "type": "array", "title": "Citations", "description": "Citations referenced by the narrative." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "Creation timestamp (UTC)." } }, "additionalProperties": false, "type": "object", "required": [ "company_id", "cik", "as_of_timestamp", "narrative_type", "window_label", "input_hash", "narrative_text", "citations", "created_at" ], "title": "NarrativeHTTP", "description": "A plain-language narrative of how a company's figures moved, with its citations." }, "NarrativeType": { "type": "string", "enum": [ "CHANGE_SUMMARY", "MARGINS_MOVE", "ROIC_CHANGE" ], "title": "NarrativeType", "description": "Supported narrative variants for AI explanations." }, "NormalizedFactHTTP": { "properties": { "metric": { "type": "string", "title": "Metric", "description": "Canonical metric code (e.g., REVENUE, NET_INCOME)." }, "metric_code": { "type": "string", "title": "Metric Code", "description": "Canonical metric code alias for consumers expecting metric_code." }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label", "description": "Human-readable label for the metric, when available." }, "unit": { "type": "string", "title": "Unit", "description": "Unit code for the value (e.g., ISO 4217 currency code such as USD)." }, "period_start": { "type": "string", "format": "date", "title": "Period Start", "description": "Inclusive start date of the reporting period." }, "period_end": { "type": "string", "format": "date", "title": "Period End", "description": "Inclusive end date of the reporting period." }, "value": { "type": "string", "title": "Value", "description": "Stringified numeric value in full units suitable for JSON." }, "dimension": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Dimension", "description": "Optional simple dimensional context (e.g., {'segment': 'US'})." }, "dimension_key": { "type": "string", "title": "Dimension Key", "description": "Stable fact dimension key (e.g., default or consolidation=CONSOLIDATED)." }, "source_line_item": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Line Item", "description": "Original line-item label from the filing, when available." }, "value_origin": { "type": "string", "title": "Value Origin", "description": "Provenance of the value: 'SOURCE' (as-reported by the filer), 'DERIVED' (computed from other reported values via an exact accounting identity), or 'UNRECORDED' when the origin is not recorded. 'UNRECORDED' is not a claim that the value is unreliable; it is the absence of a claim, and such facts carry no source_line_item either.", "default": "UNRECORDED" }, "correction_rule": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Correction Rule", "description": "Stable identifier of the correction applied to this value, when one was. A served value is not always the number as tagged: a cost the filer tagged as a credit is re-signed, and a top line tagged under a residual concept is replaced by the revenue the filer reported alongside its gross profit. as_filed_value and as_filed_concept give the figure as tagged. Null -- the ordinary case -- means no correction is recorded and the value is as tagged." }, "as_filed_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "As Filed Value", "description": "The value as the filing tagged it, before the correction named by correction_rule. Null when no correction applied, or when the correction changed which fact was selected rather than the number." }, "as_filed_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "As Filed Concept", "description": "Source XBRL concept the superseded value came from, when the correction replaced one selection with another." }, "split_adjusted_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Split Adjusted Value", "description": "Value restated into current share terms when a split occurred after this period. Null when no split applies or the metric is not share-denominated. The 'value' field always remains as filed." }, "split_adjustment_factor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Split Adjustment Factor", "description": "Cumulative new-shares-per-old-share ratio applied to reach split_adjusted_value, as a decimal string. Null when no split applies." }, "period_origin": { "type": "string", "title": "Period Origin", "description": "Provenance of period_start: 'SOURCE' (the span as filed, taken from the XBRL context) or 'DERIVED' (inferred from fiscal period and period_end because the statement predates span capture). Instant facts report 'INSTANT' and carry period_start equal to period_end.", "default": "SOURCE" }, "usd": { "anyOf": [ { "$ref": "#/components/schemas/UsdValueHTTP" }, { "type": "null" } ], "description": "Present only when include_usd=true and the value converts: the value in US dollars, with its rate, the rate's dates and its source. Absent for a value that is not money (a share count), and when no rate covers its period: the Federal Reserve Board's H.10 release publishes rates for 22 currencies, and an as-of request uses only rates published by its date. value always stays as filed." } }, "additionalProperties": false, "type": "object", "required": [ "metric", "metric_code", "unit", "period_start", "period_end", "value", "dimension_key" ], "title": "NormalizedFactHTTP", "description": "HTTP schema for a single normalized fact.\n\nThis is the atomic modeling unit extracted from a normalized EDGAR\npayload. It is intentionally simple and wire-friendly.\n\nAttributes:\n metric:\n Canonical metric code (e.g., \"REVENUE\", \"NET_INCOME\").\n metric_code:\n Backward-compatible alias for the canonical metric code.\n label:\n Human-readable label for the metric, when available.\n unit:\n ISO 4217 currency code or other unit code (e.g., \"USD\").\n period_start:\n Inclusive start of the fact's reporting period.\n period_end:\n Inclusive end of the fact's reporting period.\n value:\n Stringified numeric value in full units, suitable for JSON.\n dimension:\n Optional simple dimensional context (e.g., {\"segment\": \"US\"}).\n dimension_key:\n Stable fact dimension key (e.g., \"default\").\n source_line_item:\n Original line-item label from the filing, when available.", "examples": [ { "dimension": { "segment": "US" }, "dimension_key": "segment=US", "label": "Revenue", "metric": "REVENUE", "metric_code": "REVENUE", "period_end": "2024-03-31", "period_start": "2024-01-01", "source_line_item": "Net sales", "unit": "USD", "value": "123456.78" } ] }, "NormalizedStatementHTTP": { "properties": { "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "High-level statement taxonomy (income, balance sheet, cash flow)." }, "accounting_standard": { "$ref": "#/components/schemas/AccountingStandard", "description": "Accounting standard (e.g., US_GAAP, IFRS)." }, "statement_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Statement Date", "description": "Reporting period end date for the statement, when known." }, "fiscal_year": { "anyOf": [ { "type": "integer", "minimum": 1.0 }, { "type": "null" } ], "title": "Fiscal Year", "description": "Fiscal year associated with the statement, when available." }, "fiscal_period": { "anyOf": [ { "$ref": "#/components/schemas/FiscalPeriod" }, { "type": "null" } ], "description": "Fiscal period within the year. FY is a whole fiscal year: 358 to 372 days, or the year the filer declares. Q1-Q4 are quarters and H1 a half year. OTHER is any other reported span: a transition period, a short first year, or one of the two periods of a fiscal year split at a business combination or fresh-start reorganization. An OTHER period's dates are period_start and statement_date, and two OTHER periods are never added together into a year." }, "period_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period Start", "description": "First day of the period the statement reports; statement_date is the last. Null for a balance sheet, which reports a single date, and when the filing's span is not available." }, "reporting_entity": { "type": "string", "enum": [ "REGISTRANT", "PREDECESSOR" ], "title": "Reporting Entity", "description": "PREDECESSOR when the filing presents this period as its predecessor's: the business the registrant succeeded in a business combination or fresh-start reorganization, which it reports as its own history; otherwise REGISTRANT.", "default": "REGISTRANT" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency", "description": "ISO 4217 currency code for monetary values (e.g., USD), when known." }, "cik": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cik", "description": "Central Index Key for the filer, if known." }, "unit_multiplier": { "type": "integer", "title": "Unit Multiplier", "description": "Power of ten the values are scaled by; 0 means values are in full units.", "default": 0 }, "source_accession_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Accession Id", "description": "Originating EDGAR accession identifier, when available." }, "_meta": { "anyOf": [ { "$ref": "#/components/schemas/StatementMetricMetaHTTP" }, { "type": "null" } ], "description": "Optional statement metadata container. Includes statement completeness and optional per-metric provenance details." }, "facts": { "items": { "$ref": "#/components/schemas/NormalizedFactHTTP" }, "type": "array", "title": "Facts", "description": "Collection of normalized facts belonging to this statement." } }, "additionalProperties": false, "type": "object", "required": [ "statement_type", "accounting_standard" ], "title": "NormalizedStatementHTTP", "description": "HTTP schema for a normalized EDGAR statement.\n\nThis is a wire-facing analytics view that groups normalized facts under a\nstatement identity. It keeps the required surface small for clients while\nexposing richer metadata when available.\n\nAttributes:\n statement_type:\n Statement type (income, balance sheet, cash flow, etc.).\n accounting_standard:\n Accounting standard (e.g., US_GAAP, IFRS).\n statement_date:\n Reporting period end date, if known.\n fiscal_year:\n Fiscal year associated with the statement, when available.\n fiscal_period:\n Fiscal period within the year (e.g., FY, Q1, Q2), when available.\n period_start:\n First day of the reported span; None for a balance sheet.\n reporting_entity:\n REGISTRANT, or PREDECESSOR for a predecessor's period.\n currency:\n ISO 4217 currency code for monetary values (e.g., \"USD\"), when known.\n cik:\n Central Index Key for the filer, when available.\n unit_multiplier:\n Power of ten the values are scaled by; 0 means full units.\n source_accession_id:\n Originating EDGAR accession identifier, when available.\n facts:\n Collection of normalized facts belonging to this statement.", "examples": [ { "_meta": { "provenance": { "REVENUE": { "filing_accession": "0000320193-24-000012", "mapping_type": "DIRECT", "override_applied": true, "override_reason": "taxonomy override for revenue", "xbrl_concept": "us-gaap:Revenues" } } }, "accounting_standard": "US_GAAP", "cik": "0000320193", "currency": "USD", "facts": [ { "dimension": { "segment": "US" }, "label": "Revenue", "metric": "REVENUE", "period_end": "2024-03-31", "period_start": "2024-01-01", "source_line_item": "Net sales", "unit": "USD", "value": "123456.78" } ], "fiscal_period": "Q1", "fiscal_year": 2024, "period_start": "2024-01-01", "reporting_entity": "REGISTRANT", "source_accession_id": "0000320193-24-000012", "statement_date": "2024-03-31", "statement_type": "INCOME_STATEMENT", "unit_multiplier": 0 } ] }, "NormalizedStatementViewHTTP": { "properties": { "latest": { "$ref": "#/components/schemas/EdgarStatementHTTP", "description": "The statement as the latest SEC filing for the requested identity reports it, with its figures." }, "version_history": { "items": { "$ref": "#/components/schemas/EdgarStatementHTTP" }, "type": "array", "title": "Version History", "description": "The statement as each filing reported it: one entry per SEC filing, in SEC acceptance order, so an original filing and each amendment appear once. For a fiscal year split into two OTHER periods, a filing that reports both appears once per period, ordered by statement_date." }, "periods": { "items": { "$ref": "#/components/schemas/EdgarStatementHTTP" }, "type": "array", "title": "Periods", "description": "The statement as the latest SEC filing reports it, once per period the requested identity covers, ordered by statement_date. One entry, the same statement as `latest`, for every identity except a fiscal year split at a business combination or fresh-start reorganization: its OTHER identity reports the predecessor's period and the registrant's, told apart by period_start, statement_date and reporting_entity, and `latest` is the later of the two. statement_date narrows the response to one period." }, "availability": { "anyOf": [ { "$ref": "#/components/schemas/EndpointAvailabilityHTTP" }, { "type": "null" } ], "description": "Whether the requested statement is available, and if not, why." } }, "additionalProperties": false, "type": "object", "required": [ "latest" ], "title": "NormalizedStatementViewHTTP", "description": "A statement as the latest filing reports it, with each filing's version of it.\n\nAttributes:\n latest:\n The statement as the latest SEC filing for the period reports it.\n version_history:\n The statement as each filing reported it: one entry per SEC\n filing, in SEC acceptance order. Empty unless requested.\n periods:\n The latest statement of each period the identity reports, ordered\n by statement_date. Two entries only for a fiscal year split into\n two OTHER periods.", "examples": [ { "availability": { "availability_status": "PUBLISHED", "evidence": { "accession_id": "0000320193-24-000123" }, "identity": { "cik": "0000320193", "fiscal_period": "FY", "fiscal_year": 2024, "statement_type": "INCOME_STATEMENT" }, "reporting_lifecycle_status": "RECENT_IPO_OR_NEW_REPORTER", "required": true, "source_gap_terminal": false }, "latest": { "accepted_at": "2024-11-01T10:01:36Z", "accession_id": "0000320193-24-000123", "accounting_standard": "US_GAAP", "cik": "0000320193", "company_name": "Apple Inc.", "content": { "_meta": {}, "accounting_standard": "US_GAAP", "cik": "0000320193", "currency": "USD", "facts": [ { "dimension": { "consolidation": "CONSOLIDATED" }, "dimension_key": "consolidation=CONSOLIDATED", "metric": "BASIC_EPS", "metric_code": "BASIC_EPS", "period_end": "2024-09-28", "period_origin": "SOURCE", "period_start": "2023-10-01", "source_line_item": "us-gaap:EarningsPerShareBasic", "unit": "USD", "value": "6.11", "value_origin": "SOURCE" }, { "dimension": { "consolidation": "CONSOLIDATED" }, "dimension_key": "consolidation=CONSOLIDATED", "metric": "COST_OF_REVENUE", "metric_code": "COST_OF_REVENUE", "period_end": "2024-09-28", "period_origin": "SOURCE", "period_start": "2023-10-01", "source_line_item": "us-gaap:CostOfGoodsAndServicesSold", "unit": "USD", "value": "210352000000", "value_origin": "SOURCE" } ], "fiscal_period": "FY", "fiscal_year": 2024, "source_accession_id": "0000320193-24-000123", "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT", "unit_multiplier": 0 }, "currency": "USD", "filing_date": "2024-11-01", "filing_type": "10-K", "fiscal_period": "FY", "fiscal_year": 2024, "is_amendment": false, "is_restated": false, "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT" }, "version_history": [ { "accepted_at": "2024-11-01T10:01:36Z", "accession_id": "0000320193-24-000123", "accounting_standard": "US_GAAP", "cik": "0000320193", "company_name": "Apple Inc.", "content": { "_meta": {}, "accounting_standard": "US_GAAP", "cik": "0000320193", "currency": "USD", "facts": [ { "dimension": { "consolidation": "CONSOLIDATED" }, "dimension_key": "consolidation=CONSOLIDATED", "metric": "BASIC_EPS", "metric_code": "BASIC_EPS", "period_end": "2024-09-28", "period_origin": "DERIVED", "period_start": "2023-09-29", "unit": "USD", "value": "6.11", "value_origin": "SOURCE" }, { "dimension": { "consolidation": "CONSOLIDATED" }, "dimension_key": "consolidation=CONSOLIDATED", "metric": "COST_OF_REVENUE", "metric_code": "COST_OF_REVENUE", "period_end": "2024-09-28", "period_origin": "DERIVED", "period_start": "2023-09-29", "unit": "USD", "value": "210352000000", "value_origin": "SOURCE" } ], "fiscal_period": "FY", "fiscal_year": 2024, "source_accession_id": "0000320193-24-000123", "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT", "unit_multiplier": 0 }, "currency": "USD", "filing_date": "2024-11-01", "filing_type": "10-K", "fiscal_period": "FY", "fiscal_year": 2024, "is_amendment": false, "is_restated": false, "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT" } ] } ] }, "OverrideRuleApplicationHTTP": { "properties": { "rule_id": { "type": "string", "title": "Rule Id", "description": "Stable identifier of the override rule." }, "scope": { "type": "string", "title": "Scope", "description": "Override scope (e.g. GLOBAL, INDUSTRY, COMPANY, ANALYST). This is a stringified domain enum." }, "priority": { "type": "integer", "minimum": 0.0, "title": "Priority", "description": "Priority of the rule within its scope. Higher values win when multiple rules at the same scope match." }, "action": { "type": "string", "title": "Action", "description": "Effective action of the rule (e.g. REMAP, SUPPRESS, NO_OP)." }, "source_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Concept", "description": "Source GAAP/IFRS concept or canonical metric code the rule matches." }, "target_metric_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Metric Code", "description": "Target canonical metric code when the rule performs a remap." }, "target_dimension_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Target Dimension Key", "description": "Target dimension key when the rule adjusts dimensional context." }, "is_effective": { "type": "boolean", "title": "Is Effective", "description": "Whether this rule actually changed any facts in the evaluated slice." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Optional human-readable explanation of why the rule did or did not apply." }, "contributes_to_metrics": { "type": "boolean", "title": "Contributes To Metrics", "description": "Whether this rule contributes to at least one canonical metric in the evaluated slice." } }, "additionalProperties": false, "type": "object", "required": [ "rule_id", "scope", "priority", "action", "is_effective", "contributes_to_metrics" ], "title": "OverrideRuleApplicationHTTP", "description": "One mapping override rule and how it applied to the statement." }, "PaginatedEnvelopeFundamentalsTimeSeriesHTTP": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/FundamentalsTimeSeriesPointHTTP" }, "type": "array", "title": "Items" }, "availability": { "anyOf": [ { "$ref": "#/components/schemas/EndpointAvailabilityHTTP" }, { "type": "null" } ], "description": "Optional source-aware availability metadata for empty or classified time-series responses." } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "PaginatedEnvelope", "description": "Paginated fundamentals time-series envelope with availability metadata." }, "PaginatedEnvelopeMetricTimeSeriesHTTP": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/MetricTimeSeriesPointHTTP" }, "type": "array", "title": "Items" }, "availability": { "anyOf": [ { "$ref": "#/components/schemas/EndpointAvailabilityHTTP" }, { "type": "null" } ], "description": "Optional source-aware availability metadata for empty or classified metric time-series responses." } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "PaginatedEnvelope", "description": "Paginated metric time-series envelope with availability metadata." }, "QualityCheckGroupHTTP": { "properties": { "passed_count": { "type": "integer", "minimum": 0.0, "title": "Passed Count", "description": "Rules the statement passed." }, "failed_count": { "type": "integer", "minimum": 0.0, "title": "Failed Count", "description": "Rules the statement failed." }, "skipped_count": { "type": "integer", "minimum": 0.0, "title": "Skipped Count", "description": "Rules that could not be checked." }, "pass_rate": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Pass Rate", "description": "passed_count over passed_count plus failed_count, in [0,1] to four places. Null when no rule could be checked: a skipped rule is neither a pass nor a fail." }, "failed_rules": { "items": { "$ref": "#/components/schemas/QualityFailedCheckHTTP" }, "type": "array", "title": "Failed Rules", "description": "Each failed rule with the figures it compared." }, "skipped_rules": { "items": { "$ref": "#/components/schemas/QualitySkippedCheckHTTP" }, "type": "array", "title": "Skipped Rules", "description": "Each rule that could not be checked, with its reason." } }, "additionalProperties": false, "type": "object", "required": [ "passed_count", "failed_count", "skipped_count", "pass_rate" ], "title": "QualityCheckGroupHTTP", "description": "Outcome of one group of reconciliation rules on the statement." }, "QualityFailedCheckHTTP": { "properties": { "rule_id": { "type": "string", "title": "Rule Id", "description": "Stable identifier of the rule." }, "severity": { "$ref": "#/components/schemas/MaterialityClass", "description": "How material the difference is." }, "expected_value": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Expected Value", "description": "What the rule expected, in full units." }, "actual_value": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Actual Value", "description": "What the statement reports, in full units." }, "delta": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Delta", "description": "actual_value minus expected_value." }, "tolerance": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Tolerance", "description": "The difference the rule allows for rounding, when it states one." } }, "additionalProperties": false, "type": "object", "required": [ "rule_id", "severity" ], "title": "QualityFailedCheckHTTP", "description": "One reconciliation rule the statement failed." }, "QualitySkippedCheckHTTP": { "properties": { "rule_id": { "type": "string", "title": "Rule Id", "description": "Stable identifier of the rule." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "Stable code for why the rule could not be checked, e.g. MISSING_REQUIRED_METRICS or NO_SPANNING_INTERVAL." } }, "additionalProperties": false, "type": "object", "required": [ "rule_id" ], "title": "QualitySkippedCheckHTTP", "description": "One reconciliation rule that could not be checked, and why." }, "QueryExecuteRequestHTTP": { "properties": { "query_type": { "type": "string", "title": "Query Type", "description": "Supported deterministic query type: 'financial_state_time_series', 'metric_time_series', 'metric_bundle_time_series', 'financials_as_of' or 'financials_as_of_page'. 'financials_as_of' takes cik, and optionally audit_mode, and requires as_of_date. 'financials_as_of_page' is one page of that read, as GET /v1/edgar/as-of/{date}/financials/{cik}/page selects it: it takes cik, and optionally audit_mode, statement_type, fiscal_year_from, fiscal_year_to, fiscal_period, latest_only, offset, limit (1-50, default 20) and as_of_timestamp (a timestamp with an offset, falling on as_of_date), and requires as_of_date." }, "parameters": { "additionalProperties": true, "type": "object", "title": "Parameters", "description": "Query parameters for the selected query type. Keys the query type does not take are ignored and not stored." }, "as_of_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "As Of Date", "description": "Optional no-lookahead boundary date applied by supported query types." }, "include_result": { "type": "boolean", "title": "Include Result", "description": "Whether to include the executed result payload in the response body.", "default": true } }, "additionalProperties": false, "type": "object", "required": [ "query_type" ], "title": "QueryExecuteRequestHTTP", "description": "HTTP request body for deterministic query execution.", "examples": [ { "as_of_date": "2025-03-31", "include_result": true, "parameters": { "cik": "0000320193", "fiscal_year_from": 2023, "fiscal_year_to": 2024, "page": 1, "page_size": 50, "period_type": "annual" }, "query_type": "financial_state_time_series" } ] }, "QueryExecuteResponseHTTP": { "properties": { "manifest": { "$ref": "#/components/schemas/QueryManifestHTTP", "description": "Immutable execution manifest metadata." }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result", "description": "Optional deterministic query result payload." } }, "additionalProperties": false, "type": "object", "required": [ "manifest" ], "title": "QueryExecuteResponseHTTP", "description": "HTTP response for deterministic query execution.", "examples": [ { "manifest": { "created_at": "2026-09-23T04:51:19Z", "input_hash": "a206975abffb6d6667975307efc5f6c4826e289a794fcd9347ccb982531239bb", "parameters": { "cik": "0000320193", "fiscal_year_from": 2023, "fiscal_year_to": 2024, "metric": "REVENUE", "page_size": 2 }, "query_hash": "a20bcfc744ad8fc9d63a302c094507739603d94d151ff57652e033dcc19d9657", "query_type": "metric_time_series", "replay_token": "5a98228437e753830338901c29a554d168598e321ae9f17631235b479396a71e", "result_hash": "5e8d97d3e0a9df7e9cd6acc69cae2d133e911015abfd8caff06e470f1498d824", "snapshot_hashes": [], "status": "COMPLETED" }, "result": { "items": [ { "accepted_at": "2023-11-02T22:08:27+00:00", "cik": "0000320193", "filing_accession": "0000320193-23-000106", "filing_date": "2023-11-03", "filing_type": "10-K", "fiscal_period": "FY", "fiscal_year": 2023, "is_restated": false, "metric": "REVENUE", "period_end": "2023-09-30", "provenance": { "filing_accession": "0000320193-23-000106", "mapping_type": "DIRECT", "override_applied": false }, "source_line_item": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", "statement_type": "INCOME_STATEMENT", "unit": "USD", "value": "383285000000.000000" }, { "accepted_at": "2024-11-01T10:01:36+00:00", "cik": "0000320193", "filing_accession": "0000320193-24-000123", "filing_date": "2024-11-01", "filing_type": "10-K", "fiscal_period": "FY", "fiscal_year": 2024, "is_restated": false, "metric": "REVENUE", "period_end": "2024-09-28", "provenance": { "filing_accession": "0000320193-24-000123", "mapping_type": "DIRECT", "override_applied": false }, "source_line_item": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", "statement_type": "INCOME_STATEMENT", "unit": "USD", "value": "391035000000.000000" } ], "page": 1, "page_size": 2, "total": 2 } } ] }, "QueryManifestHTTP": { "properties": { "replay_token": { "type": "string", "title": "Replay Token", "description": "Stable replay token for later manifest lookup." }, "query_type": { "type": "string", "title": "Query Type", "description": "Logical query type that was executed." }, "query_hash": { "type": "string", "title": "Query Hash", "description": "Stable SHA-256 identifier of the query: the same query type, parameters and as_of_date give the same hash." }, "input_hash": { "type": "string", "title": "Input Hash", "description": "SHA-256 identifier of the statements the query was answered from; it changes when the statements behind the answer change." }, "result_hash": { "type": "string", "title": "Result Hash", "description": "SHA-256 hash of the deterministic result payload." }, "as_of_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "As Of Date", "description": "Optional no-lookahead boundary date." }, "snapshot_hashes": { "items": { "type": "string" }, "type": "array", "title": "Snapshot Hashes", "description": "snapshot_hash of each as-of snapshot the query resolved against. Populated for 'financials_as_of', which reads through as-of snapshots; empty for the time-series types, whose statements input_hash identifies." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "UTC timestamp when the manifest was created." }, "parameters": { "additionalProperties": true, "type": "object", "title": "Parameters", "description": "The query parameters, in canonical form." }, "status": { "type": "string", "title": "Status", "description": "Stable manifest status label." } }, "additionalProperties": false, "type": "object", "required": [ "replay_token", "query_type", "query_hash", "input_hash", "result_hash", "created_at", "status" ], "title": "QueryManifestHTTP", "description": "The manifest of one deterministic query: its identity, inputs and result hashes.", "examples": [ { "as_of_date": "2025-03-31", "created_at": "2025-03-31T12:00:00Z", "input_hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "parameters": { "cik": "0000320193", "fiscal_year_from": 2023, "fiscal_year_to": 2024, "period_type": "annual" }, "query_hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "query_type": "financial_state_time_series", "replay_token": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "result_hash": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd", "snapshot_hashes": [], "status": "COMPLETED" } ] }, "QueryReplayResponseHTTP": { "properties": { "replay_mode": { "type": "string", "title": "Replay Mode", "description": "Outcome of re-executing the query against current data: 'recomputed_verified' when it reproduces the original result hash, 'recomputed_format_changed' when it returns the same filings and values in a response whose bytes differ, 'recomputed_diverged' when the underlying data has changed since, and 'stored_manifest' when the query can no longer be re-executed. In every mode, result carries the original response when it is available." }, "manifest": { "$ref": "#/components/schemas/QueryManifestHTTP", "description": "Stored immutable query manifest metadata." }, "stored_result_available": { "type": "boolean", "title": "Stored Result Available", "description": "Whether the original result was stored when the query was executed. False only for replay tokens minted before results were stored." }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result", "description": "The original response, exactly as first returned; its hash is the manifest's result_hash. Null only for a token minted before results were stored whose recomputation no longer reproduces that hash." }, "recomputed_result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Recomputed Result", "description": "What the query returns against current data, present only when it diverges from the original result." }, "recomputed_result_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recomputed Result Hash", "description": "Hash of the recomputed result, comparable with the manifest's result_hash. Null when the query could not be re-executed." }, "matches_original_result": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Matches Original Result", "description": "Whether the recomputed result hash equals the manifest's result_hash." }, "data_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Data Hash", "description": "SHA-256 of the original result's data alone: its filings, periods, metrics and values. A change to the response format does not change it. Null when the original result is not available." }, "recomputed_data_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recomputed Data Hash", "description": "SHA-256 of the recomputed result's data, taken the same way as data_hash; equal to it when the query returns the same figures. Null when the query could not be re-executed." } }, "additionalProperties": false, "type": "object", "required": [ "replay_mode", "manifest", "stored_result_available" ], "title": "QueryReplayResponseHTTP", "description": "HTTP response for a replayed query: its original result plus a fresh re-verification.", "examples": [ { "data_hash": "8b1c2f6a0d4e93b7c5a1f08e6d2b4c97a3e5f1d0b8c6a4e2f9d7b5c3a1e0f8d6", "manifest": { "created_at": "2026-09-23T04:51:19Z", "input_hash": "a206975abffb6d6667975307efc5f6c4826e289a794fcd9347ccb982531239bb", "parameters": { "cik": "0000320193", "fiscal_year_from": 2023, "fiscal_year_to": 2024, "metric": "REVENUE", "page_size": 2 }, "query_hash": "a20bcfc744ad8fc9d63a302c094507739603d94d151ff57652e033dcc19d9657", "query_type": "metric_time_series", "replay_token": "5a98228437e753830338901c29a554d168598e321ae9f17631235b479396a71e", "result_hash": "5e8d97d3e0a9df7e9cd6acc69cae2d133e911015abfd8caff06e470f1498d824", "snapshot_hashes": [], "status": "COMPLETED" }, "matches_original_result": true, "recomputed_data_hash": "8b1c2f6a0d4e93b7c5a1f08e6d2b4c97a3e5f1d0b8c6a4e2f9d7b5c3a1e0f8d6", "recomputed_result_hash": "5e8d97d3e0a9df7e9cd6acc69cae2d133e911015abfd8caff06e470f1498d824", "replay_mode": "recomputed_verified", "result": { "items": [ { "accepted_at": "2023-11-02T22:08:27+00:00", "cik": "0000320193", "filing_accession": "0000320193-23-000106", "filing_date": "2023-11-03", "filing_type": "10-K", "fiscal_period": "FY", "fiscal_year": 2023, "is_restated": false, "metric": "REVENUE", "period_end": "2023-09-30", "provenance": { "filing_accession": "0000320193-23-000106", "mapping_type": "DIRECT", "override_applied": false }, "source_line_item": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", "statement_type": "INCOME_STATEMENT", "unit": "USD", "value": "383285000000.000000" }, { "accepted_at": "2024-11-01T10:01:36+00:00", "cik": "0000320193", "filing_accession": "0000320193-24-000123", "filing_date": "2024-11-01", "filing_type": "10-K", "fiscal_period": "FY", "fiscal_year": 2024, "is_restated": false, "metric": "REVENUE", "period_end": "2024-09-28", "provenance": { "filing_accession": "0000320193-24-000123", "mapping_type": "DIRECT", "override_applied": false }, "source_line_item": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", "statement_type": "INCOME_STATEMENT", "unit": "USD", "value": "391035000000.000000" } ], "page": 1, "page_size": 2, "total": 2 }, "stored_result_available": true } ] }, "QueryVerificationHTTP": { "properties": { "replay_token": { "type": "string", "title": "Replay Token", "description": "The replay token verified." }, "verdict": { "type": "string", "enum": [ "MATCHES", "DOES_NOT_MATCH", "NOT_RECOMPUTED" ], "title": "Verdict", "description": "MATCHES when re-running the query now returns the same statements and values as when the token was minted; DOES_NOT_MATCH when it returns different data; NOT_RECOMPUTED when the query can no longer be re-run." }, "matches_original_result": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Matches Original Result", "description": "Whether the re-run result is byte-for-byte the original: its SHA-256 equals result_hash. False with verdict MATCHES means the same data in a response format that has changed since. Null when not re-run." }, "query_type": { "type": "string", "title": "Query Type", "description": "The query type the token was minted for." }, "parameters": { "additionalProperties": true, "type": "object", "title": "Parameters", "description": "The query's parameters, in canonical form." }, "as_of_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "As Of Date", "description": "The query's as-of date." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "UTC time the token was first minted." }, "result_hash": { "type": "string", "title": "Result Hash", "description": "SHA-256 hash of the original result." }, "recomputed_result_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recomputed Result Hash", "description": "SHA-256 hash of the result the query returns now. Null when not re-run." }, "data_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Data Hash", "description": "SHA-256 of the original result's data alone: its filings, periods, metrics and values. A change to the response format does not change it. Null when the original result is not available." }, "recomputed_data_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recomputed Data Hash", "description": "SHA-256 of the data the query returns now, taken the same way as data_hash; equal to it when the figures are the same. Null when not re-run." }, "accessions": { "items": { "type": "string" }, "type": "array", "title": "Accessions", "description": "SEC accession numbers of the filings the original result was read from." }, "verified_at": { "type": "string", "format": "date-time", "title": "Verified At", "description": "UTC time of this verification." } }, "additionalProperties": false, "type": "object", "required": [ "replay_token", "verdict", "query_type", "created_at", "result_hash", "verified_at" ], "title": "QueryVerificationHTTP", "description": "Whether re-running a replay token's query today returns the same data.", "examples": [ { "accessions": [ "0000320193-23-000106", "0000320193-24-000123" ], "created_at": "2026-09-23T04:51:19Z", "data_hash": "8b1c2f6a0d4e93b7c5a1f08e6d2b4c97a3e5f1d0b8c6a4e2f9d7b5c3a1e0f8d6", "matches_original_result": true, "parameters": { "cik": "0000320193", "fiscal_year_from": 2023, "fiscal_year_to": 2024, "metric": "REVENUE", "page_size": 2 }, "query_type": "metric_time_series", "recomputed_data_hash": "8b1c2f6a0d4e93b7c5a1f08e6d2b4c97a3e5f1d0b8c6a4e2f9d7b5c3a1e0f8d6", "recomputed_result_hash": "5e8d97d3e0a9df7e9cd6acc69cae2d133e911015abfd8caff06e470f1498d824", "replay_token": "5a98228437e753830338901c29a554d168598e321ae9f17631235b479396a71e", "result_hash": "5e8d97d3e0a9df7e9cd6acc69cae2d133e911015abfd8caff06e470f1498d824", "verdict": "MATCHES", "verified_at": "2026-10-13T09:00:00Z" } ] }, "ReadinessResponse": { "properties": { "status": { "$ref": "#/components/schemas/HealthState" }, "checks": { "items": { "$ref": "#/components/schemas/CheckResult" }, "type": "array", "title": "Checks" } }, "additionalProperties": false, "type": "object", "required": [ "status" ], "title": "ReadinessResponse", "description": "Aggregated readiness response.\n\nAttributes:\n status: Overall service classification derived from all checks.\n checks: Individual dependency results in deterministic order (DB, Redis).", "examples": [ { "checks": [ { "duration_ms": 9.0, "name": "db", "status": "ok" }, { "duration_ms": 1.4, "name": "redis", "status": "ok" } ], "status": "ok" } ] }, "RealFundamentalMetricPointHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "metric": { "type": "string", "title": "Metric", "description": "Canonical statement metric code." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "EDGAR statement period end date." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year for the statement point." }, "fiscal_period": { "type": "string", "title": "Fiscal Period", "description": "Fiscal period for the statement point." }, "nominal_value": { "type": "string", "title": "Nominal Value", "description": "Nominal EDGAR metric value as decimal string." }, "real_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Real Value", "description": "Inflation-adjusted metric value when CPI is available." }, "cpi_observation_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Cpi Observation Date", "description": "Aligned CPI observation date." }, "cpi_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cpi Value", "description": "Aligned CPI value." }, "base_cpi_value": { "type": "string", "title": "Base Cpi Value", "description": "Base CPI value used for real-value scaling." }, "source_provider": { "type": "string", "title": "Source Provider", "description": "Macro source provider." }, "source_series_id": { "type": "string", "title": "Source Series Id", "description": "Macro source series id." }, "realtime_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Realtime Start", "description": "Macro realtime_start when available." }, "realtime_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Realtime End", "description": "Macro realtime_end when available." }, "vintage_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Vintage Date", "description": "Macro vintage_date when available." }, "retrieved_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Retrieved At", "description": "Macro retrieval timestamp when available." }, "source_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Hash", "description": "Macro source hash when available." }, "filing_accession": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filing Accession", "description": "EDGAR filing accession id." }, "snapshot_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Snapshot Hash", "description": "Optional Arche snapshot hash when applicable." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "metric", "statement_date", "fiscal_year", "fiscal_period", "nominal_value", "base_cpi_value", "source_provider", "source_series_id" ], "title": "RealFundamentalMetricPointHTTP", "description": "HTTP schema for one inflation-adjusted EDGAR metric point." }, "RealFundamentalMetricSeriesHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "metric": { "type": "string", "title": "Metric", "description": "Canonical statement metric code." }, "base_year": { "type": "integer", "minimum": 1900.0, "title": "Base Year", "description": "CPI base year used for inflation adjustment." }, "cpi_series": { "type": "string", "title": "Cpi Series", "description": "Approved CPI series code used for the adjustment." }, "points": { "items": { "$ref": "#/components/schemas/RealFundamentalMetricPointHTTP" }, "type": "array", "title": "Points", "description": "Deterministically ordered inflation-adjusted metric points." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "metric", "base_year", "cpi_series" ], "title": "RealFundamentalMetricSeriesHTTP", "description": "HTTP schema for an inflation-adjusted EDGAR metric series.", "examples": [ { "base_year": 2026, "cik": "0000320193", "cpi_series": "CPIAUCSL", "metric": "REVENUE", "points": [ { "base_cpi_value": "332.813", "cik": "0000320193", "cpi_observation_date": "2022-03-01", "cpi_value": "287.674", "filing_accession": "0000320193-22-000059", "fiscal_period": "Q2", "fiscal_year": 2022, "metric": "REVENUE", "nominal_value": "97278000000", "real_value": "112541915550.2408976827937179", "realtime_end": "2026-08-12", "realtime_start": "2026-08-12", "retrieved_at": "2026-08-26T23:39:44Z", "source_hash": "1b79d1ca5057876c618ec8db5d75c8daf66e2466158ed78f579061cc09756608", "source_provider": "FRED", "source_series_id": "CPIAUCSL", "statement_date": "2022-03-26", "vintage_date": "2026-08-12" }, { "base_cpi_value": "332.813", "cik": "0000320193", "cpi_observation_date": "2022-06-01", "cpi_value": "294.957", "filing_accession": "0000320193-22-000070", "fiscal_period": "Q3", "fiscal_year": 2022, "metric": "REVENUE", "nominal_value": "82959000000", "real_value": "93606300806.55824408303583234", "realtime_end": "2026-08-12", "realtime_start": "2026-08-12", "retrieved_at": "2026-08-26T23:39:44Z", "source_hash": "937339a2d4bcef6fc9f5383c8aa3eed7a6a650dbcbafa240fb96e07e77927b47", "source_provider": "FRED", "source_series_id": "CPIAUCSL", "statement_date": "2022-06-25", "vintage_date": "2026-08-12" } ] } ] }, "ReconciliationMetaHTTP": { "properties": { "identity": { "$ref": "#/components/schemas/IdentitySummaryHTTP", "description": "Accounting-identity reconciliation summary." }, "rollforward": { "$ref": "#/components/schemas/RollforwardSummaryHTTP", "description": "Rollforward reconciliation summary." }, "cross_statement": { "$ref": "#/components/schemas/RollforwardSummaryHTTP", "description": "Cross-statement reconciliation summary." }, "reconciliation_supported_rules_count": { "type": "integer", "minimum": 0.0, "title": "Reconciliation Supported Rules Count", "description": "Total supported reconciliation rules (rollforward + cross-statement)." }, "reconciliation_total_rules_count": { "type": "integer", "minimum": 0.0, "title": "Reconciliation Total Rules Count", "description": "Total reconciliation rules configured for this response." }, "reconciliation_skipped_rules_count": { "type": "integer", "minimum": 0.0, "title": "Reconciliation Skipped Rules Count", "description": "Total reconciliation rules skipped due to missing/unsupported inputs." } }, "additionalProperties": false, "type": "object", "required": [ "identity", "rollforward", "cross_statement", "reconciliation_supported_rules_count", "reconciliation_total_rules_count", "reconciliation_skipped_rules_count" ], "title": "ReconciliationMetaHTTP", "description": "Reconciliation metadata container." }, "ReconciliationResultHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "statement_type": { "type": "string", "title": "Statement Type", "description": "Statement type for the evaluated identity." }, "fiscal_year": { "type": "integer", "title": "Fiscal Year", "description": "Fiscal year for the evaluated identity." }, "fiscal_period": { "type": "string", "title": "Fiscal Period", "description": "Fiscal period for the evaluated identity." }, "accession_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accession Id", "description": "SEC accession of the filing whose statement the result describes. With cik, statement_type, fiscal_year and fiscal_period it names one public statement; null when the result is not tied to a filing.", "examples": [ "0001069183-25-000075" ] }, "rule_id": { "type": "string", "title": "Rule Id", "description": "Stable reconciliation rule identifier." }, "rule_category": { "$ref": "#/components/schemas/ReconciliationRuleCategory", "description": "Rule category." }, "status": { "$ref": "#/components/schemas/ReconciliationStatus", "description": "Rule outcome. PASS or FAIL when the rule was evaluated. SKIPPED when it could not be, with the reason in notes.reason: a SKIPPED rule was not evaluated and is not a pass." }, "severity": { "type": "string", "title": "Severity", "description": "Severity (MaterialityClass aligned)." }, "expected_value": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Expected Value", "description": "Expected value under the rule." }, "actual_value": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Actual Value", "description": "Actual observed value." }, "delta": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Delta", "description": "Actual - expected." }, "dimension_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dimension Key", "description": "Dimension key when rule is dimension-specific." }, "dimension_labels": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Dimension Labels", "description": "Dimension labels when applicable." }, "notes": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Notes", "description": "Machine-readable diagnostic payload." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "fiscal_year", "fiscal_period", "rule_id", "rule_category", "status", "severity" ], "title": "ReconciliationResultHTTP", "description": "Single reconciliation rule evaluation result in HTTP form." }, "ReconciliationRuleCategory": { "type": "string", "enum": [ "IDENTITY", "ROLLFORWARD", "FX", "CALENDAR", "SEGMENT" ], "title": "ReconciliationRuleCategory", "description": "High-level reconciliation rule categories." }, "ReconciliationStatus": { "type": "string", "enum": [ "PASS", "FAIL", "SKIPPED" ], "title": "ReconciliationStatus", "description": "Outcome of a reconciliation rule evaluation.\n\n``PASS`` and ``FAIL`` are the two conclusions an evaluated rule reaches.\n``SKIPPED`` is a rule that could not be evaluated -- a required figure the\nfiling does not report, no preceding period, no figures -- and is\nneither. There is no fourth outcome." }, "ReconciliationSummaryBucketHTTP": { "properties": { "fiscal_year": { "type": "integer", "title": "Fiscal Year", "description": "Fiscal year." }, "fiscal_period": { "type": "string", "title": "Fiscal Period", "description": "Fiscal period (FiscalPeriod.value)." }, "accession_id": { "type": "string", "title": "Accession Id", "description": "SEC accession of the filing whose statement the bucket counts. Each filing is counted once, through its current statement.", "examples": [ "0001069183-25-000075" ] }, "statement_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Statement Date", "description": "End date of the counted statement's period. A filing that splits a fiscal year at a business combination or fresh-start reorganization reports two OTHER statements, and each is counted in its own bucket.", "examples": [ "2024-12-31" ] }, "rule_category": { "$ref": "#/components/schemas/ReconciliationRuleCategory", "description": "Rule category." }, "pass_count": { "type": "integer", "minimum": 0.0, "title": "Pass Count", "description": "Number of PASS results." }, "fail_count": { "type": "integer", "minimum": 0.0, "title": "Fail Count", "description": "Number of FAIL results." }, "skip_count": { "type": "integer", "minimum": 0.0, "title": "Skip Count", "description": "Number of SKIPPED results: rules that could not be evaluated because the statement did not report the inputs they need, or had no preceding period." } }, "additionalProperties": false, "type": "object", "required": [ "fiscal_year", "fiscal_period", "accession_id", "rule_category", "pass_count", "fail_count", "skip_count" ], "title": "ReconciliationSummaryBucketHTTP", "description": "Aggregated PASS/FAIL/SKIPPED counts for a fiscal period and rule category." }, "ReconciliationSummaryHTTP": { "properties": { "reconciliation_max_severity": { "anyOf": [ { "$ref": "#/components/schemas/MaterialityClass" }, { "type": "null" } ], "description": "Max reconciliation severity across rules." }, "reconciliation_fail_count": { "type": "integer", "minimum": 0.0, "title": "Reconciliation Fail Count", "description": "Count of reconciliation failures for the statement.", "default": 0 } }, "additionalProperties": false, "type": "object", "title": "ReconciliationSummaryHTTP", "description": "HTTP schema for a reconciliation summary block.", "examples": [ { "reconciliation_fail_count": 2, "reconciliation_max_severity": "MEDIUM" } ] }, "RestatementAlertEventHTTP": { "properties": { "restatement_alert_event_id": { "type": "string", "title": "Restatement Alert Event Id", "description": "Immutable restatement alert event identifier." }, "company_id": { "type": "string", "title": "Company Id", "description": "Company identifier for the affected issuer." }, "cik": { "type": "string", "title": "Cik", "description": "Issuer CIK.", "examples": [ "0000320193" ] }, "ticker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ticker", "description": "Primary ticker when reliably available for the issuer.", "examples": [ "AAPL" ] }, "accession_id": { "type": "string", "title": "Accession Id", "description": "SEC accession of the filing whose statement restated the prior one." }, "prior_accession_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prior Accession Id", "description": "SEC accession of the filing whose statement was restated, when one existed." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Affected statement type." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Affected statement date." }, "fiscal_year": { "type": "integer", "title": "Fiscal Year", "description": "Affected fiscal year." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Affected fiscal period." }, "accepted_at": { "type": "string", "format": "date-time", "title": "Accepted At", "description": "UTC time the SEC accepted the filing named by accession_id." }, "facts_changed_count": { "type": "integer", "title": "Facts Changed Count", "description": "Total number of fact revision events in the batch." }, "material_facts_count": { "type": "integer", "title": "Material Facts Count", "description": "Number of tracked key metrics contributing to materiality scoring." }, "materiality_score": { "$ref": "#/components/schemas/MaterialityClass", "description": "Deterministic aggregate materiality classification for the alert." }, "change_class_counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Change Class Counts", "description": "Counts of fact revision change classes included in the alert." }, "summary_metrics": { "items": { "$ref": "#/components/schemas/RestatementAlertSummaryMetricHTTP" }, "type": "array", "title": "Summary Metrics", "description": "Compact summary of the highest-signal changed metrics." }, "materiality_summary": { "type": "string", "title": "Materiality Summary", "description": "Compact explanation of why the materiality bucket was assigned." }, "model_impacts": { "items": { "$ref": "#/components/schemas/RestatementModelImpactHTTP" }, "type": "array", "title": "Model Impacts", "description": "Derived model-impact summaries omitted when required inputs were unavailable." } }, "additionalProperties": false, "type": "object", "required": [ "restatement_alert_event_id", "company_id", "cik", "accession_id", "statement_type", "statement_date", "fiscal_year", "fiscal_period", "accepted_at", "facts_changed_count", "material_facts_count", "materiality_score", "materiality_summary" ], "title": "RestatementAlertEventHTTP", "description": "HTTP schema for one immutable restatement alert event.", "examples": [ { "accepted_at": "2023-09-09T00:37:40Z", "accession_id": "0001477932-23-006781", "change_class_counts": { "NEW_DISCLOSURE": 2 }, "cik": "0001938338", "company_id": "2eb4d8b9-d3dd-400a-b15f-ac4e37c0e293", "facts_changed_count": 2, "fiscal_period": "FY", "fiscal_year": 2022, "material_facts_count": 0, "materiality_score": "LOW", "materiality_summary": "LOW severity across 2 fact revisions; impacts: current_ratio, working_capital", "model_impacts": [ { "current_value": "0.3249", "delta_value": "0.0000", "impact_code": "current_ratio", "previous_value": "0.3249" }, { "current_value": "-26022828", "delta_value": "0", "impact_code": "working_capital", "previous_value": "-26022828" } ], "prior_accession_id": "0001477932-23-006211", "restatement_alert_event_id": "d3f24fb1-ca96-b5eb-0095-7bfb8c100c4a", "statement_date": "2022-12-31", "statement_type": "BALANCE_SHEET", "summary_metrics": [ { "change_type": "NEW_DISCLOSURE", "metric_code": "additional_paid_in_capital", "new_value": "0.000000" }, { "change_type": "NEW_DISCLOSURE", "metric_code": "goodwill", "new_value": "0.000000" } ], "ticker": "GLTK" } ] }, "RestatementAlertSummaryMetricHTTP": { "properties": { "metric_code": { "type": "string", "title": "Metric Code", "description": "Canonical metric code that changed." }, "change_type": { "type": "string", "enum": [ "NEW_DISCLOSURE", "REMOVED_DISCLOSURE", "VALUE_REVISION", "RECLASSIFICATION", "PERIOD_CORRECTION", "CONCEPT_CHANGE", "PRESENTATION_ONLY" ], "title": "Change Type", "description": "What the filing changed about the fact." }, "old_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Old Value", "description": "Prior fact value when available." }, "new_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "New Value", "description": "Current fact value when available." }, "delta_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Delta Value", "description": "Current minus prior value." } }, "additionalProperties": false, "type": "object", "required": [ "metric_code", "change_type" ], "title": "RestatementAlertSummaryMetricHTTP", "description": "HTTP schema for a compact changed-metric summary." }, "RestatementDeltaHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK for the statement identity." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement type for the restatement (e.g., INCOME_STATEMENT)." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year for the statement identity. The filer's own name for its fiscal year, as its annual reports declare it: a year closing 2025-02-01 that the filer calls fiscal 2024 is served as 2024." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period for the statement identity (e.g., FY, Q1)." }, "from_version": { "$ref": "#/components/schemas/RestatementDeltaVersionHTTP", "description": "The filing the 'from' side resolved to." }, "to_version": { "$ref": "#/components/schemas/RestatementDeltaVersionHTTP", "description": "The filing the 'to' side resolved to." }, "summary": { "$ref": "#/components/schemas/RestatementSummaryHTTP", "description": "High-level summary of the restatement." }, "deltas": { "items": { "$ref": "#/components/schemas/RestatementMetricDeltaHTTP" }, "type": "array", "title": "Deltas", "description": "Per-metric changes between the two versions; empty when nothing changed." }, "metrics_only_in_from": { "items": { "type": "string" }, "type": "array", "title": "Metrics Only In From", "description": "Metrics the 'from' version carries and the 'to' version does not. They are not diffed, so a change to one of them does not appear in deltas. Limited to the requested metrics when a subset is given." }, "metrics_only_in_to": { "items": { "type": "string" }, "type": "array", "title": "Metrics Only In To", "description": "Metrics the 'to' version carries and the 'from' version does not. They are not diffed, so a change to one of them does not appear in deltas. Limited to the requested metrics when a subset is given." }, "comparability_warning": { "type": "boolean", "title": "Comparability Warning", "description": "True when one version carries metrics the other does not; they are listed in metrics_only_in_from and metrics_only_in_to.", "default": false } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "fiscal_year", "fiscal_period", "from_version", "to_version", "summary" ], "title": "RestatementDeltaHTTP", "description": "HTTP schema for a restatement delta between two filings of one statement.", "examples": [ { "cik": "0001069183", "comparability_warning": true, "deltas": [ { "diff": "-680289000", "metric": "LONG_TERM_DEBT", "new_value": "0", "old_value": "680289000" }, { "diff": "680289000", "metric": "TOTAL_CURRENT_LIABILITIES", "new_value": "1677875000", "old_value": "997586000" } ], "fiscal_period": "FY", "fiscal_year": 2024, "from_version": { "accepted_at": "2025-02-28T21:22:06Z", "accession_id": "0001069183-25-000019", "form_type": "10-K" }, "metrics_only_in_from": [], "metrics_only_in_to": [ "CURRENT_PORTION_OF_LONG_TERM_DEBT" ], "statement_type": "BALANCE_SHEET", "summary": { "has_material_change": true, "total_metrics_changed": 2, "total_metrics_compared": 20 }, "to_version": { "accepted_at": "2025-05-07T20:38:11Z", "accession_id": "0001069183-25-000075", "form_type": "10-K/A" } } ] }, "RestatementDeltaSuccessEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/RestatementDeltaHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "SuccessEnvelopeRestatementDeltaHTTP", "description": "Success envelope for restatement delta responses.\n\nAttributes:\n data:\n RestatementDeltaHTTP payload containing restatement deltas and\n summary information for a specific statement identity." }, "RestatementDeltaVersionHTTP": { "properties": { "accession_id": { "type": "string", "title": "Accession Id", "description": "SEC accession of the filing compared on this side. Pass it back as from_accession or to_accession to repeat exactly this comparison." }, "form_type": { "type": "string", "title": "Form Type", "description": "SEC form of that filing as the SEC lists it. An amendment carries the /A suffix, so an original annual report reads 10-K and its amendment 10-K/A.", "examples": [ "10-K/A" ] }, "accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Accepted At", "description": "When the SEC accepted that filing; null when no acceptance time is recorded." } }, "additionalProperties": false, "type": "object", "required": [ "accession_id", "form_type" ], "title": "RestatementDeltaVersionHTTP", "description": "HTTP schema for one end of a restatement delta." }, "RestatementLedgerEntryHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK for the statement identity." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement type for the ledger." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year for the ledger identity. The filer's own name for its fiscal year, as its annual reports declare it: a year closing 2025-02-01 that the filer calls fiscal 2024 is served as 2024." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period for the ledger identity." }, "from_version": { "$ref": "#/components/schemas/RestatementDeltaVersionHTTP", "description": "The filing on the 'from' side of the hop." }, "to_version": { "$ref": "#/components/schemas/RestatementDeltaVersionHTTP", "description": "The filing on the 'to' side of the hop." }, "summary": { "$ref": "#/components/schemas/RestatementSummaryHTTP", "description": "High-level summary of the restatement between the two filings." }, "deltas": { "items": { "$ref": "#/components/schemas/RestatementMetricDeltaHTTP" }, "type": "array", "title": "Deltas", "description": "Per-metric restatement deltas for this hop, when available." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "fiscal_year", "fiscal_period", "from_version", "to_version", "summary" ], "title": "RestatementLedgerEntryHTTP", "description": "HTTP schema for a single hop in a restatement ledger." }, "RestatementLedgerHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK for the statement identity." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement type for the ledger." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year for the ledger identity. The filer's own name for its fiscal year, as its annual reports declare it: a year closing 2025-02-01 that the filer calls fiscal 2024 is served as 2024." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period for the ledger identity." }, "total_hops": { "type": "integer", "minimum": 0.0, "title": "Total Hops", "description": "Total number of restatement hops in the ledger." }, "entries": { "items": { "$ref": "#/components/schemas/RestatementLedgerEntryHTTP" }, "type": "array", "title": "Entries", "description": "Ordered list of restatement ledger entries." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "fiscal_year", "fiscal_period", "total_hops" ], "title": "RestatementLedgerHTTP", "description": "HTTP schema for a restatement ledger over the filings of one statement.", "examples": [ { "cik": "0000320193", "entries": [], "fiscal_period": "FY", "fiscal_year": 2024, "statement_type": "INCOME_STATEMENT", "total_hops": 0 } ] }, "RestatementMetricDeltaHTTP": { "properties": { "metric": { "type": "string", "title": "Metric", "description": "Canonical metric code (e.g., REVENUE, EPS_DILUTED)." }, "old_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Old Value", "description": "Stringified numeric value from the 'from' version, or null if the metric did not exist in that version." }, "new_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "New Value", "description": "Stringified numeric value from the 'to' version, or null if the metric is no longer present." }, "diff": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Diff", "description": "Stringified numeric difference (new - old), or null if not computable." } }, "additionalProperties": false, "type": "object", "required": [ "metric" ], "title": "RestatementMetricDeltaHTTP", "description": "HTTP schema for a single restatement metric delta." }, "RestatementMetricTimelineHTTP": { "properties": { "cik": { "type": "string", "title": "Cik" }, "statement_type": { "$ref": "#/components/schemas/StatementType" }, "fiscal_year": { "type": "integer", "title": "Fiscal Year" }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod" }, "by_metric": { "additionalProperties": { "items": { "items": { "type": "string" }, "type": "array" }, "type": "array" }, "type": "object", "title": "By Metric" }, "restatement_frequency": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Restatement Frequency" }, "per_metric_max_delta": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Per Metric Max Delta" }, "total_hops": { "type": "integer", "title": "Total Hops" }, "timeline_severity": { "type": "string", "title": "Timeline Severity" } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "fiscal_year", "fiscal_period", "by_metric", "restatement_frequency", "per_metric_max_delta", "total_hops", "timeline_severity" ], "title": "RestatementMetricTimelineHTTP", "description": "HTTP schema for a restatement metric timeline.\n\nThis schema represents a hop-aligned time series of restatement deltas\nfor a single statement identity, one hop per change between SEC filings.\n\nAttributes:\n cik:\n Company CIK for the statement identity.\n statement_type:\n Statement type (e.g., INCOME_STATEMENT, BALANCE_SHEET).\n fiscal_year:\n Fiscal year associated with the statement identity.\n fiscal_period:\n Fiscal period (e.g., FY, Q1, Q2, Q3, Q4).\n by_metric:\n Mapping from metric code to a list of [hop_index, absolute_delta]\n pairs, both encoded as strings for wire stability. hop_index is\n the 1-based hop index within the ledger.\n restatement_frequency:\n Mapping from metric code to the number of hops in which that metric\n exhibited a non-zero absolute delta.\n per_metric_max_delta:\n Mapping from metric code to the largest absolute delta observed\n across all hops, stringified.\n total_hops:\n Total number of hops in the underlying restatement ledger.\n timeline_severity:\n Aggregate severity classification for the timeline, as a string\n (e.g., \"NONE\", \"LOW\", \"MEDIUM\", \"HIGH\").", "example": { "by_metric": { "NET_INCOME": [ [ "1", "5000000.00" ] ], "REVENUE": [ [ "1", "15000000.00" ], [ "2", "25000000.00" ] ] }, "cik": "0000320193", "fiscal_period": "FY", "fiscal_year": 2023, "per_metric_max_delta": { "NET_INCOME": "5000000.00", "REVENUE": "25000000.00" }, "restatement_frequency": { "NET_INCOME": 1, "REVENUE": 2 }, "statement_type": "INCOME_STATEMENT", "timeline_severity": "LOW", "total_hops": 3 } }, "RestatementModelImpactHTTP": { "properties": { "impact_code": { "type": "string", "title": "Impact Code", "description": "Derived impact code such as operating_margin or working_capital." }, "previous_value": { "type": "string", "title": "Previous Value", "description": "Prior derived metric value." }, "current_value": { "type": "string", "title": "Current Value", "description": "Current derived metric value." }, "delta_value": { "type": "string", "title": "Delta Value", "description": "Current minus prior derived metric value." } }, "additionalProperties": false, "type": "object", "required": [ "impact_code", "previous_value", "current_value", "delta_value" ], "title": "RestatementModelImpactHTTP", "description": "HTTP schema for a compact derived model-impact summary." }, "RestatementSummaryHTTP": { "properties": { "total_metrics_compared": { "type": "integer", "title": "Total Metrics Compared", "description": "Total number of metrics considered in the restatement." }, "total_metrics_changed": { "type": "integer", "title": "Total Metrics Changed", "description": "Number of metrics whose value changed between versions." }, "has_material_change": { "type": "boolean", "title": "Has Material Change", "description": "True when at least one metric changed between the two versions." } }, "additionalProperties": false, "type": "object", "required": [ "total_metrics_compared", "total_metrics_changed", "has_material_change" ], "title": "RestatementSummaryHTTP", "description": "HTTP schema for a high-level restatement summary." }, "RollforwardFailedRuleHTTP": { "properties": { "rule_name": { "type": "string", "title": "Rule Name", "description": "Stable rollforward rule name." }, "delta": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Delta", "description": "Actual minus expected for the failed rollforward rule." } }, "additionalProperties": false, "type": "object", "required": [ "rule_name" ], "title": "RollforwardFailedRuleHTTP", "description": "Failed rollforward rule summary item." }, "RollforwardSkippedRuleDiagnosticHTTP": { "properties": { "rule_name": { "type": "string", "title": "Rule Name", "description": "Stable skipped rollforward rule name." }, "reason": { "type": "string", "title": "Reason", "description": "Stable reason code explaining the skip." }, "scope_evidence": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Scope Evidence", "description": "Deterministic statement-scope signatures supporting the skip." } }, "additionalProperties": false, "type": "object", "required": [ "rule_name", "reason" ], "title": "RollforwardSkippedRuleDiagnosticHTTP", "description": "Evidence-backed diagnostic for a skipped rollforward rule." }, "RollforwardSummaryHTTP": { "properties": { "pass_rate": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Pass Rate", "description": "Pass rate in [0,1] across the checks that were evaluated (skipped checks are excluded). Null when no check was evaluated: a skipped check is neither a pass nor a fail." }, "total_rules_count": { "type": "integer", "minimum": 0.0, "title": "Total Rules Count", "description": "Total rollforward rules in scope for this response." }, "supported_rules_count": { "type": "integer", "minimum": 0.0, "title": "Supported Rules Count", "description": "Rollforward rules with sufficient inputs (pass-rate denominator)." }, "skipped_rules_count": { "type": "integer", "minimum": 0.0, "title": "Skipped Rules Count", "description": "Rollforward rules skipped due to missing/unsupported inputs." }, "failed_rules": { "items": { "$ref": "#/components/schemas/RollforwardFailedRuleHTTP" }, "type": "array", "title": "Failed Rules", "description": "Failed rollforward rule names and deltas." }, "skipped_rules": { "items": { "type": "string" }, "type": "array", "title": "Skipped Rules", "description": "Skipped rollforward rule names." }, "skipped_rule_diagnostics": { "items": { "$ref": "#/components/schemas/RollforwardSkippedRuleDiagnosticHTTP" }, "type": "array", "title": "Skipped Rule Diagnostics", "description": "Evidence-backed diagnostics for skipped rollforward rules." } }, "additionalProperties": false, "type": "object", "required": [ "pass_rate", "total_rules_count", "supported_rules_count", "skipped_rules_count" ], "title": "RollforwardSummaryHTTP", "description": "Rollforward reconciliation summary metadata." }, "StatementCompletenessQualityHTTP": { "properties": { "metrics_expected": { "type": "integer", "minimum": 0.0, "title": "Metrics Expected", "description": "Canonical metrics defined for the statement type." }, "metrics_populated": { "type": "integer", "minimum": 0.0, "title": "Metrics Populated", "description": "Of those, metrics the statement serves a value for." }, "completeness_ratio": { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Completeness Ratio", "description": "metrics_populated over metrics_expected, in [0,1] to three places." }, "missing_metrics": { "items": { "type": "string" }, "type": "array", "title": "Missing Metrics", "description": "Expected metrics with no value, sorted." }, "metrics_not_reported": { "type": "integer", "minimum": 0.0, "title": "Metrics Not Reported", "description": "Missing metrics the filing never reported, so they are not a gap (a bank reports no inventories). Zero when absence has not been classified." }, "metrics_unresolved": { "type": "integer", "minimum": 0.0, "title": "Metrics Unresolved", "description": "Missing metrics the filing did report that are not served: the real gap." }, "reported_completeness_ratio": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Reported Completeness Ratio", "description": "metrics_populated over the metrics the filer reported (metrics_expected less metrics_not_reported), to three places. Null when absence has not been classified." } }, "additionalProperties": false, "type": "object", "required": [ "metrics_expected", "metrics_populated", "completeness_ratio", "metrics_not_reported", "metrics_unresolved" ], "title": "StatementCompletenessQualityHTTP", "description": "How many of its type's canonical metrics the statement serves." }, "StatementDQOverlayHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "statement_type": { "type": "string", "title": "Statement Type", "description": "Statement type (e.g. INCOME_STATEMENT)." }, "fiscal_year": { "type": "integer", "minimum": 0.0, "title": "Fiscal Year", "description": "Fiscal year (>= 0)." }, "fiscal_period": { "type": "string", "title": "Fiscal Period", "description": "Fiscal period (e.g. FY, Q1, Q2, Q3, Q4)." }, "accession_id": { "type": "string", "title": "Accession Id", "description": "SEC accession of the filing whose statement the overlay describes. With cik, statement_type, fiscal_year and fiscal_period it names one public statement; the overlay reads the filing's current statement.", "examples": [ "0001069183-25-000075" ] }, "accounting_standard": { "type": "string", "title": "Accounting Standard", "description": "Accounting standard (e.g. US_GAAP, IFRS)." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Reporting period end date." }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency code (e.g. USD)." }, "max_severity": { "anyOf": [ { "$ref": "#/components/schemas/MaterialityClass" }, { "type": "null" } ], "description": "Highest severity observed across facts and anomalies, if any." }, "validation_confidence_score": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Validation Confidence Score", "description": "Validation confidence for the filing's statement, on the inclusive 0-to-1 scale. Null means the statement has no validation score; it is never inferred from data-quality findings." }, "confidence_status": { "type": "string", "enum": [ "AVAILABLE", "NOT_EVALUATED" ], "title": "Confidence Status", "description": "AVAILABLE when the statement has a validation_confidence_score; NOT_EVALUATED when it has none." }, "facts": { "items": { "$ref": "#/components/schemas/NormalizedFactHTTP" }, "type": "array", "title": "Facts", "description": "Flattened facts for the statement identity." }, "fact_quality": { "items": { "$ref": "#/components/schemas/FactQualityHTTP" }, "type": "array", "title": "Fact Quality", "description": "Fact-level quality evaluations aligned to the statement." }, "anomalies": { "items": { "$ref": "#/components/schemas/DQAnomalyHTTP" }, "type": "array", "title": "Anomalies", "description": "Rule-level anomalies associated with the statement." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "fiscal_year", "fiscal_period", "accession_id", "accounting_standard", "statement_date", "currency", "confidence_status" ], "title": "StatementDQOverlayHTTP", "description": "A filing's statement with its data-quality findings.", "examples": [ { "accession_id": "0000320193-24-000123", "accounting_standard": "US_GAAP", "anomalies": [ { "details": { "change_ratio": "6.352694018783984181908057341", "current_value": "29749000000.000000", "previous_value": "4046000000.000000", "status": "FAIL", "threshold_ratio": "5" }, "message": "HISTORICAL_OUTLIER:FAIL", "metric": "INCOME_TAX_EXPENSE", "rule_code": "HISTORICAL_OUTLIER", "severity": "MEDIUM" } ], "cik": "0000320193", "confidence_status": "AVAILABLE", "currency": "USD", "fact_quality": [ { "cik": "0000320193", "details": { "HISTORICAL_OUTLIER": "PASS", "NON_NEGATIVE": "NOT_EVALUATED", "PRESENCE": "PASS" }, "dimension_key": "consolidation=CONSOLIDATED", "fiscal_period": "FY", "fiscal_year": 2024, "has_known_issue": false, "is_consistent_with_history": true, "is_present": true, "metric": "BASIC_EPS", "severity": "NONE", "statement_type": "INCOME_STATEMENT" }, { "cik": "0000320193", "details": { "HISTORICAL_OUTLIER": "PASS", "NON_NEGATIVE": "NOT_EVALUATED", "PRESENCE": "PASS" }, "dimension_key": "consolidation=CONSOLIDATED", "fiscal_period": "FY", "fiscal_year": 2024, "has_known_issue": false, "is_consistent_with_history": true, "is_present": true, "metric": "BASIC_EPS", "severity": "NONE", "statement_type": "INCOME_STATEMENT" } ], "facts": [ { "dimension": { "consolidation": "CONSOLIDATED" }, "dimension_key": "consolidation=CONSOLIDATED", "metric": "BASIC_EPS", "metric_code": "BASIC_EPS", "period_end": "2024-09-28", "period_origin": "SOURCE", "period_start": "2024-09-28", "source_line_item": "us-gaap:EarningsPerShareBasic", "unit": "USD", "value": "6.110000", "value_origin": "SOURCE" }, { "dimension": { "consolidation": "CONSOLIDATED" }, "dimension_key": "consolidation=CONSOLIDATED", "metric": "COST_OF_REVENUE", "metric_code": "COST_OF_REVENUE", "period_end": "2024-09-28", "period_origin": "SOURCE", "period_start": "2024-09-28", "source_line_item": "us-gaap:CostOfGoodsAndServicesSold", "unit": "USD", "value": "210352000000.000000", "value_origin": "SOURCE" } ], "fiscal_period": "FY", "fiscal_year": 2024, "max_severity": "MEDIUM", "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT", "validation_confidence_score": 1.0 } ] }, "StatementDataQualityHTTP": { "properties": { "evaluated_rule_count": { "type": "integer", "minimum": 0.0, "title": "Evaluated Rule Count", "description": "Data-quality rules checked against the statement's metrics." }, "passed_rule_count": { "type": "integer", "minimum": 0.0, "title": "Passed Rule Count", "description": "Checked rules that passed." }, "failed_rule_count": { "type": "integer", "minimum": 0.0, "title": "Failed Rule Count", "description": "Checked rules that failed." }, "total_rule_count": { "type": "integer", "minimum": 0.0, "title": "Total Rule Count", "description": "Rules in scope, whether or not they could be checked." }, "not_evaluated_metric_count": { "type": "integer", "minimum": 0.0, "title": "Not Evaluated Metric Count", "description": "Metrics none of whose rules could be checked." }, "pass_rate": { "anyOf": [ { "type": "string", "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$" }, { "type": "null" } ], "title": "Pass Rate", "description": "passed_rule_count over evaluated_rule_count, in [0,1] to four places. Null when no rule could be checked." }, "flags": { "items": { "$ref": "#/components/schemas/DataQualityFlagItemHTTP" }, "type": "array", "title": "Flags", "description": "Each failed rule, by metric and rule, ordered by metric then rule." } }, "additionalProperties": false, "type": "object", "required": [ "evaluated_rule_count", "passed_rule_count", "failed_rule_count", "total_rule_count", "not_evaluated_metric_count", "pass_rate" ], "title": "StatementDataQualityHTTP", "description": "The statement's data-quality findings." }, "StatementMappingQualityHTTP": { "properties": { "mapping_type_counts": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Mapping Type Counts", "description": "Served metrics by how each was mapped: DIRECT (the filer's own concept for the metric), FALLBACK (an accepted alternative concept), CALCULATED (exact arithmetic over other reported lines), INFERRED, or UNKNOWN (not recorded). Every key is present." }, "overridden_metrics": { "items": { "type": "string" }, "type": "array", "title": "Overridden Metrics", "description": "Metrics an override rule set. Check them before relying on the figures." }, "corrected_metrics": { "items": { "type": "string" }, "type": "array", "title": "Corrected Metrics", "description": "Metrics whose value differs from the figure as tagged; each fact names its correction_rule." }, "withheld_metrics": { "items": { "type": "string" }, "type": "array", "title": "Withheld Metrics", "description": "Metrics the filing reported that are not served because the filer's own subtotals contradict them." }, "metrics_from_other_filings": { "items": { "type": "string" }, "type": "array", "title": "Metrics From Other Filings", "description": "Metrics taken from a filing other than the statement's own accession." } }, "additionalProperties": false, "type": "object", "required": [ "mapping_type_counts" ], "title": "StatementMappingQualityHTTP", "description": "How the statement's metrics were taken from the filing." }, "StatementMetricAuditChainHTTP": { "properties": { "metric_name": { "type": "string", "title": "Metric Name", "description": "Canonical metric name for this audit chain (upper-snake-case)." }, "cik": { "type": "string", "title": "Cik", "description": "Canonical company CIK of the statement." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement family (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year of the statement." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period of the statement (e.g., FY, Q1)." }, "accession_id": { "type": "string", "title": "Accession Id", "description": "EDGAR accession of the filing that reported the statement." }, "filing_accession": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filing Accession", "description": "EDGAR accession of the filing the metric's figure came from, when recorded." }, "xbrl_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Xbrl Concept", "description": "Authoritative XBRL concept QName for the metric, when tracked." }, "mapping_type": { "anyOf": [ { "type": "string", "enum": [ "DIRECT", "FALLBACK", "CALCULATED", "INFERRED", "UNKNOWN" ] }, { "type": "null" } ], "title": "Mapping Type", "description": "How the metric was mapped from the filing, when recorded." }, "overrides": { "items": { "$ref": "#/components/schemas/MetricOverrideAuditHTTP" }, "type": "array", "title": "Overrides", "description": "Deterministically ordered override events for the metric (applied_at asc, with a fixed tie-break)." }, "steps": { "items": { "$ref": "#/components/schemas/StatementMetricAuditStepHTTP" }, "type": "array", "title": "Steps", "description": "The chain in order: each source fact, the calculation for a derived figure, the mapping, each override in the order applied, and the served value. A link that was not recorded is left out." } }, "additionalProperties": false, "type": "object", "required": [ "metric_name", "cik", "statement_type", "fiscal_year", "fiscal_period", "accession_id" ], "title": "StatementMetricAuditChainHTTP", "description": "HTTP schema for one filing statement's metric audit chain.", "examples": [ { "accession_id": "0000320193-24-000012", "cik": "0000320193", "filing_accession": "0000320193-24-000012", "fiscal_period": "FY", "fiscal_year": 2024, "mapping_type": "DIRECT", "metric_name": "TOTAL_ASSETS", "overrides": [ { "applied_at": "2024-11-03T12:00:00Z", "new_value_hash": "ffffeeee1111222233334444555566667777888899990000aaaabbbbccccdddd", "prior_value_hash": "aaaabbbbccccdddd1111222233334444555566667777888899990000aaaabbbb", "reason": "manual total assets mapping override", "source": "integration-test" } ], "statement_type": "BALANCE_SHEET", "steps": [ { "filing_accession": "0000320193-24-000012", "step": "SOURCE_FACT", "xbrl_concept": "us-gaap:Assets" }, { "mapping_type": "DIRECT", "step": "MAPPING" }, { "applied_at": "2024-11-03T12:00:00Z", "reason": "manual total assets mapping override", "step": "OVERRIDE" }, { "step": "SERVED_VALUE", "value": "364980000000" } ], "xbrl_concept": "us-gaap:Assets" } ] }, "StatementMetricAuditStepHTTP": { "properties": { "step": { "type": "string", "enum": [ "SOURCE_FACT", "CALCULATION", "MAPPING", "OVERRIDE", "SERVED_VALUE" ], "title": "Step", "description": "Which link this is. SOURCE_FACT is a fact the filer reported, CALCULATION the operation that combined facts, MAPPING how the figure was mapped to the metric, OVERRIDE a correction applied afterwards, and SERVED_VALUE the figure the API serves." }, "xbrl_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Xbrl Concept", "description": "On SOURCE_FACT, the XBRL concept the fact was reported under." }, "filing_accession": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filing Accession", "description": "On SOURCE_FACT, the EDGAR accession of the reporting filing." }, "calculation_steps": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Calculation Steps", "description": "On CALCULATION, the operation followed by each input and the value this statement serves for it." }, "mapping_type": { "anyOf": [ { "type": "string", "enum": [ "DIRECT", "FALLBACK", "CALCULATED", "INFERRED", "UNKNOWN" ] }, { "type": "null" } ], "title": "Mapping Type", "description": "On MAPPING, how the figure was mapped to the metric." }, "applied_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Applied At", "description": "On OVERRIDE, when the override was applied (UTC, ISO-8601)." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "On OVERRIDE, the reason recorded for it, when there is one." }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value", "description": "On SERVED_VALUE, the served figure as a decimal string." } }, "additionalProperties": false, "type": "object", "required": [ "step" ], "title": "StatementMetricAuditStepHTTP", "description": "HTTP schema for one link in a metric's audit chain.", "examples": [ { "filing_accession": "0000320193-24-000012", "step": "SOURCE_FACT", "xbrl_concept": "us-gaap:Assets" }, { "mapping_type": "DIRECT", "step": "MAPPING" }, { "step": "SERVED_VALUE", "value": "364980000000" } ] }, "StatementMetricMetaHTTP": { "properties": { "provenance": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/MetricProvenanceHTTP" }, "type": "object" }, { "type": "null" } ], "title": "Provenance", "description": "Optional per-metric provenance map keyed by metric name." }, "withheld_metrics": { "anyOf": [ { "additionalProperties": { "$ref": "#/components/schemas/WithheldMetricHTTP" }, "type": "object" }, { "type": "null" } ], "title": "Withheld Metrics", "description": "Metrics the filing reported that are not served, keyed by canonical metric code. A figure is withheld when the filer's own subtotals show it is not the metric: a non-current subtotal that is really a partial line, or a cost of revenue the filer's gross profit is not struck against, or when an earnings-per-share figure does not recompute from the filer's own net income and share count. The metric is absent from facts and counted in quality.completeness.metrics_unresolved; this records the rule, the figure as filed and its concept. Null when no withholding is recorded." } }, "additionalProperties": false, "type": "object", "title": "StatementMetricMetaHTTP", "description": "HTTP schema for statement-level metric metadata." }, "StatementMetricPublicProvenanceHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Canonical company CIK." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement family (INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Fiscal year of the statement." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Fiscal period of the statement (e.g., FY, Q1)." }, "accession_id": { "type": "string", "title": "Accession Id", "description": "EDGAR accession of the filing that reported the statement." }, "metric": { "type": "string", "title": "Metric", "description": "Canonical metric code." }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value", "description": "Metric value as a decimal string." }, "source_accession": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Accession", "description": "Source filing accession." }, "filing_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Filing Type", "description": "SEC form of the source filing as the SEC lists it; an amendment carries the /A suffix (e.g. 10-K/A)." }, "filing_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Filing Date", "description": "Source filing date." }, "accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Accepted At", "description": "SEC acceptance timestamp of the filing the statement came from." }, "source_xbrl_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Xbrl Concept", "description": "Source XBRL concept when directly tracked." }, "source_line_item": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source Line Item", "description": "Source line-item label when available." }, "mapping_type": { "anyOf": [ { "type": "string", "enum": [ "DIRECT", "FALLBACK", "CALCULATED", "INFERRED", "UNKNOWN" ] }, { "type": "null" } ], "title": "Mapping Type", "description": "Resolved mapping type." }, "override_applied": { "type": "boolean", "title": "Override Applied", "description": "Whether an override affected the metric." }, "override_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Override Reason", "description": "Override reason when an override affected the metric." }, "calculation_steps": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Calculation Steps", "description": "For a calculated metric, the operation that produced it followed by each input and the value this statement serves for it, for example FREE_CASH_FLOW = NET_CASH_FROM_OPERATING_ACTIVITIES - |CAPITAL_EXPENDITURES|. Null for a figure read directly from the filing." }, "source_context": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Source Context", "description": "Context of the source fact as the filer reported it, when recorded." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "fiscal_year", "fiscal_period", "accession_id", "metric", "override_applied" ], "title": "StatementMetricPublicProvenanceHTTP", "description": "HTTP schema for the public metric-provenance drill-down.", "examples": [ { "accepted_at": "2024-11-01T10:01:36Z", "accession_id": "0000320193-24-000123", "cik": "0000320193", "filing_date": "2024-11-01", "filing_type": "10-K", "fiscal_period": "FY", "fiscal_year": 2024, "mapping_type": "DIRECT", "metric": "REVENUE", "override_applied": false, "source_accession": "0000320193-24-000123", "source_line_item": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax", "statement_type": "INCOME_STATEMENT", "value": "391035000000.000000" } ] }, "StatementOverrideTraceHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK (zero-padded string)." }, "statement_type": { "type": "string", "title": "Statement Type", "description": "Statement type (e.g. INCOME_STATEMENT, BALANCE_SHEET, CASH_FLOW_STATEMENT)." }, "fiscal_year": { "type": "integer", "minimum": 0.0, "title": "Fiscal Year", "description": "Fiscal year for the statement identity (>= 0)." }, "fiscal_period": { "type": "string", "title": "Fiscal Period", "description": "Fiscal period code (e.g. FY, Q1, Q2, Q3, Q4)." }, "accession_id": { "type": "string", "title": "Accession Id", "description": "SEC accession of the filing whose statement the trace was evaluated against. With cik, statement_type, fiscal_year and fiscal_period it names one public statement; the trace reads the filing's current statement.", "examples": [ "0001069183-25-000075" ] }, "gaap_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gaap Concept", "description": "Optional GAAP/IFRS concept filter used for this trace." }, "canonical_metric_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Canonical Metric Code", "description": "Optional canonical metric code filter used for this trace." }, "dimension_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dimension Key", "description": "Optional dimension key filter used for this trace." }, "total_facts_evaluated": { "type": "integer", "minimum": 0.0, "title": "Total Facts Evaluated", "description": "Number of normalized facts evaluated for this trace." }, "total_facts_remapped": { "type": "integer", "minimum": 0.0, "title": "Total Facts Remapped", "description": "Number of facts whose canonical metric was remapped by overrides." }, "total_facts_suppressed": { "type": "integer", "minimum": 0.0, "title": "Total Facts Suppressed", "description": "Number of facts suppressed (dropped) by overrides." }, "rules": { "items": { "$ref": "#/components/schemas/OverrideRuleApplicationHTTP" }, "type": "array", "title": "Rules", "description": "Per-rule breakdown of how overrides contributed to this slice." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "fiscal_year", "fiscal_period", "accession_id", "total_facts_evaluated", "total_facts_remapped", "total_facts_suppressed" ], "title": "StatementOverrideTraceHTTP", "description": "Which mapping override rules applied to one filing's statement.", "examples": [ { "accession_id": "0000320193-24-000123", "cik": "0000320193", "fiscal_period": "FY", "fiscal_year": 2024, "rules": [], "statement_type": "INCOME_STATEMENT", "total_facts_evaluated": 0, "total_facts_remapped": 0, "total_facts_suppressed": 0 } ] }, "StatementQualityHTTP": { "properties": { "completeness": { "anyOf": [ { "$ref": "#/components/schemas/StatementCompletenessQualityHTTP" }, { "type": "null" } ], "description": "Metric completeness. Null for a statement with no normalized figures." }, "reconciliation": { "anyOf": [ { "$ref": "#/components/schemas/StatementReconciliationQualityHTTP" }, { "type": "null" } ], "description": "Reconciliation results for the statement. Null when it has none." }, "data_quality": { "anyOf": [ { "$ref": "#/components/schemas/StatementDataQualityHTTP" }, { "type": "null" } ], "description": "Data-quality findings. Null when no data-quality check has run on it." }, "mapping": { "anyOf": [ { "$ref": "#/components/schemas/StatementMappingQualityHTTP" }, { "type": "null" } ], "description": "How the metrics were mapped. Null for a statement with no normalized figures." } }, "additionalProperties": false, "type": "object", "title": "StatementQualityHTTP", "description": "Everything known about the statement's quality, part by part.\n\nThe same block is returned with every statement, on every route.", "examples": [ { "completeness": { "completeness_ratio": "0.895", "metrics_expected": 19, "metrics_not_reported": 2, "metrics_populated": 17, "metrics_unresolved": 0, "missing_metrics": [ "INTEREST_EXPENSE", "INTEREST_INCOME" ], "reported_completeness_ratio": "1.000" }, "data_quality": { "evaluated_rule_count": 40, "failed_rule_count": 0, "flags": [], "not_evaluated_metric_count": 0, "pass_rate": "1.0000", "passed_rule_count": 40, "total_rule_count": 68 }, "mapping": { "corrected_metrics": [], "mapping_type_counts": { "CALCULATED": 0, "DIRECT": 17, "FALLBACK": 0, "INFERRED": 0, "UNKNOWN": 0 }, "metrics_from_other_filings": [], "overridden_metrics": [], "withheld_metrics": [] }, "reconciliation": { "calendar": { "failed_count": 0, "failed_rules": [], "pass_rate": "1.0000", "passed_count": 1, "skipped_count": 0, "skipped_rules": [] }, "cross_statement": { "failed_count": 0, "failed_rules": [], "passed_count": 0, "skipped_count": 0, "skipped_rules": [] }, "identity": { "failed_count": 0, "failed_rules": [], "pass_rate": "1.0000", "passed_count": 3, "skipped_count": 0, "skipped_rules": [] }, "rollforward": { "failed_count": 0, "failed_rules": [], "passed_count": 0, "skipped_count": 0, "skipped_rules": [] } } } ] }, "StatementReconciliationQualityHTTP": { "properties": { "identity": { "$ref": "#/components/schemas/QualityCheckGroupHTTP", "description": "The statement's own accounting identities, such as assets equal liabilities plus equity, or gross profit equals revenue less cost of revenue." }, "cross_statement": { "$ref": "#/components/schemas/QualityCheckGroupHTTP", "description": "Identities that tie the statement to another statement of the same period, such as the income a cash-flow statement starts from equalling the income statement's net income." }, "rollforward": { "$ref": "#/components/schemas/QualityCheckGroupHTTP", "description": "Rollforwards that close on this balance sheet: the opening balance plus the period's flows equals the closing balance, for cash and for retained earnings. Only a balance sheet closes a rollforward." }, "calendar": { "$ref": "#/components/schemas/QualityCheckGroupHTTP", "description": "Whether an annual statement closes on the filer's established fiscal year end. Checked for annual statements only." } }, "additionalProperties": false, "type": "object", "required": [ "identity", "cross_statement", "rollforward", "calendar" ], "title": "StatementReconciliationQualityHTTP", "description": "The statement's reconciliation results, by group of rules." }, "StatementType": { "type": "string", "enum": [ "INCOME_STATEMENT", "BALANCE_SHEET", "CASH_FLOW_STATEMENT" ], "title": "StatementType", "description": "Supported financial statement types.\n\nThese are intentionally coarse and modeling-oriented. More granular breakdowns\n(e.g., \"INCOME_STATEMENT_Q1\") are encoded via fiscal period metadata, not enum\nexplosion." }, "StatementUsdHTTP": { "properties": { "values": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Values", "description": "Each money entry of the statement's values in US dollars, keyed by the same metric code. A share count is absent." }, "usd_per_unit": { "type": "string", "title": "Usd Per Unit", "description": "US dollars per unit of the as-filed currency, as a decimal string." }, "rate_basis": { "type": "string", "enum": [ "PERIOD_AVERAGE", "PERIOD_END", "AS_FILED" ], "title": "Rate Basis", "description": "PERIOD_AVERAGE for an income or cash-flow statement, PERIOD_END for a balance sheet, AS_FILED for a statement filed in US dollars." }, "rate_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Rate Start", "description": "First daily rate averaged. Null unless rate_basis is PERIOD_AVERAGE." }, "rate_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Rate End", "description": "Last daily rate averaged, or the date of the period-end rate. Null when rate_basis is AS_FILED." }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Publisher of the rate: 'Federal Reserve Board H.10'. Null when rate_basis is AS_FILED." } }, "additionalProperties": false, "type": "object", "required": [ "values", "usd_per_unit", "rate_basis" ], "title": "StatementUsdHTTP", "description": "A statement's values in US dollars, with the rate they were converted at.\n\nEvery value of a statement converts at one rate: a balance sheet's rate on\nits date, or the average rate over a duration statement's period.", "examples": [ { "rate_basis": "PERIOD_AVERAGE", "rate_end": "2025-12-31", "rate_start": "2025-01-02", "source": "Federal Reserve Board H.10", "usd_per_unit": "1.1306216", "values": { "DILUTED_EPS": "1.39", "REVENUE": "92881695061.60" } } ] }, "SystemMetadataHTTP": { "properties": { "mcp_version": { "type": "string", "title": "Mcp Version", "description": "Public MCP interface version advertised to clients.", "examples": [ "1.3.0" ] }, "api_version": { "type": "string", "title": "Api Version", "description": "Public HTTP API major version.", "examples": [ "v1" ] }, "max_page_size": { "type": "integer", "minimum": 1.0, "title": "Max Page Size", "description": "Maximum public API page size accepted by paginated endpoints.", "examples": [ 200 ] } }, "additionalProperties": false, "type": "object", "required": [ "mcp_version", "api_version", "max_page_size" ], "title": "SystemMetadataHTTP", "description": "HTTP schema for static system metadata and client limits.", "examples": [ { "api_version": "v1", "max_page_size": 200, "mcp_version": "1.3.0" } ] }, "UnavailableMetricHTTP": { "properties": { "metric": { "type": "string", "title": "Metric", "description": "Metric code with no value for the period; on multi-year rows, the valuation_inputs field name." }, "reason": { "$ref": "#/components/schemas/MetricNullReason", "description": "Why the metric could not be computed. NOT_REPORTED: the filing does not report the line. NOT_ON_STATEMENT: the metric reads lines of a different statement than the row. MISSING_INPUT: an input is not reported for the period (see missing_inputs). DENOMINATOR_ZERO: the divisor is zero. NON_POSITIVE_VALUE: the formula needs a positive value (a CAGR base, a share count) and got zero or less. NO_COMPARABLE_PERIOD: no earlier period of the same length to grow from. NOT_APPLICABLE_TO_PERIOD: undefined for this kind of period, such as quarter-over-quarter growth on an annual row. INCOMPLETE_TRAILING_YEAR: not every quarter of the trailing twelve months reports the line. NOT_YET_COMPUTED: the inputs support a value that has not been computed yet; it is served once computed. INPUTS_INCONSISTENT: the filer's own figures contradict each other, so no value is computed from them." }, "missing_inputs": { "items": { "type": "string" }, "type": "array", "title": "Missing Inputs", "description": "Canonical metric codes the formula reads that were not reported for the period. Empty unless an absent input is the cause." } }, "additionalProperties": false, "type": "object", "required": [ "metric", "reason" ], "title": "UnavailableMetricHTTP", "description": "HTTP schema naming a metric with no value for a period, and why.", "examples": [ { "metric": "INVENTORY_TURNOVER", "missing_inputs": [ "INVENTORIES" ], "reason": "MISSING_INPUT" } ] }, "UniversePITSnapshotBuildingHTTP": { "properties": { "status": { "type": "string", "title": "Status", "description": "Always 'BUILDING': the snapshot is not ready yet.", "default": "BUILDING" }, "pending_ciks": { "items": { "type": "string" }, "type": "array", "title": "Pending Ciks", "description": "Companies whose model periods are still being built, ascending." }, "retry_after_seconds": { "type": "integer", "minimum": 1.0, "title": "Retry After Seconds", "description": "Estimated seconds until repeating the request returns the snapshot." } }, "additionalProperties": false, "type": "object", "required": [ "pending_ciks", "retry_after_seconds" ], "title": "UniversePITSnapshotBuildingHTTP", "description": "HTTP schema for a universe snapshot whose companies are still being modeled.", "examples": [ { "pending_ciks": [ "0000320193", "0000789019" ], "retry_after_seconds": 12, "status": "BUILDING" } ] }, "UniversePITSnapshotMetaHTTP": { "properties": { "snapshot_id": { "type": "string", "title": "Snapshot Id", "description": "Hash attesting this response: the request and the statements it was answered from. The same request over the same statements gives the same hash." }, "snapshot_hash": { "type": "string", "title": "Snapshot Hash", "description": "Hash of the statements the as-of date serves. GET /v1/edgar/as-of/{date}/financials/{cik} reports the same hash for the same date, so equal hashes mean the same data." }, "accession_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Accession Id", "description": "SEC accession number of the filing whose statement is the metric source.", "examples": [ "0000320193-24-000123" ] } }, "additionalProperties": false, "type": "object", "required": [ "snapshot_id", "snapshot_hash" ], "title": "UniversePITSnapshotMetaHTTP", "description": "HTTP schema for universe snapshot attestation metadata." }, "UniversePITSnapshotMetricHTTP": { "properties": { "cik": { "type": "string", "title": "Cik", "description": "Company CIK." }, "statement_type": { "$ref": "#/components/schemas/StatementType", "description": "Statement type." }, "metric_name": { "type": "string", "title": "Metric Name", "description": "Canonical metric code." }, "metric_value": { "type": "string", "title": "Metric Value", "description": "Decimal metric value as a string." }, "statement_date": { "type": "string", "format": "date", "title": "Statement Date", "description": "Resolved statement period end date." }, "fiscal_year": { "type": "integer", "minimum": 1.0, "title": "Fiscal Year", "description": "Resolved statement fiscal year." }, "fiscal_period": { "$ref": "#/components/schemas/FiscalPeriod", "description": "Resolved statement fiscal period." }, "_meta": { "$ref": "#/components/schemas/UniversePITSnapshotMetaHTTP", "description": "The snapshot and filing this metric was read from, and the response's attestation hash." } }, "additionalProperties": false, "type": "object", "required": [ "cik", "statement_type", "metric_name", "metric_value", "statement_date", "fiscal_year", "fiscal_period", "_meta" ], "title": "UniversePITSnapshotMetricHTTP", "description": "HTTP schema for a single universe PIT snapshot metric row.", "examples": [ { "_meta": { "accession_id": "0000320193-24-000123", "snapshot_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "snapshot_id": "d8096ece479710259f77848f7d1e57dad95a968a0c4d3f5db32f3f9cc32ff57c" }, "cik": "0000320193", "fiscal_period": "FY", "fiscal_year": 2024, "metric_name": "REVENUE", "metric_value": "100.000000", "statement_date": "2024-09-28", "statement_type": "INCOME_STATEMENT" } ] }, "UniversePITSnapshotRequestHTTP": { "properties": { "ciks": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 50, "minItems": 1 }, { "type": "null" } ], "title": "Ciks", "description": "Universe of company CIKs. Send this or `tickers`, not both. Hard-capped to 50 identifiers per request." }, "tickers": { "anyOf": [ { "items": { "type": "string" }, "type": "array", "maxItems": 50, "minItems": 1 }, { "type": "null" } ], "title": "Tickers", "description": "Universe of companies named by ticker symbol, in place of `ciks`. Each resolves to the company whose filings hold its statements on `as_of_date`. Hard-capped to 50 identifiers per request.", "examples": [ [ "AAPL", "MSFT" ] ] }, "as_of_date": { "type": "string", "format": "date", "title": "As Of Date", "description": "As-of business date (YYYY-MM-DD)." }, "statement_types": { "items": { "$ref": "#/components/schemas/StatementType" }, "type": "array", "minItems": 1, "title": "Statement Types", "description": "Statement types to resolve for each company." }, "metrics_bundle": { "type": "string", "title": "Metrics Bundle", "description": "Metric selection: 'all', or 'core' for the core metrics of each statement type (the set GET /v1/fundamentals/time-series?core_metrics_only=true uses).", "examples": [ "all" ] } }, "additionalProperties": false, "type": "object", "required": [ "as_of_date", "statement_types", "metrics_bundle" ], "title": "UniversePITSnapshotRequestHTTP", "description": "HTTP schema for universe point-in-time snapshot requests.", "examples": [ { "as_of_date": "2024-11-02", "ciks": [ "0000320193", "0000789019" ], "metrics_bundle": "core", "statement_types": [ "INCOME_STATEMENT", "BALANCE_SHEET" ] } ] }, "UsdValueHTTP": { "properties": { "value": { "type": "string", "title": "Value", "description": "The value in US dollars: the as-filed value times usd_per_unit, kept to the as-filed value's decimal places and at least to cents." }, "usd_per_unit": { "type": "string", "title": "Usd Per Unit", "description": "US dollars per unit of the as-filed currency, as a decimal string." }, "rate_basis": { "type": "string", "enum": [ "PERIOD_AVERAGE", "PERIOD_END", "AS_FILED" ], "title": "Rate Basis", "description": "PERIOD_AVERAGE for a value over a period (income and cash-flow statements): the mean of the daily rates from rate_start to rate_end. PERIOD_END for a value on one date (balance sheet): the daily rate on rate_end, the last on or before the balance date. AS_FILED when the value was filed in US dollars." }, "rate_start": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Rate Start", "description": "First daily rate averaged. Null unless rate_basis is PERIOD_AVERAGE." }, "rate_end": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Rate End", "description": "Last daily rate averaged, or the date of the period-end rate. Null when rate_basis is AS_FILED." }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Publisher of the rate: 'Federal Reserve Board H.10'. Null when rate_basis is AS_FILED." } }, "additionalProperties": false, "type": "object", "required": [ "value", "usd_per_unit", "rate_basis" ], "title": "UsdValueHTTP", "description": "A fact's value in US dollars, with the rate it was converted at.\n\nAttributes:\n value: The value in US dollars.\n usd_per_unit: US dollars per unit of the as-filed currency.\n rate_basis: PERIOD_AVERAGE, PERIOD_END or AS_FILED.\n rate_start: First rate date averaged, for a period average.\n rate_end: Last rate date averaged, or the date of a period-end rate.\n source: Publisher of the rate.", "examples": [ { "rate_basis": "PERIOD_AVERAGE", "rate_end": "2025-12-31", "rate_start": "2025-01-02", "source": "Federal Reserve Board H.10", "usd_per_unit": "1.1306216", "value": "92881695061.60" } ] }, "ValuationInputsHTTP": { "properties": { "revenue": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revenue", "description": "Revenue for the period (decimal string)." }, "gross_profit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gross Profit", "description": "Gross profit for the period (decimal string)." }, "operating_income": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Operating Income", "description": "Operating income for the period (decimal string)." }, "net_income": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Income", "description": "Net income for the period (decimal string)." }, "income_before_tax": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Income Before Tax", "description": "Income before tax for the period (decimal string)." }, "income_tax_expense": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Income Tax Expense", "description": "Income tax expense for the period (decimal string)." }, "interest_expense": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Interest Expense", "description": "Interest expense for the period (decimal string)." }, "interest_income": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Interest Income", "description": "Interest income for the period (decimal string)." }, "depreciation_and_amortization": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Depreciation And Amortization", "description": "Depreciation and amortization expense (decimal string)." }, "stock_based_compensation_in_cfo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Stock Based Compensation In Cfo", "description": "Stock-based compensation add-back reported in CFO (decimal string)." }, "depreciation_and_amortization_in_cfo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Depreciation And Amortization In Cfo", "description": "D&A add-back reported in CFO, when disclosed (decimal string)." }, "change_in_accounts_receivable": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change In Accounts Receivable", "description": "Reported CFO change in accounts receivable (decimal string)." }, "change_in_inventories": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change In Inventories", "description": "Reported CFO change in inventories (decimal string)." }, "change_in_accounts_payable": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change In Accounts Payable", "description": "Reported CFO change in accounts payable (decimal string)." }, "change_in_other_current_assets": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change In Other Current Assets", "description": "Reported CFO change in other current assets (decimal string)." }, "change_in_other_current_liabilities": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Change In Other Current Liabilities", "description": "Reported CFO change in other current liabilities (decimal string)." }, "net_working_capital_change": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Working Capital Change", "description": "Net working-capital change from available CFO deltas (ΔAR + ΔInventory + ΔAP + ΔOtherCurrentAssets + ΔOtherCurrentLiabilities)." }, "cash_from_operations": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cash From Operations", "description": "Net cash from operating activities (decimal string)." }, "capital_expenditures": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Capital Expenditures", "description": "Capital expenditures (decimal string)." }, "free_cash_flow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Free Cash Flow", "description": "Free cash flow; canonical FCF or CFO + CAPEX (decimal string)." }, "unlevered_free_cash_flow": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unlevered Free Cash Flow", "description": "Unlevered free cash flow (NOPAT + D&A + CAPEX - net_working_capital_change)." }, "total_assets": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Assets", "description": "Total assets for the period (decimal string)." }, "total_equity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Equity", "description": "Total equity for the period (decimal string)." }, "total_current_assets": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Current Assets", "description": "Total current assets (decimal string)." }, "total_current_liabilities": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Current Liabilities", "description": "Total current liabilities (decimal string)." }, "cash_and_cash_equivalents": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cash And Cash Equivalents", "description": "Cash and cash equivalents (decimal string)." }, "short_term_debt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Short Term Debt", "description": "Short-term debt (decimal string)." }, "current_portion_long_term_debt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Portion Long Term Debt", "description": "Current portion of long-term debt (decimal string)." }, "long_term_debt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Long Term Debt", "description": "Long-term debt (decimal string)." }, "weighted_average_shares_basic": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Weighted Average Shares Basic", "description": "Weighted average basic shares (decimal string)." }, "weighted_average_shares_diluted": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Weighted Average Shares Diluted", "description": "Weighted average diluted shares (decimal string)." }, "ebit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ebit", "description": "EBIT (income before tax + interest expense - interest income)." }, "ebitda": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ebitda", "description": "EBITDA (operating income + D&A)." }, "tax_rate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tax Rate", "description": "Effective tax rate (income tax expense / income before tax)." }, "nopat": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nopat", "description": "Net operating profit after tax (decimal string)." }, "working_capital": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Working Capital", "description": "Working capital (current assets - current liabilities)." }, "total_debt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Total Debt", "description": "Total debt (short-term + current portion + long-term)." }, "net_debt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Debt", "description": "Net debt (total debt - cash)." }, "invested_capital": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invested Capital", "description": "Invested capital (equity + total debt - cash)." }, "net_capex": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Net Capex", "description": "Net capex (capital expenditures + D&A)." } }, "additionalProperties": false, "type": "object", "title": "ValuationInputsHTTP", "description": "HTTP schema for valuation input primitives.", "examples": [ { "capital_expenditures": "-10.00", "cash_and_cash_equivalents": "10.00", "cash_from_operations": "25.00", "change_in_accounts_payable": "4.00", "change_in_accounts_receivable": "-3.00", "change_in_inventories": "-2.00", "change_in_other_current_assets": "-1.00", "change_in_other_current_liabilities": "2.00", "current_portion_long_term_debt": "5.00", "depreciation_and_amortization": "4.00", "depreciation_and_amortization_in_cfo": "3.00", "ebit": "27.00", "ebitda": "34.00", "free_cash_flow": "15.00", "gross_profit": "60.00", "income_before_tax": "25.00", "income_tax_expense": "5.00", "interest_expense": "3.00", "interest_income": "1.00", "invested_capital": "100.00", "long_term_debt": "20.00", "net_capex": "-6.00", "net_debt": "20.00", "net_income": "20.00", "net_working_capital_change": "0.00", "nopat": "21.60", "operating_income": "30.00", "revenue": "100.00", "short_term_debt": "5.00", "stock_based_compensation_in_cfo": "6.00", "tax_rate": "0.200000", "total_assets": "200.00", "total_current_assets": "90.00", "total_current_liabilities": "50.00", "total_debt": "30.00", "total_equity": "80.00", "unlevered_free_cash_flow": "14.60", "weighted_average_shares_basic": "1000.00", "weighted_average_shares_diluted": "1020.00", "working_capital": "40.00" } ] }, "VersionMetricDeltaHTTP": { "properties": { "metric": { "type": "string", "title": "Metric", "description": "Canonical or derived metric code." }, "original_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Original Value", "description": "Metric value as first filed." }, "comparison_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comparison Value", "description": "Metric value as most recently filed." }, "absolute_delta": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Absolute Delta", "description": "Comparison minus original value." }, "percent_delta": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Percent Delta", "description": "Absolute delta divided by original value." }, "first_filing_accession_id": { "type": "string", "title": "First Filing Accession Id", "description": "Accession id for the original filing." }, "comparison_filing_accession_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comparison Filing Accession Id", "description": "Accession id for the comparison filing." }, "change_accepted_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Change Accepted At", "description": "UTC time the SEC accepted the first filing whose figure differs from the original; null when no filing changed it." } }, "additionalProperties": false, "type": "object", "required": [ "metric", "first_filing_accession_id" ], "title": "VersionMetricDeltaHTTP", "description": "Change in one metric between a period's first-filed and latest-filed figures.", "examples": [ { "absolute_delta": "25.0", "change_accepted_at": "2024-11-02T16:05:00Z", "comparison_filing_accession_id": "0000320193-24-000120", "comparison_value": "125.0", "first_filing_accession_id": "0000320193-24-000100", "metric": "REVENUE", "original_value": "100.0", "percent_delta": "0.250000" } ] }, "WebhookSubscriptionCreateRequestHTTP": { "properties": { "event_type": { "type": "string", "title": "Event Type", "description": "Canonical outbound event type: `restatement.detected` when a filing restates a statement already served, or `statement.created` when a filing gives a company a statement for a period it had none for.", "examples": [ "restatement.detected" ] }, "target_url": { "type": "string", "title": "Target Url", "description": "HTTPS endpoint to receive outbound webhook payloads.", "examples": [ "https://example.com/arche/webhooks" ] } }, "additionalProperties": false, "type": "object", "required": [ "event_type", "target_url" ], "title": "WebhookSubscriptionCreateRequestHTTP", "description": "Request payload to create an account-scoped outbound webhook subscription." }, "WebhookSubscriptionHTTP": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Subscription identifier. Name it in the rotate-secret and delete paths, and it appears in each delivery's `delivery_dedupe_key`." }, "event_type": { "type": "string", "title": "Event Type", "description": "Canonical outbound event type currently supported for delivery.", "examples": [ "restatement.detected" ] }, "target_url": { "type": "string", "title": "Target Url", "description": "HTTPS endpoint that receives outbound restatement alerts.", "examples": [ "https://example.com/arche/webhooks" ] }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the subscription is active." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the subscription was registered, in UTC." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "When the subscription last changed, in UTC. A rotation moves it." } }, "additionalProperties": false, "type": "object", "required": [ "id", "event_type", "target_url", "is_active", "created_at", "updated_at" ], "title": "WebhookSubscriptionHTTP", "description": "Account-scoped outbound webhook subscription payload." }, "WebhookSubscriptionListHTTP": { "properties": { "items": { "items": { "$ref": "#/components/schemas/WebhookSubscriptionHTTP" }, "type": "array", "title": "Items", "description": "Every subscription the organization holds in the selected environment, without signing secrets. Its length against the plan's limit is how many slots are left." } }, "additionalProperties": false, "type": "object", "required": [ "items" ], "title": "WebhookSubscriptionListHTTP", "description": "List envelope for account-scoped webhook subscriptions." }, "WebhookSubscriptionWithSecretHTTP": { "properties": { "id": { "type": "string", "format": "uuid", "title": "Id", "description": "Subscription identifier. Name it in the rotate-secret and delete paths, and it appears in each delivery's `delivery_dedupe_key`." }, "event_type": { "type": "string", "title": "Event Type", "description": "Canonical outbound event type currently supported for delivery.", "examples": [ "restatement.detected" ] }, "target_url": { "type": "string", "title": "Target Url", "description": "HTTPS endpoint that receives outbound restatement alerts.", "examples": [ "https://example.com/arche/webhooks" ] }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether the subscription is active." }, "created_at": { "type": "string", "format": "date-time", "title": "Created At", "description": "When the subscription was registered, in UTC." }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At", "description": "When the subscription last changed, in UTC. A rotation moves it." }, "signing_secret": { "type": "string", "title": "Signing Secret", "description": "Secret for verifying this subscription's deliveries. Each delivery carries `X-Arche-Signature: t=,v1=`, where the hex value is HMAC-SHA256 with this secret over `.` followed by the raw request body. Compare in constant time and reject timestamps more than five minutes old.", "examples": [ "whsec_4Jq0uW2mX9..." ] } }, "additionalProperties": false, "type": "object", "required": [ "id", "event_type", "target_url", "is_active", "created_at", "updated_at", "signing_secret" ], "title": "WebhookSubscriptionWithSecretHTTP", "description": "Webhook subscription with its signing secret.\n\nReturned only by create and rotate. Store the secret when you receive it:\nlisting subscriptions does not return it." }, "WithheldMetricHTTP": { "properties": { "rule": { "type": "string", "title": "Rule", "description": "Stable identifier of the rule that withheld the figure. GROSS_PROFIT_IDENTITY_CONTRADICTED: a cost of revenue the filer's own gross profit is not struck against. ASSETS_SUBTOTALS_IDENTITY_CONTRADICTED and LIABILITIES_SUBTOTALS_IDENTITY_CONTRADICTED: a non-current subtotal the filer's own total less its current subtotal shows is a partial line. EPS_FAILS_OWN_ARITHMETIC: an earnings-per-share figure that does not recompute from the filer's own net income and weighted-average share count, or a share count of zero or less that one rests on." }, "as_filed_value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "As Filed Value", "description": "The figure as the filing tagged it, as a decimal string in full units." }, "as_filed_concept": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "As Filed Concept", "description": "Source XBRL concept the withheld figure was tagged under." } }, "additionalProperties": false, "type": "object", "required": [ "rule" ], "title": "WithheldMetricHTTP", "description": "A metric withheld from the statement because the filer's own subtotals contradict it.\n\nAttributes:\n rule: Stable identifier of the rule that withheld the figure.\n as_filed_value: The figure the filer tagged, in full units.\n as_filed_concept: Source XBRL concept the figure was tagged under.", "examples": [ { "as_filed_concept": "us-gaap:CostOfGoodsAndServicesSold", "as_filed_value": "307200000", "rule": "GROSS_PROFIT_IDENTITY_CONTRADICTED" } ] }, "AnomalyExplanationPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/AnomalyExplanationHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "AnomalyExplanationPage" }, "AsReportedConceptPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/AsReportedConceptHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "AsReportedConceptPage" }, "AsReportedFactPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/AsReportedFactHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "AsReportedFactPage" }, "BulkSnapshotPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/BulkSnapshotHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "BulkSnapshotPage" }, "CompanyCoverageSummaryPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/CompanyCoverageSummaryHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "CompanyCoverageSummaryPage" }, "CompanyIdentityPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/CompanyIdentityHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "CompanyIdentityPage" }, "DataQualityIssuePage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/DataQualityIssueHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "DataQualityIssuePage" }, "DerivedMetricsTimeSeriesPointPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/DerivedMetricsTimeSeriesPointHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "DerivedMetricsTimeSeriesPointPage" }, "EdgarFilingDisclosureSummaryPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/EdgarFilingDisclosureSummaryHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "EdgarFilingDisclosureSummaryPage" }, "EdgarFilingPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/EdgarFilingHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "EdgarFilingPage" }, "EdgarStatementPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/EdgarStatementHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "EdgarStatementPage" }, "FilingFactPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/FilingFactHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "FilingFactPage" }, "FinancialStatePeriodPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/FinancialStatePeriodHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "FinancialStatePeriodPage" }, "MetricBundleTimeSeriesRowPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/MetricBundleTimeSeriesRowHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "MetricBundleTimeSeriesRowPage" }, "MetricCoverageSummaryPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/MetricCoverageSummaryHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "MetricCoverageSummaryPage" }, "MetricDimensionPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/MetricDimensionHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "MetricDimensionPage" }, "ModelGrowthPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/ModelGrowthHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "ModelGrowthPage" }, "ModelMultiYearPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/ModelMultiYearHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "ModelMultiYearPage" }, "ModelPeriodPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/ModelPeriodHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "ModelPeriodPage" }, "ModelRatiosPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/ModelRatiosHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "ModelRatiosPage" }, "ModelTTMPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/ModelTTMHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "ModelTTMPage" }, "NarrativePage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/NarrativeHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "NarrativePage" }, "ReconciliationResultPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/ReconciliationResultHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "ReconciliationResultPage" }, "RestatementAlertEventPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/RestatementAlertEventHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "RestatementAlertEventPage" }, "UniversePITSnapshotMetricPage": { "properties": { "page": { "type": "integer", "minimum": 1.0, "title": "Page" }, "page_size": { "type": "integer", "maximum": 200.0, "minimum": 1.0, "title": "Page Size" }, "total": { "type": "integer", "minimum": 0.0, "title": "Total" }, "items": { "items": { "$ref": "#/components/schemas/UniversePITSnapshotMetricHTTP" }, "type": "array", "title": "Items" } }, "additionalProperties": false, "type": "object", "required": [ "page", "page_size", "total", "items" ], "title": "UniversePITSnapshotMetricPage" }, "AgentCheckoutLinkEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/AgentCheckoutLinkHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "AgentCheckoutLinkEnvelope" }, "AgentClaimEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/AgentClaimHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "AgentClaimEnvelope" }, "AgentSignupEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/AgentSignupHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "AgentSignupEnvelope" }, "BulkDownloadUrlEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/BulkDownloadUrlHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "BulkDownloadUrlEnvelope" }, "BulkLicenseAcceptanceRecordEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/BulkLicenseAcceptanceRecordHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "BulkLicenseAcceptanceRecordEnvelope" }, "BulkLicenseEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/BulkLicenseHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "BulkLicenseEnvelope" }, "BulkSnapshotManifestEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/BulkSnapshotManifestHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "BulkSnapshotManifestEnvelope" }, "CompanyCoverageSummaryEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/CompanyCoverageSummaryHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "CompanyCoverageSummaryEnvelope" }, "CompanyIdentityResolveEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/CompanyIdentityResolveHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "CompanyIdentityResolveEnvelope" }, "CoverageSelectionEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/CoverageSelectionHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "CoverageSelectionEnvelope" }, "EdgarCompanyCompletenessEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/EdgarCompanyCompletenessHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "EdgarCompanyCompletenessEnvelope" }, "EdgarCompanyProfileEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/EdgarCompanyProfileHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "EdgarCompanyProfileEnvelope" }, "EdgarCompanyResolveEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/EdgarCompanyResolveHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "EdgarCompanyResolveEnvelope" }, "EdgarDerivedMetricsCatalogEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/EdgarDerivedMetricsCatalogHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "EdgarDerivedMetricsCatalogEnvelope" }, "EdgarDerivedMetricsTimeSeriesEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/EdgarDerivedMetricsTimeSeriesHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "EdgarDerivedMetricsTimeSeriesEnvelope" }, "EdgarFilingDisclosureEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/EdgarFilingDisclosureHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "EdgarFilingDisclosureEnvelope" }, "EdgarFilingEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/EdgarFilingHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "EdgarFilingEnvelope" }, "EdgarFinancialsAsOfEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/EdgarFinancialsAsOfHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "EdgarFinancialsAsOfEnvelope" }, "EdgarFinancialsAsOfPageEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/EdgarFinancialsAsOfPageHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "EdgarFinancialsAsOfPageEnvelope" }, "EdgarStatementListEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/EdgarStatementListHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "EdgarStatementListEnvelope" }, "FactRevisionLedgerEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/FactRevisionLedgerHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "FactRevisionLedgerEnvelope" }, "IngestionStatusEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/IngestionStatusHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "IngestionStatusEnvelope" }, "MCPManifestEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/MCPManifestHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "MCPManifestEnvelope" }, "MacroContextEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/MacroContextHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "MacroContextEnvelope" }, "MacroSeriesEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/MacroSeriesHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "MacroSeriesEnvelope" }, "MetricCoverageSummaryEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/MetricCoverageSummaryHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "MetricCoverageSummaryEnvelope" }, "MetricDefinitionEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/MetricDefinitionHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "MetricDefinitionEnvelope" }, "MetricDriftEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/MetricDriftHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "MetricDriftEnvelope" }, "MetricViewsCatalogEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/MetricViewsCatalogHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "MetricViewsCatalogEnvelope" }, "ModelImpactEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/ModelImpactHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "ModelImpactEnvelope" }, "NormalizedStatementViewEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/NormalizedStatementViewHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "NormalizedStatementViewEnvelope" }, "QueryExecuteResponseEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/QueryExecuteResponseHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "QueryExecuteResponseEnvelope" }, "QueryReplayResponseEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/QueryReplayResponseHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "QueryReplayResponseEnvelope" }, "QueryVerificationEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/QueryVerificationHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "QueryVerificationEnvelope" }, "RealFundamentalMetricSeriesEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/RealFundamentalMetricSeriesHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "RealFundamentalMetricSeriesEnvelope" }, "RestatementAlertEventEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/RestatementAlertEventHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "RestatementAlertEventEnvelope" }, "RestatementLedgerEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/RestatementLedgerHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "RestatementLedgerEnvelope" }, "RestatementMetricTimelineEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/RestatementMetricTimelineHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "RestatementMetricTimelineEnvelope" }, "StatementDQOverlayEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/StatementDQOverlayHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "StatementDQOverlayEnvelope" }, "StatementMetricAuditChainEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/StatementMetricAuditChainHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "StatementMetricAuditChainEnvelope" }, "StatementMetricPublicProvenanceEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/StatementMetricPublicProvenanceHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "StatementMetricPublicProvenanceEnvelope" }, "StatementOverrideTraceEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/StatementOverrideTraceHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "StatementOverrideTraceEnvelope" }, "SystemMetadataEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/SystemMetadataHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "SystemMetadataEnvelope" }, "UniversePITSnapshotBuildingEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/UniversePITSnapshotBuildingHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "UniversePITSnapshotBuildingEnvelope" }, "VersionMetricDeltaEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/VersionMetricDeltaHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "VersionMetricDeltaEnvelope" }, "WebhookSubscriptionEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscriptionHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "WebhookSubscriptionEnvelope" }, "WebhookSubscriptionListEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscriptionListHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "WebhookSubscriptionListEnvelope" }, "WebhookSubscriptionWithSecretEnvelope": { "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscriptionWithSecretHTTP", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "WebhookSubscriptionWithSecretEnvelope" }, "BulkDatasetListEnvelope": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BulkDatasetHTTP" }, "type": "array", "title": "Data", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "BulkDatasetListEnvelope" }, "MacroSeriesDefinitionListEnvelope": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MacroSeriesDefinitionHTTP" }, "type": "array", "title": "Data", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "MacroSeriesDefinitionListEnvelope" }, "MetricBundleCatalogItemListEnvelope": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MetricBundleCatalogItemHTTP" }, "type": "array", "title": "Data", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "MetricBundleCatalogItemListEnvelope" }, "MetricDefinitionListEnvelope": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MetricDefinitionHTTP" }, "type": "array", "title": "Data", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "MetricDefinitionListEnvelope" }, "ReconciliationSummaryBucketListEnvelope": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ReconciliationSummaryBucketHTTP" }, "type": "array", "title": "Data", "description": "Returned resource or value." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "ReconciliationSummaryBucketListEnvelope" }, "SuccessEnvelope": { "additionalProperties": false, "description": "Success envelope for non-paginated responses: {\"data\": T}.", "properties": { "data": { "description": "Returned resource or value.", "title": "Data" } }, "required": [ "data" ], "title": "SuccessEnvelope", "type": "object" }, "PaginatedEnvelope": { "additionalProperties": false, "description": "Paginated success envelope.", "properties": { "page": { "minimum": 1, "title": "Page", "type": "integer" }, "page_size": { "maximum": 200, "minimum": 1, "title": "Page Size", "type": "integer" }, "total": { "minimum": 0, "title": "Total", "type": "integer" }, "items": { "items": {}, "title": "Items", "type": "array" } }, "required": [ "page", "page_size", "total", "items" ], "title": "PaginatedEnvelope", "type": "object" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT bearer token (Clerk) via Authorization header." }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "API key for data-plane and control-plane access." } } } }